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

  • readonly

    state : Number

    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

Static properties

  • since 4.13.0 static

    CREATION_MODE : Number

    Indicates that the dialog is introducing new changes to the editor, for example inserting a newly created element as a part of a feature used with this dialog.

    Defaults to 0

  • since 4.13.0 static

    EDITING_MODE : Number

    Indicates that the dialog is modifying the existing editor state, for example updating an existing element as a part of a feature used with this dialog.

    Defaults to 1

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.

  • chainable

    foreach( fn ) → dialog

    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.

  • since 4.13.0

    getMode( editor ) → Number

    Returns the current dialog mode based on the state of the feature used with this dialog.

    In case if the dialog definition did not define the CKEDITOR.dialog.definition.getMode function, it will use the getModel method to recognize the editor mode:

    The editing mode is used when the method returns:

    Otherwise the creation mode is used.

    Parameters

    editor : editor

    Returns

    Number

    Dialog mode.

  • getModel( editor ) → element | widget | Object | null

    Returns the subject of the dialog.

    For most plugins, like the table or link plugin, it should return a DOM element instance if there is an element related to the dialog. For widget plugins (image2, placeholder) it should return a CKEDITOR.plugins.widget instance that is the subject of this dialog.

    Parameters

    editor : editor

    Returns

    element | widget | Object | null

    Returns null if the dialog does not use the model.

  • 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.

  • since 3.5.0

    layout()

    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.

  • chainable

    reset() → dialog

    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.

  • since 4.5.0

    setState( state )

    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.

  • since 4.13.0 private

    setModel( newModel )

    Sets the given model as the subject of the dialog.

    For most plugins, like the table or link plugin, the given model should be a DOM element instance if there is an element related to the dialog. For widget plugins (image2, placeholder) you should provide a CKEDITOR.plugins.widget instance that is the subject of this dialog.

    Parameters

    newModel : element | widget | Object | null

    The model to be set.

Static methods

  • static

    add( name, dialogDefinition )

    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

  • static

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

    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.

  • static

    addUIElement( typeName, builder )

    Registers a dialog UI element.

    Parameters

    typeName : String

    The name of the UI element.

    builder : Function

    The function to build the UI element.

  • static

    cancelButton()

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

  • static

    exists( name )

    Parameters

    name : Object
  • static

    getCurrent()

  • since 4.1.0 static

    isTabEnabled( editor, dialogName, tabName ) → Boolean

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

    Parameters

    editor : editor
    dialogName : String
    tabName : String

    Returns

    Boolean
  • static

    okButton()

    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
  • 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
  • since 3.5.0

    resize( evt )

    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
  • static

    resize( evt )

    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
  • selectPage( evt )

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

    Parameters

    evt : eventInfo
  • show( evt )

    Event fired when a dialog is shown.

    Parameters

    evt : eventInfo
  • since 4.5.0

    state( evt )

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

    Parameters

    evt : eventInfo