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' );

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

readonlystate : NumberCKEDITOR.dialog#state

Static properties

since 4.13.0 staticCREATION_MODE : NumberCKEDITOR.dialog#CREATION_MODE

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

chainableforeach( 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.0getMode( 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.0layout()CKEDITOR.dialog#layout

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

Parameters

chainablereset() → dialogCKEDITOR.dialog#reset

Returns

resize( width, height )CKEDITOR.dialog#resize

Parameters

selectPage( id )CKEDITOR.dialog#selectPage

Parameters

since 4.5.0setState( 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 privatesetModel( newModel )CKEDITOR.dialog#setModel

Parameters

Static methods

staticadd( 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 )`