ckeditor add event handler to dialog element

Question

I'm writing a custom dialog/plugin for ckeditor. What I want to know is how I can add an eventlistener to a select box in the dialog, to alert when the selected value has been changed. How can I do this?

I've looked at the API and I've come across some useful information but it is not detailed enough. I can't make a connection between the API information and what I am trying to implement.

Answer 1

The select elements in the dialogs automatically fire a change event when they are changed. You can add an onChange function in the definition for the select element. Here's an example from the api:

onChange : function( api ) {
  // this = CKEDITOR.ui.dialog.select
  alert( 'Current value: ' + this.getValue() );
}

These pages have examples for creating definitions used by dialogs and ui elements:
Class CKEDITOR.dialog
http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.html

Class CKEDITOR.dialog.definition
http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.definition.html

Class CKEDITOR.dialog.definition.select
http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.definition.select.html

---

If you would like to listen for a change to a select element from another location, you can create a listener that keys on the "dialogShow" event. Here's an example:

// Watch for the "dialogShow" event to be fired in the editor, 
// when it's fired, perform this function
editor.on( 'dialogShow', function( dialogShowEvent )
{
  // Get any data that was sent when the "fire" method fired the dialogShow event
  var dialogShowEventData = dialogShowEvent.data;

  // Get the dialog name from the array of data 
  // that was sent when the event was fired
  var currentDialogName = dialogShowEventData._.name;
  alert( currentDialogName );

  // Create a reference to a particular element (ELEMENT-ID)
  // located on a particular tab (TAB-ID) of the dialog that was shown.
  var selectorObj = dialogShowEventData._.contents.TAB-ID.ELEMENT-ID;

  // Watch for the "change" event to be fired for the element you 
  // created a reference to (a select element in this case).
  selectorObj.on( 'change', function( changeEvent )
  {
    alert("selectorObj Changed");
  });
});

You can check if the dialog you want to work with is the one that fired the "dialogShow" event. If so, you can create an object for the select element you're interested in and listen for a "change" event.

Note: the TAB-ID and ELEMENT-ID placeholders I used do not refer to the Id attribute of the element. The Id refers to the Id assigned in the dialog definition file. The Id attribute for the various elements are different each time the dialog is loaded.

This page has some info on events:
Class CKEDITOR.event
http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.event.html

Be Well, Joe

---

Answers to additional questions asked in comments:

Q1) Your event here is 'dialogShow', what other events are allowed? i.e are they pre-defined or user defined?

A1) The 'dialogShow' event is predefined. You can look at the file containing the dialogs code in your CKEditor install directory or on the website:
ckeditor\_source\plugins\dialog\plugin.js
http://docs.cksource.com/ckeditor_api/symbols/src/plugins_dialog_plugin.js.html

If you search the file for 'fire', you'll see all the events that are fired for dialogs. The end of the file has definitions for the various events.

You can also define your own events to key on by using the "fire" method in your dialog code:

this.fire( 'yourEventNameHere', { yourPropertyOne : "propertyOneValue", yourPropertyTwo : "propertyTwoValue" } );

Then watch for it:

editor.on( 'yourEventNameHere', function( eventProperties )
{
  var propOne = eventProperties.data.yourPropertyOne; // propOne = "propertyOneValue"
  var propTwo = eventProperties.data.yourPropertyTwo; // propTwo = "propertyTwoValue"
  Do something here...
});

---

Q2) Can you explain the syntax dialogShowEventData._.name ? I've seen it before but i don't know the significance, something to do with private variables?

A2) For anyone wondering about the "._." syntax used in the CKEditor code, it's used to reduce the size of the code and replaces ".private." See this post by @AlfonsoML in the CKEditor forum:
http://cksource.com/forums/viewtopic.php?t=22982

---

Q3) Where can i get more info on TAB-ID.ELEMENT-ID?

A3) The Tab-ID is the id that you assign to a particular tab (pane) of a dialog. ( see below: id : 'tab1', )
The Element-ID is the id that you assign to a particular element contained in a tab in your dialog. ( see below: id : 'textareaId', )
Look at this page: http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.html#.add
It shows how you define the tabs and elements contained in a dialog window ( I added an example of a select element that fires a user defined event ):

var dialogDefinition =

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
            },
            // Here's an example of a select element:
            {
              type : 'select',
              id : 'sport',
              label : 'Select your favourite sport',
              items : [ [ 'Basketball' ], [ 'Baseball' ], [ 'Hockey' ], [ 'Football' ] ],
              'default' : 'Football',
              onChange : function( api ) {
                // this = CKEDITOR.ui.dialog.select
                alert( 'Current value: ' + this.getValue() );

                // CKEditor automatically fires a "change" event here, but
                // here's an example of firing your own event
                this.fire( 'sportSelector', { sportSelectorPropertyOne : "propertyOneInfo" } );
              }
          ]
        }
      ],

---

Q4) Can you briefly explain what the above code is doing?

A4) See the original code, I've added comments.