Toolbar
Contents
The aim of this article is to explain how to work with toolbars.
Main Toolbar
CKFinder comes with a contextual toolbar (code name: main
) that appears at the top of the application. The buttons that appear in the toolbar depend on the current location and selection.
Whenever selection changes inside the CKFinder main page, an event is fired allowing plugins to register their button for a particular context:
- toolbar:reset:Main:file – Fired if a single file is selected.
- toolbar:reset:Main:files – Fired if multiple files are selected.
- toolbar:reset:Main:folder – Fired if a folder or a resource type is selected.
- toolbar:reset:Main:resources – Fired if resource types are shown when config.displayFoldersPanel is set to
false
.
It is also possible to listen to an event that is fired whenever the main
toolbar is reset regardless of the selection using the toolbar:reset:Main event.
Adding a Button to an Existing Toolbar
Knowing that toolbar:reset:Main
events are fired whenever the user does an action that results in a toolbar change, you may use it to add custom toolbar items to it. The information passed as evt.data
can be used to conditionally enable a button depending e.g. on the type of the file selected.
finder.on( 'toolbar:reset:Main:file', function( evt ) {
evt.data.toolbar.push( {
type: 'button',
priority: 100,
label: 'Show name',
action: function() {
var files = evt.finder.request( 'files:getSelected' ).toArray();
alert( files[ 0 ].get( 'name' ) )
}
} );
} );
Example 1
See the CustomButton plugin for a complete example of a plugin that adds a button with a custom icon.
Removing a Button from the Toolbar
The same event that was used for adding a button can also be used to remove buttons from the toolbar.
In the example below the "View" option is removed from the file toolbar. Note that the priority in the on event was set to a high number to make sure all buttons were registered by previous listeners.
finder.on( 'toolbar:reset:Main:file', function( evt ) {
var toRemove = [];
evt.data.toolbar.forEach( function( button, index, toolbar ) {
if ( button.get( 'name' ) == 'View' ) {
toRemove.push( button );
}
} );
evt.data.toolbar.remove( toRemove );
}, this, null, 1000 );
Creating a Custom Toolbar
In order to create a toolbar you will need to create a page in which the toolbar will be displayed.
After a page is created you can add a toolbar to it using the toolbar:create request.
finder.request( 'toolbar:create', {
name: 'MyToolbar',
page: 'MyPage'
} );
Buttons are added to the toolbar on the toolbar:reset:NAME event, which is automatically fired when toolbar:reset is requested.
// Request resetting the toolbar when the page is shown.
finder.once( 'page:show:MyPage', function() {
finder.request( 'toolbar:reset', { name: 'MyToolbar' } );
} );
Now, when the toolbar:reset:NAME event is fired, you can use it to register custom toolbar items:
// When MyToolbar is reset, add a button to it.
finder.on( 'toolbar:reset:MyToolbar', function( evt ) {
evt.data.toolbar.push( {
icon: 'ckf-view',
label: 'Test me!',
type: 'button',
action: function() {
alert( 'It works!' );
}
} );
} );
Example 2
For a complete example of a plugin that adds a custom page and a toolbar, check the CustomPage plugin.