Client-Server protocol API 1.x¶
Connector is server-side script (PHP, Python). Client is user-side script witch works in a browser (JavaScript). When user makes any actions with files client sends request to the server (connector) and gets response. Connector receive data from client using GET or POST (only when upload and edit) request. Connector always return JSON object to client.
Only always required parameter for connector is cmd - name of the command: http://localhost/connector.php?cmd=open
- current : (String) hash from the path of a current working directory
- target : (String) hash from the path to a file that take action
- targets : (Array) array of hashes of files/directories which take action
- error : (String) string containing error message
- errorData : (Object) object with non-fatal errors, keys - filenames, values - error message
- select : (Array) array of hashes of files/directories which will be selected after action by client (upload, mkdir, mkfile и т.д.)
- debug : (Object) object contains debug information
- reload, back client commands use connector command open
- list, icons, quicklook, copy, cut client commands work without request to connector
Any connector command which get invalid argument from client stops it execution and returns error message, except open command which returns error message and contents ot root directory.
Important! paths to files are not send in plain text, they are encoded using hash function from path (md5 or any other hash-function).
File manager initialization¶
Arguments sent by client to connector (client -> server):- cmd : open
- init : true
- tree : true
Example: http://localhost:8001/~troex/cgi/connector.py?cmd=open&init=true&tree=true
Response (server -> client): see open command description, additionally response contains:
- disabled : (Array) list of disabled commands
- params: (Object)
- dotFiles : (Boolean) allow hidden files begining with dot
- uplMaxSize : (String) max upload size (example: 128M)
- archives : (Array) list of mime-type archives which can be created by connector
- extract : (Array) list of mime-type archives which connector can extract
- url : (String) URL where file root is located
Example of correct answer:
JSON:
1 {
2 "cwd": {
3 "name" : "Home",
4 "hash" : "b4473c8c08d1d499ecd7112f3398f125",
5 "rel" : "Home",
6 "date" : "30 Jan 2010 14:25",
7 "mime" : "directory",
8 "size" : 0,
9 "read" : true,
10 "write" : true,
11 "rm" : false
12 },
13 "cdc": [
14 {
15 "name" : "test",
16 "hash" : "ac4b61565950a73395c871f9c3fc7362",
17 "date" : "Today 14:11",
18 "mime" : "directory",
19 "size" : 102,
20 "read" : true,
21 "write" : true,
22 "rm" : true
23 },
24 {
25 "name" : "link to README",
26 "hash" : "4fc059e61577f0267fbd6c1c5bafb1b4",
27 "url" : "http://localhost:8001/~troex/git/elfinder/files/wiki/README.txt",
28 "date" : "Today 16:50",
29 "mime" : "text/plain",
30 "size" : 10,
31 "read" : true,
32 "write" : true,
33 "rm" : true,
34 "link" : "8d331825ebfbe1ddae14d314bf81a712",
35 "linkTo": "Home/README.txt",
36 "parent": "b4473c8c08d1d499ecd7112f3398f125"
37 },
38 {
39 "name" : "logo.png",
40 "hash" : "a696323d7fd86513754004ba8bc12967",
41 "url" : "http://localhost:8001/~troex/git/elfinder/files/wiki/logo.png",
42 "date" : "11 Nov 2009 21:57",
43 "mime" : "image/png",
44 "size" : 18782,
45 "read" : true,
46 "write" : true,
47 "rm" : true,
48 "resize": true,
49 "dim" : "200x150",
50 "tmb" : "http://localhost:8001/~troex/git/elfinder/.tmb/a696323d7fd86513754004ba8bc12967.png"
51 },
52 {
53 "name" : "README.txt",
54 "hash" : "8d331825ebfbe1ddae14d314bf81a712",
55 "url" : "http://localhost:8001/~troex/git/elfinder/files/wiki/README.txt",
56 "date" : "Today 14:25",
57 "mime" : "text/plain",
58 "size" : 1171,
59 "read" : true,
60 "write" : true,
61 "rm" : true
62 }
63 ],
64 "tree": {
65 "name" : "Home",
66 "hash" : "b4473c8c08d1d499ecd7112f3398f125",
67 "read" : true,
68 "write" : true,
69 "dirs" : [
70 {
71 "name" : "test",
72 "hash" : "ac4b61565950a73395c871f9c3fc7362",
73 "read" : true,
74 "write" : true,
75 "dirs" : [
76 {
77 "name" : "test2",
78 "hash" : "b3615611cf9f8f6a8821ef20eda450b5",
79 "read" : true,
80 "write" : true,
81 "dirs" : []
82 }
83 ]
84 }
85 ],
86 },
87 "disabled" : [],
88 "params" : {
89 "url" : "http://localhost:8001/~troex/git/elfinder/files/wiki",
90 "dotFiles" : true,
91 "uplMaxSize" : "15M",
92 "extract" : [
93 "application/x-7z-compressed",
94 "application/x-tar",
95 "application/x-gzip",
96 "application/x-bzip2",
97 "application/zip"
98 ],
99 "archives" : [
100 "application/x-7z-compressed",
101 "application/x-tar",
102 "application/x-gzip",
103 "application/x-bzip2",
104 "application/zip"
105 ]
106 }
107 }
Command list¶
open - open directory or send file to browser
mkdir - create new directory
mkfile - create new text file
rename - rename directory or file
upload - upload files
ping - service command, needed for Safari (file upload)
paste - make a copy or move files/directories to selected destination
rm - delete files/directories
duplicate - duplicate file/directory
read - get text file content
edit - save text file content
extract - extract archive
archive - compress files/directories into archive
tmb - create thumbnails for images that don't have them
resize - resize image
Command description¶
open¶
Open directory or send file to browser.
1. Directory open
Arguments:- cmd : open
- target : hash of directory to open
- tree : Optional argument, if set additionally include file tree in response
Response must contain (Object) cwd and (Array) cdc, additionally can contain (Object) tree and/or (Boolean) tmb, example:
1 {
2 "cwd" : { // (Object) Current Working Directory - information about current directory
3 "name" : "Home", // (String) directory name
4 "hash" : "b4473c8c08d1d499ecd7112f3398f125", // (String) hash from absolute path to current dir
5 "mime" : "directory", // (String) always set to "directory"
6 "rel" : "Home", // (String) relative path to current directory
7 "size" : 0, // (Number) directory size in bytes
8 "date" : "30 Jan 2010 14:25", // (String) modification time (mtime)
9 "read" : true, // (Boolean) read access
10 "write" : true, // (Boolean) write access
11 "rm" : false // (Boolean) delete access
12 },
13 "cdc" : [ // (Array) (of Objects) Current Directory Content - info about current dir content
14 {
15 "name" : "link to README", // (String) file/dir name
16 "hash" : "4fc059e61577f0267fbd6c1c5bafb1b4", // (String) hash
17 "url" : "http://localhost:8001/~troex/git/elfinder/files/wiki/README.txt", // (String) URL
18 "date" : "Today 16:50", // (String) modification time (mtime)
19 "mime" : "text/plain", // (String) MIME-type of file or "directory"
20 "size" : 10, // (Number) file/dir size in bytes
21 "read" : true, // (Boolean) read access
22 "write" : true, // (Boolean) write access
23 "rm" : true, // (Boolean) delete access
24 "link" : "8d331825ebfbe1ddae14d314bf81a712", // (String) only for links, hash of file to
25 // which point link
26 "linkTo": "Home/README.txt", // (String) only for links, relative path to
27 // file on which points links
28 "parent": "b4473c8c08d1d499ecd7112f3398f125", // (String) only for links, hash of directory
29 // in which is linked file is located
30 "resize": true, // (Boolean) only for images, if true will
31 // enable Resize contextual menu
32 "dim" : "600x400", // (String) only for images, dimension of image
33 // must be set if resize is set to true.
34 "tmb" : "http://localhost:8001/~troex/git/elfinder/files/.tmb/4fc059e61577f0267fbd6c1c5bafb1b4.png"
35 // (String) only for images
36 // URL to thumbnail
37 },
38 {
39 // ...
40 }
41 ],
42 "tree" : { // (Object) directory tree. Optional parameter, only if "tree" was requested
43 "name" : "Home", // (String) dir name
44 "hash" : "b4473c8c08d1d499ecd7112f3398f125", // (String) hash
45 "read" : true, // (Boolean) read access
46 "write" : true, // (Boolean) write access
47 "dirs" : [ // (Array) (of Objects) array of child directories
48 {
49 "name" : "test",
50 "hash" : "ac4b61565950a73395c871f9c3fc7362",
51 "read" : true,
52 "write" : true,
53 "dirs" : [
54 {
55 // ...
56 },
57 {
58 // ...
59 }
60 ]
61 }
62 },
63 "tmb" : true // (Boolean) Optional parameter, if true, will cause client to initiate _tmb_ commands.
64
65 }
- Important!* if invalid target argument was requestd, connector will root directory content (cdc, cdw) and error message (error).
2. File open (send file contents to browser).
Аргументы:- cmd : open
- target : hash of file
- current : hash of current directory where file is located
Response:
File must be send to browser with valid headers.
mkdir¶
Create new directory.
Arguments:- cmd : mkdir
- current : hash of current directory where new directory will be created
- name : name of new directory
Response: open with directory tree and select - hash of new directory
1 {
2 // open
3 "cwd" : {
4 // ...
5 },
6 "cdc" : [
7 // ...
8 ],
9 "tree" : {
10 // ...
11 },
12 "select": [ "ac4b61565950a73395c871f9c3fc7362" ] // (String) hash of new directory
13 }
mkfile¶
Create new text file.
Arguments:- cmd : mkfile
- current : hash of current directory where new file will be created
- name : name of new file
Response: open and select - hash of new file
rename¶
Rename file/directory.
Arguments:- cmd : rename
- current : hash of directory where file is located
- target : hash of file/directory which to rename
- name : new name
Response: open (if directory was renamed then return open with tree) and select - hash of renamed file/directory
upload¶
File upload.
Arguments (send using POST):- cmd : upload
- current : hash of directory where to upload files
- upload : array of files to upload (upload[])
Response:
1. If no files where uploaded return:
1 {
2 "error" : "Unable to upload files"
3 }
2. If at least one file was uploaded response with open and select. If some files failed to upload append error and errorData:
1 {
2 // open
3 "select" : [ "8d331825ebfbe1ddae14d314bf81a712" ], // (Array) array of hashes of files that were uploaded
4 "error" : "Some files was not uploaded", // (String) return if not all files where uploaded
5 "errorData" : { // (Object) warnings which files were not uploaded
6 "some-file.exe" : "Not allowed file type" // (String) "file name": "error"
7 }
8 }
ping¶
Service command needed to workaround Safari bug while uploading http://www.webmasterworld.com/macintosh_webmaster/3300569.htm
Arguments:- cmd : ping
Response: send empty page with headers Connection: close
paste¶
Copy or move file/directory.
Arguments:- cmd : paste
- src : hash of source directory where files/directories which to copy is located
- dst : hash of destination directory where to copy
- targets : array of hashes copied files/directories
- cut : 1 if you move or not set if copy
Response:
If copy/move was successful response open with file tree. If some files/directories were not copied or moved than add error and errorData to response.
Important! Command must stop execution if any error occurred. It is not allowed to rewrite files/directories with the same names.
rm¶
Delete file or directory (recursive).
Arguments:- cmd : rm
- current : hash of directory from where to delete
- targets : array of hashes of files/directories to delete
Response: open with directory tree, on errors add error and errorData.
duplicate¶
Create copy of file/directory. Name of the copy must be unique and formed next way (basename + " copy NUM" + ext):- readme.txt
- readme copy.txt
- readme copy 1.txt
- readme copy 2.txt
- cmd : duplicate
- current : hash of directory where to make a copy
- target : hash of file/directory which to copy
Response: open (if directory was duplicated response open with tree), select - hash of duplicated object.
read¶
Read text file and response with its contents.
Arguments:- cmd : read
- current : hash of directory in which file is located
- target : hash of the file
Response: content - content of the file
1 {
2 "content": "Hello world!" // (String) file content
3 }
edit¶
Save submitted text to file.
Arguments (send using POST):- cmd : edit
- current : hash of directory where to save file
- target : hash of file in which content will be saved
- content : new content of the file
Response: file - object the same as cdc object in open command
1 {
2 "file" : {
3 "name" : "README.txt",
4 "hash" : "8d331825ebfbe1ddae14d314bf81a712",
5 "url" : "http://localhost:8001/~troex/git/elfinder/files/wiki/README.txt",
6 "date" : "Today 14:25",
7 "mime" : "text/plain",
8 "size" : 1171,
9 "read" : true,
10 "write" : true,
11 "rm" : true
12 }
13 }
extract¶
Extract archive.
Arguments:- cmd : extract
- current : hash of directory where archive is located
- target : hash of archive
Response: open with directory tree
archive¶
Create archive from files/directories.
Arguments:- cmd : archive
- type : mime-type of archive to create
- current : hash of directory where files/directories that we add to archive is located
- targets : array of hashes of files/directories to add to archive
Response: open, select - hash of new archive
tmb¶
Background command. Creates thumbnails for images that don't have them yet. Amount of thumbnails to create per request is configured in connector with option tmbAtOnce. By default - 5.
Arguments:- cmd : tmb
- current : hash of directory where images don't have thumbnails yet
Response:
1 {
2 "current": "b4473c8c08d1d499ecd7112f3398f125", // (String) hash of directory for which thumbnails were created
3 "images" : { // (Object)
4 "a696323d7fd86513754004ba8bc12967": // (String) hash of image path
5 "http://localhost:8001/~troex/git/elfinder/files/.tmb/a696323d7fd86513754004ba8bc12967.png"
6 // (String) thumbnail URL
7 },
8 "tmb": true // (Boolean) true if more thumbnails can be created in current directory
9 // or not set if all images have thumbnails
10 }
resize¶
Resize image.
Arguments:- cmd : resize
- current : hash of directory where image is located
- target : hash of image path
- width : new width for image
- height : new height for image
Response: open, select - hash of image path.
In order for the contextual menu Resize to appear for a given file, its cdc entry must contain both resize and dim. resize must be set to true and dim must be a string containing the file's width and height (eg. "600x400"). If resize is specified without dim the contextual menu will appear, but will not function correctly.
