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

Public
Inherited
Mixed
Protected
Private
Deprecated

Properties

state : Number

readonly

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

See source

Defaults to CKEDITOR.DIALOG_STATE_IDLE

Static properties

CREATION_MODE : Number

since 4.13.0 static

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.

See source

Defaults to 0
EDITING_MODE : Number

since 4.13.0 static

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.

See source

Defaults to 1

Methods

constructor( editor, dialogName ) → dialog

Creates a dialog class instance.

See source

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.

See source

Parameters

element : element

[ index ] : Number
addPage( contents )

Adds a tabbed page into the dialog.

See source

Parameters

contents : Object

Content definition.
click( id ) → Object

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

See source

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.

See source
```
dialogObj.commitContent();

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

Disables a dialog button.

See source

Parameters

id : String

The id of the button.
enableButton( id )

Enables a dialog button.

See source

Parameters

id : String

The id of the button.
foreach( fn ) → dialog

chainable

Executes a function for each UI element.

See source

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.

See source

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.

See source
```
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.

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

element

The <span> element containing this dialog.
getMode( editor ) → Number

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

See source
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:
- A CKEDITOR.dom.element attached to the DOM.
- A CKEDITOR.plugins.widget instance.
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.

See source

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.

See source
```
var dialogName = dialogObj.getName();
```
Returns

String

The name of this dialog.
getPageCount() → Number

Gets the number of pages in the dialog.

See source

Returns

Number

Page count.
getParentEditor() → editor

Gets the editor instance which opened this dialog.

See source

Returns

editor

Parent editor instances.
getPosition() → Object
Gets the dialog's position in the window.

See source
```
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.

See source

Returns

element

The element that was selected, or null.
getSize() → Object

Gets the current size of the dialog in pixels.

See source

var width = dialogObj.getSize().width;

Returns

Object

Properties

width : Number

height : Number
getValueOf( pageId, elementId ) → Object
Gets the value of a dialog UI element.

See source
```
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.

See source
```
dialogObj.hide();
```
hidePage( id )
Hides a page's tab away from the dialog.

See source
```
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.

See source
move( x, y, save )

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

See source

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.

See source
```
dialogObj.reset();
```
Returns

dialog

this
resize( width, height )
Resizes the dialog.

See source
```
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.

See source
```
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.

See source

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.

See source
```
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.

See source
```
dialogObj.setupContent();

var timestamp = ( new Date() ).valueOf();
dialogObj.setupContent( timestamp );
```
show()
Shows the dialog box.

See source
```
dialogObj.show();
```
showPage( id )
Unhides a page's tab.

See source
```
dialog.showPage( 'tab_2' );
```
Parameters

id : String

The page's Id.
updateStyle()

Dialog state-specific style updates.

See source
setModel( newModel )

since 4.13.0 private

Sets the given model as the subject of the dialog.

See source

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

`add( name, dialogDefinition )`

static

Registers a dialog.

See source

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

See source

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.

See source

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.

See source
exists( name )

static

See source

Parameters

name : Object
getCurrent()

static

See source
isTabEnabled( editor, dialogName, tabName ) → Boolean

since 4.1.0 static

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

See source

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.

See source

Events

cancel( evt )

Event fired when the user tries to dismiss a dialog.

See source

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.

See source

Parameters

evt : eventInfo
ok( evt )

Event fired when the user tries to confirm a dialog.

See source

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.

See source

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.

See source

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.

See source

Parameters

evt : eventInfo

Properties

data : Object

Properties

page : String

The ID of the page that is going to be selected.

currentPage : String

The ID of the current page.
show( evt )

Event fired when a dialog is shown.

See source

Parameters

evt : eventInfo
state( evt )

since 4.5.0

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

See source

Parameters

evt : eventInfo

Properties

data : Object

data : Number

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

CKEDITOR.dialog

Filtering

Properties

state : NumberCKEDITOR.dialog#state

Static properties

CREATION_MODE : NumberCKEDITOR.dialog#CREATION_MODE

EDITING_MODE : NumberCKEDITOR.dialog#EDITING_MODE

Methods

constructor( editor, dialogName ) → dialogCKEDITOR.dialog#constructor

Parameters

Returns

addFocusable( element, [ index ] )CKEDITOR.dialog#addFocusable

Parameters

addPage( contents )CKEDITOR.dialog#addPage

Parameters

click( id ) → ObjectCKEDITOR.dialog#click

Parameters

Returns

commitContent()CKEDITOR.dialog#commitContent

disableButton( id )CKEDITOR.dialog#disableButton

Parameters

enableButton( id )CKEDITOR.dialog#enableButton

Parameters

foreach( fn ) → dialogCKEDITOR.dialog#foreach

Parameters

Returns

getButton( id ) → buttonCKEDITOR.dialog#getButton

Parameters

Returns

getContentElement( pageId, elementId ) → uiElementCKEDITOR.dialog#getContentElement

Parameters

Returns

getElement() → elementCKEDITOR.dialog#getElement

Returns

getMode( editor ) → NumberCKEDITOR.dialog#getMode

Parameters

Returns

getModel( editor ) → element | widget | Object | nullCKEDITOR.dialog#getModel

Parameters

Returns

getName() → StringCKEDITOR.dialog#getName

Returns

getPageCount() → NumberCKEDITOR.dialog#getPageCount

Returns

getParentEditor() → editorCKEDITOR.dialog#getParentEditor

Returns

getPosition() → ObjectCKEDITOR.dialog#getPosition

Returns

getSelectedElement() → elementCKEDITOR.dialog#getSelectedElement

Returns

getSize() → ObjectCKEDITOR.dialog#getSize

Returns

getValueOf( pageId, elementId ) → ObjectCKEDITOR.dialog#getValueOf

Parameters

Returns

hide()CKEDITOR.dialog#hide

hidePage( id )CKEDITOR.dialog#hidePage

Parameters

layout()CKEDITOR.dialog#layout

move( x, y, save )CKEDITOR.dialog#move

Parameters

reset() → dialogCKEDITOR.dialog#reset

Returns

resize( width, height )CKEDITOR.dialog#resize

Parameters

selectPage( id )CKEDITOR.dialog#selectPage

Parameters

setState( state )CKEDITOR.dialog#setState

Parameters

setValueOf( pageId, elementId, value )CKEDITOR.dialog#setValueOf

Parameters

setupContent()CKEDITOR.dialog#setupContent

show()CKEDITOR.dialog#show

showPage( id )CKEDITOR.dialog#showPage

Parameters

updateStyle()CKEDITOR.dialog#updateStyle

setModel( newModel )CKEDITOR.dialog#setModel

Parameters

Static methods

add( name, dialogDefinition )CKEDITOR.dialog#add

`state : Number`

`CREATION_MODE : Number`

`EDITING_MODE : Number`

`constructor( editor, dialogName ) → dialog`

`addFocusable( element, [ index ] )`

`addPage( contents )`

`click( id ) → Object`

`commitContent()`

`disableButton( id )`

`enableButton( id )`

`foreach( fn ) → dialog`

`getButton( id ) → button`

`getContentElement( pageId, elementId ) → uiElement`

`getElement() → element`

`getMode( editor ) → Number`

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

`getName() → String`

`getPageCount() → Number`

`getParentEditor() → editor`

`getPosition() → Object`

`getSelectedElement() → element`

`getSize() → Object`

`getValueOf( pageId, elementId ) → Object`

`hide()`

`hidePage( id )`

`layout()`

`move( x, y, save )`

`reset() → dialog`

`resize( width, height )`

`selectPage( id )`

`setState( state )`

`setValueOf( pageId, elementId, value )`

`setupContent()`

`show()`

`showPage( id )`

`updateStyle()`

`setModel( newModel )`

`add( name, dialogDefinition )`

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

`addUIElement( typeName, builder )`

`cancelButton()`

`exists( name )`

`getCurrent()`

`isTabEnabled( editor, dialogName, tabName ) → Boolean`

`okButton()`

`cancel( evt )`

`hide( evt )`

`ok( evt )`

`resize( evt )`

`resize( evt )`

`selectPage( evt )`

`show( evt )`

`state( evt )`