Friday, June 2, 2017

Go To Location | Alchemy Plugin for SDL Web

At SDL Web Dev Summit 2017 in India, I got this opportunity to show & tell on "how to create a Alchemy Plugin in 30 mins". And I choose to build this simple "GoToLocation" Alchemy Plugin there.

This plugin adds a Ribbon Tool Bar Button 'Go To Location' to the Repository Local Items Views including Page, Component, Schema, Component Templates, Page Templates and Template Building Blocks. On clicking the button SDL Web redirects the user to the location of the item.

This plugin is useful in the situations when a user wants to navigate to the Item's location form the Item's View.

In case you missed the event, lets revisit the plugin again. So before we begin, get the plugin's code from here so that we both are on the same page.

Facts about the plugin:
  1. It is a Ribbon Toolbar Extension, which places a "Go To Location" button in the ribbon.
  2. It will be applicable to following views:
    • Component
    • Page
    • Schema
    • Page Templates
    • Component Templates
    • Template Building Blocks
  3. On clicking the button, a Command fires to take the control to the item's location.
  4. It needs to have following resources (Resource Group) available in Tridion
    • Image - to be applied on the button
    • CSS File - to define styling on the extension button
    • Command JS File - to define the command to be fired on button click

Lets visit the code against the above points:
  1. Open the file "Config\GoToLocationExtension.cs". you would notice that the class is extended with the base class "RibbonToolbarExtension". Doing this you instruct Alchemy Framework that your extension is a Ribbon Toolbar Extension.
  2. In the same file you would see the lines like Apply.ToView(Constants.Views.{ViewName}). The code is to apply the extension on different views.
  3. We always define the Tridion Commands in JS files and place it inside a fixed folder structure "Static/Commands". You can see we have "GotoLocationCommands.js" in there to define our command. In execute method of the command, we simply get the "GoTo" command defined in Anguilla Framework and execute it on selected item.
  4. Resources are generally supportive files needed in Tridion for your extension. These files are organized in a fixed structure in the project inside the "Static" folder.
    • Image: To apply an image, we need to add the image in the project inside the folder "Static/Images" so that it is available to use.
    • CSS File: This file contains all the styling we need to add to our extension and sits in "Static/Styles" folder. In this case we just want a background image for the ribbon bar button as styling. If you notice in the css file, we are applying the image on a element with the id "RibbonToolbarGoToLocationButton". The id is nothing but the Assign Id of the extension (defined in "GoToLocationExtension.cs" file), which ends up as a HTML element id for the extension. 
    • Command JS File:  The file is located at "Static/Commands" and contains the command as we mentioned in point 3.
Now when we created different pieces we need for the functioning of our extension, We need to instruct Alchemy Framework; what is what and how these are inter connected?
  1. Alchemy Framework needs to know about the commands your extension have and to define it, we create a class derived from "CommandSet" base class. The class "GoToLocationExtension.cs" could be spotted under "Config" folder, having the command added (defined in the Command JS File, the name must match)
  2. We must tell Alchemy, which resources are going to use for the extension and to define it, we create another class derived from "ResourceGroup" base class. This class adds all the Resource Files, Command Sets and other dependencies needed for the extension. The class can be found at "Config/GoToLocationResouceGroup.cs".
  3. Lastly tell Alchemy that the extension is dependent on the Resource Group we just created. To do so, add the line Dependencies.Add<GoToLocationResouceGroup>() to the extension class "Config\GoToLocationExtension.cs".
And that's it. All other properties in the code files are quite self explanatory. 
Now build the project, you get your .A4T alchemy file for the extension. yay!