CKFinder.Application
Mixins
The CKFinder instance class. Instances of CKFinder can only be created using one of the startup methods listed in the CKFinder API.
The access to the CKFinder instance is given to plugins in their CKFinder.Plugin.init method.
Alternatively, it is also possible to provide a CKFinder.Config.onInit configuration parameter to register a callback that receives a CKFinder.Application instance when CKFinder is ready.
CKFinder.popup( {
onInit: function( finder ) {
finder.request( 'dialog:info', { msg: 'It works!' } );
}
} );
Properties
Backbone and Marionette libraries. Contains Backbone and Backbone.Marionette namespace.
An object storing translated language strings defined in CKFinder and plugin language files. See CKFinder.Application.lang for methods that format text according to locale.
Methods
Fires a specific event in the object. All registered listeners are called at this point.
someObject.on( 'someEvent', function() { ... } );
someObject.on( 'someEvent', function() { ... } );
someObject.fire( 'someEvent' ); // Both listeners are called.
someObject.on( 'someEvent', function( event ) {
alert( event.data ); // 'Example'
} );
someObject.fire( 'someEvent', 'Example' );
Parameters
- eventName : String
The name of the event to fire.
- data : Object (optional)
The data to be sent as the CKFinder.Event.EventInfo.data when calling the listeners.
- finder : CKFinder.Application (optional)
The finder instance to send as the CKFinder.Event.EventInfo.finder when calling the listener.
Returns
- Boolean|Object
A Boolean value indicating that the event is to be canceled, or the data returned by one of the listeners.
Fires a specific event in the object, releasing all listeners registered to that event. The same listeners are not called again on successive calls of it or of fire.
someObject.on( 'someEvent', function() { ... } );
someObject.fire( 'someEvent' ); // Above listener called.
someObject.fireOnce( 'someEvent' ); // Above listener called.
someObject.fire( 'someEvent' ); // No listeners called.
Parameters
- eventName : String
The event name to fire.
- data : Object (optional)
Data to be sent as CKFinder.Event.EventInfo.data when calling the listeners.
- finder : CKFinder.Application (optional)
The finder instance to send as CKFinder.Event.EventInfo.finder when calling the listener.
Returns
- Boolean/Object
A Boolean value indicating that the event is to be canceled, or the data returned by one of the listeners.
Gets the currently registered handler for the specified name. Returns undefined if no handler is found.
Parameters
- name : String
The name of the request handler.
Determines whether or not a handler is registered.
Parameters
- name : String
The name of the request handler.
Returns
- Boolean
Checks if there is any listener registered to a given event.
var myListener = function() { ... };
someObject.on( 'someEvent', myListener );
alert( someObject.hasListeners( 'someEvent' ) ); // true
alert( someObject.hasListeners( 'noEvent' ) ); // false
Parameters
- eventName : String
The event name.
Returns
- Boolean
Registers a listener to a specific event in the current object.
someObject.on( 'someEvent', function() {
alert( this == someObject ); // true
} );
someObject.on( 'someEvent', function() {
alert( this == anotherObject ); // true
}, anotherObject );
someObject.on( 'someEvent', function( event ) {
alert( event.listenerData ); // 'Example'
}, null, 'Example' );
someObject.on( 'someEvent', function() { ... } ); // 2nd called
someObject.on( 'someEvent', function() { ... }, null, null, 100 ); // 3rd called
someObject.on( 'someEvent', function() { ... }, null, null, 1 ); // 1st called
Parameters
- eventName : String
The event name to which to listen.
- listenerFunction : Function
The function listening to the event. A single CKFinder.EventInfo object instanced is passed to this function containing all the event data.
- scopeObj : Object (optional)
The object used to scope the listener call (the
this
object). If omitted, the current object is used. - listenerData : Object (optional)
Data to be sent as the listener.
- priority : Number (optional)
The listener priority. Lower priority listeners are called first. Listeners with the same priority value are called in registration order.
Defaults to:
10
Returns
- Object
An object containing the
removeListener
function which can be used to remove the listener at any time.
Removes all existing listeners on this object for cleanup purposes.
Unregisters a listener function from being called at the specified event. No errors are thrown if the listener has not been registered previously.
var myListener = function() { ... };
someObject.on( 'someEvent', myListener );
someObject.fire( 'someEvent' ); // myListener called.
someObject.removeListener( 'someEvent', myListener );
someObject.fire( 'someEvent' ); // myListener not called.
Parameters
- eventName : String
The event name.
- listenerFunction : Function
The listener function to unregister.
Processes requests.
Parameters
- name : String
The name of the request handler.
Adds a handler for the given name.
Parameters
- name : String
The name of the request handler.
- handler : Function
Handler function.
- context : Object (optional)
An optional context of the handler.
Adds multiple handlers using an object literal configuration.
Parameters
- handlers : Object
Handlers configuration.
Events
Fired when a serious application error occurs that prevents it from operating properly and that is unrelated to the result of the server-side commands.
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- msg : String
Error message.
- msg : String
- data : Object
Fired when all modules are loaded, soon after receiving the command:ok:Init
event.
Note: The application is still launching while this event is fired.
Parameters
- evt : CKFinder.Event.EventInfo
Fired after command response for command name given as NAME - fired after command:ok
and command:error
events.
// Fired after CKFinder is initialized
finder.on( 'command:after:Init', function( evt ) {
// Your event handler
} );
// Fired after the list of files is requested from the server.
// Fired even when an error occurs, so might be better to use `command:ok:GetFiles`.
finder.on( 'command:after:GetFiles', function( evt ) {
console.log( evt.data.response.files );
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- name : String
Command name
- response : Object
The response from the server
- context : Object (optional)
Additional info that is not sent to the server, but may be useful for event listeners to understand the context in which the command is executed.
- name : String
- data : Object
Fired after command response for command name given as NAME - fired after command:ok
and command:error
events.
// Fired after CKFinder is initialized
finder.on( 'command:after:Init', function( evt ) {
// Your event handler
} );
// Fired after the list of files is requested from the server.
// Fired even when an error occurs, so might be better to use `command:ok:GetFiles`.
finder.on( 'command:after:GetFiles', function( evt ) {
console.log( evt.data.response.files );
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- response : Object
The response from the server
- context : Object (optional)
Additional info that is not sent to the server, but may be useful for event listeners to understand the context in which the command is executed.
- response : Object
- data : Object
Fired before issuing command to server for command name given as NAME.
finder.on( 'command:before', function( evt ) {
console.log( evt.data.params );
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- folder : CKFinder.Models.Folder (optional)
Folder in context of which the request is made. If provided, the following attributes are automatically appended to the query string:
currentFolder
,hash
,type
. - name : String
The name of the command
- params : Object
Data sent to the server (excluding
lang
and the attributes fetched fromdata.folder
-currentFolder
,hash
,type
). - context : Object
Additional info that is not sent to the server, but may be useful for event listeners to understand the context in which the command is executed.
- folder : CKFinder.Models.Folder (optional)
- data : Object
Fired before issuing command to server for command name given as NAME.
finder.on( 'command:before:RenameFile', function( evt ) {
console.log( evt.data.params.newFileName );
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- folder : CKFinder.Models.Folder (optional)
Folder in context of which the request is made. If provided, the following attributes are automatically appended to the query string:
currentFolder
,hash
,type
. - name : String
The name of the command
- params : Object
Data sent to the server (excluding
lang
and the attributes fetched fromdata.folder
-currentFolder
,hash
,type
). - context : Object
Additional info that is not sent to the server, but may be useful for event listeners to understand the context in which the command is executed.
- folder : CKFinder.Models.Folder (optional)
- data : Object
Fired when communication error occurs.
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- response : Object
The response from the server
- context : Object (optional)
Additional info that is not sent to the server, but may be useful for event listeners to understand the context in which the command is executed.
- response : Object
- data : Object
Fired when communication error occurs for command name given as NAME.
finder.on( 'command:error:GetFiles', function( evt ) {
// Your event handler
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- response : Object
The response from the server
- context : Object (optional)
Additional info that is not sent to the server, but may be useful for event listeners to understand the context in which the command is executed.
- response : Object
- data : Object
Fired after successful command response for command name given as NAME.
finder.on( 'command:ok:GetFiles', function( evt ) {
// Your event handler
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- response : Object
The response from the server
- context : Object (optional)
Additional info that is not sent to the server, but may be useful for event listeners to understand the context in which the command is executed.
- response : Object
- data : Object
Triggered on context menu creation.
// Create a custom context menu group
finder.on( 'contextMenu', function( evt ) {
evt.data.groups.add( {
name: 'TestMe'
} );
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- groups : Backbone.Collection
Context menu groups definition.
- context : Object (optional)
Context data set when requesting context menu with contextMenu request.
- groups : Backbone.Collection
- data : Object
Triggered on context menu creation. See contextMenu:file and contextMenu:folder.
finder.on( 'contextMenu:CustomContextMenu', function( evt ) {
evt.data.groups.addGroup( {
name: 'TestMe'
} );
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- groups : Backbone.Collection
Context menu groups definition.
- context : Object (optional)
Context data set when requesting context menu with contextMenu request.
- groups : Backbone.Collection
- data : Object
Triggered on context menu creation for each defined group. Example group event contextMenu:file.
finder.on( 'contextMenu:CustomContextMenu:TestMe', function( evt ) {
evt.data.items.add( {
name: 'TestMe',
label: 'Test Me!',
isActive: true,
icon: 'ckf-view',
action: function() {
alert( 'It works' );
}
} );
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- items : Backbone.Collection
Context menu items definition.
- context : Object (optional)
Context data set when requesting context menu with contextMenu request.
- items : Backbone.Collection
- data : Object
Triggered on file context menu. Can be used to define own context menu items groups.
finder.on( 'contextMenu:file', function( evt ) {
evt.data.groups.add( {
name: 'custom'
} );
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- groups : Backbone.Collection
Context menu groups.
- context : Object
- file : CKFinder.Models.File
The file on which the context menu was fired.
- file : CKFinder.Models.File
- groups : Backbone.Collection
- data : Object
Triggered on file context menu. Can be used to define own context menu items groups.
finder.on( 'contextMenu:file:view', function( evt ) {
evt.data.items.add( {
name: 'ShowFileUrl',
label: 'Show URL',
isActive: evt.data.context.file.get( 'folder' ).get( 'acl' ).fileView,
icon: 'ckf-view',
action: function() {
alert( evt.data.context.file.getUrl() );
}
} );
} );
List of available groups:
choose
- only when CKFinder.Config.chooseFiles set totrue
view
edit
delete
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- items : Backbone.Collection
Context menu group items.
- context : Object
- file : CKFinder.Models.File
The file on which the context menu was fired.
- file : CKFinder.Models.File
- items : Backbone.Collection
- data : Object
Triggered on folder context menu. Can be used to define own context menu items.
finder.on( 'contextMenu:folder', function( evt ) {
evt.data.groups.add( {
name: 'Custom'
} );
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- groups : Backbone.Collection
Context menu groups.
- context : Object
- folder : CKFinder.Models.Folder
The folder on which the context menu was fired.
- folder : CKFinder.Models.Folder
- groups : Backbone.Collection
- data : Object
Triggered on edit group in folder context menu. Can be used to define own context menu items.
finder.on( 'contextMenu:folder:edit', function( evt ) {
evt.data.items.add( {
name: 'ShowFolderUrl',
label: 'Show URL',
isActive: evt.data.context.folder.get( 'acl' ).fileView,
icon: 'ckf-view',
action: function() {
alert( evt.data.context.folder.getUrl() );
}
} );
} );
List of available groups:
edit
delete
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- items : Backbone.Collection
Context menu items.
- context : Object
- folder : CKFinder.Models.Folder
The folder on which the context menu was fired.
- folder : CKFinder.Models.Folder
- items : Backbone.Collection
- data : Object
Called after resource types are created.
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- resources : Array.<CKFinder.Models.Folder>
Collection of created resources
- resources : Array.<CKFinder.Models.Folder>
- data : Object
Called before resource types are created.
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- resources : Array.<CKFinder.Models.Folder>
Resources to be created
- resources : Array.<CKFinder.Models.Folder>
- data : Object
Fired after pressing BUTTON in a dialog window (with given NAME).
finder.on( 'dialog:RenameFolder:ok', function( evt ) {
// Your event handler
} );
Available buttons:
cancel
ok
okClose
(note: fires dialog:NAME:ok event)- Lowercase name of custom button.
Available dialogs:
ChooseFolder
ChooseResizedImage
CopySuccess
CreateFolder
DeleteFilesErrors
EditImageConfirm
EditImageSaveProgress
MoveCopyDialogPage
MoveSuccess
RenameFile
RenameFolder
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- view : Backbone.View
Dialog inner view (contents)
- model : Backbone.Model (optional)
Model set for dialog's inner view
- context : Object (optional)
Optional data set by requester when calling
finder.request()
- view : Backbone.View
- data : Object
Fired after dialog (with given NAME) is closed.
finder.on( 'dialog:close:MyDialog', function( evt ) {
// Your event handler
} );
For available dialogs check dialog:NAME:BUTTON.
Available since: 3.2
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- context : Object (optional)
Optional data set by requester when calling
finder.request()
- context : Object (optional)
- data : Object
Fired during image editing, after performing an action on it (e.g. after rotating an image, changing brightness).
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- actions : Object
The list of actions to be done on an image.
- actions : Object
- data : Object
Fired when user chooses resized image when choosing files is enabled (see config.chooseFiles).
finder.on( 'file:choose:resizedImage', function( evt ) {
alert( evt.data.resizedUrl );
// Call the code below if you would like to close the "Choose Resized" dialog window.
finder.request( 'dialog:destroy' );
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- file : CKFinder.Models.File
File for which the resized image was requested.
- resizedUrl : String
The URL to a resized image.
- file : CKFinder.Models.File
- data : Object
Fired when file receives dblclick event.
this.finder.on( 'file:dblclick', function( evt ) {
alert('File was clicked twice');
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- evt : jQuery.Event
jQuery Event wrapper for the DOM event.
- model : CKFinder.Models.File
The file that was clicked.
- evt : jQuery.Event
- data : Object
Fired when file receives dbltap event.
this.finder.on( 'file:dbltap', function( evt ) {
alert('File was taped twice');
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- evt : jQuery.Event
jQuery Event wrapper for the last touch DOM event.
- model : CKFinder.Models.File
The file that was taped.
- evt : jQuery.Event
- data : Object
Fired when file receives keydown event.
this.finder.on( 'file:keydown', function( evt ) {
if ( evt.data.evt.keyCode == 89 ) {
alert('Y key was pressed');
}
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- evt : jQuery.Event
jQuery Event wrapper for the DOM event.
- model : CKFinder.Models.File
The file that was focused before the key was pressed (the last focused file in case multiple files were selected).
- evt : jQuery.Event
- data : Object
Fired on generating file preview. To add custom file preview attach a listener and add a template to render view.
finder.on( 'file:preview', function( evt ) {
// Check if file extension is supported your plugin
if ( evt.data.file.isImage() ) {
// Stop event propagation so no other listener is fired
evt.stop();
// Add data for template
evt.data.templateData = {
url: evt.data.url,
alt: 'Alternate text'
};
// Add template for file preview rendering
evt.data.template = '<div class="my-div" style="position:absolute;top:0;left:0;bottom:0;right:0;text-align:center;">' +
'<h1 style="color:#fff;">My preview</h1>' +
'<img alt="{{= it.alt }}" src="{{= it.url }}">' +
'</div>';
// Add view events handlers
evt.data.events = {
'click .my-div': function( evt ) {
evt.stopPropagation();
alert( 'Click!' );
}
};
}
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- extension : String
Extension of file
- file : CKFinder.Models.File
The file that is shown
- template : String
The template used to render the file
- templateData : Object
- url : String
Url of a file
- afterRender : Function
Callback that is called after rendering a template.
- extension : String
- data : Object
Fired when user chooses one or many files when choosing files is active (see config.chooseFiles).
finder.on( 'files:choose', function( evt ) {
var files = evt.data.files;
var chosenFiles = '';
files.forEach( function( file, i ) {
chosenFiles += ( i + 1 ) + '. ' + file.get( 'name' ) + '\n';
} );
alert( chosenFiles );
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- files : Backbone.Collection
A collection of chosen files (@see CKFinder.Models.File).
- files : Backbone.Collection
- data : Object
Fired after one or more files were deleted.
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- files : Array.<CKFinder.Models.File>
Array with deleted files
- files : Array.<CKFinder.Models.File>
- data : Object
Fired when file selection has changed. Also triggered when files are unselected.
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- files :
{Backbone.Collection} Currently selected files (@see CKFinder.Models.File)
- files :
- data : Object
Fired when folder was properly deleted
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- folder : CKFinder.Models.Folder
Folder that was deleted
- folder : CKFinder.Models.Folder
- data : Object
Fired when object is dropped into a folder.
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- evt : jQuery.Event
jQuery Event wrapper for the DOM event.
- folder : CKFinder.Models.Folder
The folder on which an item was dragged.
- view : CKFinder.Modules.Folders.Views.FolderTreeNodeView (optional)
- el : jQuery (optional)
- evt : jQuery.Event
- data : Object
Fired when folder is about to expand.
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- folder : CKFinder.Models.Folder
The folder that is expanded.
- view : CKFinder.Modules.Folders.Views.FolderTreeNodeView
- folder : CKFinder.Models.Folder
- data : Object
Fired after files are displayed and after the command:ok:GetFiles
event.
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- folder : CKFinder.Models.Folder
The folder from which the files were displayed
- folder : CKFinder.Models.Folder
- data : Object
Fired before files are displayed and before the command:before:GetFiles
event.
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- folder : CKFinder.Models.Folder
The folder from which the files will be displayed
- folder : CKFinder.Models.Folder
- data : Object
Fired when folder receives keydown event.
this.finder.on( 'folder:keydown', function( evt ) {
if ( evt.data.evt.keyCode == 89 )
alert('Y key was pressed');
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- evt : jQuery.Event
jQuery Event wrapper for the DOM event.
- folder : CKFinder.Models.Folder
The folder that was focused before the key was pressed.
- view : CKFinder.Modules.Folders.Views.FolderTreeNodeView
- evt : jQuery.Event
- data : Object
Triggered after folder is selected.
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- folder : CKFinder.Models.Folder
Selected folder
- folder : CKFinder.Models.Folder
- data : Object
Fired on keydown event.
Note:
- When key is pressed on selected file or folder, separate events are fired: file:keydown and folder:keydown.
- In order to listen for key event, `key:listen` request must be called first.
finder.request( 'key:listen', { key: 65 } );
finder.on( 'keydown:65', function( evt ) {
alert('Key "a" was pressed');
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- evt : jQuery.Event
jQuery Event wrapper for the DOM event.
- evt : jQuery.Event
- data : Object
Fired on keyup event.
Note:
- When key is pressed on selected file or folder, separate events are fired: file:keydown and folder:keydown.
- In order to listen for key event, `key:listen` request must be called first.
finder.on( 'keyup:65', function( evt ) {
alert('Key "a" was pressed');
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- evt : jQuery.Event
jQuery Event wrapper for the DOM event.
- evt : jQuery.Event
- data : Object
Fired when updating columns of files list view.
finder.on( 'listView:columns', function( evt ) {
// Reorder columns
var sizeColumn = evt.data.columns.findWhere( { name: 'size' } );
if ( sizeColumn ) {
sizeColumn.set( 'priority', 40 );
}
var dateColumn = evt.data.columns.findWhere( { name: 'date' } );
if( dateColumn ) {
dateColumn.set( 'priority', 30 );
}
} );
Available since: 3.2
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- columns : Backbone.Collection
Collection of columns. Each column must contain the following attributes:
name
– The name of the column. Reserved column names are:icon
,name
,size
, anddate
.label
– The label for the column displayed in the column header.priority
– Sorting priority of the column. Columns with higher priority are placed closer to the folders tree.width
– A CSS property to set the width of the column. By default, a column has no width set so it takes all available space (since 3.4).
- columns : Backbone.Collection
- data : Object
Fired when displaying custom column for a file. If config.displayFoldersPanel
is set to true
you must also define a view for a folder's cell during listView:folder:column:NAME
event.
// Define a column
finder.on( 'listView:columns', function( evt ) {
evt.data.columns.push( {
name: 'acl',
label: 'ACL',
priority: 25
} );
} );
// Add a view template for custom column.
finder.on( 'listView:file:column:acl', function( evt ) {
evt.data.template: '<td>{{= it.formatACL( it.folder.get( "acl" ) ) }}</td>',
evt.data.templateHelpers: {
formatACL: function ( acl ) {
var out = '';
out += acl.fileDelete ? 'd' : '_';
out += acl.fileRename ? 'r' : '_';
out += acl.fileView ? 'v' : '_';
return out;
}
};
} );
Note: This event was changed in version 3.3. It no longer support data.view
parameter.
Available since: 3.2
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- template : String
A placeholder for a template. Attach a string with doT.js compatible template to render a cell view. Each cell view obtains a file data
- templateHelpers : Object
A placeholder for a template helpers. Add any method or key that is used in template.
- template : String
- data : Object
Fired when updating columns of folder in list view. Only fired when
config.displayFoldersPanel is set to true
.
// Define a column
finder.on( 'listView:columns', function( evt ) {
var sizeColumn = evt.data.columns.findWhere( { name: 'size' } );
if ( sizeColumn ) {
sizeColumn.set( 'priority', 40 );
}
var dateColumn = evt.data.columns.findWhere( { name: 'date' } );
dateColumn.set( 'priority', 30 );
} );
// Add a view for custom column.
finder.on( 'listView:folder:column:acl', function( evt ) {
var ItemView = finder.Backbone.Marionette.ItemView;
evt.data.template: '<td>{{= it.formatACL( it.folder.get( "acl" ) ) }}</td>',
evt.data.templateHelpers: {
formatACL: function ( acl ) {
var out = '';
out += acl.fileUpload ? 'u' : '_';
out += acl.folderCreate ? 'c' : '_';
out += acl.folderDelete ? 'd' : '_';
out += acl.folderRename ? 'r' : '_';
out += acl.folderView ? 'v' : '_';
return out;
}
};
} );
Note: This event was changed in version 3.3. It no longer support data.view
parameter.
Available since: 3.2
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- template : String
A placeholder for a template. Attach a string with doT.js compatible template to render a cell view. Each cell view obtains a folder data.
- templateHelpers : Object
A placeholder for a template helpers. Add any method or key that is used in template.
- template : String
- data : Object
Fired before creating page NAME .
finder.on( 'page:create:Main', function( evt ) {
// do something
} );
Parameters
- evt : CKFinder.Event.EventInfo
Fired before showing page NAME.
Available pages:
Main
EditImage
Parameters
- evt : CKFinder.Event.EventInfo
Fired when panel with name NAME is opened.
finder.on( 'panel:open:settings', function( evt ) {
// do something
} );
Panels available:
folders
html5upload
settings
Parameters
- evt : CKFinder.Event.EventInfo
Fired after plugin:allReady event for each plugin that failed to load.
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- configKey : String
A configuration key that was used to load plugin.
- url : String
A resulting url from which CKFinder tried to load plugin.
- configKey : String
- data : Object
Fired when plugin is loaded
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- plugin : object
Plugin instance that have been initialized
- plugin : object
- data : Object
Called after a resource selection view is shown, ie: user selects to top level folder ('/') in breadcrumbs. Occurs only when config.displayFoldersPanel is set to true.
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- resources : Array.<CKFinder.Models.Folder>
Collection of resources
- resources : Array.<CKFinder.Models.Folder>
- data : Object
Called before a resource selection view is shown, ie: user selects to top level folder ('/') in breadcrumbs. Occurs only when config.displayFoldersPanel is set to true.
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- resources : Array.<CKFinder.Models.Folder>
Collection of resources
- resources : Array.<CKFinder.Models.Folder>
- data : Object
Fired when settings were changed in any element that belongs to GROUP.
finder.on('settings:change:files', function(evt) {
alert('Files settings were changed!');
} );
Possible values:
settings:change:files
settings:change:folders
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- changed : String
The name of a setting that was changed
- settings : Object
Settings values.
- changed : String
- data : Object
Fired when settings were changed in NAME element that belongs to GROUP.
finder.on('settings:change:files:thumbSize', function(evt) {
alert('The size of thumbnails was changed!');
} );
Possible values:
settings:change:files:displayDate
settings:change:files:displayName
settings:change:files:displaySize
settings:change:files:thumbSize
settings:change:files:viewType
settings:change:files:sortBy
settings:change:files:sortByOrder
settings:change:folders:lastFolder
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- value : *
The new value.
- previousValue : *
The previous value. (Added in 3.4).
- value : *
- data : Object
Triggered before building shortcuts listing dialog. Use it to define shortcuts group.
finder.on( 'shortcuts:list', function( evt ) {
evt.data.groups.add( {
name: 'myPlugin',
label: 'My plugin shortcuts',
priority: 50
} );
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- groups : Backbone.Collection
Shortcuts groups collection.
- groups : Backbone.Collection
- data : Object
Triggered before building shortcuts listing dialog for each defined shortcuts group on shortcuts:list event.
// Create shortcuts group
finder.on( 'shortcuts:list', function( evt ) {
evt.data.groups.add( {
name: 'myPlugin',
label: 'My plugin shortcuts',
priority: 50
} );
} );
// Add shortcuts to group
finder.on( 'shortcuts:list:myPlugin', function( evt ) {
evt.data.shortcuts.add( {
label: 'Run some action',
shortcuts: '{ctrl}+{e}'
} );
evt.data.shortcuts.add( {
label: 'Run other action',
// You can provide list of shortcuts by separating them with pipe.
shortcuts: '{ctrl}+{f}|{ctrl}+{shift}+{f}'
} );
} );
CKFinder uses internally those groups:
general
files
folders
Since some keys might not be read by screen readers software evt.data.keys
object is present.
You can add custom key as below:
finder.on( 'shortcuts:list:myPlugin', function( evt ) {
evt.data.keys.dot = {
display: '.', // A string or HTML entity that will be used as visual representation of a key
text: 'Dot' // A text that be used as text used by screen readers
};
evt.data.shortcuts.add( {
label: 'Run some action',
shortcuts: '{ctrl}+{dot}'
} );
} );
CKFinder defines keys:
{leftArrow}
- Left arrow (displays: ←){rightArrow}
- Right arrow (displays: →){upArrow}
- Up arrow (displays: ↑){downArrow}
- Down arrow (displays: ↓){ctrl}
- Control (displays: ctrl){del}
- Delete (displays: del){esc}
- Escape (displays: esc){question}
- Question mark (displays: ?)
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- groups : Backbone.Collection
Shortcuts groups collection.
- keys : Object
Shortcuts special keys definition.
- groups : Backbone.Collection
- data : Object
Fired when status bar is created. Listen to this event to register you own parts inside status bar using reqeust-statusBar:addRegion.
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- name : String
Name of status bar.
- page : String
Name of page in which status bar created.
- name : String
- data : Object
Fired before creating template for view.
finder.on( 'template', function( evt ) {
console.log( 'Template name:' + evt.data.name );
console.log( 'Template code:' + evt.data.template );
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- name : String
Name of a view
- template : string
Template string
- imports : Object
Template imports
- name : String
- data : Object
Fired before creating template for view. See view:NAME
for a list of possible values or use template
event listener to discover names of templates used by CKFinder.
finder.on( 'template:FileThumb', function( evt ) {
evt.data.template = evt.data.template + '<div>My info</div>';
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- name : String
Name of a view
- template : string
Template string
- imports : Object
Template imports
- name : String
- data : Object
Generic toolbar event fired after creating a toolbar.
finder.on( 'toolbar:create', function( evt ) {
console.log( 'A "' + evt.data.name + '" toolbar was created for "' + evt.data.page + '" page.');
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- name : String
Toolbar name.
- page : String
Name of page fro which toolbar was created.
- name : String
- data : Object
Generic toolbar event fired after toolbar was destroyed.
finder.on( 'toolbar:destroy:Main', function( evt ) {
console.log( 'A "' + evt.data.name + '" toolbar was destroyed.');
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- name : String
Toolbar name.
- page : String
Name of page fro which toolbar was created.
- name : String
- data : Object
Fired before creating toolbar elements for single file. Can be used to define own buttons.
finder.on( 'toolbar:reset:Main:file', function( evt ) {
evt.data.toolbar.push( {
name: 'ShowName',
type: 'button',
priority: 100,
label: 'Show name',
action: function() {
var files = evt.finder.request( 'files:getSelected' ).toArray();
alert( files[ 0 ].get( 'name' ) )
}
} );
} );
Using this event it is also possible to remove toolbar buttons.
finder.on( 'toolbar:reset:Main:file', function( evt ) {
var toRemove = evt.data.toolbar.filter( function( button ) {
return button.get( 'name' ) === 'Download';
} );
evt.data.toolbar.remove( toRemove );
}, null, null, 1000 );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- file : CKFinder.Models.File
File model for which toolbar is created.
- toolbar : Array
Toolbar buttons. See toolbar:reset:NAME:EVENT event.
- file : CKFinder.Models.File
- data : Object
Fired before creating toolbar elements for multiple files. Can be used to define own buttons.
finder.on( 'toolbar:reset:Main:files', function( evt ) {
evt.data.toolbar.push( {
name: 'FilesInfo',
type: 'button',
priority: 100,
label: 'Files info',
action: function( evt ) {
alert( 'Number of selected files: ' + evt.finder.request( 'files:getSelected' ).length );
}
} );
} );
Using this event it is also possible to remove toolbar buttons.
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- files : Backbone.Collection
A collection of File models for which toolbar is created.
- toolbar : Array
Toolbar buttons. See toolbar:reset:NAME:EVENT event.
- files : Backbone.Collection
- data : Object
Fired before creating toolbar elements for folder (or resource type). Can be used to define own buttons.
finder.on( 'toolbar:reset:Main:folder', function( evt ) {
evt.data.toolbar.push( {
name: 'FolderInfo',
type: 'button',
priority: 100,
label: 'Folder info',
action: function() {
var files = evt.finder.request( 'files:getCurrent' ).toArray();
alert(
'Number of files in a folder: ' + files.length + '\n' +
'Is root folder: ' + ( evt.data.folder.get( 'isRoot' ) ? 'Yes' : 'No' ) + '\n' +
'Deleting files allowed: ' + ( evt.data.folder.get( 'acl' ).fileDelete ? 'Yes' : 'No' )
);
}
} );
} );
Using this event it is also possible to remove toolbar buttons.
finder.on( 'toolbar:reset:Main:folder', function( evt ) {
evt.data.toolbar = evt.data.toolbar.filter( function( item ) {
return !( item.name == 'Maximize' || ( item.attributes && item.attributes.name == 'Maximize' ) );
} );
}, null, null, 1000 );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- folder : CKFinder.Models.Folder
Folder model for which toolbar is created.
- toolbar : Array
Toolbar buttons. See toolbar:reset:NAME:EVENT event.
- folder : CKFinder.Models.Folder
- data : Object
Fired before creating toolbar elements for resource types when
config.displayFoldersPanel is set to false
.
Can be used to define own buttons.
Parameters
- evt : CKFinder.Event.EventInfo
Generic toolbar event fired before changing toolbar configuration.
finder.on( 'toolbar:reset:Main', function( evt ) {
evt.data.toolbar.push( {
type: 'button',
priority: 100,
label: 'Action',
name: 'MyToolbarAction',
action: function() {
alert( 'Toolbar action!' );
}
} );
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- toolbar : Backbone.Collection
Toolbar buttons configuration. See CKFinder.Models.ToolbarItem for details.
- toolbar : Backbone.Collection
- data : Object
Generic toolbar event fired before changing toolbar configuration.
finder.on( 'toolbar:reset:Main:folder', function( evt ) {
evt.data.toolbar.push( {
name: 'MyToolbarAction',
type: 'button',
priority: 100,
label: 'Action',
action: function() {
alert( 'Toolbar action!' );
}
} );
} );
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- toolbar : Backbone.Collection
Toolbar buttons configuration. See CKFinder.Models.ToolbarItem for details.
- toolbar : Backbone.Collection
- data : Object
Fired when an application has lost focus, ie. other tab in browser is clicked or other application window.
Parameters
- evt : CKFinder.Event.EventInfo
Fired when an application has gained focus, ie. user is coming from other tab in browser or other application to CKFinder.
Parameters
- evt : CKFinder.Event.EventInfo
Fired when calculated mode is changed.
Parameters
- evt : CKFinder.Event.EventInfo
- mode : String
Current mode:
mobile
ordesktop
- modeChanged : Boolean
Set to
true
when mode is changed
- mode : String
Fired when a swipe event occurs moving in the left direction.
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- evt : jQuery.Event
jQuery Event wrapper for the DOM event.
- evt : jQuery.Event
- data : Object
Fired when a swipe event occurs moving in the right direction.
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- evt : jQuery.Event
jQuery Event wrapper for the DOM event.
- evt : jQuery.Event
- data : Object
Fired before creating view.
Available views:
ActionsView
ActionView
ChooseFolderDialogLayoutView
ChooseResizedItem
ChooseResizedCustomItem
ContextMenu
ContextMenuEmpty
ContextMenuItem
CreateFolder
CropView
CropBoxView
DateCellView
DeleteFileError
EditImageLayout
EditImageProgressDialogView
EmptyCellView
FileIconCellView
FileListView
FileNameCellView
FileRowView
FilesInfoView
FileThumb
FolderIconCellView
FolderNameCellView
FolderRowView
FoldersTree
FolderThumb
ImagePreview
Main
MessageView
MoveCopyDialogLayoutView
MoveCopyErrorsView
MoveCopyResultView
PageLayout
PanelLayout
PresetsView
ProgressView
RenameFile
RenameFolder
ResizeView
RotateView
CheckboxSetting
RadioSetting
RangeSetting
SelectSetting
TextSetting
SettingsGroupView
SettingsView
ShortcutsColumnView
ShortcutsGroupView
ShortcutsListing
ShortcutView
SizeCellView
StatusBarView
ThumbnailsView
ToolbarFolder
ToolbarFolders
ToolbarItemButton
ToolbarItemText
ToolbarView
UploadFileForm
UploadForm
UploadList
UploadListItem
UploadListSummary
Parameters
- evt : CKFinder.Event.EventInfo
- data : Object
- view : Backbone.View
View
- view : Backbone.View
- data : Object
Requests
Request CKFinder to close the popup window created with CKFinder.popup()
.
finder.request( 'closePopup' );
Request CKFinder to send a command to the backend server.
// Note: in order to delete a folder and have all related tasks done automatically
// (like refreshing the list of folders) use 'folder:delete' request.
var currentFolder = finder.request( 'folder:getActive' );
if ( confirm( 'Delete ' + currentFolder.get( 'name' ) + '?')) {
finder.request( 'command:send', {
name: 'DeleteFolder',
type: 'post',
folder: currentFolder
} );
}
// In some cases it may be convenient to use the returned Promise object
var currentFolder = finder.request( 'folder:getActive' );
if ( confirm( 'Delete ' + currentFolder.get( 'name' ) + '?')) {
finder.request( 'command:send', {
name: 'DeleteFolder',
type: 'post',
folder: currentFolder
} ).done( function( response ) {
if ( !response.error ) {
alert( 'The folder has been deleted successfully!' );
}
} );
}
Parameters
- data : Object
- name : String
Command name (to be handled by the server side connector)
- folder : CKFinder.Models.Folder (optional)
Current folder of command if needed
- type : String (optional)
Command request type
Defaults to:
'get'
- post : Object (optional)
Post data. Only used when
data.type="post"
- params : Object (optional)
Command parameters
- context : Object (optional)
Additional info that is not sent to the server, but may be useful for event listeners to understand the context in which the command is executed.
- sendPostAsJson : Boolean (optional)
Orders CKFinder to send all
data.post
info as JSON encoded paramjsonData
in POST.Defaults to:
false
- name : String
Returns
- jQuery.Promise
Returns jQuery.Promise object.
Requests a complete URL to the server connector that can be used to execute the specified command.
// Request URL if file is selected and "u" key is pressed
finder.on( 'file:keydown', function( evt ) {
if ( evt.data.evt.keyCode == 85 ) {
var currentFolder = finder.request( 'folder:getActive' );
var params = {
fileName: evt.data.file.get( 'name' ),
size: '400x400'
};
var url = finder.request( 'command:url', { command: 'ImagePreview', params: params, folder: currentFolder } );
console.log( url );
}
} );
Parameters
- data : Object
- command : String
Command name
- params : Object (optional)
Additional query string parameters
- folder : CKFinder.Models.Folder (optional)
Current folder of command if needed
- command : String
Returns
- String
URL to the server connector that can be used to execute the specified command.
Requests to create a context menu.
finder.request( 'contextMenu', {
name: 'CustomContextMenu',
position: { x: 100, y: 20 }
} );
Parameters
- data : Object
- name : String
Name of context menu used by contextMenu:NAME
- position : Object
Coordinates of upper left corner of context menu. Example:
data.position = { x: 100, y: 200 };
. - evt : jQuery.Event (optional)
jQuery Event wrapper for the DOM "mouse" event that invokes context menu.
- positionToEl : jQuery (optional)
If passed context menu will try to position itself to DOM node matched by jQuery object.
- context : Object (optional)
Context data for events.
- name : String
Request the value of the CSRF token from CKFinder.
CKFinder uses CSRF protection mechanism based on double submit cookies_Prevention_Cheat_Sheet#Double_Submit_Cookies). This request returns the value of the CSRF token and generates a required cookie if it's not present.
console.log( finder.request( 'csrf:getToken' ) );
Returns
- String
CSRF token value.
Request dialog window to render. Allows for creating custom dialog windows.
See Dialog Windows documentation for examples.
CKFinder.require( [ 'backbone' ], function( Backbone ) {
var model = new finder.Backbone.Model( { text: 'archive.zip' } );
finder.request( 'dialog', {
name: 'DownloadDialog',
title: 'Download As',
template: '<div><label>Download selected files as:<input value="{{= it.text }}" name="filename"></label></div>',
templateModel: model,
buttons: ['ok','cancel']
} );
} );
Parameters
- data : Object
- name : String
Dialog name (used e.g. to construct event names).
- buttons : Array (optional)
Buttons to show. Possible values:
cancel
,ok
,okClose
(same asok
, but additionally closes the dialog) or a button definition object that containslabel
andname
keys, ie:{ name: 'Button1', label: 'Request Info' }
.Defaults to:
['ok','cancel']
- context : Object (optional)
Additional info passed to dialog:NAME:BUTTON event listeners.
- title : String (optional)
Dialog title (displayed to the user).
- template : String (optional)
A doT.js template to render inside dialog.
- templateModel : Object (optional)
Data for doT.js template.
- view : Marionette.View (optional)
A view instance that should be showed inside dialog instead of template.
- captureFormSubmit : Boolean (optional)
Defines if dialog should automatically trigger
dialog:NAME:ok
dialogDefaults to:
true
- restrictHeight : Boolean (optional)
If set to true the dialog would not be bigger then viewport.
Defaults to:
true
- uiOptions : Object (optional)
Pass options to jQuery mobile popup widget.
- uiOpen : Object (optional)
Pass options open method.
- contentClassName : String|Boolean (optional)
Additional class name to be put on
.ckf-dialog-contents
div that holds dialog content view. Set to false to not add any additional class. event if dialog contains a form element and this form is submitted.Defaults to:
ui-content
- name : String
Shorthand request for dialog with confirmation message and buttons OK and Cancel.
finder.request( 'dialog:confirm', {
msg: 'Are you sure?',
name: 'MyDialog',
title: 'Please confirm'
} );
finder.once( 'dialog:MyDialog:ok', function( evt ) {
alert('Okay!');
} );
Parameters
- data : Object
- msg : String
Message to display
- buttons : Array (optional)
Buttons to show. Possible values:
cancel
,ok
,okClose
(same asok
, but additionally closes the dialog)Defaults to:
[ 'okClose', 'cancel' ]
- context : Object (optional)
Additional info passed to dialog:NAME:BUTTON event listeners,
- name : String (optional)
Dialog name (used e.g. to construct event names)
Defaults to:
Confirm
- title : String (optional)
Dialog title (displayed to the user)
- msg : String
Request to destroy any displayed dialog.
finder.request( 'dialog:info', {
msg: 'Operation completed successfully',
title: 'Information'
} );
// Destroy the dialog above after 2 seconds.
setTimeout( function() {
finder.request( 'dialog:destroy' );
}, 2000);
Shorthand request for dialog with only message displayed.
finder.request( 'dialog:info', {
msg: 'Operation completed successfully',
title: 'Information'
} );
Parameters
- data : Object
- msg : String
Message to display
- buttons : Array (optional)
Buttons to show. Possible values:
cancel
,ok
,okClose
(same asok
, but additionally closes the dialog)Defaults to:
[]
- context : Object (optional)
Additional info passed to dialog:NAME:BUTTON event listeners,
- name : String (optional)
Dialog name (used e.g. to construct event names)
Defaults to:
Confirm
- title : String (optional)
Dialog title (displayed to the user)
- msg : String
Request file download. The file will be sent to the user/downloaded by the browser.
// Request file download when "a" key is pressed
finder.on( 'file:keydown', function( evt ) {
if ( evt.data.evt.keyCode == 65 ) {
finder.request( 'file:download', { file: evt.data.file } );
}
} );
Parameters
- data : Object
- file : CKFinder.Models.File
File which should be downloaded
- file : CKFinder.Models.File
Request an active file - which is focused in files pane.
Available since: 3.1.1
Requests path to an icon for a file with given extension.
finder.request( 'file:getIcon', { size: 40, file: file } )
Parameters
- data : Object
- size : Number
Size in pixels.
- file : CKFinder.Models.File
A file for which icon is needed.
- size : Number
Returns
- String
A URL to a file icon that does not exceed the provided size.
Obtain file url based on Proxy command. If the Proxy method is used the file is served by CKFinder connector. For details about Proxy command please have a look at useProxyCommand documentation.
finder.request( 'files:getCurrent' ).forEach( function( file ) {
var fileUrl = finder.request( 'file:getProxyUrl', { file: file } );
console.log( 'The file: ' + file.get( 'name' ) + ' has url: ' + fileUrl );
} );
Parameters
- data : Object
- file : CKFinder.Models.File
File for which obtain url.
- cache : Number (optional)
Cache lifetime in seconds. If set, the response from connector will contain appropriate caching headers.
- params : Object (optional)
Additional query string parameters.
- file : CKFinder.Models.File
Returns
- String
URL to a file build using Proxy command.
Requests path to a thumbnail for given file. Note: the returned path to a thumbnail points to the server connector, so it's not recommended to use it in created documents or to save a reference to it in a database.
finder.request( 'file:getThumb', { file: currentFile } )
Parameters
- data : Object
- file : CKFinder.Models.File
The file for which the thumbnail should be returned
- file : CKFinder.Models.File
Returns
- String
A URL to a thumbnail.
Obtain file url. Works for remote Resource Types (such as Dropbox or Amazon S3) where url cannot be created from file path. The request will return jQuery.Promise object. Use then method to obtain requested url. After first fetch file's url is cached in CKFinder.Models.File.url attribute.
Note: If useProxyCommand flag is set for a backend where the file is stored, this command will return an URL based on Proxy command.
finder.request( 'files:getCurrent' ).forEach( function( file ) {
finder.request( 'file:getUrl', { file: file } )
.then( function( fileUrl ) {
console.log( 'The file: ' + file.get( 'name' ) + ' has url: ' + fileUrl );
} );
} );
Parameters
- data : Object
- file : CKFinder.Models.File
File for which obtain url.
- thumbnail : String (optional)
If set
- file : CKFinder.Models.File
Returns
- jQuery.Promise
Returns jQuery.Promise object.
Request URL to show file preview. If no file passed as start file the preview will start from first file.
finder.request( 'file:preview' );
Parameters
- data : Object
- file : CKFinder.Models.File (optional)
Optional file from which start a preview.
- file : CKFinder.Models.File (optional)
Requests file rename.
finder.request( 'file:rename', { file: currentFile } );
Parameters
- data : Object
- file : CKFinder.Models.File
A file to rename
- file : CKFinder.Models.File
Chooses files (for example to embed in the page content). Passed files will be used in following choose event.
// Choose all files in current.
finder.request( 'files:choose', { files: finder.request( 'files:getSelected' ) } )
Parameters
- data : Object
- files :
{Backbone.Collection} Files to choose (@see CKFinder.Models.File)
- files :
Requests copying files to the specified destination folder.
Parameters
- data : Object
- files : Array.<CKFinder.Models.File>
Files to copy
- toFolder : CKFinder.Models.Folder
Destination folder
- files : Array.<CKFinder.Models.File>
Requests file deletion.
// Delete files if at least one file is selected and "d" key is pressed
finder.on( 'file:keydown', function( evt ) {
if ( evt.data.evt.keyCode == 68 ) {
var selected = finder.request( 'files:getSelected' ).toArray();
if ( selected.length ) {
finder.request( 'files:delete', { files: selected } );
}
}
} );
Parameters
- data : Object
- file : Array.<CKFinder.Models.File>
Files to delete
- file : Array.<CKFinder.Models.File>
Requests deselecting all currently selected files.
finder.request( 'files:deselectAll' );
Requests filtering the list of files in a current folder.
// Show only files that contain '.png' in their name (PNG files)
finder.request( 'files:filter', { text: '.png' } )
Parameters
- data : Object
- text : String
The string that filtered file names must contain.
- text : String
Returns a collection of all files that are in the current folder, including the one that are currently not displayed due to an active Search Box filter.
finder.request( 'files:getCurrent' );
Returns
- Backbone.Collection
A collection of files (@see CKFinder.Models.File) which are in the current folder
Returns a collection of all files that are currently displayed the current folder.
It may return less files than files:getCurrent
is user typed something in the Search Box.
finder.request( 'files:getDisplayed' )
Returns
- Backbone.Collection
Files which are currently displayed
Used to obtain currently selected files.
finder.request( 'files:getSelected' )
Returns
- Backbone.Collection
Currently selected files (@see CKFinder.Models.File)
Requests moving files to the specified destination folder.
Parameters
- data : Object
- files : Array.<CKFinder.Models.File>
Files to copy
- toFolder : CKFinder.Models.Folder
Destination folder
- files : Array.<CKFinder.Models.File>
Requests file selection in current folder.
// Select all files in current folder (see files:selectAll).
var allFiles = finder.request( 'files:getCurrent' );
finder.request( 'files:select', { files: allFiles.toArray() } );
Parameters
- data : Object
- files :
{Array.<CKFinder.Models.File>} Files to select
- files :
Requests toggling file selection in current folder. Selected files from given array are unselected and vice versa.
var allFiles = finder.request( 'files:getCurrent' );
finder.request( 'files:select:toggle', { files: allFiles.toArray() } );
Parameters
- data : Object
- files :
{Array.<CKFinder.Models.File>} Files to select
- files :
Requests selecting all files in current folder.
finder.request( 'files:selectAll' );
Request to focus next element in DOM based on tabindex.
// inside a view
finder.request( 'focus:prev', { node: this.$el } );
Parameters
- data : Object
- node : jQuery
A current node which has focus
Request to focus prev element in DOM based on tabindex.
// inside a view
finder.request( 'focus:prev', { node: this.$el } );
Parameters
- data : Object
- node : jQuery
A current node which has focus
Request to store currently focused event.
finder.request( 'focus:remember' );
Request to restore last remembered focused element.
finder.request( 'focus:restore' );
Request a certain node to keep TAB focus cycle within. Tabbing order is according to DOM order of elements. Elements that gain focus are:
a
button
input
select
- any item with positive
tabindex
attribute
Elements with tabindex="-1"
are removed from tab order.
finder.request( 'focus:trap', { node: jQuery( '#my-div' ) } );
Parameters
- data : Object
- node : jQuery
A node within focus should stay.
- node : jQuery
Request subfolder creation. If the newFolderName
property is omitted, the request handler creates a dialog window
and asks the user for the folder name.
finder.request( 'folder:create', {
parent: finder.request( 'folder:getActive'),
newFolderName: 'FooBar'
} );
Parameters
- data : Object
- parent : CKFinder.Models.Folder
- newFolderName : String (optional)
- parent : CKFinder.Models.Folder
Requests folder deletion.
var currentFolder = finder.request( 'folder:getActive' );
// Root folders cannot be deleted
if ( !currentFolder.get( 'isRoot' ) ) {
finder.request( 'folder:delete', { folder: currentFolder } );
}
Parameters
- data : Object
- folder : CKFinder.Models.Folder
Folder do delete
- folder : CKFinder.Models.Folder
Retrieves active folder.
var folder = finder.request( 'folder:getActive' );
Returns
- CKFinder.Models.Folder
Currently viewed folder
Requests fetching list of files in a given folder. Might be used to refresh the list of files in a folder.
finder.request( 'folder:getFiles', { folder : currentFolder } );
Parameters
- data : Object
- folder : CKFinder.Models.Folder
Folder model for which lists files
- folder : CKFinder.Models.Folder
Requests path to an icon for a folder.
finder.request( 'file:getIcon', { size: 40, folder: folder } )
Parameters
- data : Object
- size : Number
Size in pixels.
- folder : CKFinder.Models.Folder
A folder for which icon is needed.
- size : Number
Returns
- String
A URL to a file icon that does not exceed the provided size.
Requests opening the specified path.
finder.request( 'folder:openPath', { path: 'Files:/', expand: true } );
Parameters
- data : Object
- path : String
Path to open in a format
<resource>:/<path>
. E.g.Files:/folder1/subfolder2
- expand : Boolean
Whether to expand the last folder
- path : String
Requests current folder view to refresh the list of files.
finder.request( 'folder:refreshFiles' ) ;
Requests folder rename. If newFolderName is not set the handler will display dialog to input data.
finder.request( 'folder:rename', { folder: currentFolder } );
Parameters
- data : Object
- newFolderName : String (optional)
The new name for a folder
- folder : CKFinder.Models.Folder
A folder to rename
- newFolderName : String (optional)
Request to select a folder (open folder and request files).
// Select parent folder.
var currentFolder = finder.request( 'folder:getActive' );
finder.request( 'folder:select', { folder: currentFolder.get( 'parent' ) } );
Parameters
- data : Object
- folder : CKFinder.Models.Folder
Folder to switch to
- folder : CKFinder.Models.Folder
Obtain information about existing resized versions of an image file.
finder.request( 'image:getResized', { file: currentFile } ).then( function( file ) {
// Backbone.Collection
console.log( file.get( 'imageResizeData' ) );
// Object { medium="brown-dog__600x338.jpg", large="brown-dog__800x450.jpg", small="brown-dog__480x270.jpg"}
console.log( file.get( 'imageResizeData').get( 'resized' ) );
} );
Parameters
- data : Object
- file : CKFinder.Models.File
File for which obtain resized information
- file : CKFinder.Models.File
Returns
- jQuery.Promise
Returns jQuery.Promise object.
Request a URL to a resized version of an image.
finder.request( 'image:getResized', { file: currentFile } ).then( function( file ) {
var resizedVersions = file.get( 'imageResizeData').get( 'resized' );
finder.request( 'image:getResizedUrl', { file: currentFile, thumbnail : resizedVersions.large } ).then( function( url ) {
// /userfiles/images/__thumbs/brown-dog.jpg/brown-dog__800x450.jpg
console.log( url );
} );
} );
Parameters
- data : Object
- file : CKFinder.Models.File
File for which obtain thumbnail url.
- thumbnail : String
The name of an existing resized image file (retrieved with
image:getResized
).
- file : CKFinder.Models.File
Request URL to image preview with given preview dimensions. Returned image might be slightly bigger/smaller dependent on server side configuration.
var imageUrl = finder.request( 'image:previewUrl', { file: currentFile, maxWidth: 250, maxHeight: 250 } );
console.log( imageUrl );
// Example log: http://example.com/core/connector/php/connector.php?command=ImagePreview&lang=en&type=Images¤tFolder=%2F&hash=78200e8b45d3f1c2&fileName=brown-dog.jpg&size=250x250
Parameters
- data : Object
- file : CKFinder.Models.File
- maxWidth : String|Number
Maximum width of image preview
- maxHeight : String|Number
Maximum height of image preview
- noCache : Boolean (optional)
If set to true request will have appended timestamp param
Defaults to:
false
- file : CKFinder.Models.File
Request creation of resized image on the server.
finder.request( 'image:resize', { file: currentFile, name: '__custom', size: '500x500', save: true }).then( function( file ) {
// /userfiles/images/__thumbs/brown-dog.jpg/brown-dog__500x281.jpg
console.log( file.get( 'imageResizeData' ).get( 'resizedUrl_custom500x500' ) );
} );
Parameters
- data : Object
- file : CKFinder.Models.File
File for which create a resized version
- name : String
Name of predefined configuration, or
'__custom'
to provide own dimensions - save : Boolean
save Whether cache response in
'resized'
data of file - size : String (optional)
Size string for
'__custom'
key, ie:'300x200'
- file : CKFinder.Models.File
Returns
- jQuery.Promise
Returns jQuery.Promise object.
Return true if CKFinder is in maximized mode.
finder.request( 'isMaximized' );
Register global key listener for given key code. When listener is registered, the keydown:NUMBER event is fired for specified key code.
finder.request( 'key:listen', { key: 65 } );
finder.on( 'keydown:65', function( evt ) {
alert('Key "a" was pressed');
} );
Parameters
- data : Object
- key : Number
Key code to listen
- key : Number
Removes global key listener for given key code.
finder.request( 'key:listen:stop', { key: 65 } );
Parameters
- data : Object
- key : Number
Key code to stop listening
- key : Number
Shows loader (spinner).
finder.request( 'loader:show', { text: 'Requesting data...' } );
Parameters
- data : Object
- text : String
Text do display
- text : String
Requests CKFinder to maximize instance.
finder.request( 'maximize' );
Requests CKFinder to minimize instance.
finder.request( 'minimize' );
Requests CKFinder to append region to page's layout. There is always a 'Main'
region with priority set to 50
which is created during page:create request.
CKFinder.require( [ 'backbone', 'marionette', 'doT' ], function( Backbone, Marionette, doT ) {
finder.on( 'page:show:Main', function() {
// Register a region inside main part of layout
finder.request( 'page:addRegion', {
page: 'Main',
name: 'myRegion',
id: finder._.uniqueId( 'my-' ),
priority: 10 // will be placed above default controls (ie. files thumbs)
} );
var MyViewClass = Marionette.ItemView.extend( {
template: doT.template('<h2>{{=it.title}}</h2>')
} );
var myView = new MyViewClass( {
model: new Backbone.Model( { title: 'My Files' } )
} );
finder.request( 'page:showInRegion', {
view: myView,
page: 'Main',
region: 'myRegion'
} );
} );
} );
Parameters
- data : Object
Definition of region
- id : String
Unique id attribute of generated region
- name : String
Name of new region
- page : String
Name of page in which region should be appended. There should always be 'Main' page.
- priority : Number (optional)
Priority in region placement. Lower values are placed before higher values.
Defaults to:
50
- className : String (optional)
Additional CSS class name for region.
- id : String
Requests page creation. A page takes the whole available space, so if a new page is created and shown then the CKFinder UI gets hidden.
Created page has always a region named 'Main' with priority equal to 50
. The view passed to request is placed in that region.
CKFinder.require( [ 'backbone', 'marionette', 'doT' ], function( Backbone, Marionette, doT ) {
var MyViewClass = Marionette.ItemView.extend( {
template: doT.template('<h2>{{=it.title}}</h2><button data-inline="true">Back to CKFinder</button></p>'),
events: {
"click button": function() {
finder.request( 'page:hide', { name: 'MyPage' } );
}
}
} );
var myView = new MyViewClass( {
model: new Backbone.Model( { title: 'My own page' } )
} );
finder.request( 'page:create', {
view: myView,
title: 'My page',
name: 'MyPage',
className: 'ckf-mypage'
} );
finder.request( 'page:show', { name: 'MyPage' } );
} );
Parameters
- data : Object
Definition of page
- view : Marionette.View (optional)
View instance that will be shown inside page. It can be any View that inherits from
Marionette.View
. If now view is passed use page:showInRegion to show a view inside a'main'
region. - name : String
Name of new page. Used to fire page:create:NAME event
- mainRegionAutoHeight : Boolean (optional)
If set to true, the main region will expand its height to fill available space. When page layout calculates region height it will trigger 'maximize' event on passed view instance.
Defaults to:
false
- className : String (optional)
Class name to be added
Defaults to:
''
- uiOptions : Object (optional)
Pass options to jQuery mobile page widget.
- view : Marionette.View (optional)
Return currently active page name. Default page in CKFinder is called Main
.
var activePageName = finder.request( 'page:current' );
if ( activePageName === 'Main' ) {
alert( 'Main page is active' );
}
Requests removing (destroying) the page. If the page to destroy is currently displayed, the previous page will be shown automatically.
finder.request( 'page:destroy', { name: 'MyPage' } );
Parameters
- data : Object
- page : String
Name of a destroyed page.
- page : String
Requests hiding a page. If the page to hide is currently displayed, the previous page will be shown automatically.
finder.request( 'page:hide', { name: 'MyPage' } );
Requests showing a page. See also page:create.
// Has no effect if the default, 'Main', page is already shown
finder.request( 'page:show', { name: 'Main' } );
Parameters
- data : Object
- page : String
Name of the page.
- page : String
Request CKFinder to display view inside registered region. See page:addRegion for a complete example.
There is always a 'Main'
region which is created during page:create request.
var MyViewClass = Marionette.ItemView.extend( {
template: doT.template('<h2>{{=it.title}}</h2>')
} );
var myView = new MyViewClass( {
model: new Backbone.Model( { title: 'My Files' } )
} );
finder.request( 'page:showInRegion', {
view: myView,
page: 'Main',
region: 'myRegion'
} );
Parameters
- data : Object
- page : String
Page in which view should rendered. There should always be 'Main' page.
- region : String
Name of region. Region should be prior instantiated with page:addRegion request.
- view : Marionette.View
View to render.
- page : String
Returns
- Boolean
Returns false if page doesn't exists or true otherwise.
Request to close (hide) panel. Panel must be created with request panel:create
finder.request( 'panel:close', { name: 'myPanel' } );
Parameters
- data : Object
- name : String
Panel name
- name : String
Requests panel creation. See Panels documentation for a complete guide.
Parameters
- data : Object
- name : String
Panel name.
- position : String
Panel position 'primary' or 'secondary'. Rendered as 'left/right' in LTR or 'right/left' in RTL.
- closeButton : Boolean
If set to true panel will be rendered with a header and a close button.
- scrollContent : Boolean
If set to true panel will have scrollbars for content that overflows panel height.
- className : String (optional)
The additional class name to add for the panel
- panelOptions : Object (optional)
Panel options. For the list of options check Panel Widget documentation
- view : Marionette.View
View instance that will be shown inside panel. It can be any View that inherits from
Marionette.View
- name : String
Closes panel and removes panel object. Panel must be created with request panel:create
finder.request( 'panel:destroy', { name: 'myPanel' } );
Parameters
- data : Object
- name : String
Panel name
- name : String
Opens panel. Panel must be created with request panel:create
finder.request( 'panel:open', { name: 'myPanel' } );
Parameters
- data : Object
- name : String
Panel name
- name : String
Request to toggle panel. Panel must be created with request panel:create
finder.request( 'panel:toggle', { name: 'myPanel' } );
Parameters
- data : Object
- name : String
Panel name
- name : String
Returns top level representation of resources.
var resources = finder.request( 'resources:get' );
resources.forEach( function( resource, index ) {
console.log( 'Resource found: ' + resource.get( 'name' ) + '!' );
} );
Returns
Request to display resource selection view. It is designed to work primary when configuration
config.displayFoldersPanel is set to false
so it might work incorrectly in other settings.
Requests creation of settings that will be displayed in the settings
panel.
finder.on( 'app:start', function() {
function logChange( evt ) {
console.log( 'Changed setting: ', evt.data );
}
finder.on( 'settings:change:mygroup:checkbox1', logChange );
finder.on( 'settings:change:mygroup:range1', logChange );
finder.on( 'settings:change:mygroup:text1', logChange );
finder.on( 'settings:change:mygroup:select1', logChange );
finder.on( 'settings:change:mygroup:radio1', logChange );
finder.request( 'settings:define', {
group: 'mygroup',
label: 'Settings demo',
settings: [
{
label: 'Checkbox',
name: 'checkbox1',
type: 'checkbox'
},
{
label: 'Range',
name: 'range1',
type: 'range',
defaultValue: 6,
attributes: {
min: 2,
max: 10,
step: 2
}
},
{
label: 'Text',
name: 'text1',
defaultValue: 'Text input'
},
{
label: 'Hidden',
name: 'hidden1',
type: 'hidden',
defaultValue: 'Must not render'
},
{
label: 'Select',
name: 'select1',
type: 'select',
defaultValue: 'b',
attributes: {
options: {
a: 'Option A',
b: 'Option B',
c: 'Option C'
}
}
},
{
label: 'Radio',
name: 'radio1',
type: 'radio',
defaultValue: 'a',
attributes: {
options: {
a: 'Radio A',
b: 'Radio B'
}
}
}
]
} );
} );
Parameters
- data : Object
- group : String
Settings group name, used to construct event names and to access settings in requests,
- label : String
Label displayed to the end user,
- settings : Array
Settings definitions
- label : String
Label displayed to the end user,
- defaultValue : String (optional)
Default value
- name : String
Setting name, used to construct event names and to access setting in requests.
- type : String (optional)
checkbox
,hidden
,radio
,range
,text
,select
Defaults to:
text
- attributes : Object (optional)
Required for
radio
,range
,select
- options : Object (optional)
Required for
radio
,select
. Available options in the form ofkey:value
.- min : Number (optional)
Required for
range
. - max : Number (optional)
Required for
range
. - step : Number (optional)
Required for
range
.
- min : Number (optional)
- options : Object (optional)
- label : String
- group : String
Requests disabling setting option.
// Disable slider for selecting size of thumbnails.
finder.request( 'settings:disable', {
group: 'files',
// Other built-in names: displayName, displaySize, displayDate
name: 'thumbSize'
} );
Parameters
- data : Object
- group : String
Setting group name
- name : String
Setting name
- group : String
Requests enabling a disabled setting option.
finder.request('settings:enable', {
group: 'files',
name: 'thumbSize'
} );
Parameters
- data : Object
- group : String
Setting group name
- name : String
Setting name
- group : String
Returns the value of a setting.
// Requests the value of a hidden CKFinder setting.
// Returns e.g. Images:/flowers/
finder.request( 'settings:getValue', {
group: 'folders',
name: 'lastFolder'
} );
Parameters
- data : Object
- group : String
Setting group name
- name : String
Setting name
- group : String
Sets the value of a setting.
finder.request( 'settings:setValue', {
group: 'mygroup',
name: 'hidden1',
value: 'new value'
} );
Parameters
- data : Object
- group : String
Setting group name
- name : String
Setting name
- value : mixed
Setting value
- group : String
Request to create a region inside status bar. Must be used after statusBar:create request.
finder.on( 'statusBar:create', function( evt ) {
if( evt.data.name === 'MyStatusBar' ) {
evt.finder.request( 'statusBar:addRegion', { name: 'MyStatusBar', id: _.uniqueId( 'my-status-' ) } );
}
} );
Parameters
- data : Object
- name : String
Name of created status bar.
- id : String
Unique id of your region.
- priority : Number (optional)
Priority in region placement.
Defaults to:
50
- name : String
Creates status bar inside a page. In order to create a status bar you will need a page created with
page:create request. The Main
page in default configuration has no
status bar so you can create a status bar for that page.
finder.request( 'statusBar:create', {
name: 'MyStatusBar',
page: 'Main',
label: 'My Status Bar'
} );
Parameters
- data : Object
- name : String
Name of created status bar.
- page : String
Page name where the status bar should be created.
- name : String
Request to destroy a Status Bar.
finder.request( 'statusBar:destroy', { name: 'MyStatusBar' } );
Parameters
- data : Object
- id : String
Unique id of your part
- id : String
Request to show a view inside a region of a status bar. Must be used after statusBar:addRegion request.
finder.on( 'statusBar:create', function( evt ) {
var messageModel = new Backbone.Model( { message: '' } );
var statusBarView = new Marionette.ItemView( {
tagName: 'p',
template: doT.template( '{{ it.message }}' ),
model: messageModel,
modelEvents: { 'change': 'render' }
} );
var id = _.uniqueId( 'my-status-bar-' );
evt.finder.request( 'statusBar:addRegion', { name: 'MyStatusBar', id: id, priority: 10 } );
evt.finder.request( 'statusBar:showView', { name: 'MyStatusBar', region: id } );
} );
finder.request( 'statusBar:create', { name: 'MyStatusBar', page: 'Main', label: 'My Status Bar' } );
Parameters
- data : Object
- name : String
Name of created status bar.
- label : String
Label for created status bar. Used by screen reader software.
- region : String
Id of of region. Region should be prior instantiated with reqyest-statusBar:addRegion request.
- view : Marionette.View
View to render.
- name : String
Creates toolbar inside a page. In order to create a toolbar you will need a page created with page:create request. A toolbar can have different configurations that are changed with toolbar:reset request.
finder.request( 'toolbar:create', {
name: 'MyToolbar',
page: 'MyPage'
} );
Parameters
- data : Object
- name : String
Name of created toolbar.
- page : String
Page name where the toolbar should be created.
- name : String
Destroys toolbar if exists.
// Destroy the main CKFinder toolbar.
finder.request( 'toolbar:destroy', { name: 'Main' } );
Parameters
- data : Object
- name : String
Name of a toolbar
- name : String
Resets toolbar and fires associated event. This request is used to add toolbar buttons. Toolbar is contextual and changes very often due to changing context. The change of context requires rendering different buttons on the same toolbar so on each context change whole toolbar is rerendered.
finder.request( 'toolbar:create', {
name: 'MyToolbar',
page: 'MyPage'
} );
// Listen to 'default' event on toolbar
finder.on( 'toolbar:reset:MyToolbar:default', function( evt ) {
evt.data.toolbar.push( {
name: 'MyToolbarAction',
type: 'button',
priority: 100,
label: 'Action',
action: function() {
alert( 'Toolbar msg: ' + evt.data.context.msg );
}
} );
} );
finder.once( 'page:show:MyPage', function() {
finder.request( 'toolbar:reset', {
name: 'MyToolbar',
event: 'default', // Name of event to fire
context: { msg: 'Action message' }
} );
} );
Parameters
- name : String
Name of toolbar
- event : String (optional)
Optional Event name that will be fired for toolbar, see toolbar:reset:NAME:EVENT. When event parameter is not passed only toolbar:reset:NAME is fired.
Returns detected mode of operation: desktop or mobile.
Returns
- String
Mode of operation. One of "mobile", "desktop".
Triggers file upload process which handle UI rendering. Depending on browser capabilities Form or HTML5 upload view will be displayed. If uploads are disabled or user has no upload rights no view will be displayed.
finder.request( 'upload' );