"Collapse" button plugin for CKEditor for Drupal

Submitted by mishutka on

Several days ago I needed to add an ability to add "spoilers" to comments and nodes at VELOBY.NET web site (Minsk's cycling community). Spoiler is a part of text, that is hidden from viewing by default. It expands by click showing previously hidden content to users.

I've googled nice Collapse Text module for Drupal. Installed it, enabled in input format settings. Everything is fine with it.

We use CKEditor as wysiwyg-editor on VELOBY.NET. And I wanted to add a button to its toolbar, to be able to insert [collapsed]...[/collapsed] meta tags before and after text, selected in editor. Googling almost an hour gave me nothing. So I decided to write own plugin for CKEditor with this functionality.

This small article is about creating this plugin.

There is a really good tutorial Creating a Simple CKEditor Plugin. So I'm not reproducing whole plugin creation process here step-by-step. There will be only comments about final plugin code. Full source code is attached at the end of article.

First of all we think of name for new plugin and create a folder with this name. I chose mtcollapsed as plugin name.

Our plugin will add a button to editor's toolbar, so let take care about icon for it before starting coding. It should be 16x16 pixels, and I prefer PNG format. This is what I drew: . Gave it name button.png and put into our mtcollapsed directory.

Then I created an empty plugin.js file to put plugin code in. Our plugin consists of 3 parts: command, toolbar button, and dialog.

Command is really simple:

editor.addCommand('cmdMTCollapsedDialog', new CKEDITOR.dialogCommand('mtcollapsedDialog'));

It adds command cmdMTCollapsedDialog that shows mtcollapsedDialog dialog.

Adding a toolbar is simple and easy to understand too:

editor.ui.addButton('MTcollapsed', { label: 'Insert spoiler', command: 'cmdMTCollapsedDialog', icon: this.path + 'button.png' });

This adds a button with MTcollapsed name with Insert spoiler label (tooltip), with our button.png as button's icon. Clicking this button executes our cmdMTCollapsedDialog command.

And here is most complicated part - dialog:

CKEDITOR.dialog.add( 'mtcollapsedDialog', function ( editor )
    {
      return
      {
        title : 'Spoiler settings',
        minWidth : 300,
        minHeight : 200,
        contents :
        [{
          id : 'tab1',
          label : 'Settings',
          elements :
          [{
            type : 'text',
            id : 'title',
            label : 'Spoiler title',
            onShow : function() { this.setValue('Hidden text'); },
            validate : CKEDITOR.dialog.validate.notEmpty( "Spoiler title should be provided" )
          }]
        }],
        onOk : function()
               {
                 var dialog = this;
                 var title = dialog.getValueOf( 'tab1', 'title' );
 
                 var openTag = '[collapsed title=' + title + ']';
                 var closeTag = '[/collapsed]';
                 var inplaceTag = ' ' + openTag + ' text ' + closeTag + ' ';
 
                 var S = editor.getSelection();
 
                 if( S == null)
                 {
                   editor.insertHtml(inplaceTag);
                   return;
                 }
 
                 var R = S.getRanges();
                 R = R[0];
     
                 if( R == null)
                 {
                   editor.insertHtml(inplaceTag);
                   return;
                 }
 
                 var startPos = Math.min(R.startOffset, R.endOffset);
                 var endPos = Math.max(R.startOffset, R.endOffset);
                 
                 if( startPos == endPos )
                 { editor.insertHtml(inplaceTag); return; }
 
                 var container = new CKEDITOR.dom.element('p');
                 var fragment = R.extractContents();
                 
                 container.appendText(openTag);                  
                 fragment.appendTo(container);  
                 container.appendText(closeTag);
 
                 editor.insertElement(container);
               }
      };
    });

Lines 5-7: dialog parameters setup. Dialogs params described here.

Lines 8-20: Dialog's GUI elements. We just need one textbox (type = 'text') for user to be able to provide a title for hidden text. Line 17 sets default value for this textbox. Line 18 obliges user to provide a title.

Default dialog has two buttons: OK and Cancel. Cancel button just closes dialog without any other actions. Clicking OK button raises onOk event where most work is done (lines 21-61):

Line 24: accessing value provided by user in textbox.

Lines 26-28: preparing meta tags code to insert into editor. If there is a text selected open and close tags inserted before and after this text. If there are no text selected inline open-close metatag inserted ([collapsed title='title text'][/collapsed]).

Lines 30-36: Check if there is a selection in editor. Insert inline open-close metatag at cursor position if there is no selection.

Lines 38-45: Selection consists of ranges. We need first range of selection (actually there is alway just one range in selection). Insert inline open-close metatag at cursor position if there is no first range.

Lines 47-51: Sometimes there is a selection with a range, but this range starts and ends at the same position. This means that nothing still selected. Same thing: insert inline open-close metatag at cursor position.

If there is a selection wit a range we should create a container for its contents (because there could be severals elements selected, for example two paragraphs or paragrah and image).

Lines 53-54: Create container element and prepare range contents.

Lines 56-58: Adding open tag, range contents and close tag to our container.

Line 60: Insert container to editor at cursor position (replacing current selection).

Thats all! Full plugin.js source is in archive attached at the end of this article.

Now we should add our plugin to Drupal's CKEditor. There are two ways of adding plugind to CKEditor in Drupal:

  • An easy one: just putting your plugin into "plugins" folder in CKEditor's module directory. This is really easy. But you'll have to keep this in mind everytime you updating the CKEditor module.
  • As part of own module: you should create owm Drupal module, or add some code to a new one.

I have own module on VELOBY.NET site already, so second way is right for me. But you can try to experiment with first one. it should work as well. To add CKEditor plugin with own module your module should implement hook_ckeditor_plugin hook function. This hook should return an array with plugin definitions. There is only one plugin in our case.

This is what I've added to my velobynet.module file:

/**
* CKEditor plugins hook
*/
function velobynet_ckeditor_plugin() {
  return array(
        'mtcollapsed' => array(
            'name' => 'mtcollapsed',
            'desc' => 'MTCollapsed - ' . t('Inserts [collapsed][/collapsed] tags'),
            'path' => drupal_get_path('module', 'velobynet') . '/ckeditor-plugins/mtcollapsed/',
            'buttons' => array(
                'MTcollapsed' => array('label' => 'Insert spoiler',
                                       'icon' => 'button.png' ),
            )
        )
    );
}

Line 7: Plugin name.

Line 8: Plugin description to show at CKEditor's settings page.

Line 9: Full path (with trailing slash) to plugin folder.

Lines 10-13: Plugin buttons definitions (optional). We define just one button with 'Insert spoiler' label and button.png icon.

After adding this we can enable plugin in some CKEditor's profile settings, and try how it works.

Thank you for reading this and excuse me for my English, it is far from perfect yet .

Please contact us if you have any questions.

Module was tested with Drupal v.6.24, CKEditor (itself) v.3.6.2 and CKEditor (Drupal module) v6.x-1.8.

Downloads