Home > Programming, Tridion > Setting up a Tridion 2011 GUI extension in 8 steps

Setting up a Tridion 2011 GUI extension in 8 steps


The new 2011 Tridion GUI framework is a major overhaul to the way extensions have been previously developed. The framework now is far more robust and well designed. Building new and exciting extensions has never been easier. However, configuring your extension may not be the easiest thing in the world to do…

The following tutorial steps show how to configure an extension for the Tridion 2011 GUI from start to finish.

The example configuration and code is based on my extension: The Item XML Display.

The Steps

1)      Decide on a disk location (typically on the CMS server) where you will create your extension in. Something like: “C:\Extensions” will do.

2)      Create a “config” folder under your chosen location (c:\Extensions\config).

3)      Create an “extension.config” file in your “config” folder.

4)      Start with the following XML, simply copy it into the “extension.config” file:

<?xml version=”1.0″?>
<Configuration xmlns=”http://www.sdltridion.com/2009/GUI/Configuration/Merge&#8221; xmlns:cfg=”http://www.sdltridion.com/2009/GUI/Configuration&#8221; xmlns:ext=”http://www.sdltridion.com/2009/GUI/extensions&#8221; xmlns:cmenu=”http://www.sdltridion.com/2009/GUI/extensions/ContextMenu&#8221;>
<resources cache=”true”>
<cfg:filters/>
<cfg:groups/>
</resources>
<definitionfiles/>
<extensions>
<ext:editorextensions/>
<ext:dataextenders/>
</extensions>
<commands/>
<contextmenus/>
<localization/>
<settings>
<defaultpage>/Views/Default.aspx</defaultpage>
<navigatorurl>/Views/Default.aspx</navigatorurl>
<editurls/>
<listdefinitions/>
<itemicons/>
<theme>
<path/>
</theme>
<customconfiguration/>
</settings>
</Configuration>

I recommend editing configuration XML, or any XML for that matter in Visual Studio. Besides syntax coloring and validation, VS has a nice feature to make it easier for us to know which elements go where using Intellisense. To enable this, simply right-click anywhere in the white space of the XML document. Click on “Properties” in the menu. On the right-hand side of the screen you should see the properties pane,

VS XML properties

Click on the button to the right of the “Schemas” field. A dialog will open. In the dialog click on the “Add” button and browse to: <Tridion_home>\web\WebUI\Core\Schemas. Select all XSD files and click open.

Make sure that the “Use” column is checked for these schemas you selected.

VS XML Schemas

Once you’ve done this, Visual Studio will validate your configuration file against these schemas and will also show you which elements and attributes can be added:

VS XML intellisense

5)      Next step is to add the necessary elements to your extension’s configuration file:

a. Creating a command

A command is what we extend through our script. This is the piece of code that will be executed when an action is taken by the User in the interface.

Under the “commands” element create a new “commandset” that looks like this:

<cfg:commandset id=”2011Extensions.Commands.ItemXmlDisplay”>
<cfg:command name=”ItemXmlDisplay” implementation=”Extensions.ItemXmlDisplay”/>
<cfg:dependencies>
<cfg:dependency>Extensions.Resources.Base</cfg:dependency>
</cfg:dependencies>
</cfg:commandset>

 

Notice the “implementation” attribute, this one points to the javascript object defined in the script file which you already have or about to create.

Dependencies can also be specified for this command, in this example this is a resource group we get to configure in the next step.

Both the “commandset” and the “command” elements should have their “id” and “name” attributes respectively set to a unique and preferably clear names.

b. Creating a resource group

Inside the “cfg:groups” element create a new resource group for your extension.

A group allows to manage several resources, such as script and CSS files as one unit. Your group should include all of the files needed by the Extension that the GUI will send to the browser:

<cfg:group name=”Extensions.Resources.ItemXmlDisplay” merger=”Tridion.Web.UI.Core.Configuration.Resources.CommandGroupProcessor” merge=”always”>
<cfg:fileset>
<cfg:file type=”style”>/client/commands/ItemXmlDisplay/Styles/ItemXmlDisplay.css</cfg:file>
<cfg:file type=”script”>/client/commands/ItemXmlDisplay/ItemXmlDisplay.js</cfg:file>
<cfg:file type=”reference”>2011Extensions.Commands.ItemXmlDisplay</cfg:file>
</cfg:fileset>
<cfg:dependencies>
<cfg:dependency>Tridion.Web.UI.Editors.CME</cfg:dependency>
<cfg:dependency>Tridion.Web.UI.Editors.CME.commands</cfg:dependency>
</cfg:dependencies>
</cfg:group>

Notice that for each resource file you need specify the type. For CSS specify “style” while for javascript files specify “script”. The last item is extremely important to remember to configure, without it, the extension will not function. The “reference” type must match the “id” attribute of the “commandset” configured in the previous step.

c. Creating the extension configuration

Now that we have all the dependencies in place, we are ready to configure the actual extension, meaning, what we want to extend in the GUI.

First, add an element under the “ext:editorextensions” like so:

<extensions>
<ext:editorextensions>
<ext:editorextension target=”CME”>

It is very important that the “target” attribute is set to: “CME”.

Under the “editorextension” node you can extend different interface elements such as the context menus or the ribbon toolbar, etc. (The  Intellisense will show you the other elements possible to extend).

For this example we will look at how to extend the GUI context menu as well as the ribbon toolbar.

Context Menu Extension

Add the following elements to the “editorextension” element:

<ext:editurls/>
<ext:listdefinitions/>
<ext:taskbars/>
<ext:commands/>
<ext:commandextensions/>
<ext:contextmenus>
<ext:add>
<ext:extension name=”ItemXmlDisplayExtension” assignid=”ext_xmldisplay” insertbefore=”cm_refresh”>
<ext:menudeclaration externaldefinition=””>
<cmenu:ContextMenuItem id=”ext_ItemXmlDisplay” name=”Show Item Xml” command=”ItemXmlDisplay”/>
</ext:menudeclaration>
<ext:dependencies>
<cfg:dependency>Extensions.Resources.ItemXmlDisplay</cfg:dependency>
</ext:dependencies>
<ext:apply>
<ext:view name=”DashboardView”/>
</ext:apply>
</ext:extension>
</ext:add>
</ext:contextmenus>
<ext:lists/>
<ext:tabpages/>
<ext:toolbars/>
<ext:ribbontoolbars/>

You must add the empty elements in this order for the configuration XML to be valid.

There are quite a few things to notice about the extension set up; the “name” attribute should receive a unique name and so should the “assigned”.

If you wish to place your menu item before an already existing item you will need to know the ID of that item. Unfortunately, Im not aware of any documentations detailing the default GUI IDs so there are two ways to go about finding these. 1) Find it somewhere in the GUI configuration files or 2) Which I find easier, is to use Firebug in Firefox:

Firebug - context menu ids

As you can see, all of the IDs are neatly visible for each menu item element (li).

Next is to specify the menu item details (cmenu:ContextMenuITem) which should include the unique ID, the “name” attribute value is the title the button will receive in the GUI and the “command” attribute which points to the name of the command specified in step 5.a.

Notice the dependency element pointing to the name of the resource group defined in step 5.b.

Lastly, the “ext:apply” element specifies the view in which to show this context menu you created. For the main GUI window we use the view name: “DasboardView”.

Ribbon Toolbar Extension

The Ribbon Toolbar is divided into different levels.

A Page (“Home”):

ribbon - page

A Group (“Manage”):

ribbon - group

A “Button”:

ribbon - button

It is possible to add a new button to an existing group, to create a new group or even a new page using the extension configuration.

The following example shows how to add a button to an existing group:

<ext:ribbontoolbars>
<ext:add>
<ext:extension pageid=”HomePage” groupid=”ManageGroup” name=”Item Xml” assignid=”ItemXmlBtn”>
<ext:command>ItemXmlDisplay</ext:command>
<ext:title>ItemXml</ext:title>
<ext:dependencies>
<cfg:dependency>Extensions.Resources.ItemXmlDisplay</cfg:dependency>
</ext:dependencies>
<ext:apply>
<ext:view name=”DashboardView”>
<ext:control id=”DashboardToolbar”/>
</ext:view>
</ext:apply>
</ext:extension>
</ext:add>
</ext:ribbontoolbars>

To be able to add the button to an existing page and group, we need to know their IDs. Again, the easiest I’ve found is to simply use Firebug and inspect the HTML.
You tell the GUI where to place your button using the “pageid” and “groupid” attributes.

The rest of the configuration is very similar to the context menu example.

Theme Path

Optionally, you can set a theme path for your extensions.

This is done by entering a relative location into the “settings\theme\path” element.
Once this is done you will be able to use the theme path in your CSS files, for example:

.ItemXmlDisplay .image {background-image:url({ThemePath}/itemXmlDisplay/styles/icons/xmlicon16.png);}

6)  Now that the extension configuration is ready we need to make sure the code is set up correctly. Create a javascript (.js) file under the Extension folder (for example: “c:\extensions\commands\ItemXmlDisplay”).

In the script file there are a few lines of code that must be present for any command to work:

a)   Decide on a namespace for your extension and register it. This is a very good practice to make sure there are never any conflicts with GUI code or other extensions added later:

Type.registerNamespace(“Extensions”);

b)      Add a constructor to your object:

Extensions.ItemXmlDisplay = function Extensions$ItemXmlDisplay()
{
Type.enableInterface(this, “Extensions.ItemXmlDisplay”);
this.addInterface(“Tridion.Cme.Command”, ["ItemXmlDisplay"]);
};

Notice the “addInterface” call, this makes sure your object will extend the “Tridion.CME.Command” interface and allow it to be used as a command by the GUI.

c)  Add the 3 methods a Command object is expected to have:

Extensions.ItemXmlDisplay.prototype.isAvailable = function ItemXmlDisplay$isAvailable(selection)
{
}

The result (Boolean) of this method tells the GUI whether to show the extension.

Extensions.ItemXmlDisplay.prototype.isEnabled = function ItemXmlDisplay$isEnabled(selection)
{
}

The result (Boolean) of this method tells the GUI whether to enable the extension.

Extensions.ItemXmlDisplay.prototype._execute = function ItemXmlDisplay$_execute(selection)
{
}

This method will be called in response to the user action such as clicking the menu item or the toolbar button.

Make sure the resource file configuration element is pointing to the right location. This is relative to the extension’s root folder (i.e. “C:\extensions”).

7)      Now that your extension is ready to be used, first step to install it is to set up the extension’s location as a virtual directory in IIS.

a)      In the IIS console, browse to the SDL Tridion 2011 website.

b)      Under the “WebUI\Editors” directory add a new Virtual Directory, pointing to your extension’s location on the disk:

IIS - extension virtual directory

8)      The last step is to let the GUI know about your extension. To do this, find the system.config file under “<Tridion_home>\web\WebUI\WebRoot\Configuration”.

a)      Make a backup of the file first so you can always revert to the way it was with no extensions configured.

b)      Locate the “<editors>” element and add a new “editor” like so:

<editor name=”2011Extensions” xmlns=”http://www.sdltridion.com/2009/GUI/Configuration&#8221;>

<installpath xmlns=”http://www.sdltridion.com/2009/GUI/Configuration&#8221;>C:\development\Yoav\Extensions\2011Extensions\</installpath>
<configuration xmlns=”http://www.sdltridion.com/2009/GUI/Configuration&#8221;>Config\extension.config</configuration>
<vdir xmlns=”http://www.sdltridion.com/2009/GUI/Configuration&#8221;>2011Extensions</vdir>
</editor>

The editor element  has 3 important elements:

a)      installpath – The exact location of where we created the extension.

b)      configuration – the relative location of the extension configuration file.

c)       vdir – The name of the virtual directory as its set up in IIS.

 

That’s it. Following these steps should let you start using the extension immediately.

For examples of working extensions and their configuration see my previous post: My Tridion 2011 CTP Extensions Go GA.


  1. Roland Muts
    March 8, 2011 at 20:23

    Hey Yoav,

    Clean article.

    Could you also make sure you update the instructions posted in the various articles on sdltridionworld? It seems because of changes in the config xml structure between the CTP2011 and the GA version, that older articles no longer have the correct approach with regards to installing the extensions.

    Other than that, very cool — will be using this simple extension as the basis for future ones!

  2. June 10, 2011 at 13:23

    Just a quick question yoav:

    I see the following line in your xmllistview extension

    Extensions.ItemXmlDisplay._xsltLocation = $config.expandEditorPath(“/client/commands/itemXmlDisplay/itemXmlDisplay.xslt”, “2011Extensions”);

    when rendered in the browser this is converted into the path:

    /WebUI/Editors/2011Extensions/client/commands/itemXmlDisplay/itemXmlDisplayu.xslt

    However i’ve placed the extension outside of the /WebUI/Editors/2011Extensions directory in c:/tridion/extensions/ so the xslt file returns a 404.

    Is there a better way for me to code this path so it is relative to the extension location and not the wcm webui folder?

    thanks

    john

    • Yoav Niran
      June 11, 2011 at 23:07

      Hi John,

      Thats a bit strange that you should have this problem since I dont put my editors/extensions under the tridion installation folder either. thats why one of the steps needed is to make the folder containing your extensions a virtual folder in IIS under the /WebUI/Editors/.

      Once you do this, the URL returned by the expand path method will be valid.

      However, my extensions expect the editor folder to be called “2011Extensions” if you have selected a different name make sure you also change the editor name in the utils.js file. Also make sure you are using the latest version of my extensions since I have made sure that the editor name is no longer hardcoded anywhere.

      If you’re using the List Quick Helper which i believe still has some hardcoded values you will have to find and change them in the code or wait just a little bit more as im very close to releasing a new (and wonderful) version of the extension :)

      Hope this helps,
      Yoav.

  3. June 16, 2011 at 09:24

    Hi Yoav,

    Thanks for the help, i suspect i’ve missed the IIS step. About to install the new list quick helper, it’s looking great.

    Cheers

    John

  4. Andreas Vestlund
    October 17, 2011 at 10:18

    Hi Yoav!

    When extending the ribbon toolbar, is it possible to insert a new button inside a item group? For example a new button right under the “Delete” button in the Management group.

    Thanks
    Andreas

  5. December 7, 2011 at 16:47

    Hi Yoav,
    Nice article.Am kind of novice working in GUI extensions.
    with help of this article am able to setup GUI extension in Dashboardview-DashboardToolbar with noissues.

    I want to do similar extension in ComponentView-ItemToolbar .
    1) i want this to work on the “FormatPage” [with "ComponentView-ItemToolbar"]. The button shows up but is disabled. The “isEnabled” function of this command returns “True” so it is enabled always. Is there a configuration i’m missing?

    2) So i did _isEnabled=true & _isAvailable=true(with underscore).This still dont have any effect on the ComponentView buttons.

    Please advise, where i’m missing a config parameter, or what i’m not configuring correctly?
    .

  6. January 9, 2013 at 11:40

    “Setting up a Tridion 2011 GUI extension in 8 steps Life of
    a geek and a part-time poet” was in fact a quite excellent blog, .
    I hope you keep authoring and I’ll continue to keep viewing! Thanks for the post -Sheri

  7. February 25, 2013 at 18:23

    Hi Yoav,

    I’ve been trying to follow your steps and things appear to be working out okay… but my goal is to have a button in the ribbon toolbar go to a custom page in Tridion. Would I then register a command under my extension namespace whose purpose is to navigate to my custom page? How does that JavaScript look?

    • Yoav Niran
      February 25, 2013 at 20:21

      Hi there,
      I actually havent been working for Tridion or on Tridion implementations in a very long time.
      I would advise posting your question on stackoverflow.com (http://stackoverflow.com/questions/tagged/tridion)
      for the best way to get it answered.

      Good luck
      Yoav.

      • February 26, 2013 at 05:49

        תודה רבה

  1. March 14, 2011 at 22:11
  2. May 19, 2014 at 18:54

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 315 other followers

%d bloggers like this: