Click or drag to resize
AlchemyGUI Extensions

GUI Extenions for Alchemy4Tridion are built off of the existing Anguilla framework but contain utilities and tools that help automate a lot of the pain staking tasks that you might have had to deal with before. One of the main differences in building a GUI Extension for Alchemy4Tridion versus the tradtional way is with how configuration is dealt with. A good reference point that you can use as an example is the Hello World plugin project.

This topic contains the following sections:

Configuration

Configuration in Alchemy4Tridion for GUI Extension utilizes code over configuration. That is, you'll no longer be figuring out what elements to add to the editor config, but rather will be creating classes in .NET that inherit base classes that represent the type of items you are trying to create. For example, to create a Resource Group, you'll create a class that inherits from ResourceGroup and in your constructor call any methods and properties to configure your resource group to your needs. This provides the benefit of having Intellisense to provide you with tips/instructions as well as compile time error checking (no more accidently misspelling an element name and having Tridion's GUI go haywire on you).

Note Note

Alchemy4Tridion still uses an Editor Configuration file behind the scenes. When your plugin installs, the framework is responsible for adding the necessary elements which your config classes represents. During an uninstall, the framework removes all elements that were created by your plugin.

Basics

Most of the GUI Extension types that you'll create have the same basic steps that you will follow for each one.

  1. Add static files to your "Static" or "Assets" folder in your class library project. This includes JavaScript files that represent Commands or functionality for your plugin, StyleSheets to make your extensions look good, views or user controls, etc. This is pretty much the same step that you'd do with a traditional extension.

  2. If you're including JavaScript Commands, include a class that inherits from CommandSet.

    C#
    public class MyCommands : CommandSet
    {
        public ServicerCommandSet()
        {
            AddCommand("MyCommand");
        }
    }
    Tip Tip

    In the above example, it is assumed that you created a command with the name of "MyCommand" via JavaScript in the previous step. Note that no Implements is required as long as you add commands to the default namespace of Alchemy.Plugins.YourPluginName.Commands.CommandName. If you've created your namespace for the command differs, you will have to supply it in the 2nd argument of AddCommand.

  3. Add a class that inherits from ResourceGroup. This represents a Resource Group... that is a uniquely named group that contains a set of JavaScript and Stylesheets. When a Tridion page or view loads, it bundles all of the resource groups utilized by the page's dependencies into a single source and minifies it (minification can be turned off of course).

    Resource groups can be dependent on other resource groups... this ensures that resources in those groups are added above yours during the bundling process. If a group is included more than once for a particular view due to multiple items being dependent on it, Tridion ensures that those resources only get included once and not multile times.

    C#
    public class MyResourceGroup : ResourceGroup
    {
        public MyResourceGroup()
        {
            AddFile("my-js-file.js");
            AddFile("my-stylesheet.css");
    
            Dependencies.AddAlchemyCore();
        }
    }
    Tip Tip

    You'll notice in the above example we only have to supply the filenames and not the full paths. This is due to Alchemy placing static files in specific folders within the plugin package.

    If your plugin contains a command and you created the command set from the previous step, you'll need to reference it in your resource group. You can use the parameterless AddFile method with a generic type of your command set class.

    C#
    AddFile<MyCommands>();

    If you require proxies to web services that you are creating, or if you need the special proxied out of the box services like being able to get your custom configuration client settings, you'll need to also call AddWebApiProxy.

    C#
    AddWebApiProxy();
    Tip Tip

    The WebApi proxy automatically includes a reference to the core Alchemy resource group, so there is no need to call Dependencies.AddAlchemyCore(). However, if you do call both methods, there is no harm done.

  4. Add a class that inherits from the Extension type that you want to add, like ContextMenuExtension (if you want to add items to the context menu).

    public class MyContextMenu : ContextMenuExtension
    {
        public MyContextMenu()
        {
            // This is the id which gets put on the html element for this menu (to target with css/js).
            AssignId = "MyContextMenuId";
    
            // The name of this extension
            Name = "MyName";
    
            // Where to add your custom items. In this case it'll be before the refresh icon.
            InsertBefore = "cm_refresh";
    
            AddItem("cm_my_context", "My Context Menu", "MyCommand");
        }
    }
    Note Note

    The AddItem call above includes three arguments. The first is the id of the element that will be created (you can use #cm_my_context in your css or js selectors). The second argument will be the label that is displayed. The third argument is the name of the command to call when that item is clicked... in this case it'll be the custom command that you created.

  5. Configure a4t.xml, Build, Upload to Webstore, Install/Deploy.

    These last steps are the same regardless of the type of plugin you are building.

GUI Extension Types

The following GUI Extension Types are currently supported by the Alchemy4Tridion framework. Anything not listed below is not yet supported. Documentation to come on any section below without it...

See Also