Report an issue
Class

CKEDITOR.dialog

class

This is the base class for runtime dialog objects. An instance of this class represents a single named dialog for a single editor instance.

var dialogObj = new CKEDITOR.dialog( editor, 'smiley' );

Filtering

Properties

  • state : Number

    readonly

    Current state of the dialog. Use the setState method to update it. See the state event to know more.

    Defaults to CKEDITOR.DIALOG_STATE_IDLE

Methods

  • constructor( editor, dialogName ) → dialog

    Creates a dialog class instance.

    Parameters

    editor : Object

    The editor which created the dialog.

    dialogName : String

    The dialog's registered name.

    Returns

    dialog
  • addFocusable( element, [ index ] )

    Adds element to dialog's focusable list.

    Parameters

    element : element
    [ index ] : Number
  • addPage( contents )

    Adds a tabbed page into the dialog.

    Parameters

    contents : Object

    Content definition.

  • click( id ) → Object

    Simulates a click to a dialog button in the dialog's button row.

    Parameters

    id : String

    The id of the button.

    Returns

    Object

    The return value of the dialog's click event.

  • commitContent()

    Calls the CKEDITOR.dialog.definition.uiElement.commit method of each of the UI elements, with the arguments passed through it. It is usually being called when the user confirms the dialog, to process the values.

    dialogObj.commitContent();
    
    var timestamp = ( new Date() ).valueOf();
    dialogObj.commitContent( timestamp );
    
  • disableButton( id )

    Disables a dialog button.

    Parameters

    id : String

    The id of the button.

  • enableButton( id )

    Enables a dialog button.

    Parameters

    id : String

    The id of the button.

  • foreach( fn ) → dialog

    chainable

    Executes a function for each UI element.

    Parameters

    fn : Function

    Function to execute for each UI element.

    Returns

    dialog

    The current dialog object.

  • getButton( id ) → button

    Gets the UI element of a button in the dialog's button row.

    Parameters

    id : String

    The id of the button.

    Returns

    button

    The button object.

  • getContentElement( pageId, elementId ) → uiElement

    Gets a dialog UI element object from a dialog page.

    dialogObj.getContentElement( 'tabId', 'elementId' ).setValue( 'Example' );
    

    Parameters

    pageId : String

    id of dialog page.

    elementId : String

    id of UI element.

    Returns

    uiElement

    The dialog UI element.

  • getElement() → element

    Gets the root DOM element of the dialog.

    var dialogElement = dialogObj.getElement().getFirst();
    dialogElement.setStyle( 'padding', '5px' );
    

    Returns

    element

    The <span> element containing this dialog.

  • getName() → String

    Gets the name of the dialog.

    var dialogName = dialogObj.getName();
    

    Returns

    String

    The name of this dialog.

  • getPageCount() → Number

    Gets the number of pages in the dialog.

    Returns

    Number

    Page count.

  • getParentEditor() → editor

    Gets the editor instance which opened this dialog.

    Returns

    editor

    Parent editor instances.

  • getPosition() → Object

    Gets the dialog's position in the window.

    var dialogX = dialogObj.getPosition().x;
    

    Returns

    Object
    Properties
    x : Number
    y : Number
  • getSelectedElement() → element

    Gets the element that was selected when opening the dialog, if any.

    Returns

    element

    The element that was selected, or null.

  • getSize() → Object

    Gets the current size of the dialog in pixels.

    var width = dialogObj.getSize().width;

    Returns

    Object
    Properties
    width : Number
    height : Number
  • getValueOf( pageId, elementId ) → Object

    Gets the value of a dialog UI element.

    alert( dialogObj.getValueOf( 'tabId', 'elementId' ) );
    

    Parameters

    pageId : String

    id of dialog page.

    elementId : String

    id of UI element.

    Returns

    Object

    The value of the UI element.

  • hide()

    Hides the dialog box.

    dialogObj.hide();
    
  • hidePage( id )

    Hides a page's tab away from the dialog.

    dialog.hidePage( 'tab_3' );
    

    Parameters

    id : String

    The page's Id.

  • layout()

    since 3.5.0

    Rearrange the dialog to its previous position or the middle of the window.

  • move( x, y, save )

    Moves the dialog to an (x, y) coordinate relative to the window.

    dialogObj.move( 10, 40 );

    Parameters

    x : Number

    The target x-coordinate.

    y : Number

    The target y-coordinate.

    save : Boolean

    Flag indicate whether the dialog position should be remembered on next open up.

  • reset() → dialog

    chainable

    Resets all input values in the dialog.

    dialogObj.reset();
    

    Returns

    dialog

    this

  • resize( width, height )

    Resizes the dialog.

    dialogObj.resize( 800, 640 );
    

    Parameters

    width : Number

    The width of the dialog in pixels.

    height : Number

    The height of the dialog in pixels.

  • selectPage( id )

    Activates a tab page in the dialog by its id.

    dialogObj.selectPage( 'tab_1' );
    

    Parameters

    id : String

    The id of the dialog tab to be activated.

  • setState( state )

    since 4.5.0

    Sets the dialog state.

    Parameters

    state : Number

    Either CKEDITOR.DIALOG_STATE_IDLE or CKEDITOR.DIALOG_STATE_BUSY.

  • setValueOf( pageId, elementId, value )

    Sets the value of a dialog UI element.

    dialogObj.setValueOf( 'tabId', 'elementId', 'Example' );
    

    Parameters

    pageId : String

    id of the dialog page.

    elementId : String

    id of the UI element.

    value : Object

    The new value of the UI element.

  • setupContent()

    Calls the CKEDITOR.dialog.definition.uiElement.setup method of each of the UI elements, with the arguments passed through it. It is usually being called when the dialog is opened, to put the initial value inside the field.

    dialogObj.setupContent();
    
    var timestamp = ( new Date() ).valueOf();
    dialogObj.setupContent( timestamp );
    
  • show()

    Shows the dialog box.

    dialogObj.show();
    
  • showPage( id )

    Unhides a page's tab.

    dialog.showPage( 'tab_2' );
    

    Parameters

    id : String

    The page's Id.

  • updateStyle()

    Dialog state-specific style updates.

Static methods

  • add( name, dialogDefinition )

    static

    Registers a dialog.

    // Full sample plugin, which does not only register a dialog window but also adds an item to the context menu.
    // To open the dialog window, choose "Open dialog" in the context menu.
    CKEDITOR.plugins.add( 'myplugin', {
        init: function( editor ) {
            editor.addCommand( 'mydialog',new CKEDITOR.dialogCommand( 'mydialog' ) );
    
            if ( editor.contextMenu ) {
                editor.addMenuGroup( 'mygroup', 10 );
                editor.addMenuItem( 'My Dialog', {
                    label: 'Open dialog',
                    command: 'mydialog',
                    group: 'mygroup'
                } );
                editor.contextMenu.addListener( function( element ) {
                    return { 'My Dialog': CKEDITOR.TRISTATE_OFF };
                } );
            }
    
            CKEDITOR.dialog.add( 'mydialog', function( api ) {
                // CKEDITOR.dialog.definition
                var dialogDefinition = {
                    title: 'Sample dialog',
                    minWidth: 390,
                    minHeight: 130,
                    contents: [
                        {
                            id: 'tab1',
                            label: 'Label',
                            title: 'Title',
                            expand: true,
                            padding: 0,
                            elements: [
                                {
                                    type: 'html',
                                    html: '<p>This is some sample HTML content.</p>'
                                },
                                {
                                    type: 'textarea',
                                    id: 'textareaId',
                                    rows: 4,
                                    cols: 40
                                }
                            ]
                        }
                    ],
                    buttons: [ CKEDITOR.dialog.okButton, CKEDITOR.dialog.cancelButton ],
                    onOk: function() {
                        // "this" is now a CKEDITOR.dialog object.
                        // Accessing dialog elements:
                        var textareaObj = this.getContentElement( 'tab1', 'textareaId' );
                        alert( "You have entered: " + textareaObj.getValue() );
                    }
                };
    
                return dialogDefinition;
            } );
        }
    } );
    
    CKEDITOR.replace( 'editor1', { extraPlugins: 'myplugin' } );
    

    Parameters

    name : String

    The dialog's name.

    dialogDefinition : Function | String

    A function returning the dialog's definition, or the URL to the .js file holding the function. The function should accept an argument editor which is the current editor instance, and return an object conforming to CKEDITOR.dialog.definition. CKEDITOR.dialog.definition

  • addIframe( name, title, src, minWidth, minHeight, [ onContentLoad ], [ userDefinition ] )

    static

    An iframe base dialog.

    Parameters

    name : String

    Name of the dialog.

    title : String

    Title of the dialog.

    src : String

    URL address of the dialog.

    minWidth : Number

    Minimum width of the dialog.

    minHeight : Number

    Minimum height of the dialog.

    [ onContentLoad ] : Function

    Function called when the iframe has been loaded. If it isn't specified, the inner frame is notified of the dialog events ('load', 'resize', 'ok' and 'cancel') on a function called 'onDialogEvent'.

    [ userDefinition ] : Object

    Additional properties for the dialog definition.

  • addUIElement( typeName, builder )

    static

    Registers a dialog UI element.

    Parameters

    typeName : String

    The name of the UI element.

    builder : Function

    The function to build the UI element.

  • cancelButton()

    static

    The default cancel button for dialogs. Fires the cancel event and closes the dialog if no UI element value changed.

  • exists( name )

    static

    Parameters

    name : Object
  • getCurrent()

    static

  • isTabEnabled( editor, dialogName, tabName ) → Boolean

    since 4.1.0 static

    Check whether tab wasn't removed by CKEDITOR.config.removeDialogTabs.

    Parameters

    editor : editor
    dialogName : String
    tabName : String

    Returns

    Boolean
  • okButton()

    static

    The default OK button for dialogs. Fires the ok event and closes the dialog if the event succeeds.

Events

  • cancel( evt )

    Event fired when the user tries to dismiss a dialog.

    Parameters

    evt : eventInfo
    Properties
    data : Object
    Properties
    hide : Boolean

    Whether the event should proceed or not.

  • hide( evt )

    Event fired when a dialog is hidden.

    Parameters

    evt : eventInfo
  • ok( evt )

    Event fired when the user tries to confirm a dialog.

    Parameters

    evt : eventInfo
    Properties
    data : Object
    Properties
    hide : Boolean

    Whether the event should proceed or not.

  • resize( evt )

    since 3.5.0

    Event fired when a dialog is being resized. The event is fired on both the CKEDITOR.dialog object and the dialog instance since 3.5.3, previously it was only available in the global object.

    Parameters

    evt : eventInfo
    Properties
    data : Object
    Properties
    width : Number

    The new width.

    height : Number

    The new height.

  • resize( evt )

    static

    Event fired when a dialog is being resized. The event is fired on both the CKEDITOR.dialog object and the dialog instance since 3.5.3, previously it was only available in the global object.

    Parameters

    evt : eventInfo
    Properties
    data : Object
    Properties
    dialog : dialog

    The dialog being resized (if it is fired on the dialog itself, this parameter is not sent).

    skin : String

    The skin name.

    width : Number

    The new width.

    height : Number

    The new height.

  • selectPage( evt )

    Event fired when a tab is going to be selected in a dialog.

    Parameters

    evt : eventInfo
    Properties
    data : Object
    Properties
    page : String

    The id of the page that it's gonna be selected.

    currentPage : String

    The id of the current page.

  • show( evt )

    Event fired when a dialog is shown.

    Parameters

    evt : eventInfo
  • state( evt )

    since 4.5.0

    Event fired when the dialog state changes, usually by setState.

    Parameters

    evt : eventInfo
    Properties
    data : Object
    data : Number

    The new state. Either CKEDITOR.DIALOG_STATE_IDLE or CKEDITOR.DIALOG_STATE_BUSY.