elFinder

h1. Описание протокола клиент-сервер

{{>toc}}

_Коннектор (connector)_ - обрабатывается на сервере (PHP, Python). _Клиент (client)_ - обрабатывается на стороне пользователя в браузере (JavaScript). Когда пользователь выполняет какое-либо действие с файлами _клиент_ отправляет на сервер (в _коннектор_) запрос и получает ответ. _Коннектор_ получает данные от _клиента_ через GET или через POST (только при загрузке _upload_ и редактировании _edit_). _Коннектор_ всегда возвращает _клиенту_ объект JSON.

Обязятельный параметр, всегда ожидаемый коннектором - *cmd* - имя команды, пример: @http://localhost/connector.php?cmd=open@

Для любой команды ответ коннектора может содержать следующие параметры:

* *error* : Строка с сообщением об ошибке

* *errorData* : Массив с сообщениями о нефатальных ошибках

* *select* : массив хэшей файлов, которые необходимо выделить после перерисовки контента (upload, mkdir, mkfile и тд)

* *debug* : массив с отладочной информацией

Команды клиентской части не полностью совпадают с командами коннектора:

* *reload*, *back* - реализуются серверной командой *open*

* *list*, *icons*, *quicklook*, *copy*, *cut* - работают только на клиенте и не обращаются к коннектору

Любая команда, получившая некорректные аргументы, прекращает дальнейшее выполнение и возвращает *error* (сообщение об ошибке); исключение *open* - возвращает сообщение об ошибке и контент корневой директории.

*Внимание!* Пути к файлам не передаются в чистом виде, только hash от пути (md5 или любая другая hash-функция).

h2. Список команд

*open* - открыть директорию или вывести содержимое файла в браузер

*mkdir* - создать директорию

*mkfile* - создать текстовый файл

*rename* - переименовать директориб или файл

*upload* - загрузить файлы

*ping* - служебная команда. необходима для Safari (загрузка файлов)

*paste* - скопировать или переместить файлы/директории в указанную директорию

*rm* - удалить директорию/файлы

*duplicate* - сделать копию директории/файла

*read* - вернуть содержимое текстового файла

*edit* - сохранить текст в файл

*extract* - распаковать архив

*archive* - сжать директории/файлы в архив

*tmb* - создать превьюшки для картинок, не имеющих их

*resize* - изменить размер изображения

h2. Инициализация файлового менеджера

Аргументы передаваемые клиентом коннектору (клиент -> сервер):

* *cmd* : open

* *init* : true

* *tree* : true

Пример: @http://localhost:8001/~troex/cgi/connector.py?cmd=open&init=true&tree=true@

Ответ (сервер -> клиент): смотрите описание команды [[Client-Server_Protocol_RU#open|open]], плюс дополнительно ответ включает:

* *disabled* : (Array) список отключенных команд

* *params*: (Object) 

** *url*: (String) 

** *dotFiles* : (Boolean) разрешено ли показывать скрытые файлы, начинающиеся с точки

** *uplMaxSize* : (String) макимальный разрешенный размер загружаемых файлов (например: 128M)

** *archives* : (Array) Список mime-типов архивов, которые могут быть созданы коннектором

** *extract* : (Array) Список mime-типов архивов, которые коннектор может распаковать

Пример корректного ответа:

!elFinder-init.png!

JSON:

<pre><code class="json">

{

    "cwd": {

        "name"  : "Home",

        "hash"  : "b4473c8c08d1d499ecd7112f3398f125",

        "rel"   : "Home",

        "date"  : "30 Jan 2010 14:25",

        "mime"  : "directory",

        "size"  : 0,

        "read"  : true,

        "write" : true,

        "rm"    : false

    },

    "cdc": [

    {

        "name"  : "test",

        "hash"  : "ac4b61565950a73395c871f9c3fc7362",

        "date"  : "Today 14:11",

        "mime"  : "directory",

        "size"  : 102,

        "read"  : true,

        "write" : true,

        "rm"    : true

    },

    {

        "name"  : "link to README", 

        "hash"  : "4fc059e61577f0267fbd6c1c5bafb1b4", 

        "url"   : "http://localhost:8001/~troex/git/elfinder/files/wiki/README.txt", 

        "date"  : "Today 16:50", 

        "mime"  : "text/plain", 

        "size"  : 10, 

        "read"  : true, 

        "write" : true, 

        "rm"    : true, 

        "link"  : "8d331825ebfbe1ddae14d314bf81a712", 

        "linkTo": "Home/README.txt", 

        "parent": "b4473c8c08d1d499ecd7112f3398f125"

    }, 

    {

        "name"  : "logo.png", 

        "hash"  : "a696323d7fd86513754004ba8bc12967", 

        "url"   : "http://localhost:8001/~troex/git/elfinder/files/wiki/logo.png", 

        "date"  : "11 Nov 2009 21:57", 

        "mime"  : "image/png", 

        "size"  : 18782, 

        "read"  : true, 

        "write" : true, 

        "rm"    : true

    }, 

    {

        "name"  : "README.txt",

        "hash"  : "8d331825ebfbe1ddae14d314bf81a712",

        "url"   : "http://localhost:8001/~troex/git/elfinder/files/wiki/README.txt",

        "date"  : "Today 14:25",

        "mime"  : "text/plain",

        "size"  : 1171,

        "read"  : true,

        "write" : true,

        "rm"    : true

    }

    ],

    "tree": {

        "name"  : "Home",

        "hash"  : "b4473c8c08d1d499ecd7112f3398f125",

        "read"  : true,

        "write" : true,

        "dirs"  : [

        {

            "name"  : "test",

            "hash"  : "ac4b61565950a73395c871f9c3fc7362",

            "read"  : true,

            "write" : true,

            "dirs"  : [

            {

                "name"  : "test2",

                "hash"  : "b3615611cf9f8f6a8821ef20eda450b5",

                "read"  : true,

                "write" : true,

                "dirs"  : []

            }

            ]

        }

        ],

    },

    "disabled"  : [],

    "params"    : {

        "url"        : "http://localhost:8001/~troex/git/elfinder/files/wiki",

        "dotFiles"   : true,

        "uplMaxSize" : "15M",

        "extract"    : [

            "application/x-7z-compressed",

            "application/x-tar",

            "application/x-gzip",

            "application/x-bzip2",

            "application/zip"

        ],

        "archives"   : [

            "application/x-7z-compressed",

            "application/x-tar",

            "application/x-gzip",

            "application/x-bzip2",

            "application/zip"

        ]

    }

}

</code></pre>

h2. Описание команд

h3. open

Возвращает содержимое директории или выводит файл в браузер.

1. Открытие директории

Аргументы:

* *cmd* : open

* *target* : hash пути директории

* *tree* : Не обязательный параметр. Если задан - дополнительно вернуть дерево директорий

Ответ должен содержать (Object) _cwd_ и массив (Array) _cdc_, дополнительно может присутствовать (Object) _tree_, пример:

<pre><code class="json">

{

    "cwd" : { // (Object) Current Working Directory - Информация о текущей директории

        "name"  : "Home",                             // (String)  Имя директории

        "hash"  : "b4473c8c08d1d499ecd7112f3398f125", // (String)  hash от абсолютного пути файла на сервере

        "mime"  : "directory",                        // (String)  всегда "directory"

        "rel"   : "Home",                             // (String)  относительный путь до текущей директории

        "size"  : 0,                                  // (Number)  размер директории в байтах

        "date"  : "30 Jan 2010 14:25",                // (String)  время изменения (mtime)

        "read"  : true,                               // (Boolean) право на чтение

        "write" : true,                               // (Boolean) право на запись

        "rm"    : false                               // (Boolean) право на удаление

    },

    "cdc" : [ // (Array) (of Objects) Current Directory Content - Информация о содержимом текущей директории

    {

        "name"  : "link to README",                   // (String)  Имя директории/файла

        "hash"  : "4fc059e61577f0267fbd6c1c5bafb1b4", // (String)  hash

        "url"   : "http://localhost:8001/~troex/git/elfinder/files/wiki/README.txt", // (String) URL

        "date"  : "Today 16:50",                      // (String)  время изменения (mtime)

        "mime"  : "text/plain",                       // (String)  MIME тип файла или "directory"

        "size"  : 10,                                 // (Number)  размер директории в байтах

        "read"  : true,                               // (Boolean) право на чтение

        "write" : true,                               // (Boolean) право на запись

        "rm"    : true,                               // (Boolean) право на удаление

        "link"  : "8d331825ebfbe1ddae14d314bf81a712", // (String)  только для ссылок, hash файла

                                                      //           на который ведёт ссылка

        "linkTo": "Home/README.txt",                  // (String)  только для ссылок, относительный путь

                                                      //           до файла, на который указывает ссылка

        "parent": "b4473c8c08d1d499ecd7112f3398f125"  // (String)  только для ссылок, hash директории

                                                      //           в который находиться файл, на который

                                                      //           указывает ссылка

    },

    {

        // ...

    }

    ],

    "tree" : { // (Object) Дерево директорий. Не обязательный параметр, только если был передан аргумент "tree"

	    "name"  : "Home",                             // (String)  Имя директории

        "hash"  : "b4473c8c08d1d499ecd7112f3398f125", // (String)  hash

        "read"  : true,                               // (Boolean) право на чтение

        "write" : true,                               // (Boolean) право на запись

        "dirs"  : [                                   // (Array) (of Objects) массив дочерних директории

        {

            "name"  : "test",

            "hash"  : "ac4b61565950a73395c871f9c3fc7362",

            "read"  : true,

            "write" : true,

            "dirs"  : [

            {

                // ...

            },

            {

                // ...

            }

            ]

        }

    }

}

</code></pre>

*Внимание!* Если передан некорректный аргумент *target*, возвращает контент корневой директории (_cdc, cdw_) и сообщение об ошибке (_error_).

2. Открытие файла (вывод содержимого в браузер).

Аргументы:

* *cmd* : open

* *target* : hash пути файла

* *current* : hash пути к директории, где находится файл

Ответ:

Файл выводится в браузер с соответствующими заголовками.

h3. mkdir

Создать новую папку.

Аргументы:

* *cmd* : mkdir

* *current* : hash директории, в которой создаем новую директорию

* *name* : имя новой директории

Ответ: [[Client-Server_Protocol_RU#open|open]] с деревом директорий _tree_ и

* *select* : hash новой директории

<pre><code class="json">

{

    // open

    "cwd"   : {

        // ...

    },

    "cdc"   : [

        // ...

    ],

    "tree"  : {

        // ...

    },

    "select": "ac4b61565950a73395c871f9c3fc7362" // (String) hash новой директории

}

</code></pre>

h3. mkfile

Создать новый файл.

Аргументы:

* *cmd* : mkfile

* *current* : hash директории, в которой создаем файл

* *name* : имя нового файла

Ответ: [[Client-Server_Protocol_RU#open|open]] и

* *select* : hash нового файла

h3. rename

Переименование директории/файла

Аргументы:

* *cmd* : rename

* *current* : hash директории, где файл находится

* *target* : hash директории/файла для переименования

* *name* : новое имя директории/файла

Ответ: [[Client-Server_Protocol_RU#open|open]], если переименовали директорию по open возвращается с деревом директорий

*select* : hash переименованной директории/файла

h3. upload

Загрузка файлов

Аргументы (передаются методом POST):

* *cmd* : upload

* *current* : hash директории, в которую загружаем файлы

* *files* : массив файлов

Ответ:

1. Если ни одного файла не удалось загрузить, возвращаем только

<pre><code class="json">

{

    "error" : "Unable to upload files"

}

</code></pre>

2. Если хотя бы один файл был загружен, ответ [[Client-Server_Protocol_RU#open|open]] и

<pre><code class="json">

{

    // open

    "select"    : [ "8d331825ebfbe1ddae14d314bf81a712" ], // (Array)  массив hash'ей путей загруженных файлов

    "error"     : "Some files was not uploaded",          // (String) если не все файлы были загружены

    "errorData" : {                                       // (Object) инф. о файлах, которые не удалось загрузить

        "some-file.exe" : "Not allowed file type"         // (String) "имя файла": "ошибка"

    }

}

</code></pre>

h3. ping

Служебная команда, необходима для исправления бага Safari при загрузке файлов http://www.webmasterworld.com/macintosh_webmaster/3300569.htm

Аргументы:

* *cmd* : ping

Ответ: отсылает пустую страницу с заголовком @Connection: close@

h3. paste

Копирует или перемещает директории/файлы

Аргументы:

* *cmd* : paste

* *src* : hash директории, из которой перемещаем/копируем файлы

* *dst* : hash директории, в которую перемещаем/копируем файлы

* *files* : массив hash'ей копируемых директорий/файлов

* *cut* : true если файлы перемещаются, false или аргумент отсутствует если файлы копируются

Ответ:

1. Если не удалось скопировать/переместить хотя бы один файл:

* *error* : сообщение об ошибке

2. Если копирование/перемещение прошло успешно, возвращает [[Client-Server_Protocol_RU#open|open]] с деревом директорий.

*Внимание!* Команда должна прекращать копирование при первой же ошибке. Не допускается перезапись файлов/директорий с одинаковыми именами.

h3. rm

Удаление файлов и рекурсивное удаление директорий

Аргументы:

* *cmd* : rm

* *current* : hash папки, из которой удалем файлы

* *rm* : массив hash'ей удаляемых папок/файлов

Ответ:

Всегда такой же как у open, плюс

tree : дерево директорий

error : "Unable to remove file", //если была ошибка удаления

errorData : {} //если была ошибка удаления - инф о файлах, который не удалось удалить (аналогично ошибке в upload)

h3. duplicate

Создает копию папки/файла. Имя копии формируется следующим образом: базовое_имя_файла copy+порядковый номер.расширение(если есть)

Аргументы:

* *cmd* : duplicate

* *current* : hash папки, в которой создаем дубликат

* *file* : hash папки/файла, для которого создаем дубликат

Ответ:

tree : дерево директорий, // если создали дубликат для папки

select : hash пути дубликата

h3. read

возвращает содержимое текстового файла.

Аргументы:

* *cmd* : edit

* *current* : hash папки, в которой читаем файл

* *file* : hash файла

Ответ:

content : содержимое текстового файла

h3. edit

сохраняет текст в файл

Аргументы (передаются методом POST):

* *cmd* : edit

* *current* : hash папки, в которой сохраняем файл

* *file* : hash файла

* *content* : новое содержимое файла

Ответ:

file : {// объект, аналогичный объекту, описывающему файл в cdc команды open

  'name'  : Имя файла,

  'hash'  : hash пути,

  'mime'  : mime-тип

  'date'  : отформатированая дата изменения файла, 

  'size'  : размер,

  'read'  : права на чтение,

  'write' : права на запись,

  'rm'    : права для удаления,

  'resize' : true (только для картинок, которые можно ресайзить)

}

h3. extract

распаковывает архив

Аргументы:

* *cmd* : extract

* *current* : hash папки, в которой находится файл

* *target* : hash файла архива

Ответ:

Такой же как у команды open, плюс

tree : дерево директорий

h3. archive

упаковывает папки/файлы в архив

Аргументы:

* *cmd* : archive

* *type* : mime-тип создаваемого архива

* *current* : hash папки, в которой находятся добавляемые в архив папки/файлы

* *files* : массив хэшей папок/файлов

Ответ:

Такой же как у команды open, плюс

* *select* : hash нового архива

h3. tmb

Фоновая команда. Создает миниатюрки для картинок, не имеющих их. Кол-во создаваемых за раз миниатюрок, указывается в [[Connector_Configuration_RU|конфиге коннектора]] опцией _tmbAtOnce_. По умолчанию - 5.

Аргументы:

* *cmd* : tmb

* *current* : hash пути к директории, в которой создаем миниатюрки

Ответ:

<pre><code class="json">

{

    "current": "b4473c8c08d1d499ecd7112f3398f125", // (String) hash пути к директории, в которой были созданы миниатюрки

    "images" : {                                   // (Object)

        "a696323d7fd86513754004ba8bc12967":        // (String) hash пути файла

            "http://localhost:8001/~troex/git/elfinder/files/.tmb/a696323d7fd86513754004ba8bc12967.png"

                                                   // (String) URL миниатюрки

    }, 

    "tmb": true  // (Boolean) возвращает true если ещё остались картинки для которых не были созданы миниатюрки,

                 // иначе параметр отсутствует

}

</code></pre>

h3. resize

изменяет размер изображения

Аргументы:

* *cmd* : resize

* *current* : hash папки, в которой находится файл

* *file* : hash пути картинки

* *width* : новая ширина картинки

* *height* : новая высота картинки

Ответ:

Такой же как у команды open