GUI Extension Installer

December 11th, 2013 | Posted by Robert Curlette in GUI Extension - (2 Comments)

The GUI Extension installer does everything on the CMS to install and register a Tridion GUI Extension, saving you time and letting you try out new GUI Extensions easier and quicker.  The idea was started at the Tridion MVP retreat and then I continued working on the installer after the retreat.  Special thanks to Dominic Cronin for sharing some PowerShell secrets to help me get started.

Run the installer at the PowerShell command line like this:

InstallExtension.ps1 ExtensionName.zip
  • Creates a Virtual Directory in IIS
  • Copies the GUI Extension files to the correct folder on the CMS Server
  • Updates the Tridion System.config with references to the GUI Extension

Try it out – a good sample extension to install is the Copy URI extension here:  https://github.com/rcurlette/CopyUri  Download the extension and you will have a CopyUri-master.zip file.  Then open PowerShell and type:

InstallExtension.ps1 CopyUri-master.zip

The file structure is important and should follow this structure:

  • /Editor/Configuration/editor.config
  • /Model/Configuration/model.config
  • /dlls

Source code

Have fun and please leave feedback!

The Tridion GUI is powered by JavaScript while the backend is powered by .Net and sending a (nice) message from .Net to the GUI has been very challenging – until now. Using SignalR, an open-source product from Microsoft, it is possible to show or ‘echo’ the message from the .Net Event System, Templates or Customer Resolvers and show them in the GUI. Check out the tutorial that Will Price and I wrote published on SDL Tridion World to find out how to implement this yourself. Special thanks to SDL’s Bart Koopman for helping get the article online and embracing the GitHub Gist embed for source code.

Sometimes, especially for System Administration or Developer Extensions, we don’t want to have the Context Menu GUI Extension visible to the end user.

We can use the IsAvailable option in the GUI Extension Command.js file and set it to false if the user is in a not allowed group. The following code can be used for hiding a GUI Extension context menu item.

Extensions.SetPermissions.prototype.isAvailable = function SetPermissions$isAvailable(selection, pipeline) {
    var showOption = true;
	var groupsWithNoAccess = ["Author","Chief Editor"];

	// Get the groups the user belongs to
	var groups = Tridion.UI.UserSettings.getJsonUserSettings(true).User.Data.GroupMemberships;
	if(groups["@title"] == undefined)  // 1 group membership
	{
		if(groups.Group["@title"] == groupsWithNoAccess[0])
			showOption = false;
	}
	else
	{
		// if the user belongs to a group with no access, hide the option
		for (var i = 0; i < groups.length; i++) {
		    var userIsInGroup = groups[i]["@title"];
		    length = groupsWithNoAccess.length;
		    while(length--) {
		         if (userIsInGroup.indexOf(groupsWithNoAccess[length])!=-1) {
			      showOption = false;
		              return showOption;
			 }
		     }
		}
	}
	return showOption;
};

 

Show Context Menu Item for Authorized Groups
And, if we want th do the inverse, and show the Context Menu item for only authorized groups we would use the following:


Extensions.SetPermissions.prototype.isAvailable = function SetPermissions$isAvailable(selection, pipeline) {
        var showOption = false;
	
	var groupsWithAccess = ["Administrator"];  // Specify all access groups here
	
	var groups = Tridion.UI.UserSettings.getJsonUserSettings(true).User.Data.GroupMemberships;
	if(groups["@title"] == undefined)  // 1 group membership
	{
		if(groups.Group["@title"] == groupsWithAccess[0])
			showOption = true;
	}
	else
	{
		// many group memberships
		for (var i = 0; i < groups.length; i++) {
			var userIsInGroup = groups[i]["@title"];		
			length = groupsWithAccess.length;
			while(length--) {
			   if (userIsInGroup.indexOf(groupsWithAccess[length])!=-1) {
				   showOption = true;
				   return showOption;
			   }
			}
		}
	}
	
	return showOption;
};

This is a small example of how to create a context-menu extension to copy the URI of a Tridion Item.  

Getting Started

The most important and also difficult part of every GUI Extension is the configuration file.  It’s best to start with a previous working example.  For this article I used the classic 8 Steps post from Yoav Nirlan.

Create the Directory

Create a new Folder in:
C:\Program Files (x86)\Tridion\web\WebUI\Editors\CopyUri

Configuration File

I started with the configuration file from the Tutorial and also loaded the Schemas into Visual Studio from Tridion.  This was a very important step because Tridion 2011 SP1 has a slightly different XML Schema for the Context Menu than Yoav’s sample does.  I relied on the intellisenne in Visual Studio and the XML Schema to get a properly formatted Configuration file.  In the future I will start with this updated config file below for Context-menu extensions.

Save it as CopyUri.config in the folder created above.

<?xml version="1.0"?>
<Configuration xmlns="http://www.sdltridion.com/2009/GUI/Configuration/Merge" xmlns:cfg="http://www.sdltridion.com/2009/GUI/Configuration" xmlns:ext="http://www.sdltridion.com/2009/GUI/extensions" xmlns:cmenu="http://www.sdltridion.com/2009/GUI/extensions/ContextMenu">
  <resources cache="true">
    <cfg:filters/>
    <cfg:groups>
      <cfg:group name="Extensions.Resources.CopyUri" merger="Tridion.Web.UI.Core.Configuration.Resources.CommandGroupProcessor" merge="always">
        <cfg:fileset>
          <cfg:file type="script">/Commands/CopyUriCommand.js</cfg:file>
          <cfg:file type="reference">2011Extensions.Commands.CopyUri</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>
    </cfg:groups>
  </resources>
  <definitionfiles/>
  <extensions>
    <ext:editorextensions>
      <ext:editorextension target="CME">
        <ext:editurls />
        <ext:listdefinitions/>
        <ext:taskbars/>
        <ext:commands />
        <ext:commandextensions/>
        <ext:contextmenus>
          <ext:add>
            <ext:extension name="CopyUriExtension" assignid="ext_copyuri" insertbefore="cm_refresh">
              <ext:menudeclaration externaldefinition="">
                <cmenu:ContextMenuItem id="ext_CopyUri" name="Copy URI" command="CopyUri"/>
              </ext:menudeclaration>
              <ext:dependencies>
                <cfg:dependency>Extensions.Resources.CopyUri</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/>
      </ext:editorextension>
    </ext:editorextensions>
    <ext:dataextenders/>
  </extensions>
  <commands>
    <cfg:commandset id="2011Extensions.Commands.CopyUri">
    <cfg:command name="CopyUri" implementation="Extensions.CopyUri"/>
    <cfg:dependencies>
    <cfg:dependency>Extensions.Resources.Base</cfg:dependency>
    </cfg:dependencies>
    </cfg:commandset>
  </commands>
  <contextmenus/>
  <localization/>
  <settings>
    <defaultpage>/Views/Default.aspx</defaultpage>
    <navigatorurl>/Views/Default.aspx</navigatorurl>
    <editurls/>
    <listdefinitions/>
    <itemicons/>
    <theme>
      <path/>
    </theme>
    <customconfiguration/>
  </settings>
</Configuration>

Important parts of the Configuration File

Location of the command in the Context Menu:

insertbefore="cm_refresh"

Text of the menu item:

name="Copy URI"

Important info for the JavaScript in the next part:
1.  Command name
2.  Implementation

<cfg:command name="CopyUri" implementation="Extensions.CopyUri"/>

The command name is also used here:

<cmenu:ContextMenuItem id="ext_CopyUri" name="Copy URI" command="CopyUri"/>

The Commands are in the xml root ‘commands’ node, not the ‘ext:commands’.

 </extensions>
  <commands>
    <cfg:commandset id="2011Extensions.Commands.CopyUri">
    <cfg:command name="CopyUri" implementation="Extensions.CopyUri"/>
    <cfg:dependencies>
    <cfg:dependency>Extensions.Resources.Base</cfg:dependency>
    </cfg:dependencies>
    </cfg:commandset>
  </commands>
  <contextmenus/>

No Ribbon button was added in this demo.

JavaScript Code

1.  Create a new folder ‘Commands’.
2.  Create a new file called CopyUriCommand.js

Type.registerNamespace("Extensions");

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

Extensions.CopyUri.prototype.isAvailable = function CopyUri$isAvailable(selection) {
    return true;
}

Extensions.CopyUri.prototype.isEnabled = function CopyUri$isEnabled(selection) {
    if (selection.getItems().length > 1)
        return false;
    else
        return true;
}

Extensions.CopyUri.prototype._execute = function CopyUri$_execute(selection) {
    selectedItem = selection.getItems()[0];
    prompt("Copy the Item ID using Ctrl/Cmd + C:", selection.getItems()[0]);
}

 Code Explained:

1.  The isEnabled method tells the GUI if the menu option is enabled or disabled.  This extension shows the URI for only one item, so I only enable the extension if one item is selected.
2.  The execute method does the action.  We have available all methods and objects in the Tridion Anguilla framework.  The getItem method returns null but we are lucky that getItems returns whatever is selected in the GUI.  We use the prompt method of JavaScript to provide a nice small window to copy the URI from.

Creating the Virtual Directory in IIS

Create a new Virtual Directory in WebUI/Editors called CopyUri.  This name needs to be the same as the VDIR in the config from the next step.  You may need to update the Security settings for the folder and allow the Network Service user read access.  Use the ‘Test’ button after setting up and you should have a checkmark next to the first test.  The second test will fail and this is normal.

Enabling the Extension

Open the System.config file located at:  <Tridion_home>\web\WebUI\WebRoot\Configuration

Add the following to ‘turn on’ the Extension.  If your Tridion GUI stops working – comment out the following line and it should return to normal.  Double-check your config and settings.

<editor name="CopyUri" xmlns="http://www.sdltridion.com/2009/GUI/Configuration">
	<installpath xmlns="http://www.sdltridion.com/2009/GUI/Configuration">C:\Program Files (x86)\Tridion\web\WebUI\Editors\CopyUri\</installpath>
		  <configuration xmlns="http://www.sdltridion.com/2009/GUI/Configuration">CopyUri.config</configuration>
		  <vdir xmlns="http://www.sdltridion.com/2009/GUI/Configuration">CopyUri</vdir>
</editor>

Copying the WebDav URL

Big thanks to Alex Klock from Tridion Community for answering my question about getting the WebDavURL in Anguilla.  Here is the code we could add to the execute method above to show the WebDav URL instead of URI.

var item = $models.getItem(selectedItem),
    webDavUrl = item.getWebDavUrl();

if (!webDavUrl) {
    // WebDavUrl for cached item hasn't been loaded yet, so lets load it.
    $evt.addEventHandler(item, "loadwebdavurl", function (event) {
        webDavUrl = item.getWebDavUrl(); // also could do event.source.getWebDavUrl()
    });
    item.loadWebDavUrl();
}

Summary

This is a simple GUI Extension but it highlights some basics we need to know when developing a GUI Extension.  The Developer Console in the Chrome Browser was a big help while debugging and writing the JavaScript code.  A big thanks to Hristo Chakarov for his help with the JavaScript development in this post.

In this post we’ll continue Nuno’s series on Content Validation and create a GUI Extension using the Anguilla framework to validate a Component’s field content while exploring little-seen Anguilla JavaScript methods to inspect the field content and validate the Save events from the GUI.  Big thanks to Nuno Linhares for writing this article and allowing me to be the Editor.

Solution on Github:  https://github.com/rcurlette/ValidateTitleFieldPart2/

Summary:  Validate that the Component Title field contains an Uppercase letter as the first character after pressing the Save button and show a warning message if a number or lowercase letter is the first character.  We will use Anguilla JavaScript for the field validation.  The estimated time to complete this tutorial is around 90 minutes.  Here is what it will look like in the end:

Overview

  1. Create the Visual Studio Project , Folders and Files (empty)
  2. Create the GUI Extension configuration and setup IIS
  3. Add the Anguilla JavaScript code to Validate the Title Field
  4. Debugging

Create the Visual Studio Project and setup the file structure

We’re going to do this using the CME API (Anguilla) with a javascript alert, and we will extend the following 3 CME commands: “Save”, “Save and Close” and “Save and New”.
Let’s start by creating a Visual Studio Project for our requirements. I tend to start with an Empty Solution, then add the the “Editor” project.  In the next part of this tutorial we will also use a  “Model” project but not in this tutorial. (note that I use the project type “ASP.NET Empty Web Application”).

Delete the first project that Visual Studio always creates.

Now add 1 new project: ValidateTitleFieldEditor

Again, use the “Empty ASP.NET solution” template.

Let’s create the skeleton of our extension. In the Editor project, add the following folders:

  • Commands
  • Config

Under commands, let’s create a file named “ValidateTitleFieldCommand.js” – Visual Studio seems to believe people still use Jscript, let’s not get bothered by it.

Under Config create a file named “ValidateTitleFieldEditor.config”.  This will be used to configure our GUI Extension to ‘listen’ to the Save events.

You should have something similar to this in your project now:

Create the GUI Extension configuration and setup IIS

Here we will add the configuration to the ValidateTitleFieldEditor.config and much of it will not make any sense.  Please follow along and we will be at the fun part in no time.

Open the Configuration ValidateTitleFieldEditor.js file.

If you haven’t learned how to yet, make sure you add the Tridion Schemas to this editor. Right click anywhere on the config file, select properties.

Click on the … button for the Schemas, and add all schemas from [Tridion]\Web\WebUi\Core\Schemas

Tip: you may want to add these schemas to the default Visual Studio schemas, under “C:\Program Files (x86)\Microsoft Visual Studio 10.0\Xml\Schemas”

Let’s build our configuration file with the following:

<?xml version="1.0"?>
<Configuration xmlns="http://www.sdltridion.com/2009/GUI/Configuration/Merge"
               xmlns:cfg="http://www.sdltridion.com/2009/GUI/Configuration"
               xmlns:ext="http://www.sdltridion.com/2009/GUI/extensions"
               xmlns:cmenu="http://www.sdltridion.com/2009/GUI/extensions/ContextMenu">
  <resources cache="true">
    <cfg:filters />
    <cfg:groups>
      <cfg:group name="ValidateTitleField.CommandSet">
        <cfg:fileset>
          <cfg:file type="script">/Commands/ValidateTitleFieldCommand.js</cfg:file>
          <cfg:file type="reference">ValidateTitleField.Interface</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>
    </cfg:groups>
  </resources>
  <definitionfiles />
  <extensions>
    <ext:dataextenders />
    <ext:editorextensions>
      <ext:editorextension target="CME">
        <ext:editurls />
        <ext:listdefinitions />
        <ext:taskbars />
        <ext:commands />
        <ext:commandextensions>
          <ext:commands>
            <ext:command name="Save" extendingcommand="ValidateTitleField"/>
          </ext:commands>
          <ext:dependencies>
            <cfg:dependency>ValidateTitleField.CommandSet</cfg:dependency>
          </ext:dependencies>
        </ext:commandextensions>
        <ext:contextmenus />
        <ext:lists />
        <ext:tabpages />
        <ext:toolbars />
        <ext:ribbontoolbars />
      </ext:editorextension>
    </ext:editorextensions>
  </extensions>
  <commands>
    <cfg:commandset id="ValidateTitleField.Interface">
      <cfg:command name="ValidateTitleField" implementation="Company.Extensions.ValidateTitleFieldCommand"/>
    </cfg:commandset>
  </commands>
  <contextmenus />
  <localization />
  <settings>
    <defaultpage />
    <editurls />
    <listdefinitions />
    <itemicons />
    <theme>
      <path />
    </theme>
    <customconfiguration>
    </customconfiguration>
  </settings>
</Configuration>

What are we doing in this configuration?

We’re defining 1 group of files:

<cfg:group name="ValidateTitleField.CommandSet">
        <cfg:fileset>
          <cfg:file type="script">/Commands/ValidateTitleFieldCommand.js</cfg:file>
          <cfg:file type="reference">ValidateTitleField.Interface</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>

The group is a “CommandSet” and we’re basically telling Tridion to treat these files as a group, and that the files have dependencies on other Tridion items.

We’re also saying that this extension targets an existing editor: CME

<ext:editorextension target="CME">

 

And within this, we’re extending the “Save” Command with our own CommandSet.  Note:  This is where we wire up to the Save, Save and Close, and Save and New commands.

<ext:commandextensions>
          <ext:commands>
            <ext:command name="Save" extendingcommand="ValidateTitleField"/>
	    <ext:command name="SaveClose" extendingcommand="ValidateTitleField"/>
	    <ext:command name="SaveNew" extendingcommand="ValidateTitleField"/>
          </ext:commands>
          <ext:dependencies>
            <cfg:dependency>ValidateTitleField.CommandSet</cfg:dependency>
          </ext:dependencies>
        </ext:commandextensions>

 

And finally we’re registering a new CME Command:

<commands>
    <cfg:commandset id="ValidateTitleField.Interface">
      <cfg:command name="ValidateTitleField" implementation="Company.Extensions.ValidateTitleFieldCommand"/>
    </cfg:commandset>
  </commands>

That “implementation” attribute is the name of the Anguilla Class that we will use to implement the command.

 

Adding the extension to IIS and registering in Tridion

Let’s add our extension as a Virtual Directory to the CME’s “Editors” folder. I tend to point these directly to my development folder so that all code changes are immediate.

As you can see in the screenshot, the physical path should match the start of your “Editor” project.

Tridion Content Manager Explorer Configuration
The Tridion CME uses a file to hold all the editor and model configurations (plus quite a lot of other settings). You will find this file under [Tridion]\Web\WebUI\WebRoot\Configuration\System.Config

1. Make a backup copy of this file, and edit it with a proper XML Editor (like Visual Studio).
2. Find the Element named “<editors default=”CME”>” (around line 1000 in my system.config).
3. Add one editor configuration element with YOUR values to change the path:

<editor name="ValidateTitleFieldEditor">
      <installpath>D:\Tridion 2011\ValidateTitleField\ValidateTitleFieldEditor</installpath>
      <configuration>Config\ValidateTitleFieldEditor.config</configuration>
      <vdir>ValidateTitleField</vdir>
    </editor>

4. Restart IIS (iisreset) and reload the Tridion Content Manager Explorer.

Summary
We’re done with the boring part.  Now we can have some fun with the JavaScript action and doing something in the GUI.

 

Creating the JavaScript  for the Anguilla Save Event – The Command

Let’s create our Command. Open the “ValidateTitleFieldCommand.js” file.

For now, all that we want is to get our extension loading (and being able to verify it), so let’s add the following code:

Type.registerNamespace("Company.Extensions");

Company.Extensions.ValidateTitleFieldCommand = function ValidateTitleFieldCommand() {
    Type.enableInterface(this, "Company.Extensions.ValidateTitleFieldCommand");
    this.addInterface("Tridion.Cme.Command", ["ValidateTitleFieldCommand"]);
};

Company.Extensions.ValidateTitleFieldCommand.prototype._isAvailable = function ValidateTitleFieldCommand$_isAvailable(selection) {
    console.debug("Is Available called");
    return $cme.getCommand("Save")._isAvailable(selection);
};

Company.Extensions.ValidateTitleFieldCommand.prototype._isEnabled = function ValidateTitleFieldCommand$_isEnabled(selection) {
    console.debug("Is Enabled called");
    return $cme.getCommand("Save")._isEnabled(selection);
};

Company.Extensions.ValidateTitleFieldCommand.prototype._execute = function ValidateTitleFieldCommand$_execute(selection, pipeline) {
    console.debug("Execute called");
    return $cme.getCommand("Save")._execute(selection, pipeline);
};

This implements the _isAvailable, _isEnabled, and _execute functions required for every command. As you can see, all we’re doing is logging that the code was invoked (so we can verify it was loaded) and telling Tridion to go ahead and execute the “Save” Command.  The console.debug statement will write the output the the Firebug Console window or Console window in the Chrome Developer Tools.

We should now have enough to register this (Editor) extension with Tridion. To do this, we need to tell Tridion that we are an extension, and where the configuration for the extension is.

How do I know it’s working?

Well, there’s a few easy ways to do this. If you messed up something, chances are that your CME will look like this:

Open a Javascript console (Firebug is best here) and you’re likely to see this error:
Uncaught ReferenceError: Tridion is not defined

This is very generic, but usually comes with a very useful URL just before it:
http://t2011guruv3/WebUI/Editors/CME/Views/Dashboard/Dashboard_v6.1.0.55920.11_.aspx?mode=js
or http://$$SERVERNAME$$/WebUI/Editors/CME/Views/Dashboard/Dashboard_v$$TRIDION_CME_VERSION$$.$$CONFIGURATION_VERSION$$.aspx?mode=js

URL in FireBug GUI:

Open this url in your browser and you might have a lot more information (Chrome does not show the URL):

In this case, the error is caused because my Editor configuration in System.Config points to a vdir named “ValidateTitleFieldEditor” but the Virtual Directory in IIS is called “ValidateTitleField”. Changing the configuration to specify the correct vdir will fix the issue. If you had a different issue, chances are that opening this url in a browser will give you concrete error messages that should guide you into fixing your problem.

Once you fix your issue you should be able to load both the CME and the JS file:

Tip – if your Javascript is loading minified/obfuscated, you can change this setting.

If you were paying attention to any of this, you should know how to test if your command is being called. If you weren’t, here’s how.

  1. We configured our command as an extension to the “Save” Command (in ValidateTitleFieldEditor.config)
  2. We added 3 functions to our JS – _isAvailable, _isEnabled and _execute
  3. We added a “console.debug” instruction to all those functions.

So basically now we just need to:

  1. Clear your browser cache
  2. Reload the CME
  3. Open a Javascript debug console (I recommend chrome)
  4. Go somewhere in the CME where the Save command would be available (open a page or a component)

If you now open the console you should be able to see something like this:

This confirms our command is being called and our GUI Extension is working.

Now let’s tell our users about their mistake with a popup.  In the popup we will show them a message that the title field needs to start with a Captial letter.  This involves using the Anguilla API to inspect the field’s value when the Save, Save and Close, or Save and New button.

Before moving on, let’s do ‘Save All’ in Visual Studio.  Here’s a neat trick that might help you moving forward.  Instead of opening the project as we have defined now, try doing the following:

  1. Open Visual Studio
  2. Select File -> Open -> Website
  3. Select “Local IIS” on the left side, then search for the “SDL Tridion 2011″ website, expand it and select “WebUI”.

Visual Studio is going to ask you if you want to upgrade your configuration to ASP.NET 2.0 – Select ‘No’ – do not ever say yes, unless you can safely claim you know what you’re doing.  If you have not yet saved all files, the first popup will ask if you want to ave files – for this select ‘yes’

Once it’s open you should now see your editor under “Editors”:

This loads the rest of the Tridion CME as well, which will:

  1. Make visual studio pretty slow at times
  2. Give you some small help with some IntelliSense (though you can’t trust the whole of it)

Now that we’re here, we’re going to try reading the current value of the “Title” field in the component you’re trying to save. So, just like with any other Tridion Extension, the first thing we’ll do is make sure we should be executing _at all_.

Conditions for executing are:

  1. Item you’re editing is a component
  2. Current component’s schema has a field named “Title”
  3. Value of this field does not start with an Uppercase letter.

Open the ValidateTitleFieldCommand.js file and modify the _execute method to determine if we should execute:

Company.Extensions.ValidateTitleFieldCommand.prototype._execute = function ValidateTitleFieldCommand$_execute(selection, pipeline) {
    console.debug("Execute called");
    var p = this.properties;
    var item = $display.getItem();
    if (item) {
        if (item.getItemType() == "tcm:16") {
            // We know it's a component
            var fieldBuilder = $display.getView().properties.controls.fieldBuilder;
            if (fieldBuilder.getField("Title")) {
                // We have a field named Title
                var titleField = fieldBuilder.getField("Title");
                if (titleField.getValues().length > 0) {
                    var fieldValue = titleField.getValues()[0];
                    console.debug("Current title value is " + fieldValue);
                    // Voodoo magic
                    var firstCharacter = fieldValue.substring(0, 1);
                    if (isNaN(firstCharacter)) {
                        if (firstCharacter != firstCharacter.toUpperCase()) {
                            console.debug("First character is NOT uppercase");
                        } else {
                            console.debug("First character is uppercase");
                        }
                    } else {
                        // Interestingly isNaN returns false on a space. Good to know, I guess
                        console.debug("First character is a number!");
                    }
                }
            }
        }
    }
    return $cme.getCommand("Save")._execute(selection, pipeline);
};

The fieldBuilder is the magic here that provides us the ability to read fields in the Tridion GUI.  Using the JavaScript FireBug Console we can set a breakpoint on this line and then go to the Console window and inspect the object for other properties and methods.

Also, notice the return statement where we allow the GUI to continue saving.

At this point we can start thinking about the real solution. You could, for instance, add an alert(“First letter of title must be Upper Case”) to your code and stop the execution of the Save command (commented the changes to the code):

Company.Extensions.ValidateTitleFieldCommand.prototype._execute = function ValidateTitleFieldCommand$_execute(selection, pipeline) {
    console.debug("Execute called");
    var item = $display.getItem();
    var failed = false;  // ** Added
    if (item) {
        if (item.getItemType() == "tcm:16") {
            // We know it's a component
            var fieldBuilder = $display.getView().properties.controls.fieldBuilder;
            if (fieldBuilder.getField("Title")) {
                // We have a field named Title
                var titleField = fieldBuilder.getField("Title");
                if (titleField.getValues().length > 0) {
                    var fieldValue = titleField.getValues()[0];
                    console.debug("Current title value is " + fieldValue);
                    // Voodoo magic
                    var firstCharacter = fieldValue.substring(0, 1);
                    if (isNaN(firstCharacter)) {
                        if (firstCharacter != firstCharacter.toUpperCase()) {
                            console.debug("First character is NOT uppercase");
                            // *** Show popup
                            alert("First character of 'Title' field must be uppercase");
                            failed = true;
                        } else {
                            console.debug("First character is uppercase");
                        }
                    } else {
                        // Interestingly isNaN returns false on a space. Good to know, I guess
                        console.debug("First character is a number!");
                        // *** Show popup
                        alert("First character of 'Title' field cannot be a number.");
                        failed = true;  // *** Stop save action
                    }
                }
            }
        }
    }
    if(!failed)
        // *** Continue saving
        return $cme.getCommand("Save")._execute(selection, pipeline);
};

Which would result in something like this showing up to your editors.  We did it!  Congratulations for making it this far!

Debugging

Let’s see if our GUI Extension code is firing:
– Open Firefox, FireBug, Script Tab
– Open a Component

Search for ‘ValidateTitleFieldCommand’ and around line 96404 you will see our new GUI Extension JavaScript code.  Here I place a breakpoint and then with pressing the Save button I can step through the code.

While stepping through code I can also go to the Console Window and see the other methods  and properties that are available for these objects.

Summary

The Tridion 2011 Anguilla Framework gives us the opportunity to provide friendlier feedback to the user and also increase the quality of content entered into Tridion by enforcing editorial guidelines.  We’ve used the Anguilla Framework to access the fieldBuilder object in the Tridion GUI and inspect the field contents, showing a warning if they do not meet our requirements.  In the next post we’ll update the popup and allow users to make changes to the content in the popup window itself.  Thanks again to Nuno for creating this awesome post.

Solution on Github:  https://github.com/rcurlette/ValidateTitleFieldPart2/

The Tridion 2011 GUI contains HTML ID attributes for many elements and lets our GUI Extension JavaScript to hook into these elements to hide, show, or manipulate their appearance. I use a wide-screen monitor and prefer to re-size my tree window pane when I’m doing lots of navigation in the Tridion tree. In this article I will show how a simple JavaScript GUI extension can re-size the tree navigation pane with one keystroke.

Making the tree pane wider

I found myself resizing the Tridion tree every time I used the GUI and decided to make a small shortcut that could set it to my desired width using 1 keystroke. With some research I found the ID tag for the Navigation Tree and was easily able to set the width using a JavaScript GUI Extension. Of course, if we know the ID of the element we can get it and perform other actions as well – such as hiding it or adding extra info to the GUI beside it. As with all GUI Extensions this requires the utmost care and consideration and should not be attempted at home without parental supervision. Using a shortcut hotkey to trigger the JavaScript call makes it less invasive than re-writing the GUI behavior by default.

Re-sizing the tree pane is accomplished with this bit of JavaScript to modify the width attribute:

$j('#NavigationPanel').width('350');

The $j maps to jQuery. At the end of my jQuery min js file I add:

window.$j = jQuery.noConflict(true);

This is needed since Tridion internally uses $ and from Jaime’s recent post it also uses $$. Interesting.

Enabling with shortcuts

To implement this tweak I put them in a JavaScript file that is loaded into Tridion using a GUI Extension. Not just any GUI Extension, however, but the Shortcut keys extension I wrote about earlier that allow us to define our own Shortcut key combination and execute JavaScript. This allows us to toggle when we want to activate these settings – since maybe other users like the default settings. You could also have multiple settings and use different hotkeys to enable them.

shortcuts.js

//If you only want your code to affect certain screens/views, you should listen to Anguilla events like this:
$evt.addEventHandler($display, "start", onDisplayStarted);

// This callback is called when any view has finished loading
function onDisplayStarted() {

	// Open Publish Queue dialog
	Mousetrap.bind('q', function() {
			//var popup = $popup.create($cme.Popups.PUBLISH_QUEUE.URL, $cme.Popups.PUBLISH_QUEUE.FEATURES);
			//popup.open();
			$commands.executeCommand('PublishingQueue')
	});

	Mousetrap.bind('w', function() {
		// make tree pane wider - must click mouse in the ribbon or breadcrumb area before activating
		// - will not work if focus is in tree or content pane
		$j('#NavigationPanel').width('350');
	});

    $evt.removeEventHandler($display, "start", onDisplayStarted);
}

Testing

Place the focus of your cursor to the breadcrumbs pane or the ribbon pane and make sure nothing is selected.  Then press the hotkey ‘w’ and witness the tree menu width being reset to your dimensions in the shortcuts.js file.  The mousetrap library does not enable shortcuts if any element is selected on the screen.  You could, of course, move the jQuery call to modify the width outside the shortcuts key, but then it would always be enabled for all users.

Installing

  1. Create Folder for Extension: C:\Program Files\Tridion\web\WebUI\Editors\Shortcuts
  2. Add the Shortcuts.config file to the folder Shortcuts
  3. In Shortcuts create a js folder. Path is: C:\Program Files\Tridion\web\WebUI\Editors\Shortcuts\js
  4. Copy 3 javascript files to the js folder.
  5. - mousetrap.js – javascript shortcut library
  6. - shortcuts.js – our Tridion GUI Extension shortcuts actions
  7. - jquery-1.7.2.min.js – jQuery library with the j$ noConflict specified
  8. Open IIS and create a Virtual Dir at SDL Tridion 2011/WebUI/Editors/Shortcuts. Point the home dir to the Editors\Shortcuts dir
  9. Open the GUI Configuration,   C:\Program Files\Tridion\web\WebUI\WebRoot\Configuration, and add the new GUI Extension.
<editor name="Shortcuts">
 <installpath>C:\Program Files\Tridion\web\WebUI\Editors\Shortcuts\</installpath>
 <configuration>Shortcuts.config</configuration>
 <vdir>Shortcuts</vdir>
 </editor>

Code here:
https://github.com/rcurlette/TridionBrowserDefaults

Tridion 2011 provides shortcuts for several actions to navigate the tree view in the GUI and open items.  However, many other operations do not have a hotkey available, such as the Publish Queue.  During a normal day I open the Publish Queue many times, often from a Component or Page view.  I also have minimized the ribbon toolbar and finding the Publish Queue button is still an effort.  I wanted a shortcut key to assign to the Publish Queue to bring it up.  In this post I’ll explain how I added the hotkey to the Tridion GUI using a GUI Extension and provide a way for you to further customize it with your own hotkeys.

Code published at https://github.com/rcurlette/Publish-Queue-Shortcut

Update:  Big thanks to @puf for the comments.  Code is updated to reflect them.

Step 1:  Create the Folder for the GUI Extension.  I created the folder for the GUI Extension:  C:\Program Files\Tridion\web\WebUI\Editors\Shortcuts

Step 2:  Add the js files

For this extension I am using an external js library called Mousetrap, http://craig.is/killing/mice.  It is an excellent library, stand-alone, no dependencies, and only 1.6kb when minified.  This is important to know because the js library will load on every GUI view.

Create a js folder in the Shortcuts folder and put the mousetrap.min.js file there.

Step 3:  Adding our shortcut

Create another js file and call it mousekeys.js.  This is the place we’ll define our shortcuts and map them to GUI Javascript calls.

The below code was borrowed and adapted  from Albert Romkes excellent post about adding js files without showing a GUI element.   http://albertromkes.com/2012/01/30/tridion-gui-extensions-how-to-load-a-javascript-without-showing-a-gui-element/

/js/mousekeys.js

//If you only want your code to affect certain screens/views, you should listen to Anguilla events like this:
$evt.addEventHandler($display, "start", onDisplayStarted);

// This callback is called when any view has finished loading
function onDisplayStarted() {

	// Open Publish Queue dialog
	Mousetrap.bind('q', function() {
	                // UPDATE:  Below is the easy way to do it.  Make sure to update your Shortcuts.config to include the CME dependencies.  Big thanks to Frank van Puffelen (@puf) for the suggestion!
                        $commands.executeCommand('PublishingQueue')

			//var popup = $popup.create($cme.Popups.PUBLISH_QUEUE.URL, $cme.Popups.PUBLISH_QUEUE.FEATURES);
			//popup.open();
	});

    $evt.removeEventHandler($display, "start", onDisplayStarted);

    //alert($display.getView().getId());

   //if ($display.getView().getId() == "ComponentView") {
		//alert('comp view');
   //}
}

Step 4:  Finding the js call for the Tridion functionality

Using Firebug I inspected the Publish Queue button and then searched through the GUI js using Firebug Script window and found the code to open the Publish Dialog.  I feel lucky to have found it and that it worked.  :)  This is not always so easy and you might want to do some research before planning on mapping a shortcut to a favorite functionality, like checking-in or checking-out TBBs.  (if you do figure out how to do this pls leave a comment!)  :)  What other hotkey mappings would you like to see?

Step 5:  Create the config file for the extension

For me this was the first time using the domain model element within the config node.  It is a distinct difference between the normal method of having the cfg:file set node under the cfg:group node.

Shortcuts.config

<?xml version="1.0" ?>
<!--
    Tridion Hotkeys Extension

    Copyright (C) 2012 Robert Curlette
-->
<Configuration xmlns="http://www.sdltridion.com/2009/GUI/Configuration/Merge" xmlns:cfg="http://www.sdltridion.com/2009/GUI/Configuration" xmlns:ext="http://www.sdltridion.com/2009/GUI/extensions" xmlns:cmenu="http://www.sdltridion.com/2009/GUI/extensions/ContextMenu">
  <resources cache="true">
    <cfg:filters/>
    <cfg:groups>
      <cfg:group name="Curlette.Shortcuts" merger="Tridion.Web.UI.Core.Configuration.Resources.CommandGroupProcessor" merge="always">
          <cfg:domainmodel name="MousetrapDomain">
            <cfg:fileset>
              <cfg:file type="script" id="mousetrapLib">/js/mousetrap.min.js</cfg:file>
              <cfg:file type="script" id="mouseKeys">/js/mousekeys.js</cfg:file>
            </cfg:fileset>
            <cfg:services />
          </cfg:domainmodel>
          <cfg:dependencies>
            <cfg:dependency>Tridion.Web.UI.Editors.CME2010</cfg:dependency>
            <cfg:dependency>Tridion.Web.UI.Editors.CME2010.commands</cfg:dependency>
          </cfg:dependencies>
      </cfg:group>
    </cfg:groups>
  </resources>
  <definitionfiles/>
  <extensions>
    <ext:editorextensions>
      <ext:editorextension target="CME">
        <ext:editurls/>
        <ext:listdefinitions/>
        <ext:taskbars/>
        <ext:commands/>
        <ext:commandextensions/>
        <ext:contextmenus />
        <ext:lists/>
        <ext:tabpages/>
        <ext:toolbars/>
        <ext:ribbontoolbars/>
      </ext:editorextension>
    </ext:editorextensions>
    <ext:dataextenders/>
  </extensions>
  <commands/>
  <contextmenus/>
  <localization/>
  <settings>
    <defaultpage/><!--/Views/Default.aspx</defaultpage>-->
    <navigatorurl/><!--/Views/Default.aspx</navigatorurl>-->
    <editurls/>
    <listdefinitions/>
    <itemicons/>
    <theme>
      <path/><!--/CSS/</path>-->
    </theme>
    <customconfiguration/>
  </settings>
</Configuration>

Step 6:  Add the GUI Extension to the GUI
C:\Program Files\Tridion\web\WebUI\WebRoot\Configuration\System.config

<editor name="TridionShortcuts" xmlns="http://www.sdltridion.com/2009/GUI/Configuration">
<installpath xmlns="http://www.sdltridion.com/2009/GUI/Configuration">C:\Program Files\Tridion\web\WebUI\Editors\Shortcuts</installpath>
      <configuration xmlns="http://www.sdltridion.com/2009/GUI/Configuration">Shortcuts.config</configuration>
      <vdir xmlns="http://www.sdltridion.com/2009/GUI/Configuration">Shortcuts</vdir>
</editor>

Step 7:  Flush browser cache and try it.

Press the ‘q’ key in any window.  The moustrap js library does not work if you are in a text box or an input element, even if you use the ctrl-q key instead of ‘q’ as a hokey.

Code published at https://github.com/rcurlette/Publish-Queue-Shortcut

Summary

The GUI Extension framework allows us to easily enhance and enrich the User Experience using existing js libraries.  However, we should use care when adding libraries since they will be loaded with each GUI View and any errors in the js code will break the GUI.  To find out if your extension is breaking the gUI you can quicly comment it out in the System.config file and be back to normal very quickly.  I hope you enjoy using this and it makes it easier and quicker to view the Publish Queue.

Adding a new Tab to the Tridion Edit window is a powerful and easy GUI Extension to implement. The tab will show in all Edit windows or only the ComponentEdit “view”. SDL recently used this approach to integrate the Translation Management System (TMS) and World Server into the interface – great example of the extension! :) In this tutorial we will create a ‘Hello There’ GUI Extension and explain the concepts behind adding an extra tab to the edit screen.

Getting Started
We’ll need the following:

  • Filesystem access to your Tridion 2011 CMS Server (Program Files\Tridion\)
  • Editor for XML, HTML, and ASCX files
  • A Tridion CMS system with no other users logged in (since we will most likely break the GUI at some point)

Summary, we will:
In Visual Studio, create a new project and an ASCX control

In a JavaScript editor, create a simple JavaScript GUI Extension

In an XML editor, create a HelloTab.config file and configure IIS

Copy files to a new folder on the server C:\Program Files (x86)\Tridion\web\WebUI\Editors\HelloTab and update the System.config file

Tips for working with Anguilla Framework

Part 1: Create the GUI Extension Project and add the User Control ASCX File

1. Open Visual Studio 2010 and create a new Project, ASP.NET Empty Web Project.
2. Add a new Web User Control (ascx file) to the project. Name it HelloTab.ascx
3. Add a literal control to the ascx page and in the code behind set the text property to ‘Hello world’.

* Note: I could have created an HTML page, but instead wanted to use an ASCX page to show where the DLL from the bin folder would end up. In real life I prefer to keep the client simple with HTML and jQuery and the heavy lifting in a Web Services layer powered by ServiceStack.net.

HelloTab.ascx

<%@ Control Language="C#" AutoEventWireup="true" CodeBehind="HelloTab.ascx.cs" Inherits="HelloTab.HelloTab" %>
<asp:Literal ID="output" runat="server"></asp:Literal>
<div id="compUri"></div>

HelloTab.ascx.cs

protected void Page_Load(object sender, EventArgs e)
{
    output.Text = "Hello world";
}

Compile and Build the Solution. The DLL will be copied to C:\Program Files (x86)\Tridion\web\WebUI\WebRoot\bin

Part 2: Create the JavaScript

Type.registerNamespace("RC");

RC.HelloTab = function RC$HelloTab$HelloTab(element) {
    console.log('Constructor');
    Tridion.OO.enableInterface(this, "RC.HelloTab");
    this.addInterface("Tridion.Controls.DeckPage", [element]); //My extension is like this
};

RC.HelloTab.prototype.initialize = function HelloTab$initialize()
{
    console.log('init');
    this.callBase("Tridion.Controls.DeckPage", "initialize");
    $evt.addEventHandler($display.getItem(), "load", this.getDelegate(this.updateView));
};

RC.HelloTab.prototype.select = function HelloTab$select() {
    var c = $display.getItem();
    $j("#compUri").text(c.getId());
    console.log('select');
    this.callBase("Tridion.Controls.DeckPage", "select");
    this.updateView();
};

RC.HelloTab.prototype.updateView = function HelloTab$updateView()
{
    console.log('update');
    if (this.isSelected())
    {
        console.log('selected')
    }
};

Tridion.Controls.Deck.registerPageType(RC.HelloTab, "RC.HelloTab");

Order of Events:

  • constructor
  • select
  • initialize
  • updateView
  • selected

Part 3: GUI Extension Configuration and Setup IIS Copy files to server

Creating the config file HellotTab.config:

Create a new file called HelloTab.config. In this example the JavaScript, CSS, and ASPX files are all in the same folder, HelloTab. Here is the source:

<?xml version="1.0"?>
<Configuration xmlns="http://www.sdltridion.com/2009/GUI/Configuration/Merge"
               xmlns:cfg="http://www.sdltridion.com/2009/GUI/Configuration"
							 xmlns:ext="http://www.sdltridion.com/2009/GUI/extensions"
               xmlns:cmenu="http://www.sdltridion.com/2009/GUI/extensions/ContextMenu">

  <resources cache="true">
    <cfg:filters />
    <cfg:groups>
      <cfg:group name="RC.HelloTab" merge="always">
        <cfg:fileset>
          <cfg:file type="script">/HelloTab.js</cfg:file>
          <cfg:file type="script">/jquery.js</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>
    </cfg:groups>
  </resources>
  <definitionfiles />
  <extensions>
    <ext:dataextenders/>
    <ext:editorextensions>
      <ext:editorextension target="CME">
        <ext:editurls/>
        <ext:listdefinitions/>
        <ext:taskbars/>
        <ext:commands/>
        <ext:commandextensions/>
        <ext:contextmenus/>
        <ext:lists />
        <ext:tabpages>
          <ext:add>
            <ext:extension assignid="HelloTab" name="Hi There!" insertbefore="InfoTab">
              <ext:control>~/HelloTab.ascx</ext:control>
              <ext:pagetype>RC.HelloTab</ext:pagetype>
              <ext:dependencies>
                <cfg:dependency>RC.HelloTab</cfg:dependency>
              </ext:dependencies>
              <ext:apply>
                <ext:view name="ComponentView">
                  <ext:control id="MasterTabControl"/>
                </ext:view>
              </ext:apply>
            </ext:extension>
          </ext:add>
        </ext:tabpages>
        <ext:toolbars/>
        <ext:ribbontoolbars/>
      </ext:editorextension>
    </ext:editorextensions>
  </extensions>
  <commands/>
  <contextmenus />
  <localization />
  <settings>
    <defaultpage/>
    <navigatorurl/>
    <editurls/>
    <listdefinitions />
    <itemicons/>
    <theme>
      <path>theme/</path>
    </theme>
    <customconfiguration />
  </settings>
</Configuration>

A few things to highlight:

Name the config group:

cfg:group name="RC.HelloTab"

Specify any js or css files needed by the extension:

<cfg:fileset>
  <cfg:file type="script">/HelloTab.js</cfg:file>
</cfg:fileset>

Define standard dependencies:

<cfg:dependencies>
  <cfg:dependency>Tridion.Web.UI.Editors.CME</cfg:dependency>
  <cfg:dependency>Tridion.Web.UI.Editors.CME.commands</cfg:dependency>
</cfg:dependencies>

Define the ID, text for the tab, and location:

<ext:extension assignid="HelloTab" name="Hi There!" insertbefore="InfoTab">

The GUI ASCX control with HTML for the tab:

<ext:control>~/HelloTab.ascx</ext:control>

Define the Namespace and method for the JS file. I missed this the first time and my JS file would not load. Thanks to the StackOverflow post here for the help.

<ext:dependencies>
    <cfg:dependency>RC.HelloTab</cfg:dependency>
</ext:dependencies>

Specify the Edit view the Tab will appear on:

<ext:apply>
    <ext:view name="ComponentView">
      <ext:control id="MasterTabControl"/>
    </ext:view>
</ext:apply>

More about the Views option
Views – Which edit screen we load our GUI Extension
We can tell Tridion to only load our new Tab when we are editing a Component and not when editing a Template. To do this we’ll need to add a magic View name to the

The Tridion GUI Views are stored on the server at C:\Program Files (x86)\Tridion\web\WebUI\Editors\CME\Views.

The views folder contains some obvious ones like PageView and ComponentView. However, I am not sure about the DashboardView or CustomPageView – and hope that the Tridion Documentation team might come to our rescue here and weed out the ones that are not valid.

  • BluePrintViewerView
  • CategoryView
  • ComponentView
  • ComponentTemplateView
  • CustomPageView
  • DashboardView
  • FolderView
  • KeywordView
  • ListFiltersView
  • MultimediaTypeView
  • PageView
  • PageTemplateView
  • PopupsView
  • PublicationView
  • PublicationTargetView
  • SchemaView
  • SplashScreenView
  • StructureGroupView
  • TargetGroupView
  • TargetTypeView
  • TemplateBuildingBlockView
  • TridionDashboardView
  • UserAccountsView
  • VirtualFolderView
  • WorkflowProcessView

Save the config file. Create a JS file HelloTab.js for the interaction with the Tridion GUI and Anguilla API. Below is a basic example:

Setup Virtual Directory in IIS
– Add VDIR to IIS, point to HelloTab Editor folder
– The name of the VDIR should match the VDIR node in the system.config file.

Part 4: Copy files to Server and update System.config

Create folder and copy files
– Create a new Folder in the Editors folder called ‘HelloTab’. Full path is ‘C:\Program Files (x86)\Tridion\web\WebUI\Editors\HelloTab’
– Copy HelloTab.ascx, HelloTab.js, and HelloTab.config files
– Copy the DLL file from the build output to ‘C:\Program Files (x86)\Tridion\web\WebUI\WebRoot\bin’. This is the location where all the DLLs associated with a GUI Extension are deployed. If you register the DLLs in the GAC then you could place them in another location.

Add Extension to System.config:

<editor name="HelloTab">
  <installpath>C:\Program Files (x86)\Tridion\web\WebUI\Editors\HelloTab\</installpath>
  <configuration>HelloTab.config</configuration>
  <vdir>HelloTab</vdir>
</editor>

Test
The new Tab should appear in the ComponentEdit screen. Great! But, we still need to do something in the tab.  Let’s add some JavaScript and talk with the Anguilla API.

Part 5: Working with the JS Anguilla API

Anguilla is the powerful Tridion JavaScript framework that makes the magic in the Tridion 2011 GUI possible.  Unfortunately, it is not well known and not too many code samples are available yet.  Some hints of methods and objects can be found in the Tridion 2011 Views folder at C:\Program Files (x86)\Tridion\web\WebUI\Editors\CME\Views. The Tridion 2011 PowerTools also use the Anguilla framework and provide additional opportunities to gain hints. SDL Tridion World has the Anguilla documentation available for download in the Documentation downloads section. With all that said – most Tridion developers that I know have a background in server-side Web development and writing OO JavaScript is not in the comfort zone of many, including me.  We have the option to do the minimum in Anguilla and then run to the Core Service to do the heavy lifting – but I hope in the future we can use more of the built-in methods in Anguilla.

Trick for jQuery

Tridion PowerTools use jQuery and have a trick to load it so it does not conflict with Outbound Email. Clever! After adding this then we use $j for our jQuery magic.

var addJquery = function ()
{
    // ... jQuery here ...
    //YM: to avoid conflict with the Outbound Email extension, we define a new shorthand for jQuery
	window.$j = jQuery.noConflict(true);
};
addJquery();

Using jQuery in the JS code:

 $j("#compUri").text("tcm:0-0-0");

Displaying the URI in the Tab

var c = $display.getItem();
$j("#compUri").text(c.getId());

Fun with the Chrome Developer Console and Anguilla:

  1. Set a breakpoint on the line after the var c =
  2. Open the Chrome Debugger
  3. Scripts tab
  4. Component…aspx script
  5. Scroll to bottom of script and find your code. Alternative use the find feature of Chrome. You should see console.log(‘select’);
  6. Add a breakpoint by clicking on the line #
  7. Now refresh and it will stop on that line when you’ve seelcted the new tab. Don’t hit continue yet.
  8. Go to the Console tab, hit c. and amaze at the amount of methods we have available – via the Anguilla JavaScript Framework – at our disposal.

The Tridion Live Documentation contains a very quick guide to Tab GUI Extensions here. Don’t forget to login first before clicking the link.

Summary

This GUI Extension is a simple one and is intended to give you the ideas and some confidence with creating your first one. With the Component URI and the power of the Anguilla Framework you can already do some magic via JavaScript in the tab with this example. However, it is also possible to make a webservice call from the js and do more server-side api work there. I hope you were able to follow along and that this inspires you to create your own extensions. A big thanks to the Tridion community on StackOverflow – without you the article would not be possible.

Get the code

https://github.com/rcurlette/GuiExtensionHelloTab

DataExtenders are one of the coolest features in Tridion 2011 – and allow us to add our own column into the default Tridion ListView for all users.  We can save time when finding content – no need to open 10s of Components to find a specific value. However, with this new power comes a greater responsibility, and we must take extra care to make our code lightning-fast and test it well. In this example I will provide a working solution for adding a Metadata field column as well as explain how to do something similar yourself. All we need now is time and a little bit of luck to pull it off.

Tridion DataExtenders edit the response sent back from the GUI to the Browser.  In other words, our code runs every time for every user using the Tridion GUI.  DataExtenders are not limited to adding additional columns to the ListView.  Tridion uses this approach for the recent SDL World Server connector where they provide extra fields in the Schema edit screen, for example.  However, we’ll first start here on the ListView as it is the most useful GUI Extension for our scenario.

Tridion editors in my current project add the product sku to the Metadata field of each product.  When changing content or updating products they often have a product name or sku – and having this sku visible in the ListView provides a big time-saving.  The GUI also nicely provides the sort and filter functionality available from other columns to our new column.  However, to add this extra column our code will take time to find the sku value – and this will add a little bit to the response time of the GUI – especially for folders with lots of Components (100s).  So, it is a trade-off – will your users wait 1 second more for every 100 items in a folder if it means they can see the product Sku?  Do most of your folders contain less than 100 items?  In my case, yes, it is worth it, and we almost never have more than 100 items in a folder.

Example, note the Metadatafield column:

Metadata Column added to Tridion GUI

Getting started – Download the Example and Run the Code

1.  Get the example here: https://github.com/rcurlette/DataExtenderMetadataCol.  Open in Visual Studio 2010.

2.  Set the metadata fieldname.  Open the AddMetadataColumn.cs file, change ‘article_number’ to your fieldname.

3.  Compile.  Copy ALL files in the VS output folder (/bin/Debug) to the CMS Server at /Tridion/web/WebUI/WebRoot/bin.

4.  Create a new Folder on the CMS server for your DataExtender GUI Extension.  For example, create the DataExtender folder here: /Tridion/web/WebUI/Editors/DataExtender 

5.  Copy the DataExtender.config file to the folder above in step 4.

6.  Add the DataExtender config location to the System.config file in Tridion\web\WebUI\WebRoot\Configuration\System.config.

<editors default="CME">
  ...
  <editor name="DataExtender">
    <!-- DLL Files for DataExtender to be deployed to /Tridion/web/WebUI/WebRoot/bin -->
    <installpath>
     C:\Program Files (x86)\Tridion\web\WebUI\Editors\DataExtender\
    </installpath>
    <configuration>DataExtender.config</configuration>
    <vdir/>
  </editor>
</editors>

7.  Refresh the GUI and behold your new GUI ListView Column

Overview

How did we make that happen?  Well, DataExtenders are a special type of GUI Extension and allow us to modify the Response the GUI sends to the clients.  This is quite different than ContextMenu GUI Extensions.  Here our code is in ASPX / C#  while the ContextMenu code is mostly in JavaScript.  It feels like we’re hooking into a different aspect of the Tridion GUI and it requires a different approach – not only to how we develop, but also to how we test the code as well as how we debug and deploy.  Read on to find out how this was built and learn some tips and tricks for building your own DataExtenders.

Creating a new DataExtender

Speed is our primary concern when writing DataExtender code.   Not how fast you can type, but how fast your code executes.   The code is executed for every response – and we filter the response for the GetList command; all items in the listview.  Test the code with a folder containing hundreds of items – not only a few!  This cannot be overstated and is why I start with this disclaimer.  With the Tracing log feature you can view how much time your code is taking and adjust accordingly.  This is the most important and limiting aspect of developing a DataExtender since it affects all users and all content.

Create the .NET Class Project –  Create a new .NET Class Project and add a new Class file.

Extend the DataExtender Class – First we need to extend the DataExtender class.

public class AddMetadataColumn : DataExtender

Add the Namespace:

using Tridion.Web.UI.Core.Extensibility;

Reference the Assembly:  (located in Tridion/web/WebUI/WebRoot/bin)

Tridion.Web.UI.Core

Override the ProcessResponse Class

The ProcessResponse class is the main entry point for the DataExtender and is called for different types of GUI responses.  Notice here we check the command to see if it is for ‘GetList’.  This is critical for filtering out other requests and only listening to the listview.

This code is from a great example written by GUI Hacker Serguei Martchenko at http://www.sdltridionworld.com/community/2011_extensions/parentchangenotifier.aspx.

public override XmlTextReader ProcessResponse(XmlTextReader reader, PipelineContext context)
{
  XmlTextReader xReader = reader;
  string command = context.Parameters["command"] as String;
  if (command == "GetList")  // Code runs on every GetList
  {
    try
    {
      xReader = PreprocessListItems(reader, context);
...

Disclaimer: Any errors in the PreprocessListItems breaks the GUI.  If your XmlTextReader does not return at least the original data you will have missing data in the GUI.

 

ReCreate the <tcm:Item /> node, return as XmlTextReader

As mentioned above, we need to pass back at least the data that Tridion is sending back.  Thanks to the example code from Serguei we only need to follow a couple of simple rules.

1.  Re-write all existing attributes to the <tcm:Item node.

 xWriter.WriteAttributes(xReader, false);

2.  Add code and logic to get additional data.

attrValue = GetMetadataValue(comp, "article_number");

 

Getting the metadata value

In the example code I call a GetMetadataValue method for getting my data.

private string GetMetadataValue(Component comp, string fieldname)
{
  string value = "";
  xmlDoc.LoadXml(comp.GetXML(Tridion.ContentManager.Interop.TDSDefines.XMLReadFilter.XMLReadDataContent));
  string xPath = String.Format("//*[local-name()='{0}']", fieldname  );
  if (xmlDoc.SelectSingleNode(xPath) != null)
  {
    value = xmlDoc.SelectSingleNode(xPath).InnerText;
  }
  return value;
}
The performance criteria of the Metadata field example pushed me to use a TDSEWrapper instead of the Core Service.  The Core Service was quite slow – although I did not use Jaime’s approach with the tcp_Binding and instead used the default http_Binding.  I tried to create the WCF client once and re-use it, but maybe I did it wrong?  Anyways, it was the slowest of my examples.  Sergeui Martchenko also uses a TDSEWrapper for his code samples – maybe for the same reason?
Performance tests with folder of 250 Components:
Core Service 12 seconds
TDSE Object Model 12 seconds
TDSE GetXml 2 seconds

The load times are surprising and I would look to persisting Tridion data to an external system such as Redis or a database to improve performance times.  This cannot be emphasized enough – the Tridion API might not be fast enough – and you should seriously think about getting the data from another source.

3. Display the value with XPath in the DataExtender.config file

 <column xmlns=”http://www.sdltridion.com/2009/GUI/extensions/List”
                             id=”Metadatafield” type=”data” title=”Metadatafield”
                             selector=”@metadataFieldValue” translate=”String” />

Debugging – Enabling GUI Tracing

While writing this example I used the Trace debugging a lot – not only for timing certain actions – but also in my try/catch blocks for writing out errors.  This is the only way to Debug DataExtender code and it works well.  However, our log file grows REALLY fast – so you might not want to keep it running all the time.  In the C# code we can use Trace.Write to write output to the GUI Trace log.  Don’t use Trace.WriteLine – it doesn’t work.  This is also the best way to know our DataExtender is being executed. If we do not see the DataExtender name in the log file then it is not being loaded.

1.  Backup original file. Rename Tridion\web\WebUI\WebRoot\bin\Tridion.Web.UI.Core.dll to Tridion\web\WebUI\WebRoot\bin\Tridion.Web.UI.Core.dll.bak

2.  Copy Tridion.Web.UI.Core.dll Trace DLL from /trace to to /bin.  Location:  \Tridion\web\WebUI\WebRoot\bin\trace\Tridion.Web.UI.Core.dll

3.  Turn on Tracing in \Tridion\web\WebUI\WebRoot\Web.Config

<compilation debug="true" defaultLanguage="c#">

4.  Confirm Trace File is Created.  Refresh GUI, Trace log, Tridion.Web.trace, created in the folder  \Tridion\web\WebUI\WebRoot.

To delete Trace file – stop IIS (net stop w3svc) and then delete.

* Warning – This produces a LOT of log output – you do not want to do this in Production.

Example Trace code to output start time

Trace.Write("==========================Start PreprocessListItems " + System.DateTime.Now.ToShortDateString() + ", " + System.DateTime.Now.ToLongTimeString() + Environment.NewLine);
Trace File Output – Notice my GUI Extension is there ‘AddMetadataCol’.

Example Trace Code to display <tcm:Item XML

return xReader;  //around line 157
Trace.Write(sWriter.ToString() + Environment.NewLine);
// Trace.WriteLine breaks code

Quickstart:  Sample Empty DataExtender Class

If you are starting a fresh DataExtender you can use this class to get started instead of my  AddMetadataColumn.cs class.

 

This code is the basis of every DataExtender – and does nothing more than re-writing the XML output.

 

1.  Rename Example Classname to yours.

2.  Add your custom code to append content to the tcm:item node.

3.  Use Trace.Write to write to logTrace.Write(sWriter.ToString() + Environment.NewLine);

* Trace.WriteLine does NOT work – will break code.

4.  Update the Tridion Project References

using Tridion.ContentManager; // C:\Program Files (x86)\Tridion\bin\client
using Tridion.Web.UI.Core.Extensibility; // C:\Program Files (x86)\Tridion\web\WebUI\WebRoot\bin

 

Compile, Deploy, and Update DataExtender Config

As with all GUI Extensions – getting the right configuration is half the battle.

1. Copy the GUI Extension DLL and ALL other DLLs in the /Debug/bin (or /Release/bin) from the output of your VS build command to the Tridion Server folder \Program Files (x86)\Tridion\web\WebUI\WebRoot\bin

2. Add extension.config file to the /Editors/YourDataExtender folder. Check out the relationships between your Namespace, Classname, and AssemblyName for the config.

Take special note of the DLL Name (from the Project Properties window) and how it corresponds to the Config.  This was the most difficult part of writing the DataExtender for me.

type=”Namespace.Classname, Assemblyname” 

DataExtender Assembly Name
DataExtender Assembly Name
DataExtender Class File
DataExtender Class File

Tridion DataExtender Config fileTridion DataExtender Config File

3. Update the System.config file with the location of your config file

 

Add the DataExtender GUI Extension to the System Config

As soon as you do this your GUI Extension is ‘enabled’ and any errors / issues will be seen immediately in the GUI for all users.

Save in:  C:\Program Files (x86)\Tridion\web\WebUI\Editors\DataExtender\ DataExtender.config

Update the System.config file 

<editors default="CME">
  ...
  <editor name="DataExtender">
    <!-- DLL Files for DataExtender to be deployed to /Tridion/web/WebUI/WebRoot/bin -->
    <installpath>
     C:\Program Files (x86)\Tridion\web\WebUI\Editors\DataExtender\
    </installpath>
    <configuration>DataExtender.config</configuration>
    <vdir/>
  </editor>
</editors>

 

DataExtender Tips:

Be Fast, be very fast - Your code is going to slow down the GUI, no question about it. But, how fast can you make your code? This is a key factor to the success of rolling out your GUI Extension.

Document it –  your code will be executed for every list view in every Publication of the GUI. Knowing what is happening there will help all developers maintain it in the future. Flow diagrams are good here.

Use your own Dev Server –  I broke the GUI a lot of times before getting it to work. So – best to do this on your own local instance or in the middle of the night.

Troubleshooting:

Nothing shows in the lists – Comment out your extension in the System.config.  Does it work now?  Ok, you definitely broke it.

Write out the Tridion tcm:Item XML.  See line 166 in the AddMetadataColumn.cs file.

xWriter.WriteAttributes(xReader, false);

Make sure the default tcm:Item attributes are added the the XML.

attrValue = GetMetadataValue(comp, "article_number");

 

Summary

Big thanks to the Tridion R&D team for giving us the power to do this.  It allows us to mold the Tridion CMS for our own organizations and improve efficiency while saving time.  This  can be very handy.  Programming the DataExtender is quite simple and most of our effort is in the Tridion API code itself – something we should all be familiar with. I am very happy with the approach and possibilities. We are very lucky that the base code has been provided from Seguei and we only need to get our config correct and deploy the files. One last warning that your code will be executed for every GetList request, so if your code is not fast then it is not for this type of extension. I can imagine for some use-cases going to the Tridion API for each piece of data will be too time-consuming and you may need to persist that data to an external system such as Redis that is much faster.  Have fun and try to remember to be kind.

Adding a new column to the Listview in Tridion 2011 is easy with using Data Extenders. With a few simple config changes we can add the TCM URI column to our default view – no code needed! In this article I will explain how to add the URI column as well as give some debugging tips.

Concept

The Tridion Listview can be extended using DataExtenders. The idea is that the config file for the extender specifies an XPath expression and matches some data in the GUI Response.  We are lucky that the URI is part of the default GUI response and we simply need a little XSLT and config to show it.  However, we can also add new data to the GUI Response is by extending the DataExtender class in .NET.   I do not cover that here but there is an example in the Tridion LiveDocs.

We will:
1. Create a new GUI Extension – but only providing our config file since the URI is part of the default GUI Response
2. Add our new extension location to the System.config folder.

Steps for Adding the ListViewTCM Extension

1. Create a new folder under Tridion\Web\WebUI\Editors\ called ‘ListViewTcm’
2. Copy the extension config file below there. The important part in this code is the selector. It is doing an XPath match on the XML the Gui response is sending and selecting the ID attribute. We are lucky the ID is part of the response. Otherwise, we would extend the DataExtender class in .NET and is something I do not cover here.

Interesting part:

<ext:columns>
  <column xmlns="http://www.sdltridion.com/2009/GUI/extensions/List  "id="MyColumnID" type="data" title="URI"
  selector="@ID" translate="String" />
</ext:columns>

Whole config file:

3. Update the System.config to let it know about our new GUI “Extension”. :)

<editor name="ListViewTcm">
  <installpath>C:\Program Files (x86)\Tridion\web\WebUI\Editors\ListViewTcm\  </installpath>
  <configuration>ListViewTcm.config</configuration>
  <vdir/>
</editor>

4. Refresh the GUI and marvel at your new URI List column. I know I was delighted and surprised when I first saw it.

Debugging tips

Mostly useful when you start building your own DataExtenders to put more info in the Response. Not used here though, since URI is already part of our response:

1. Enable debug output for the GUI
System.config, <client debug=”true”>

2. Enable GUI debugging in the Browser

http://TridionDev2011/WebUI/Editors/CME/Views/Dashboard/Dashboard.aspx?mode=debug

3. View the Tridion.Web.Trace file in the WebUI/WebRoot folder. This is mostly used when debugging the .NET DataExtenders and something not covered here. Check if your extension is listed. This means the config is good and the GUI is trying to load it. When it does, you will see this message. This is good output: “Executing request-extension : ‘ListViewTcm'”. This is bad and most likely due to wrong Namespace / Class: “Configured dataextender ‘AddSchemaTitle, ListViewTcm’ can not be created, check .Net’s fusion log for more information”

Summary

Great job to the Tridion GUI Team for giving us the power over the Listview and ability to add columns. This extra information will save countless hours when searching for that extra piece of information and not having to open the item (or mouseover) to find it. The new column gets sorting and filtering for free and behaves just like the other columns. Overall I cannot wait to play more with this new and powerful feature.