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

readonly
state : Number

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

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

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

See source
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 ] )

See source
Adds element to dialog's focusable list.

Parameters

element : element

[ index ] : Number
addPage( contents )

See source
Adds a tabbed page into the dialog.

Parameters

contents : Object

Content definition.
click( id ) → Object

See source
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()
See source
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 )

See source
Disables a dialog button.

Parameters

id : String

The id of the button.
enableButton( id )

See source
Enables a dialog button.

Parameters

id : String

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

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

See source
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
See source
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
See source
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
See source
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:
- 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

See source
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
See source
Gets the name of the dialog.
```
var dialogName = dialogObj.getName();
```
Returns

String

The name of this dialog.
getPageCount() → Number

See source
Gets the number of pages in the dialog.

Returns

Number

Page count.
getParentEditor() → editor

See source
Gets the editor instance which opened this dialog.

Returns

editor

Parent editor instances.
getPosition() → Object
See source
Gets the dialog's position in the window.
```
var dialogX = dialogObj.getPosition().x;
```
Returns

Object

Properties

x : Number

y : Number
getSelectedElement() → element

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

Returns

element

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

See source
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
See source
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()
See source
Hides the dialog box.
```
dialogObj.hide();
```
hidePage( id )
See source
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()

See source
Rearrange the dialog to its previous position or the middle of the window.
move( x, y, save )

See source
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
See source
Resets all input values in the dialog.
```
dialogObj.reset();
```
Returns

dialog

this
resize( width, height )
See source
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 )
See source
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 )

See source
Sets the dialog state.

Parameters

state : Number

Either CKEDITOR.DIALOG_STATE_IDLE or CKEDITOR.DIALOG_STATE_BUSY.
setValueOf( pageId, elementId, value )
See source
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()
See source
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()
See source
Shows the dialog box.
```
dialogObj.show();
```
showPage( id )
See source
Unhides a page's tab.
```
dialog.showPage( 'tab_2' );
```
Parameters

id : String

The page's Id.
updateStyle()

See source
Dialog state-specific style updates.
since 4.13.0 private
setModel( newModel )

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

See source

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 ] )

See source
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 )

See source
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()

See source
The default cancel button for dialogs. Fires the cancel event and closes the dialog if no UI element value changed.
static
exists( name )

See source

Parameters

name : Object
static
getCurrent()

See source
since 4.1.0 static
isTabEnabled( editor, dialogName, tabName ) → Boolean

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

Parameters

editor : editor

dialogName : String

tabName : String

Returns

Boolean
static
okButton()

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

Events

cancel( evt )

See source
Event fired when the user tries to dismiss a dialog.

Parameters

evt : eventInfo
hide( evt )

See source
Event fired when a dialog is hidden.

Parameters

evt : eventInfo
ok( evt )

See source
Event fired when the user tries to confirm a dialog.

Parameters

evt : eventInfo
since 3.5.0
resize( evt )

See source
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 )

See source
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 )

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

Parameters

evt : eventInfo
show( evt )

See source
Event fired when a dialog is shown.

Parameters

evt : eventInfo
since 4.5.0
state( evt )

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

Parameters

evt : eventInfo

CKEDITOR.dialog

Filtering

Properties

readonly state : NumberCKEDITOR.dialog#state

Static properties

since 4.13.0 static CREATION_MODE : NumberCKEDITOR.dialog#CREATION_MODE

since 4.13.0 static 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

chainable 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

since 4.13.0 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

since 3.5.0 layout()CKEDITOR.dialog#layout

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

Parameters

chainable reset() → dialogCKEDITOR.dialog#reset

Returns

resize( width, height )CKEDITOR.dialog#resize

Parameters

selectPage( id )CKEDITOR.dialog#selectPage

Parameters

since 4.5.0 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

since 4.13.0 private setModel( newModel )CKEDITOR.dialog#setModel

Parameters

Static methods

static add( name, dialogDefinition )CKEDITOR.dialog#add

readonly
`state : Number`

since 4.13.0 static
`CREATION_MODE : Number`

since 4.13.0 static
`EDITING_MODE : Number`

`constructor( editor, dialogName ) → dialog`

`addFocusable( element, [ index ] )`

`addPage( contents )`

`click( id ) → Object`

`commitContent()`

`disableButton( id )`

`enableButton( id )`

chainable
`foreach( fn ) → dialog`

`getButton( id ) → button`

`getContentElement( pageId, elementId ) → uiElement`

`getElement() → element`

since 4.13.0
`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 )`

since 3.5.0
`layout()`

`move( x, y, save )`

chainable
`reset() → dialog`

`resize( width, height )`

`selectPage( id )`

since 4.5.0
`setState( state )`

`setValueOf( pageId, elementId, value )`

`setupContent()`

`show()`

`showPage( id )`

`updateStyle()`

since 4.13.0 private
`setModel( newModel )`

static
`add( name, dialogDefinition )`

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

static
`addUIElement( typeName, builder )`

static
`cancelButton()`

static
`exists( name )`

static
`getCurrent()`

since 4.1.0 static
`isTabEnabled( editor, dialogName, tabName ) → Boolean`

static
`okButton()`

`cancel( evt )`

`hide( evt )`

`ok( evt )`

since 3.5.0
`resize( evt )`

static
`resize( evt )`

`selectPage( evt )`

`show( evt )`

since 4.5.0
`state( evt )`