How to create an Aloha editor plugin

  • Updated

This KB article shows how to create a plugin for the Aloha editor. The sample includes a .zip file of the js needed to insert a div tag into content. 

What is an Aloha plugin? 

Plugin's are open-source, customizable pieces of JavaScript code that provide editor functionality. Ektron provides several useful plug-ins that lets you customize the editor. You can specify the editor plug-ins that you want to use in the C:\inetpub\wwwroot\siteroot\ektron.cms.framework.ui.config file.

What will you need to make a plugin for the editor?

1. A site to test and apply the plugin
2. Visual Studio or notepad to build the plug in
3. Some basic JavaScript coding knowledge.

NOTE : This applies in Ektron versions 8.70 and higher.

Prerequisite : You need to know JavaScript to extend this functionality or build your own plugin.

You can create your own plugin or modify this example.

Download the divBlock sample code zip  and add it to your site.    

If using the divBlock sample, place the divBlock folder (located in the zip file) in the following location: /Workarea/FrameworkUI/js/Ektron/Controls/EktronUI/Editor/Aloha/plugins/

The div block folder contains 2 other folders, css and lib, which are both needed for the plugin to function.

The css folder contains styling you want to apply to your plugin.

The lib folder must contain a file with the "foldername"-plugin.js (in this example, divBlock-plugin.js).

If you are creating your own, mimic the zip's folder structure and place it in the same location. Otherwise, skip to step 11.

Rename the divBlock files and folder to a name you want to give to your plugin.

Open the "filename"-plugin.js file. This file performs editor actions when the button is clicked. 

Change is the path to your css, located in the define([ section. (Note that the .css extensions are not included in the path.)

Locate the namespace section. Change it to a unique namespace for your plugin.   

Change:

var namespace = "ektron-aloha-divBlock-";

To:       

var namespace = "ektron-aloha-yourfilename-";>

In the return Plugin.create("divBlock", { line, change this to match your folder name (name of the plugin).

All the rest of the code happens in the createButton function, and other functions this may call. In the current instance of the divBlock plugin, change the tooltip and the click functions. As an example, the divBlock plugin inserts a

tag into the editor. This work happens in the insertDiv function. This function contains a method to get the selection range of the editor (where the cursor position is or what it is highlighting) and inserts a

tag at that location.

Open the css folder you created earlier. Change the path to the icon and the class name of the icon that will display in the editor.

After configuring the plugin, go to the following location and open the file.

/Workarea/FrameworkUI/js/Ektron/Controls/EktronUI/Editor/Aloha/AlohaEktron.aspx

Locate the section toolbar and locate the component: section of the tab.insert.label (shown below). Add your plugin to the components: section and save the file.

...             
label: "tab.insert.label",             
showOn: { scope: 'Aloha.continuoustext' },             
  components: [             
  [             
  'hyperlink', 'library', 'template', 'embed', 'divBlock'             
  ]             
  ]             
  ...

Go to the site root and open the ektron.cms.framework.ui.config file.

Locate the section <add name="EditInContext"></add>.

Modify each key you want to add the editor plugin you have developed to. In our instance, it would look something like: <add name="Minimal" path="...common/abbr,common/characterpicker,ektron/divBlock" default="true"></add>.

If you have this set correctly, clear your browser cache and reload the editor in the Workarea. If successful, you have a working plugin. If there are errors, they will most likely appear in the browser console (which you can view using Firebug, Chrome developer tools, or IE developer tools).