Dialog Windows

The aim of this article is to explain how to work with dialog windows in CKFinder.

CKFinder makes it possible to create dialog windows using the dialog request. There are also two requests available for creating simple, but frequently used dialog windows with less effort:

• dialog:info – Creates a dialog window with a message.
• dialog:confirm – Creates a dialog window with a message and two buttons: "OK" for confirmation and "Cancel" for canceling.

Information Dialog Window

Information dialogs are useful for displaying messages with medium or low importance to users as they are easy to dismiss.

finder.request( 'dialog:info', { msg: 'The file was successfully sent to joe@example.com.' } );

Confirmation Dialog Window

You can use confirmation dialogs to ask the user simple yes/no questions.

finder.on( 'dialog:ConfirmSendFile:ok', function( evt ) {
    var email = evt.data.context.email;
    alert( 'Sending the file to ' + email );
} );

finder.request( 'dialog:confirm', {
    msg: 'Do you really want to send the file?',
    name: 'ConfirmSendFile',
    context: { email: 'joe@example.com' }
} );

Custom Dialog Window

Custom dialog windows are useful when you want to create more complex dialogs. You can pass a template string as the template parameter to the CKFinder.Application.dialog request and if needed, also pass a model instance as the templateModel parameter.

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: {
        cancel: 'cancel',
        // Define a custom 'download' button.
        download: {
            label: 'Download'
        }
    }
} );

// Event listener for the custom 'download' button.
finder.on( 'dialog:DownloadDialog:download', function( evt ) {
    alert( 'Downloading ' + evt.data.view.$el.find( '[name="filename"]' ).val() );
} );

Example

For a complete example of a plugin that adds a custom dialog window, check the CustomDialog plugin from sample CKFinder plugins.

Dialog Window Buttons

When providing a dialog definition it is possible to specify the buttons that would be displayed at the bottom of the dialog. Both predefined and custom buttons are supported.

When predefined buttons are used, it is enough to list them in an array:

buttons: [ 'okClose', 'cancel' ]

When defining custom buttons, the button label must be provided:

buttons: {
    // Define a custom 'download' button.
    download: {
        label: 'Download'
    }
}

For custom buttons the dialog:NAME:BUTTON event is fired automatically:

// Event listener for the custom 'download' button.
finder.on( 'dialog:DownloadDialog:download', function( evt ) {
    // Do something...
} );

Custom Dialog Window with a View Instance

You can create even more complex dialog windows using custom views. In order to use a view instance, pass the view parameter to CKFinder.Application.dialog request.

var model = new finder.Backbone.Model( { text: 'archive.zip' } );

var view = new finder.Backbone.Marionette.ItemView( {
    template: finder.doT.template( '<div><label>Download selected files as:<input value="{{= it.text }}" name="filename"></label></div>' ),
    model: model
} );

finder.request( 'dialog', {
    name: 'DownloadDialog',
    title: 'Download As',
    view: view,
    buttons: [
        'cancel',
        {
            name: Download,
            label: 'Download'
        }
    ]
} );

finder.on( 'dialog:DownloadDialog:download', function( evt ) {
    alert( 'Downloading ' + evt.data.view.$el.find( '[name="filename"]' ).val() );
} );