Introduction

This "How to" shows how to create a simple plug-in for the Editor, and at the same time answers some common editor plug-in questions.

Techniques

The following techniques are demonstrated:

What the Plug-in Does

Step 1: Create a Plug-In Class

Either create a new EPiServer project or open up an existing.

A new class will be created for you and added to the project. To make this class an EPiServer plug-in we need to change its inheritance and add some attributes. Modify your code to match the following:

CopyC#
using System;
using System.Data;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;

using EPiServer.Editor;
using EPiServer.Editor.Tools;

namespace EPiServerTest

{
    [EditorPlugIn( DisplayName = "Make header", 
                   Usage = ToolUsage.ContextMenu,
                   MenuGroup = "aHeaderMenu")]
    public class HeaderMakerPlugin : ToolBase, IInitializableTool
    {
        void IInitializableTool.Initialize(HtmlEditor editor)
        {
            string dialogURL = editor.CustomToolsURL + "HeaderMaker.aspx"; 
            ClientSideOnClick = String.Format("MakeHeader(this,'{0}')", dialogURL);
            ClientScriptBlock = editor.GetScriptTag("HeaderMaker.js");
            ClientSideEnabled = "IsHeaderAllowed(this)";
        }
    }
}

We define the plug-in's display name, where it will show up, etc. in the plug-in's class attributes. In this case we want it to show up as a menu item in the right-click menu, so we set the Usage to ToolUsage.ContextMenu. If we wanted the plug-in to appear in the Editor's toolbar as well, we would set the Usage to ToolUsage.ContextMenu|ToolUsage.Toolbar.

Since we implement the EPiServer.Editor.Tools.IInitializableTool interface, the Editor will notice this and call the plug-in's EPiServer.Editor.Tools.IInitializableTool.Initialize IInitializableTool.Initialize() method during startup. This is where we do our runtime initialization, like:

The editor.GetScriptTag() function above takes a javascript file and creates an HTML script block, with a path to the Editors script folder that will be sent to the browser. For example, if the applications rootdir is "/EPiServerSample/", the editor.GetScriptTag("HeaderMaker.js") call above will result in the following HTML block:

Copy 

The ClientSideEnabled property takes a javascript expression that returns a boolean, which indicates whether the plug-in should be enabled or not, at any time, in the Editor. In this case we choose to call a client-side javascript function, that we will define in the HeaderMaker.js file. The "this" keyword in the javascript statements above, for example "IsHeaderAllowed(this)", refer to the plug-in object in the browser. Each plug-in that is defined to show up on the client is represented by a unique javascript object, and all properties and methods in the object can be accessed using the "this" keyword.

Step 2: Create javascript

Create a javascript file with the following code. Save it as Util/Editor/javascript/HeaderMaker.js.

CopyC#
function MakeHeader(plugin, dialogURL)
{
    var header;
    var headerHTML;
    var args;
    var range = plugin.editorDocument.selection.createRange();  

    args = range.text;  

    header = OpenDialog(dialogURL, args, 290, 140);

    if(!header)
        return;  

    header = AddColorsToText(header);  
    range.pasteHTML(header);
} 

function AddColorsToText(text)
{
    var pos;
    var html = '';
    var colors = [ 'red','green','blue' ];  

    for(pos = 0; pos < text.length; pos++)
    {
        html += '<font color="' + colors[pos % colors.length] + 
                '">' + text.substr(pos,1) + '</font>';
    }
    html = '<h1>' + html + '</h1>';  

    return html;
} 

// Return true if text has been selected, false if an image 
// or other control is selected.
function IsHeaderAllowed(plugin)
{
 // Selection type "control" means image or some other 
 // non-text element...
    return plugin.editorDocument.selection.type.toLowerCase() == 
        'control' ? false : true;
}

There is nothing much to it; the MakeHeader() function shows the aspx (created in step 3 below) in a modal dialog window. The OpenDialog() function that we call above is defined in /Util/javascript/common.js, a file that has some useful script functions and is always included by the Editor.

Notice that we get the currently selected text and pass it in the args parameter in the OpenDialog() call. In this sample we have defined args as a string, a natural choice since we are just passing one string to the dialog. If we were to pass more than one value, we could pass the values in an array, or as properties in an object.

The "plugin" parameter used in MakeHeader() and IsHeaderAllowed() is the plug-in object that we passed as "this" in the ClientSideOnClick/ClientSideEnabled properties in the plug-in class in step 1 earlier.

The editorDocument property that is used in the code above is one of the predefined properties that are available in all client-side plugin objects.

Step 3 - Create the dialog

For the dialog we need an aspx file, so let's create one. Replace the default content on the aspx page with the text below. Save the .aspx page in the UI/Editor/Dialogs directory (that is where the CustomToolsURL property in the Editor is targeting by default).

Modify your markup to match the following:

Copy 
<%@ Page language="c#" 
        Inherits="EPiServerTest.HeaderPluginDialog" 
        Codebehind="HeaderPluginDialog.aspx.cs" %>




  


    

Enter some text for the header:




The text that is currently selected in the Editor, that we passed as the args parameter in the OpenDialog() call in step 2, is accessed using the dialogArguments property (it is actually window.dialogArguments, but we can omit the "window." part since we are executing in a dialog window).

We return any values from the dialog using the returnValue property (also a property on the window object).

The aspx code-behind class doesn't need any specific code in this sample, since we do everything we need using javascript on the .aspx page.

CopyC#
namespace EPiServerTest
{
    public partial class HeaderPluginDialog : EPiServer.TemplatePage
    {
        protected void Page_Load(object sender, EventArgs e)
        {
        }
    }
}

And that's it- just compile the code and try it out.