Working with Server

In addition to Backend Service Document Manager has Users and Tags services to work with on the server side.

Loading Data

Document Manager is a backend-oriented component.

Preview images for files are generated by a backend server.

If you do not have a backend server, you should override the methods of the Backend, Users, and Tags services. Methods must return promises of client-side data.

Dynamic Loading

Document Manager does not load all the data to the client at once:

  • the root directory and the initially opened folder,
  • the folder tree of the file system and group folders (but not their contents).

These data are loaded on demand and cached:

  • the contents of other directories and group folders are loaded when the directories are opened,
  • all tags and all users are loaded when the related components are opened (the preview, the cards mode, the popup for document sharing)

Saving data

By default, Document Manager expects a working backend server with REST API and saves data pessimistically, which means that it first sends a request to the server, then upon a successful response it updates the client. We provide an example of backend code in Golang.

Overriding Services

In general the process of overriding a service is the same as for File Manager:

  • extend a default class
  • use the override setting of Document Manager
class Users extends docManager.services.Users {
    // define custom logic
}
 
webix.ui({
    view: "docmanager",
    url: "//localhost:3200/",
    override: new Map([[docManager.services.Users, Users]]),
});

Backend Service

Backend is a server-side model. It is defined as a class and has methods for sending requests. Document Manager has the same methods as File Manager Backend Service and has several of its own.

files(id, source)

This method redefines files from File Manager Backend service. The method returns the contents of the current working directory or the contents of a group folder. The method is called when the user opens a folder.

Parameters:

  • id (string) - the ID of the current working directory
  • source (string) - points to a group folder (Favorite/Recent/Trash/Shared) or to the root directory ("My files") (the values are "files", "favorite", "recent", "trash", "shared")

Returns:

  • files (promise) - a promise that resolves with an array of objects

Request info:

  • Method: GET
  • URL example:
http://localhost:3200/files?id=%2F&source=shared

The request URL string contains the URL segment, the ID of the current directory ("/" in this case) and the ID of a group folder ("shared" in this case).

  • Response from the server:

Server returns an array of objects found on the directory.

[
  {"value":"lalala.txt","id":"/lalala.txt","size":0,
    "date":1587121183,"type":"code","users":[4,2,1,3]
  },
  {"value":"New file.txt","id":"/widgets/New file.txt","size":0,
    "date":1587133267,"type":"code","star":true,"users":[1,2]
  },
  // other
]

removePermanent(id)

Permanently removes a file or directory. The method is called when a user removes a file or directory from Trash.

Parameters:

  • id (number) - the ID of the file or directory being removed (this is a database unique ID)

Returns:

  • result (promise) - a promise that resolves with a server response:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

  • Method: DELETE
  • URL example:
http://localhost:3200/delete?id=259

Contains the URL segment and the ID of a file or directory.

restore(id)

Restores a removed file or directory from Trash.

Parameters:

  • id (number) - the ID of the file or directory being restored (this is a database unique ID)

Returns:

  • info (promise) - a promise that resolves with file or directory data (object)

Request info:

  • Method: PUT
  • URL example:
http://localhost:3200/delete
  • Response from the server:

Server returns an object with the file or directory data that is being restored.

{
  "value":"New file.txt","id":"/123/New file.txt","size":0,
  "date":1587128389,"type":"code"
}
  • Form data example:
id: 258

favour(id)

The method is called when a user adds a file/directory to Favorite.

Parameters:

  • id (string) - the ID of the file or directory being added to Favorite

Returns:

  • result (promise) - a promise that resolves with a server response:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

  • Method: POST
  • URL example:
http://localhost:3200/favorite
  • Form data example:
id: /mycat.png

unfavour(id)

The method is called when a user removes a file/directory from Favorite.

Parameters:

  • id (string) - the ID of the file or directory being removed

Returns:

  • result (promise) - a promise that resolves with a server response:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

  • Method: DELETE
  • URL example:
http://localhost:3200/favorite?id=%2Fmycat.png

Contains the URL segment and the ID of a file or directory being removed from Favorite.

writeBinary(id, filename, upload)

The method is called on saving binary files (in Document Manager it's used for saving Excel files).

Parameters:

  • id (string) - the ID of a file
  • filename (string) - the name of a file (with extension)
  • upload (blob) - a blob with the new content of a file

Returns:

  • result (promise) - a promise that resolves with the file data object

Request info:

  • Method: POST
  • URL example:
http://localhost:3200/direct?id=%2FSpread.xlsx

Contains the URL segment and the ID of the file.

  • Response from the server:

Server returns a promise that resolves with the file data object.

{
  "value":"Spread.xlsx","id":"/Spread.xlsx","size":129848,
    "date":1587383690,"type":"file"
}
  • Form data example:
upload: (binary)

Users Service

The service works with the user-related operations through the following methods:

url(path)

Returns the full path to a file, a directory or a url. url() is used by other methods for making URLs for server requests.

Parameters:

  • path (string) - a relative path.

Returns:

  • url (string) - the full path.

users()

The method returns a promise that resolves with an array of all users.

Returns:

  • users (promise) - a promise that resolves with an array of users objects

Request info:

  • Method: GET
  • URL example:
http://localhost:3200/users/all
  • Response from the server:

Server returns an array with users data objects.

[
  {"id":1,"name":"Alastor Moody","email":"alastor@ya.ru",
    "avatar":"/users/1/avatar/1.jpg"},
  {"id":2,"name":"Sirius Black","email":"sirius@gmail.com",
    "avatar":"/users/3/avatar/3.jpg"}
]

share(id, user)

The method shares a file or directory with a user. The shared file or directory is being added to the Shared group folder.

Parameters:

  • id (string) - the ID of the file or directory being shared
  • user (number) - the ID of a user to share with

Returns:

  • result (promise) - a promise that resolves with a server response:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

  • Method: POST
  • URL example:
http://localhost:3200/share
  • Form data example:
id: /mycat.png
user: 3

removeUser(id, user)

Removes a user from the "shared-with" list.

Parameters:

  • id (string) - the ID of the file or directory
  • user (number) - the ID of a user to be removed

Returns:

  • result (promise) - a promise that resolves with a server response:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

  • Method: DELETE
  • URL example:
http://localhost:3200/share?id=%2Fmycat.png&user=3

Contains the URL segment, the ID of the file or directory and the ID of the user.

comments(id)

Returns an array of comments left under a file.

Parameters:

  • id (string) - the ID of the file

Returns:

  • comments (promise) - a promise that resolves with an array of comments objects (an empty array if there are no comments left).

Request info:

  • Method: GET
  • URL example:
http://localhost:3200/comments?id=%2Fmycat.png

Contains the URL segment and the ID of the file.

  • Response from the server:

Server returns an array of comments data objects if any.

[
  {
    "id":45,"text":"He's my patronus!!","date":"2020-04-20T07:56:49Z","user_id":1
  }
]

addComment(id, value)

The method leaves a comment under a file.

Parameters:

  • id (string) - the ID of the file to comment
  • value (string) - the text of a comment

Returns:

  • result (promise) - a promise that resolves with a server response:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

  • Method: POST
  • URL example:
http://localhost:3200/comments?id=%2Fmycat.png

Contains the URL segment and the ID of the file.

  • Form data example:
value: Accio!

updateComment(id, value)

The method updates a comment after editing.

Parameters:

  • id (string) - the ID of the comment
  • value (string) - the text of a comment

Returns:

  • result (promise) - a promise that resolves with a server response:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

  • Method: PUT
  • URL example:
http://localhost:3200/comments/1

Contains the URL segment and the ID of the comment.

  • Form data example:
value: Edited text

deleteComment(id)

Removes the specified comment.

Parameters:

  • id (string) - the ID of the comment

Returns:

  • result (promise) - a promise that resolves with a server response:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

  • Method: DELETE
  • URL example:
http://localhost:3200/comments/1

Contains the URL segment and the ID of the comment.

Tags Service

The service works with the tags-related operations through the following methods:

url(path)

Returns the full path to a file, a directory or a url. url() is used by other methods for making URLs for server requests.

Parameters:

  • path (string) - a relative path.

Returns:

  • url (string) - the full path.

tags()

The method returns a promise that resolves with an array of all tags.

Returns:

  • tags (promise) - a promise that resolves with an array of all tags (an empty array if there are no tags)

Request info:

  • Method: GET
  • URL example:
http://localhost:3200/tags/all
  • Response from the server:

Server returns a promise that resolves with an array of tags (objects).

[
  {"id":1,"name":"Review","value":"Review"},
  {"id":2,"name":"Accepted","value":"Accepted"},
  {"id":3,"name":"Denied","value":"Denied"},
  {"id":4,"name":"Personal","value":"Personal"}
]

getTags(id)

The method returns a promise that resolves with an array of the tags added to a file or a directory.

Parameters:

  • id (string) - the ID of the file.

Returns:

  • tags (promise) - a promise that resolves with an array of tags (an empty array if there are no tags).

Request info:

  • Method: GET
  • URL example:
http://localhost:3200/tags?id=%2FNew%20file.txt

Contains the URL segment and the ID of the file.

  • Response from the server:

Server returns an array of the tags' IDs.

[
  4,2
]

setTags(id, value)

The method saves tags of a file.

Parameters:

  • id (string) - the ID of the file.
  • value (string) - the ID(s) of the tag(s)

Returns:

  • result (promise) - a promise that resolves with a server response:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

  • Method: PUT
  • URL example:
http://localhost:3200/tags

Contains the URL segment.

  • Form data example:
id: /New file.txt
value: 0,1
Back to top