CKFinder 3 Documentation

Toolbar

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:

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.