Create Plugin With Dialog

 This is a summary tutorial based on the following:

http://docs.ckeditor.com/#!/guide/plugin_sdk_sample_1

http://docs.ckeditor.com/#!/guide/plugin_sdk_sample_2

Folder Structure

Before we can create a plugin, we must first understand the folder structure of a plugin.

  • mypluginname/ - this folder name is also the name of your plugin
    • icons/
      • mypluginname.png - (16x16 png image)
      • hidpi/    - higher resolution for hi-density displays
        • mypluginname.png - (32x32 png image)
    • dialogs - store dialog code, folder can be named anything
      • mypluginname.js - dialog code, file can be name anything
      • plugin.js  - ckeditor expects to find a plugin.js file
    To simply things lets name our plugin "abbr". Therefore our folder structure should look like this:
    • abbr/
      • icons/
        • abbr.png
        • hidpi/
          • abbr.png
      • dialogs 
        • abbr.js 
      • plugin.js

     

    plugin.js Source Code

     

    //NOTE: the first parameter needs to be the name of your plugin.
    CKEDITOR.plugins.add( 'abbr', {
      icons: 'abbr',
      init: function( editor ) {
    
        //create a command for our plugin called
        //when the command is executed it will open a dialog window.
        //we gave this new window the identifier of "abbrDialog"
        //"abbrDialog" can be use to identify the window
        editor.addCommand( 'abbr', new CKEDITOR.dialogCommand( 'abbrDialog' ) );
    
        //add a button to the toolbar.
        //when the button is clicked it will execute the "abbr" command
        //which will open the dialog window
        editor.ui.addButton( 'Abbr', {
          label: 'Insert Abbreviation',
          command: 'abbr',
          toolbar: 'insert'
        });
    
        //the specific code to run when the dialog opens can be defined in
        //another file. "abbrDialog" is the dialog we registered above.
        //we also pass the path to the file to run. 
        //CKEDITOR.dialog.add( 'abbrDialog', this.path + 'dialogs/abbr.js' );
        //most examples I've found uses "this.path" to get the plugin directory
        //but i was getting an error with this approach
        //therefore i used CKEDITOR.plugins.getPath() to get the path to the plugin dir
        CKEDITOR.dialog.add( 'iconLink', CKEDITOR.plugins.getPath( 'abbr' ) + 'dialogs/abbr.js );
        
      }
    });

    The Dialog Definition

    Now we need to code the dialog/abbr.js file. We'll need to add the following to our file.
    We return the definition of our dialog which describes everything that should be on the dialog page such as input fields, text etc. See CKEditor.dialog.definition for all the properties of a dialog definition.

    //in our dialog/abbr.js file
    CKEDITOR.dialog.add( 'abbrDialog', function ( editor ) {
        return {
        };
    });

    Dialog Source Code

    Define our dialog window and fields in our dialg/abbr.js file.

    //dialog/abbr.js file
    //NOTE: "abbrDialog" is the name of the dialog to be opened 
    //this was defined in the init function of our plugin file
    //with this line CKEDITOR.dialogCommand( 'abbrDialog' )
    CKEDITOR.dialog.add( 'abbrDialog', function( editor ) {
      return {
        title: 'Abbreviation Properties',
        minWidth: 400, //window minimum width
        minHeight: 200,//window minimum height
        //now we need to define the content of the page
        contents: [
          //the page will have 2 tabs.
          //this is the first tab.
          {
            id: 'tab-basic',//identify the tab with a unique ID
            label: 'Basic Settings',//label text for tab
            //define the fields that will be on this tab.
            elements: [
              //define a text input field
              {
                type: 'text',
                id: 'abbr', //use to identify this field and get value during processing
                label: 'Abbreviation',
                validate: CKEDITOR.dialog.validate.notEmpty( "Abbreviation required." )
              },
              //define another text input field
              {
                type: 'text',
                id: 'title',//use to identify this field and get value during processing
                label: 'Explanation',
                validate: CKEDITOR.dialog.validate.notEmpty( "Explanation required" )
              }
            ]
          },
          //this is the second tab.
          {
            id: 'tab-adv',//identify the tab with a unique ID
            label: 'Advanced Settings',//label text for tab
            //define the fields that will be on this tab.
            elements: [
              //define a text input field
              {
                type: 'text',
                id: 'id', //use to identify this field and get value during processing
                label: 'Id'
              }
            ]
          }
        ],
        onOk: function() {
           //CODE to execute when the users presses the ok button
        }
      };
    });

    Access Dialog Field Value

    We use the dialog.getValueOf() method to get the value of a field from the dialog. Within the onOK: method we defined above, the title value can be accessed with the following code:

    onOk: function() {
       var dialog = this;
        //specify the tab and the field.
        var title = dialog.getValueOf( 'tab-basic', 'title' );
    
         //we could insert the text into the editor at the current cursor position
         editor.insertHtml('The title is:'+title);
    }

    Dialog Elements

    There are a number of input elements that can be used on the dialog page.

    Elements such as Select, Textarea, Checkboxes. etc

    A list can be found  here.

     

    Cookbook Category: 

    Add new comment

    Plain text

    • No HTML tags allowed.
    • Lines and paragraphs break automatically.
    CAPTCHA
    This question is for testing whether or not you are a human visitor and to prevent automated spam submissions.