File Manager API

Rob2 edited this page Jul 16, 2012 · 3 revisions

File Manager API

This page will describe the API used by the File Manager plugin, in order to enable development of custom handlers. The API will be JSON based, and completely transparent - which means that the File Manager should not care how, or in what language the handler is written, it will only receive JSON response. The response structure will be described in this page.

Mandatory Features

The file manager handler must support two basic methods:

    1. "Authentication" method  
    2. "List Directory" method  

Apart of these two methods, the handler can support any of the following:

    1. Rename File  
    2. Remove File  
    3. Move File  
    4. Make Directory  
    5. Upload File  

For each method above, the handler should supply a boolean value of whether it is supported or not.
If it is supported, the handler should supply the url for the handler of that function (it can be the same handler). The methods requests are listed just below. The handler should be written according to these exact requests.

Ajax Requests Format

The file manager sends several different requests.

Authentication

Request:

http://domain.com/file_manager.php
    Sent parameters (GET method):
        action: auth
        auth: jwysiwyg

Response:

{
    "success": true,
    "data": {
        "move": {
            "enabled": true,
            "handler": "http://.../upload_handler.php"
        },
        "rename": {
            "enabled": true,
            "handler": "http://.../upload_handler.php"
        },
        "remove":  {
            "enabled": true,
            "handler": "http://.../upload_handler.php"
        },
        "mkdir":  {
            "enabled": true,
            "handler": "http://.../upload_handler.php"
        },
        "upload": {
            "enabled": true,
            "handler": "http://.....",
            "accept_ext": [".png",".pdf",".doc"] // For example
        }
    }
}

List Directory

Request

http://domain.com/file_manager.php
    Sent parameters (GET method):
        action: list
        dir: // Current directory

Response

{
    "success": true,
    "data": {
        "directories": {
            "dir 1": "/path/to/dir",
            "dir 2": "/path/to/dir2",
        },
        "files": {
            "file.txt": "http://..../file1.txt",
            "music.ogg": "http://..../music.ogg",
            "video.avi": "http://..../video.avi",
        }
    }

Rename

Request

http://domain.com/file_manager.php
    Sent parameters (GET method):
        action: rename
        type: // file/dir
        dir: // Current directory
        file: // File to rename
        newName: // The new name for renamed file.

Response

{
    "success": true,
    "data": "message .. "
}

Remove

Request

http://domain.com/file_manager.php
    Sent parameters (GET method):
        action: remove
        type: // file/dir
        dir: // Current directory
        file: // File to remove

Response

{
    "success": true,
    "data": "message .. "
}

Make Dir

Request

http://domain.com/file_manager.php
    Sent parameters (GET method):
        action: mkdir
        dir: // Current directory
        newName: // The name for the new directory

Response

{
    "success": true,
    "data": "message .. "
}

Move

Request

http://domain.com/file_manager.php
    Sent parameters (GET method):
        action: move
        dir: // Current directory
        file: // File/dir to move
        newPath: // The path to the new directory

Response

{
    "success": true,
    "data": "message .. "
}

Upload

The upload feature uses an iFrame and a form for a pseudo-ajax mechanism.

Request

http://domain.com/file_manager.php
    Sent parameters (POST method):
        action: upload
        handle: // The file handler
        dir: // Directory in which to save the file
        newName: // The name of the uploaded file [Mandatory]

Response

Content-Type:text/plain; charset=utf-8

Failure/Success message goes here...

The upload handler should only respond with plain text messages regarding failure/success. It does not use JSON for responses.

Handler Responses

The handler should respond with only 2 types of response:

Success

This response is sent when the operation was perfomred successfuly.

{ 
    "success": true, 
    "data": ... // Depends on the request.
}

Error

This response is sent when something goes wrong. The file manager will always try to display the error message, when it gets an error response.

{ 
    "success": false, 
    "error": "error message", 
    "errno": 255 // positive integer error code
}
// *errno* used for i18n.