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 and expects a server to fetch data from. You can provide a link to it by the url setting:

webix.ui({
  view: "docmanager",
  url:"http://localhost:3200/"
});

Sample backend for Document Manager is available for downloading.

If you do not have a backend server, you should override the methods of the Backend service and return promises of client-side data.

Icons and preview images for files are generated by a backend service.

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:

Contents of other directories are loaded on demand, when opened, 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)

Backend Service

Backend is a server-side model. It is defined as an object and has methods for sending requests.
Check out the full list of methods.

How to Override Backend Service

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

1. Extend it.
2. Use the override setting of Document Manager.

class MyBackend extends docManager.services.Backend {
    // define and override methods here
}
 
webix.ui({
    view: "docmanager",
    url: "https://docs.webix.com/docmanager-backend/",
    override: new Map([[docManager.services.Backend, MyBackend]]),
});

Calls to Backend Server

You can send AJAX requests to your backend server:

class MyBackend extends docManager.services.Backend {
    files(id, source) {
      return webix.ajax("//localhost:3200/files", { id, source })
            .then((data) => data.json());
    }
}

Parsing client-side data

If you have client-side data, you can return them inside of a promise:

class MyBackend extends docManager.services.Backend {
    getInfo() {
        return Promise.resolve({
            stats:{
                free: 52 * 1000 * 1000,
                total: 250 * 1000 * 1000,
                used: 198.4 * 1000 * 1000,
            }
        });
    }
}

Backend Service Methods

Document Manager has the same methods as File Manager Backend Service does, and proposes several of its own. Below you can find descriptions of the following methods:

favour()
files()
removePermanent()
restore()
unfavour()
writeBinary()

files(id, source)

This method redefines files from File Manager Backend service. 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: a promise that resolves with an array of objects.

Request:

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

Response:

The 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) - ID of the file or directory being removed (this is a database unique ID).

Returns: a promise that resolves with a server response (success or error).

Request:

DELETE http://localhost:3200/delete?id=259

If the request fails the server returns an error object:

{
  invalid: true, 
  err: "Some error message here"
}

restore(id)

Restores a removed file or directory from Trash.

Parameters:

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

Returns: a promise that resolves with file or directory data object.

Request:

PUT http://localhost:3200/delete
Form Data
id: 258

Response:

The server returns an object with the file or directory data.

{
  "value":"New file.txt","id":"/123/New file.txt","size":0,
  "date":1587128389,"type":"code"
}

If the request fails the server returns an error object:

{
  invalid: true, 
  err: "Some error message here"
}

favour(id)

Is called when user adds a file/directory to Favorite.

Parameters:

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

Returns: a promise that resolves with a server response (success or error).

Request:

POST http://localhost:3200/favorite
Form Data
id: /mycat.png

unfavour(id)

Is called when user removes a file/directory from Favorite.

Parameters:

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

Returns: a promise that resolves with a server response (success or error).

Request:

DELETE http://localhost:3200/favorite?id=%2Fmycat.png

writeBinary(id, filename, upload)

Is called upon saving binary files (in Document Manager it's used for saving Excel files).

Parameters:

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

Returns: a promise that resolves with the file data object.

Request:

POST http://localhost:3200/direct?id=%2FSpread.xlsx
Form Data
upload: (binary)

Response:

The server returns a promise that resolves with the file data object.

{
  "value":"Spread.xlsx","id":"/Spread.xlsx","size":129848,
    "date":1587383690,"type":"file"
}

Users Service

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

url(path)

Is used by other methods for preparing URLs for server requests.

Parameters:

path (string) - a relative path.

Returns: the full path.

users()

Is called when user opens file preview.

Returns: a promise that resolves with an array of users objects.

Request:

GET http://localhost:3200/users/all

Response:

The 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"}
]

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

Parameters:

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

Returns: a promise that resolves with a server response (success or error).

Request:

POST http://localhost:3200/share
Form Data
id: /mycat.png
user: 3

removeUser(id, user)

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

Parameters:

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

Returns: a promise that resolves with a server response (success or error).

Request:

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

comments(id)

Is called when user opens comments section.

Parameters:

id (string) - file ID.

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

Request:

GET http://localhost:3200/comments?id=%2Fmycat.png

Response:

The 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)

Leaves a comment under a specified file.

Parameters:

id (string) - ID of the file to comment;
value (string) - text of the comment.

Returns: a promise that resolves with a server response (success or error).

Request:

POST http://localhost:3200/comments?id=%2Fmycat.png
Form Data
value: Accio!

updateComment(id, value)

Updates a specified comment.

Parameters:

id (number) - ID of the comment;
value (string) - text of a comment.

Returns: a promise that resolves with a server response (success or error).

Request:

PUT http://localhost:3200/comments/1
Form Data
value: Edited text

deleteComment(id)

Removes a specified comment.

Parameters:

id (number) - comment ID.

Returns: a promise that resolves with a server response (success or error).

Request:

DELETE http://localhost:3200/comments/1

Tags Service

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

url(path)

Is used by other methods for preparing URLs for server requests.

Parameters:

path (string)- a relative path.

Returns: the full path.

tags()

Is called when user opens file preview.

Returns: a promise that resolves with an array of all tags (an empty array if there are no tags).

Request:

GET http://localhost:3200/tags/all

Response:

The server returns a promise that resolves with an array of object tags.

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

addTag(data)

Adds a tag to the tags list.

Parameters:

data (object) - data object of the added tag.

Returns: a promise that resolves with a server response (success or error).

Request:

POST http://localhost:3200/tags
Form Data
name: New
color: #0bbed7

Response:

The server returns a data object of the added tag.

{
  "id":13,
  "name":"New",
  "value":"New",
  "color":"#0bbed7"
}

Note that by default, length of the tag name cannot exceed 32 characters. If you need a custom length you should change the corresponding table on the backend.

updateTag(id, data)

Updates an already existing tag.

Parameters:

id (number) - tag ID;
data (object) - data object of the tag being updated.

Returns: a promise that resolves with a server response (success or error).

Request:

PUT http://localhost:3200/tags/13
Form Data
name: University
color: #c87095

Response :

The server returns a data object of the updated tag.

{
  "id":13,
  "name":"University",
  "value":"University",
  "color":"#c87095" // color was changed
}

Note that by default, length of the tag name cannot exceed 32 characters. If you need a custom length you should change the corresponding table on the backend.

removeTag(id)

Removes a specified tag from the tags list.

Parameters:

id (number) - tag ID.

Returns: a promise that resolves with a server response (success or error).

Request:

DELETE http://localhost:3200/tags/3

getTags(id)

Is called when user opens the preview of a specified file.

Parameters:

id (string) - file ID.

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

Request:

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

Response:

The server returns an array of the tags' IDs.

[
  4,2
]

setTags(id, value)

Saves tags of a file.

Parameters:

id (string) - file ID;
value (string) - tag ID.

Returns: a promise that resolves with a server response (success or error).

Request:

PUT http://localhost:3200/tags
Form Data
id: /New file.txt
value: 0,1

Versions Service

The service works with the version history of text (type "code") and Excel files through the following methods:

url(path)

Is used by other methods for preparing URLs for server requests.

Parameters:

path (string) - a relative path.

Returns: the full path.

versions(id)

Is called when user opens the version history of a specified file.

Parameters:

id (string) - ID of the file (by default it is the relative path to the file).

Returns: a promise that resolves with an array of all versions (an empty array if there version history is empty).

Request:

GET http://localhost:3200/versions?id=%2Fdocker-compose.yml

Response:

The server returns an array of version objects.

[
    {
        "id":20,
        "date":"2020-07-07T08:51:00Z",
        "user":1,
        "content":"",
        "origin":null
    }
]

readText(id, diff)

Is called when user selects a file version from the history.

Parameters:

id (string) - ID of the file (by default it is the relative path to the file);
diff (boolean) - if true, the version is compared to the previous version.

Returns: a promise that resolves with a version compared to the previous version of a text file.

Request:

GET http://localhost:3200/versions/20?mode=text&diff=true
Form Data
mode: text

Response:

The server returns an HTML string like the following:

`
<span>version: &#34;3&#34;
services: 
  worker:
    networks:
      - app
      - web
    restart: always
</span><span class='webix_docmanager_diff_remove'>&#8626;<br></span>
<span class='webix_docmanager_diff_insert'>someNewKey<br></span>
`

restore(id, version)

Is called when user restores a specified version.

Parameters:

id (string) - ID of the file (by default it is the relative path to the file);
version (number) - version ID.

Returns: a promise that resolves with with the data of a new version.

Request:

POST http://localhost:3200/versions
Form Data
id: /docker-compose.yml
version: 26

Response:

The server returns file object:

{
    "value":"docker-compose.yml",
    "id":"/docker-compose.yml",
    "size":162,
    "date":1594114235,
    "type":"code"
}

directLink(id)

Is called when user opens an Excel file.

Parameters:

id (string) - ID of the file (by default it is a relative path to the file).

Returns: URL for a request to get a version of the Excel file.

Working with Server

Loading Data

Dynamic Loading

Backend Service

How to Override Backend Service

Calls to Backend Server

Parsing client-side data

Backend Service Methods

Users Service

Tags Service

Versions Service

files(id, source)

removePermanent(id)

restore(id)

favour(id)

unfavour(id)

writeBinary(id, filename, upload)

Users Service

url(path)

users()

share(id, user)

removeUser(id, user)

comments(id)

addComment(id, value)

updateComment(id, value)

deleteComment(id)

Tags Service

url(path)

tags()

addTag(data)

updateTag(id, data)

removeTag(id)

getTags(id)

setTags(id, value)

Versions Service

url(path)

versions(id)

readText(id, diff)

restore(id, version)

directLink(id)