-
Notifications
You must be signed in to change notification settings - Fork 0
Rich Filemanager was designed to make possible a flexible integration with any of server-side programming language via connectors. Each connector should implement methods of this API, described below. You can find some connectors already implemented, but since many changes have been done recently, only PHP connector is the only actual connector currently.
The entry point is a script at the following location which can respond to HTTP GET requests by returning an appropriate JSON object:
[path to FileManager]/connectors/[language extension]/filemanager.[language extension]
Rich Filemanager currently includes connectors for PHP, MVC, JSP, lasso, ASP, ASHX, PL and CFM in the following locations:
PHP: .../connectors/php/filemanager.php
ASP.NET MVC Framework .../connectors/mvc/FilemanagerController.cs
JSP: .../connectors/jsp/filemanager.jsp
lasso: .../connectors/lasso/filemanager.lasso
ASP: .../connectors/asp/filemanager.asp
ASHX: .../connectors/ashx/filemanager.asp
PL: .../connectors/pl/filemanager.pl
CFM: .../connectors/cfm/filemanager.cfm
As long as a script exists at this location to respond to requests, you may split up the code (external libraries, configuration files, etc.) however you see fit.
Every response should include two keys specific to error handling: Error and Code. If an error occurs in your script, you may populate these keys with whatever values you feel are most appropriate. If there is no error, Error should remain empty or null, and Code should be empty, null, or zero (0). Do not use zero for any actual errors. The following example would be an appropriate response if the connector uses an external file for configuration (recommended), but that file cannot be found:
{
"Error": "Configuration file missing.",
"Code": -1
}Your script should include support for the following methods/functions. GET requests from Rich Filemanager include a parameter "mode" which will indicate which type of response to return. Additional parameters will provide other information required to fulfill the request, such as the current directory.
Every request will have the following parameters. mode -> this indicates the endpoint config -> this is the ui config filename time -> this is the time of the request
The getfile method returns information about a single file.
Requests with mode "getfile" will include an additional parameter, "path", indicating which file to inspect.
Example URL:
[path to connector]?mode=getfile&path=/images/logo.png&config=filemanager.config.json&time=1471269225715
Example Request:
{
mode: 'getfile',
path: '/chm.png',
config: 'filemanager.config.json',
time: '1471269385831'
}Example Response:
{
"Path": "/images/logo.png",
"Filename": "logo.png",
"File Type": "png",
"Protected": 0,
"PreviewPath": "/userfiles/images/logo.png",
"Properties": {
"Date Created": null,
"Date Modified": "02/09/2007 14:01:06",
"filemtime": 1360237058,
"Height": 14,
"Width": 14,
"Size": 384
},
"Error": "",
"Code": 0
}The keys are as follows:
Path: Relative path to the file.
Filename: The name of the file, i.e., the last part of the path.
File Type: The file extension, "dir" if a directory, or "txt" if missing/unknown.
Protected: Indicates if the file has some reading / writing restrictions. If not, set to 0. Else set to 1.
PreviewPath: Relative path to the file prefixed with the userfiles root folder. Used for building absolute path to preview images and media files.
Properties: A nested JSON object containing specific properties of the file.
Date Created: The file's creation date, if available.
Date Modified: The file's modification date, if available.
filemtime: The file's modification timestamp, if available.
Height: If an image, the height in pixels.
Width: If an image, the width in pixels.
Size: The file size in bytes.
Capabilities (optional): You can limit the operation buttons shown for a specific file. It is an array containing ['select','delete','rename','download'] (for all capabilities), or [] (for no capabilities). If not present, all capabilities are enabled.
Error: An error message, or empty/null if there was no error.
Code: An error code, or 0 if there was no error.
The getfolder method returns an array of file and folder objects representing the contents of the given directory (indicated by a "path" parameter). It should call the getfile method to retrieve the properties of each file.
Optionally a "type" parameter can be specified to restrict returned files (depending on the connector). If a "type" parameter is given for the main index.html URL, the same parameter value is reused and passed to getfolder. This can be used for example to only show image files in a file system tree.
Example URL:
[path to connector]?mode=getfolder&path=/&getsizes=true&type=images&showThumbs=true&config=filemanager.config.json&time=1471269814932
Example Request:
{
mode: 'getfolder',
path: '/',
type: 'images',
showThumbs: 'true',
config: 'filemanager.config.json',
time: '1471269814932'
}Example Response:
{
"/music/audio.mp3": {
"Path": "/music/audio.mp3",
"Filename": "audio.mp3",
"File Type": "mp3",
"Protected": 0,
"PreviewPath": "/userfiles/music/audio.mp3",
"Properties": {
"Date Created": null,
"Date Modified": "05/05/2016 11:38:42",
"filemtime": 1462441126,
"Height": 0,
"Width": 0,
"Size": 384
},
"Error": "",
"Code": 0
},
"/images/logo.png": {
"Path": "/images/logo.png",
"Filename": "logo.png",
"File Type": "png",
"Protected": 0,
"PreviewPath": "/userfiles/images/logo.png",
"Properties": {
"Date Created": null,
"Date Modified": "05/05/2016 11:38:42",
"filemtime": 1462441126,
"Height": 14,
"Width": 14,
"Size": 384
},
"Error": "",
"Code": 0
},
"/folder/": {
"Path": "/folder/",
"Filename": "folder",
"File Type": "dir",
"Protected": 0,
"PreviewPath": "/userfiles/folder/",
"Properties": {
"Date Created": null,
"Date Modified": "05/05/2016 11:38:42",
"filemtime": 1462441126,
"Height": 0,
"Width": 0,
"Size": 0
},
"Error": "",
"Code": 0
}
}This is not an array, it is a JSON object were the path to an individual item is the key, and the value is the file object for that item.
The upload method uploads the file to the specified path. The upload form in the File Manager passes the current path as a POST param along with the uploaded file. The response includes the path as well as the name used to store the file. The uploaded file's name should be safe to use as a path component in a URL, so URL-encoded at a minimum.
Example URL:
[path to connector]?config=filemanager.config.json&time=1471269814932
Example Request:
{
mode: 'upload',
currentpath: '/images/',
config: 'filemanager.config.json',
time: '1471269814932'
}The file comes across as a posted file, in the nodejs api, multer parses this if you would like to see an example. The name of the form element is "files[]".
Example Response: See https://github.com/blueimp/jQuery-File-Upload/wiki/JSON-Response
The addfolder method creates a new directory on the server within the given path.
Example URL:
[path to connector]?mode=addfolder&path=/&name=new_folder&config=filemanager.config.json&time=1471269814932
Example Request:
{
mode: 'addfolder',
path: '/',
name: 'new_folder',
config: 'filemanager.config.json',
time: '1471269814932'
}Example Response:
{
"Parent": "/",
"Name": "newfolder",
"Error": "",
"Code": 0
}The rename method renames the item at the path given in the "old" parameter with the name given in the "new" parameter and returns an object indicating the results of that action.
Example URL:
[path to connector]?mode=rename&old=/images/logo.png&new=newlogo.png&config=filemanager.config.json&time=1471269814932
Example Request:
{
mode: 'rename',
old: '/images/logo.png',
new: 'newlogo.png',
config: 'filemanager.config.json',
time: '1471269814932'
}Example Response:
{
"Old Path": "/images/logo.png",
"Old Name": "logo.png",
"New Path": "/images/newlogo.png",
"New Name": "newlogo.png",
"Error": "",
"Code": 0
}The move method move "old" file or directory to specified "new" directory. It is possible to specify absolute path from fileRoot dir or relative path from "old" item. "root" value is mandatory to secure that relative paths don't get above fileRoot.
MOVE FILE:
Example URL:
[path to connector]?mode=move&old=/images/original/logo.png&new=/images/moved/&config=filemanager.config.json&time=1471269814932
Example Request:
{
mode: 'move',
old: '/images/original/logo.png',
new: '/images/moved/',
config: 'filemanager.config.json',
time: '1471269814932'
}Example Response:
{
"Old Path": "/uploads/images/original/",
"Old Name": "logo.png",
"New Path": "/uploads/images/moved/",
"New Name": "logo.png",
"Error": "",
"Code": 0
}MOVE DIRECTORY - no filename in 'old' request param:
Example URL:
[path to connector]?mode=move&old=/images/&new=/shared/&config=filemanager.config.json&time=1471269814932
Example Request:
{
mode: 'move',
old: '/images/',
new: '/shared/',
config: 'filemanager.config.json',
time: '1471269814932'
}Example Response:
{
"Old Path": "/uploads/images/original/",
"Old Name": "Image",
"New Path": "/uploads/new_dir/",
"New Name": "Image",
"Error": "",
"Code": 0
}The replace method allow the user to replace a specific file whatever the new filename - at least, the new file should have the same extension the original has. The old file is automatically overwritten. Unlike the other methods, this method must return its JSON response wrapped in an HTML <textarea>, so the MIME type of the response is text/html instead of text/plain. The dynamic upload form in the File Manager passes the current file path as a POST param along with the uploaded file. The response includes the path as well as the name used to store the file.
Example URL:
[path to connector]?config=filemanager.config.json&time=1471269814932
Example Request:
{
mode: 'replace',
newfilepath: '/file_to_replace.txt',
config: 'filemanager.config.json',
time: '1471269814932'
}Example Response: See https://github.com/blueimp/jQuery-File-Upload/wiki/JSON-Response
The editfile method returns the content of a given file (passed as parameter). It gives the user the ability to edit a file online (extensions are specified in configuration file). Handled as GET request.
Example URL:
[path to connector]?mode=editfile&path=/editable.txt&config=filemanager.config.json&time=1471269814932
Example Request:
{
mode: 'editfile',
path: '/editable.txt',
config: 'filemanager.config.json',
time: '1471269814932'
}Example Response:
{
"Path": "/editable.txt",
"Content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.\r\n\Phasellus eu erat lorem.\r\n\r\n\Bye!",
"Error": "",
"Code": 0
}The savefile method will overwrite the content of the current file. The edit form in the File Manager passes the mode (as savefile), path of the current file and the content as POST parameters.
Example URL:
[path to connector]?config=filemanager.config.json&time=1471269814932
Example Request:
{
content: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.\r\n\Phasellus eu erat lorem.\r\n\r\n\Bye!",
mode: 'savefile',
path: '/editable.txt',
config: 'filemanager.config.json',
time: '1471269814932'
}Example Response:
{
"Path": "/editable.txt",
"Error": "",
"Code": 0
}The delete method deletes the item at the given path.
Example URL:
[path to connector]?mode=delete&path=/images/logo.png&config=filemanager.config.json&time=1471269814932
Example Request:
{
mode: 'delete',
path: '/images/logo.png',
config: 'filemanager.config.json',
time: '1471269814932'
}Example Response:
{
"Path": "/images/logo.png",
"Error": "",
"Code": 0
}The summarize method serves to display storage (root path) summarize info:
- Total size used (in Bytes)
- Number of files
- Number of folders (optional)
Example URL:
[path to connector]?mode=summarize&config=filemanager.config.json&time=1471269814932
Example Request:
{
mode: 'summarize',
config: 'filemanager.config.json',
time: '1471269814932'
}Example Response:
{
"Size": 25167913,
"Files": 25,
"Folders": 4,
"Error": "",
"Code": 0
}The getimage method serves the requested image for displaying. The image path is passed through the path parameter. If thumbnail=true parameter is passed, the method will return an image thumbnail. An extra parameter such as UNIX time can be added to the URL to prevent cache issue.
Example URL:
[path to connector]?mode=getimage&path=/images/logo.png&thumbnail=true&config=filemanager.config.json&time=1471269814932
Example Request:
{
mode: 'getimage',
path: '/images/logo.png',
thumbnail: 'true',
config: 'filemanager.config.json',
time: '1471269814932'
}Response is a body content of the requested image.
The download method serves the requested file to the user. We currently use a MIME type of "application/x-download" to force the file to be downloaded rather than displayed in a browser. In the future we may make exceptions for specific file types that often have in-browser viewers such as PDF's and various movie formats (Flash, Quicktime, etc.).
The download will make two requests, the first one will need only a success response if the file exists, the second will contain the force=true query parameter, and this request is when you actually return the file.
Example URL 1:
[path to connector]?mode=download&path=/images/logo.png&config=filemanager.config.json&time=1471269814932
Example Request 1:
{
mode: 'download',
path: '/images/logo.png',
config: 'filemanager.config.json',
time: '1471269814932'
}Example Response 1:
{
"Error": "",
"Code": 0
}Example URL 2:
[path to connector]?mode=download&path=/images/logo.png&force=true&config=filemanager.config.json&time=1471269814932
Example Request 2:
{
mode: 'download',
path: '/images/logo.png',
force: 'true',
config: 'filemanager.config.json',
time: '1471269814932'
}Response 2 is a body content of the requested file.
The readfile method outputs the content of requested file to browser. Intended to use when it's not possible to get file by direct URL (e.g. protected file). Initially implemented for viewing audio/video/docs/pdf and other files hosted on AWS S3 remote server.
Example URL:
[path to connector]?mode=readfile&path=/manual.pdf&config=filemanager.config.json&time=1471281172178
{
mode: 'readfile',
path: '/manual.pdf',
config: 'filemanager.config.json',
time: '1471269814932'
}Response is a body content of the requested file.