Работа с сервером

В добавок к Backend Service у Document Manager есть сервисы Users и Tags для работы на сервере.

Загрузка данных

Document Manager это серверноориентированный компонент, который ожидает загрузку данных по URL. Вы можете передать ссылку на сервер через параметр url:

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

Вы также можете скачать готовый бэкенд для Document Manager.

Если у вас нет бэкенд сервера, вы можете переопределить методы сервиса Backend и возвращать промисы с клиентскими данными.

Иконки и превью-изображения для файлов генерируются сервисом Backend.

Динамическая загрузка

Document Manager не загружает все данные сразу. Что загружается сразу:

корневая директория и изначально открытая папка,
дерево групповых и обычных папок (но не их содержимое).

Содержимое остальных директорий подгружается по необходимости и кэшируется:

содержимое других директорий и групповых папок загружается при их открытии,
все тэги и пользователи загружаются при открытии соответствующих компонентов (превью, режим "cards", попап для того, чтобы поделиться файлом).

Сервис Backend

Сервис Backend это серверная модель, у которой есть методы для запросов на сервер.
Смотрите полный список методов ниже.

Как кастомизировать модель Backend

Принцип переопределения модели такой же, как и для File Manager:

1. Создать свой бэкенд сервис и наследовать его от сервиса по умолчанию.
2. Переопределить сервис с помощью свойства override.

class MyBackend extends docManager.services.Backend {
    // новые методы 
}
 
webix.ui({
    view: "docmanager",
    url: "https://docs.webix.com/docmanager-backend/",
    override: new Map([[docManager.services.Backend, MyBackend]]),
});

Запросы к бэкенд серверу

Вы можете отправлять AJAX запросы своему серверу:

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

Обработка клиентских данных

В случае необходимости вы можете вернуться клиентские данные промисом:

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

Помимо базовых методов, как у сервиса Backend в File Manager, у Document Manager есть свои специфические методы. Ниже вы найдёте описания следующих из них:

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

files(id, source)

Метод переопределяет аналогичный метод сервиса Backend в File Manager. Вызывается, когда пользователь открывает указанную директорию.

Parameters:

id (string) - ID текущей директории;
source (string) - указывает на групповую папку (Favorite/Recent/Trash/Shared) или на корневую директорию ("My files"). Возможные значения: "files", "favorite", "recent", "trash", "shared".

Returns: промис с массивом объектов файлов.

Request:

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

Response:

Сервер возвращает массив объектов файлов в директории.

[
  {"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]
  },
  // другие объекты
]

removePermanent(id)

Полностью удаляет файл или папку. Метод вызывается, когда пользователь удаляет файл или папку из корзины (Trash).

Parameters:

id (number) - ID файла или папки (уникальный ID в базе данных).

Returns: промис с ответом сервера ("success" или "error").

Request:

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

В случае ошибки, сервер возвращает объект со следующими данными:

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

restore(id)

Восстанавливает удалённые файлы из корзины (Trash).

Parameters:

id (number) - ID файла/папки (уникальный ID в базе данных).

Returns: промис с объектом файла/папки.

Request:

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

Response:

Сервер возвращает объект файла/папки.

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

В случае ошибки, сервер возвращает объект со следующими данными:

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

favour(id)

Вызывается, когда пользователь добавляет новые файл/папку в избранное (Favorite).

Parameters:

id (string) - ID файла/папки.

Returns: промис с ответом сервера ("success" или "error").

Request:

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

unfavour(id)

Вызывается, когда пользователь удаляет файл/папку из избранного (Favorite).

Parameters:

id (string) - ID файла/папки.

Returns: промис с ответом сервера ("success" или "error").

Request:

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

writeBinary(id, filename, upload)

Вызывается при сохранении бинарных файлов (в Document Manager используется для сохранения файлов Excel).

Parameters:

id (string) - ID файла;
filename (string) - имя файла (с расширением);
upload (blob) - блоб с новым содержимым файла.

Returns: промис с объектом файла.

Request:

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

Response:

Сервер возвращает объект файла.

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

Сервис Users

Сервис работает с операциями над пользователями.

url(path)

Используется другими методами для подготовки URL к запросам.

Parameters:

path (string) - относительный путь.

Returns: абсолютный путь.

users()

Вызывается, когда пользователь открывает превью файла.

Returns: промис с массивом объектов пользователей.

Request:

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

Response:

Сервер возвращает массив объектов пользователей.

[
  {"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"}
]

Делится файлом/папкой с другими пользователями. Такие файлы/папки попадают в групповую папку Shared.

Parameters:

id (string) - ID файла/папки;
user (number) - ID пользователя, с которым хотите поделиться.

Returns: промис с ответом сервера ("success" или "error").

Request:

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

removeUser(id, user)

Удаляет пользователя из списка тех, у кого есть доступ к файлу или директории.

Parameters:

id (string) - ID файла/папки;
user (number) - ID пользователя.

Returns: промис с ответом сервера ("success" или "error").

Request:

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

comments(id)

Вызывается, когда пользователь открывает комментарии к файлу.

Parameters:

id (string) - ID файла.

Returns: промис с массивом объектов комментариев (пустой массив, если комментариев нет).

Request:

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

Response:

Сервер возвращает массив объектов комментариев, если таковые есть.

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

addComment(id, value)

Добавляет комментарий под указанным файлом.

Parameters:

id (string) - ID файла;
value (string) - текст комментария.

Returns: промис с ответом сервера ("success" или "error").

Request:

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

updateComment(id, value)

Обновляет указанный комментарий.

Parameters:

id (number) - ID комментария;
value (string) - текст комментария.

Returns: промис с ответом сервера ("success" или "error").

Request:

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

deleteComment(id)

Удаляет указанный комментарий.

Parameters:

id (number) - ID комментария.

Returns: промис с ответом сервера ("success" или "error").

Request:

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

Сервис Tags

Сервис работает с операциями над тэгами.

url(path)

Используется другими методами для подготовки URL к запросам.

Parameters:

path (string)- относительный путь.

Returns: абсолютный путь.

tags()

Вызывается, когда пользователь открывает превью файла.

Returns: промис с массивом объектов тэгов (пустым массивом, если тэгов нет).

Request:

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

Response:

Сервер возвращает промис с массивом объектов тэгов.

[
  {"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)

Создаёт новый тэг.

Parameters:

data (object) - данные тэга.

Returns: промис с ответом сервера ("success" или "error").

Request:

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

Response:

Сервер возвращает объект созданного тэга.

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

Обратите внимание, что длина названия тэга не может превышать 32-х символов. Если вам необходима произвольная допустимая длина, необходимо настроить соответствующую таблицу на бэкенде.

updateTag(id, data)

Обновляет указанный тэг.

Parameters:

id (number) - ID тэга;
data (object) - данные тэга.

Returns: промис с ответом сервера ("success" или "error").

Request:

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

Response :

Сервер возвращает объект тэга.

{
  "id":13,
  "name":"University",
  "value":"University",
  "color":"#c87095" // цвет был изменён
}

removeTag(id)

Удаляет указанный тэг.

Parameters:

id (number) - ID тэга.

Returns: промис с ответом сервера ("success" или "error").

Request:

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

getTags(id)

Вызывается, когда пользователь открывает превью указанного файла.

Parameters:

id (string) - ID файла.

Returns: промис с массивом объектов тэгов (пустым массивом, если тэгов нет).

Request:

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

Response:

Сервер возвращает массив c ID тэгов.

[
  4,2
]

setTags(id, value)

Добавляет тэг указанному файлу.

Parameters:

id (string) - ID файла;
value (string) - ID тэга.

Returns: промис с ответом сервера ("success" или "error").

Request:

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

Сервис Versions

Сервис для работы с историей редактирования текстовых файлов (тип "code") и таблиц Excel. У сервиса есть следующие методы:

url(path)

Используется другими методами для подготовки URL к запросам.

Parameters:

path (string) - относительный путь.

Returns: абсолютный путь.

versions(id)

Вызывается, когда пользователь открывает историю изменений указанного файла.

Parameters:

id (string) - ID файла (по умолчанию это относительный путь к файлу).

Returns: промис с массивом всех версий (пустым массивом, если история версий пуста).

Request:

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

Response:

Сервер возвращает массив объектов версий.

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

readText(id, diff)

Вызывается, когда пользователь выбирает версию файла из списка.

Parameters:

id (string) - ID файла (по умолчанию это относительный путь к файлу);
diff (boolean) - если true, версия сравнивается с предыдущей.

Returns: промис со сравнением версий файла.

Request:

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

Response:

Сервер возвращает HTML строку:

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

Вызывается, когда пользователь восстанавливает указанную версию.

Parameters:

id (string) - ID файла (по умолчанию это относительный путь к файлу);
version (number) - ID версии.

Returns: промис с данными версии.

Request:

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

Response:

Сервер возвращает объект файла:

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

directLink(id)

Вызывается при открытии файла Excel.

Parameters:

id (string) - ID файла (по умолчанию это относительный путь к файлу).

Returns: URL для запроса к Excel файлу.

Наверх

Работа с сервером

Загрузка данных

Динамическая загрузка

Сервис Backend

Как кастомизировать модель Backend

Запросы к бэкенд серверу

Обработка клиентских данных

Методы сервиса Backend

Сервис Users

Сервис Tags

Сервис Versions

files(id, source)

removePermanent(id)

restore(id)

favour(id)

unfavour(id)

writeBinary(id, filename, upload)

Сервис Users

url(path)

users()

share(id, user)

removeUser(id, user)

comments(id)

addComment(id, value)

updateComment(id, value)

deleteComment(id)

Сервис Tags

url(path)

tags()

addTag(data)

updateTag(id, data)

removeTag(id)

getTags(id)

setTags(id, value)

Сервис Versions

url(path)

versions(id)

readText(id, diff)

restore(id, version)

directLink(id)