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

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

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

Document Manager это серверно-ориентированный компонент.

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

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

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

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

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

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

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

Сохранение данных

По умолчанию File Manager ожидает рабочий сервер с REST API и сохраняет данные следующим образом:

1) отправляет запрос на сервер;
2) если операция на сервере выполнилась без ошибок, обновляет данные на клиенте.

Мы предоставляем серверный код на Golang.

Переопределение сервисов

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

  • унаследовать класс по умолчанию
  • переопределить с помощью свойства override
class Users extends docManager.services.Users {
    // ваша логика
}
 
webix.ui({
    view: "docmanager",
    url: "//localhost:3200/",
    override: new Map([[docManager.services.Users, Users]]),
});

Backend сервис

Бэкенд это серверная модель, объект, у которого есть методы для отправки запросов. Backend сервис менеджера включает в себя все методы сервиса Backend у File Manager, а также несколько своих методов.

files(id, source)

Этот метод переопределяет метод files() у сервиса Backend в File Manager. Метод возвращает содержимое текущей директории или групповой папки. Метод вызывается, когда пользователь открывает какую-либо папку.

Parameters:

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

Returns:

  • files (promise) - промис (если выполнен), который возвращает массив объектов

Request info:

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

Строка запроса содержит сегмент URL, ID текущей директории (в данном случае "/new directory") и ID групповой папки (в данном случае "shared").

  • Response from the server:

Сервер возвращает массив объектов, найденных в директории:

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

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

Parameters:

  • id (number) - ID удаляемого файла/директории (уникальное ID в базе данных)

Returns:

  • result (promise) - промис со следующими данными:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

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

Содержит URL сегмент и ID файла или директории.

restore(id)

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

Parameters:

  • id (number) - ID восстанавливаемого файлы/директории (уникальное ID в базе данных)

Returns:

  • info (promise) - промис (если выполнен), который возвращает объект файла или директории

Request info:

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

Сервер возвращает данные восстановленного файла или директории.

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

favour(id)

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

Parameters:

  • id (string) - ID файла или директории, добавляемого в Favorite

Returns:

  • result (promise) - промис со следующими данными:
    • 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)

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

Parameters:

  • id (string) - ID файла или директории, убираемого из Favorite

Returns:

  • result (promise) - промис со следующими данными:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

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

Содержит URL сегмент и ID файла или директории.

writeBinary(id, filename, upload)

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

Parameters:

  • id (string) - ID файла
  • filename (string) - имя файла (с расширением)
  • upload (blob) - БДО (blob) с новым содержимым

Returns:

  • result (promise) - промис (если выполнен), который возвращает объект файла

Request info:

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

Содержит URL сегмент и ID файла.

  • Response from the server:

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

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

Сервис Users

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

url(path)

Возвращает абсолютный путь к файлу/папке или url. url() используется другими методами для создания URL запросов на сервер.

Parameters:

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

Returns:

  • url (string) - абсолютный путь

users()

Метод возвращает промис, который разрешается в массив со всеми пользователями.

Returns:

  • users (promise) - промис (если выполнен), который возвращает массив в объектами всех пользователей

Request info:

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

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

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

Метод открывает доступ к файлу/папке для других пользователей. Общие файлы или директории добавляются в групповую папку Shared.

Parameters:

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

Returns:

  • result (promise) - промис со следующими данными:
    • 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)

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

Parameters:

  • id (string) - ID файла или директории
  • user (number) - ID пользователя

Returns:

  • result (promise) - промис со следующими данными:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

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

Содержит URL сегмент, ID файла или директории и ID пользователя.

comments(id)

Возвращает массив комментариев файла.

Parameters:

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

Returns:

  • comments (promise) - промис (если выполнен), который возвращает массив объектов комментариев (в случае отсутствия комментариев - пустой массив).

Request info:

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

Содержит URL сегмент и ID файла.

  • Response from the server:

Сервер возвращает массив с данными комментариев или пустой массив.

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

  • result (promise) - промис со следующими данными:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

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

Содержит URL сегмент и ID файла.

  • Form data example:
value: Accio!

updateComment(id, value)

Обновляет комментарий после редактирования.

Parameters:

Returns:

  • result (promise) - промис со следующими данными:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

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

Содержит URL сегмент и ID комментария.

  • Form data example:
value: Edited text

deleteComment(id)

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

Parameters:

  • id (number) - the ID of the comment

Returns:

  • result (promise) - промис со следующими данными:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

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

Содержит URL сегмент и ID комментария.

Сервис Tags

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

url(path)

Возвращает абсолютный путь к файлу/папке или url. url() используется другими методами для создания URL запросов на сервер.

Parameters:

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

Returns:

  • url (string) - абсолютный путь

tags()

Метод возвращает промис с массивом всех тэгов.

Returns:

  • tags (promise) - промис (если выполнен), который возвращает массив объектов тэгов (в случае отсутствия тэгов - пустой массив).

Request info:

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

Возвращает промис с массивом всех тэгов (объекты данных).

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

  • result (promise) - промис (если выполнен), который возвращает ответ с сервера:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

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

Содержит URL сегмент и ID файла.

  • Response from the server:

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

{
  "id":13,
  "name":"New",
  "value":"New",
  "color":"#0bbed7"
}
  • Form data example
name: New
color: #0bbed7

updateTag(id, data)

Обновляет данные тэга.

Parameters:

  • id (number) - ID тэга
  • data (object) - объект данных тэга

Returns:

  • result (promise) - промис (если выполнен), который возвращает ответ с сервера:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

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

Содержит URL сегмент и ID тэга.

  • Response from the server:

Сервер возвращает объект данных обновлённого тэга.

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

removeTag(id)

Удаляет тэг из списка.

Parameters:

  • id (number) - ID тэга

Returns:

  • result (promise) - промис (если выполнен), который возвращает ответ с сервера:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

  • Method: DELETE
  • URL example:
http://localhost:3200/tags/3

Содержит URL сегмент и id тэга.

getTags(id)

Метод возвращает промис с массивом всех тэгов файла или директории.

Parameters:

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

Returns:

  • tags (promise) - промис (если выполнен), который возвращает массив объектов тэгов (в случае отсутствия тэгов - пустой массив).

Request info:

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

Содержит URL сегмент и ID файла или директории.

  • Response from the server:

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

[
  4,2
]

setTags(id, value)

Метод сохраняет тэги файла.

Parameters:

  • id (string) - ID файла
  • value (string) - ID(s) тэга(ов)

Returns:

  • result (promise) - промис со следующими данными:
    • success: {};
    • error: {invalid: true, error:/* Error 500 message */}).

Request info:

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

Содержит URL сегмент.

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

Сервис Versions

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

url(path)

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

Parameters:

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

Returns:

  • url (string) - абсолютный путь.

versions(id)

Метод возвращает промис (если выполнен) с массивом всех версий файла.

Parameters:

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

Returns:

  • versions (promise) - промис (если выполнен) с массивом всех версий (пустым массивом, если файл не редактировался)

Request info:

  • Method: GET
  • URL example:
http://localhost:3200/versions?id=%2Fdocker-compose.yml
  • Response from the server:

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

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

readText(id, diff)

Метод возвращает промис (если выполнен) с HTML-строкой, которая содержит запрашиваемую версию файла.

Parameters:

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

Returns:

  • text (promise) - промис (если выполнен успешно) со сравнением версий файла (заданная и предыдущая)

Request info:

  • Method: GET
  • URL example:
http://localhost:3200/versions/20?mode=text&diff=true

Пример Form data:

mode: text
  • Response from the server:

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:

  • data (promise) - промис (если выполнен) с данными версии

Request info:

  • Method: POST
  • URL example:
http://localhost:3200/versions

Пример Form data:

id: /docker-compose.yml
version: 26
  • Response from the server:

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

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

directLink(id)

Метод возвращает URL запрос на версию Excel таблицы.

Parameters:

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

Returns:

  • url (string) - URL запрос на версию Excel таблицы.
Наверх