elFinder

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

{{>toc}}

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

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

Общие параметры, часто передаваемые коннектору:

* *current* : (String) hash пути текущей директории

* *target* : (String) hash пути файла над которым совержается действие

* *targets* : (Array) массив hash'ей путей файлов/директорий над которыми совершается действие

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

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

* *errorData* : (Object) объект с сообщениями о нефатальных ошибках, ключ - имя файла/директори, значение - сообщение об ошибке

* *select* : (Array) массив hash'ей файлов/директорий, которые необходимо выделить после выполнения команды (upload, mkdir, mkfile и т.д.)

* *debug* : (Object) объект с отладочной информацией

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

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

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

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

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

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) 

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

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

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

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

** *url* : (String) URL где расположен корень файлов коннектора

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

!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. Список команд

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 директории, в которую загружаем файлы

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

Ответ:

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

<pre><code class="json">

{

    "error" : "Unable to upload files"

}

</code></pre>

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

<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 директории, в которую перемещаем/копируем файлы

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

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

Ответ:

Если копирование/перемещение прошло успешно, возвращает [[Client-Server_Protocol_RU#open|open]] с деревом директорий, если нет, то к ответу добавляются сообдения об ошибках *error* и *errorData*

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

h3. rm

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

Аргументы:

* *cmd* : rm

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

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

Ответ: [[Client-Server_Protocol_RU#open|open]] с деревом директорий, при ошибках *error* и *errorData*.

h3. duplicate

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

Аргументы:

* *cmd* : duplicate

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

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

Ответ: [[Client-Server_Protocol_RU#open|open]] (если скопировали директорию, то open возвращается с деревом директорий), *select* - hash пути дубликата.

h3. read

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

Аргументы:

* *cmd* : edit

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

* *target* : hash файла

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

<pre><code class="json">

{

    "content": "Hello world!" // (String) содержимое текстового фала 

}

</code></pre>

h3. edit

Сохраняет полученный текст в файл.

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

* *cmd* : edit

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

* *target* : hash файла

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

Ответ: *file* - объект, аналогичный описывающему файл в секции _cdc_ команды [[Client-Server_Protocol_RU#open|open]]

<pre><code class="json">

{

    "file" : {

        "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

    }

}

</code></pre>

h3. extract

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

Аргументы:

* *cmd* : extract

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

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

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

h3. archive

Упаковывает директории/файлы в архив.

Аргументы:

* *cmd* : archive

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

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

* *targets* : массив хэшей директорий/файлов

Ответ: [[Client-Server_Protocol_RU#open|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 директории, в которой находится файл

* *target* : hash пути изображения

* *width* : новая ширина изображения

* *height* : новая высота изображения

Ответ: [[Client-Server_Protocol_RU#open|open]], *select* - hash пути изображения