Requests

The aim of this article is to explain the requests API in CKFinder.

About Requests

CKFinder provides an application level request system which allows for communication between components, and avoids a tight coupling between parts of the application. One component can request an action to be performed by another component by sending an appropriate application level request with request method.

finder.request( 'requestName', optionalParameters );

A list of all possible requests you can find on CKFinder.Application API page.

Request Parameters and Returned Values

You can consider requests as similar to regular functions. Similarly, requests may require some parameters,and optionally it may return some value.

The list of taken parameters and the type of the returned value is defined for each request. Please refer to particular request documentation for details.

Usage Examples

Requests presented below are used to perform following actions:

• Getting a list of selected files.
• Sending a command to the server.
• Opening a dialog window with defined content.

Getting Selected Files

The selected files can be listed with files:getSelected request.

var selectedFiles = finder.request( 'files:getSelected' );

As you can see in the documentation, this request returns a Backbone.Collection object containing models corresponding to all selected files.

Sending Command to the Server

This functionality is provided by command:send request.

finder.request( 'command:send', {
    name: 'ImageInfo',
    folder: file.get( 'folder' ),
    params: {
        fileName: file.get( 'name' )
    }
} );

This request returns a jQuery.Promise object, which usually is a preferred way for handling the server response.

finder.request( 'command:send', {
    name: 'ImageInfo',
    folder: file.get( 'folder' ),
    params: {
        fileName: file.get( 'name' )
    }
} ).done( function( response ) {
    // Process the response
} );

It's also possible to create a listener for a particular command, like presented below.

finder.on( 'command:ok:ImageInfo', function( evt ) {
    var response = evt.data.response;
    // Process the response
} );

Opening a Dialog Window

The listing below demonstrates how to open a dialog window, after the server response for ImageInfo command is received. The callback function executes a dialog request, which provides a few useful options that simplify displaying the dialog window.

finder.request( 'dialog', {
    template: '<p>{{! it.firstName }} {{! it.lastName }}',
    templateModel: new Backbone.Model( { firstName: 'John', lastName: 'Doe' } ),
    title: 'My Dialog',
    name: 'MyDialog',
    buttons: [ 'okClose' ]
} );

Example

You can find usage examples for a few requests described above in ImageInfo plugin, which displays a basic information about selected image.