Context Menu

Contents

The aim of this article is to explain how to work with existing and custom context menus in CKFinder.

Context menu support was re-designed in CKFinder 3.1. This article describes how context menus work in CKFinder 3.0 and 3.1+ in separate sections.

CKFinder 3.1+

CKFinder comes with improved context menu support for files and folders. When the user right-clicks a file or a folder, the following events are fired:

contextMenu:file – Fired when the context menu is opened for a file.
contextMenu:folder – Fired when the context menu is opened for a folder.

You can listen to these events to create a custom context menu group.

To add items to a context menu group listen to the following events:

contextMenu:file:GROUP – Fired for each group in the context menu for a file.
contextMenu:folder:GROUP – Fired for each group in the context menu for a folder.

CKFinder uses the following context menu groups for a file:

choose
view
edit
delete

and the following groups for a folder:

edit
delete

To add a custom group to the default context menu you need to define a listener for one of the events mentioned above and provide an object with the name of the new group.

finder.on( 'contextMenu:file', function( evt ) {
    evt.data.groups.add( {
        label: 'file
    } );
} );

Note that the priority in the on event can be set to change the group position within the context menu.

To add a custom menu item to the default or defined context menu group you need to define a listener for a specific group and provide context menu items as objects with required keys as shown below:

finder.on( 'contextMenu:file:view', function( evt ) {
    evt.data.items.add( {
        label: 'Show URL',
        isActive: evt.data.context.file.get( 'folder' ).get( 'acl' ).fileView,
        icon: 'ckf-view',
        action: function() {
            alert( evt.data.context.file.getUrl() );
        }
    } );
} );

Note that the priority in the on event can be set to change the item position within the context menu group.

See the CustomButton plugin code for a complete example of a plugin that adds a custom context menu item.

Using the same events that you used to add context menu items you can also do the opposite — remove existing items.

In the example below the "Delete" button is removed from the file context menu:

finder.on( 'contextMenu:file:delete', function( evt ) {
    evt.data.items.remove( evt.data.items.findWhere( { name: 'DeleteFiles' } ) );
}, this, null, 1000);

CKFinder will not render an empty context menu group.

Note that the priority in the on event was set to a high number to make sure that all items were registered by previous listeners.

Creating Custom Context Menus

CKFinder makes it possible to create context menus using the CKFinder.Application.contextMenu request.

To create a context menu over an HTML element you should use the CKFinder.Application.contextMenu request.

The minimal required information to request a context menu is the 'name' of the context menu and the value used to calculate its position which can be an object with direct coordinates, a jQuery.Event, or a Backbone.View instance.

Direct Position Coordinates

Pass an object with x and y attributes:

finder.request( 'contextMenu', {
    name: 'CustomContextMenu',
    position: { x: 100, y: 20 }
} );

jQuery click/touch Events

Pass a jQuery.Event object:

jQuery( '#my-button' ).on( 'click', function( evt ) {
    finder.request( 'contextMenu', {
        name: 'CustomContextMenu',
        evt: evt
    } );
}

Backbone.View Instance

Alternatively you can pass a view (Backbone.View or Marionette.View) instance for which you want to create a context menu:

var myView = new Backbone.Marionette.ItemView( {
    template: doT.template('<div>Click here</div>'),
    triggers: {
        'click' : { event: 'itemclicked', preventDefault: true }
    }
} );

myView.on( 'itemclicked', function( ) {
    finder.request( 'contextMenu', {
        name: 'CustomContextMenu',
        view: myView
    } );
} );

In a similar way that items were added to the existing group in file or folder context menus, you can also add an item to your custom context menu by listening to the contextMenu:NAME and contextMenu:NAME:GROUP events:

finder.on( 'contextMenu:CustomContextMenu', function( evt ) {
    evt.data.groups.add( { name: 'default' } );
} );

finder.on( 'contextMenu:CustomContextMenu:default', function( evt ) {
    evt.data.items.add( {
        label: 'Test Me!',
        isActive: true,
        icon: 'ckf-view',
        action: function() {
            alert( 'It works' );
        }
    } );
} );

CKFinder 3.0

CKFinder comes with context menu support for files and folders. When the user right-clicks a file or a folder, the following events are fired:

contextMenu:file – Fired when the context menu is opened for a file.
contextMenu:folder – Fired when the context menu is opened for a folder.

To add a custom menu item to the default context menu you need to define a listener for one of the events mentioned above and provide a group of context menu items (or at least a group with one item).

finder.on( 'contextMenu:file', function( evt ) {
    evt.data.groups.addGroup( 'file', [
        {
            label: 'Show URL',
            isActive: evt.data.context.file.get( 'folder' ).get( 'acl' ).fileView,
            icon: 'ckf-view',
            action: function() {
                alert( evt.data.context.file.getUrl() );
            }
        }
    ] );
} );

Note that the priority in the on event can be set to change the item position within the context menu.

See the CustomButton plugin code for a complete example of a plugin that adds a custom context menu item.

Using the same events that you used to add context menu items you can also do the opposite — remove existing items.

In the example below the "Delete" button is removed from the file context menu:

finder.on('contextMenu:file', function( evt ) {
    delete evt.data.groups.groups.delete;
}, this, null, 1000);

Note that the priority in the on event was set to a high number to make sure all items were registered by previous listeners.

In a similar way that items were added to the file or folder context menus, you can also add an item to your custom context menu by listening to the contextMenu:NAME event:

finder.on( 'contextMenu:CustomContextMenu', function( evt ) {
    evt.data.groups.addGroup( 'default', [
        {
            label: 'Test Me!',
            isActive: true,
            icon: 'ckf-view',
            action: function() {
                alert( 'It works' );
            }
        }
    ] );
} );

CKFinder 3.1+

Adding Context Menu Group

Adding Context Menu Items

Custom Context Menu Example

Removing Context Menu Items