Alchemy | What do you want to extend ?

  

In one of my previous blogs, I talked about the Five Basic Things you should know before developing a Alchemy Plugin. One of the most important thing listed there is, "What do you want to extend?" in Tridion GUI. The answer to this question would lead you to the Classes in Alchemy Framework,
you would have to extend in the plugin code. You can term them as Extension Points as well.

Tridion provides some extension points/areas out of the box. In Alchemy Framework you would get all those extension points as Base Classes, you simply need to extend those classes according to your plugin need. Let's talk about the Extension Points one by one.

1. Context Menu Extension:

A Context Menu appears once a user right clicks on a Item in Tridion GUI. So if you want to add an entry in the Context Menu, you would have to extend "ContextMenuExtension" class in your plugin code.

Title Translator plugin is a really good example of Context Menu Extension, The code for the plugin can be found here.

2. Command Extension:

Tridion's Anguilla Framework exposes many commands like Open, Save, Localize etc. Which are executed on respective events in the GUI. If you want to override the behavior of a command, all you need is to extend "CommandExtension" class in your plugin's code.

For example, if you want to perform some action when user saves an item, you would need to create a Alchemy Plugin by extending the class "CommandExtension".

We have a Plugin named Localize Commenter which extends this extension point, where a custom popup appears when a "Localize" command is executed.  The code for the plugin could be found here for reference.

3. Extended Area Extension:

If your requirement is to extend a existing view, you might want to have a look at the extended areas extensibility. For example, if someone wants to add a additional check in fields details in schema design, you might need to create a plugin extending "ExtendedAreaExtension" class. I don't have any real plugin for reference, so attaching the image to give you an idea.

4. Extension Group:

So, if you don't find a suitable extension point for your plugin idea or requirement. The Extension Group extension could be your best bet. Basically this extension allows you to add your custom resources (JS, CSS, Images etc) to the different views in the GUI. These resources can then interact with the HTML and Tridion UI Core (using Anguilla framework) to produce desired results.

One good example of this type of plugin is Publication Panel Search. It places a search box above the Publication List in the left-hand panel. Users can simply start typing into the text box and Publications with the title containing the entered text will be filtered. The full code for the plugin can be referenced from here.

5. Ribbon Toolbar Extension:

As it's name suggests, this extension point is to extend the Ribbon Toolbar at the top. With this one can add buttons and manage groups in the toolbar. To achieve this all you need to extend the "RibbonToolbarExtension" class and use it's members accordingly, while coding the plugin.

There are many plugins of this type available on the Alchemy Web Store, one easy pick could be Go To Location. This plugin adds a Ribbon Tool Bar Button 'Go To Location' to the Repository Local Item views, on clicking the button user is redirected to the location of the item. The code for this plugin can be found here.

6. Tab Page Extension:

If a Tridion item is opened in explorer, there would be tabs like General, Source, Info etc. To add a custom tab to the view, in the plugin's code one has to extend the class "TabPageExtension" and use it's members accordingly.

There is again this plugin Localize Commenter which extends this extension point. The plugin adds a tab "Localize Comments" in the item's view, where localize comments can be viewed and edited. The code for the plugin can be found here for reference.

Five Basic Things you should know before developing a Alchemy Plugin

Alchemy for Tridion is getting popularity by every day passing. More and more plugins are being submitted to Alchemy Web Store. I have developed few and it's really a fun. So if you want to give it a try go ahead, all you need to do is:

1. Install the Alchemy on your DEV CMS Machine.

2. Get the Alchemy development framework to visual studio using Nuget Package or VS Pack.




Now when you are all set to develop a Alchemy Plugin from your idea. Ask the below questions to yourself and note the answers:

1. What does it do?
2. What do you want to extend?
3. Where to show your extension?
4. When to show your extension?
5. What resources you need to have in your extension?

What does it do?

The answer to this question will help you with

1. You can copy and paste the answer to the description element value of the "a4t.xml" file in your visual studio solution.

2. This will help you identify the possible conflicts with existing OOB GUI/Functionality. Which is quite important consideration before developing a plugin.

What do you want to extend?

So Tridion provides some extension points/areas OOB. In Alchemy Framework you would have all those extension points as Base Classes as below: 

• CommandExtension
• ContextMenuExtension
• ExtendedAreaExtension
• ExtensionGroup
• RibbonToolbarExtension
• TabPageExtension

You have to answer which extension point(or points), you want to extend. And based on this answer, you would create your Extension class by extending one of the above listed classes.

Where to show your extension?
So other than command extension, you need to tell Alchemy where you want to show the extension. This is really a important question as you need to make sure your extension doesn't break the existing GUI and not in conflict with another Plugin/Extension.

When to show your extension?
So there could be conditions when to show (or execute in case of command extension) the Extension. For example, a particular Extension could be available for any particular User Group. So if you have any condition like it, you would have to take care of this during the development. There are different ways to control it for different type of Extensions.

What resources you need to have in your extension?
You could have additional resources to support your extension like JS, CSS, ASPX ans ASCX files. You need to identify the resources and the place to put those. Alchemy Framework has a very specific structured way to organize those files.

I will cover all above points in detail in my coming blogs. I hope this high level information helps.    

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!

Items Panel Search Alchemy Plugin

Here is another Alchemy plugin called Items Panel Search, which is now available on Alchemy Web Store. It is inspired by another plugin called Publication Panel Search, publication panel search plugin operates on publications list but this plugin on items list in the right panel. It places a search box over items list to search or filter items. User types some text and the items list gets filtered on every key press and shows the items containing the string.

Also, the plugin preserves the search value and the search results if user open an item from the list or does the sorting. User can reset the search by clicking the refresh button at the top of the list.

Other than search for a particular item in a long item list, this plugin could be useful in situations when someone wants to operate on a set of items having a common string in title of the items. As shown in below image, all the items having “Articles” in titles are filtered.

This plugin gives users two search options, titles only and all information presented in the list. By default it searches on the titles of the items, if user want to search for all information shown, he can enable it going to plugin configuration and set the value for “SearchAllInformation” to true.

In technical term it is a GUI extension of type Resource Extension Group added to the Dashboard View. It simply contains a JS file as a resource, that is responsible to put the search box on the top of FilteredListControl and all the functionality included.

To see the plugin code please visit this Github link.

Feel free to contact if you have any questions or suggestions regarding this plugin.

Title Translator | Alchemy Plugin for Tridion

I worked on a Tridion implementation for a client managing huge local content for their websites. One could imagine that local content is hardly anything to do with a developer, but he could be wrong. So at that client, with the content inside the localized components, the title of the items were also in local languages (at many places), specifically they had tons of local taxonomies with the local language titles. Now if any issues reported for a localized website, it was a nightmare for the developers to dig in to the content while investigating that issue because we developers knew only English language.

Few weeks ago, while looking at some of old work for that client that I remembered those days and that issue. So I decided to create a Alchemy Plugin called called Title Translator to address that issue, you can follow the link to Alchemy Web Store and download it from there.
This is really a simple plugin which uses SDL Translation API in background, all you need to do is get a SDL Translation API key, set the key in Plugin Configuration and you are ready to go. In the coming versions, I will try to include the support for Microsoft and Google translation as well.

To use the plugin, simply right click on a title in your CMS Filtered Item list or left-hand​ navigation panel and select 'Translate Title'. The updated title will show in the notification bar.

On the Technical side, This plugin is created using Alchemy Framework. The idea was pretty simple, create a context menu extension and on clicking it fire a command to show the translated title in notification bar.

The Code for the Plugin can be found here on Github. This basically have following building blocks:

• TranslatorContextMenuExtension: This class holds information about your context menu extension. Other than specifying name and id, below are the important pieces of info it has:  
• The order of your extension in the context menu.
• Associated command to the context menu extension.
• Dependent resource groups.
• Which view, the extension applies to, In this extesnsion it applies to "DashboardView".
• TranslatorCommandSet: The class is all about creating a command set from the commands specified in the JS files. We have only one command called "translate" and it is add to the commandset.
• TranslatorResourceGroup: This class is used to tell alchemy, which resources (files/CommandSets) are you using in your extension. We have just one JS file named "TranslatorCommand.js" and one command set, so adding those in there.
• TranslatorCommand.js file: This file holds the command code, which fires once "Translate Title" in context menu is clicked. The code basically sends the request to the SDL Machine Translation Service and gets back the translated title as an response and shows it in notification bar.

That's it chaps, go use it. And yeah, feel free to leave comments, questions, report bugs, improvements, pretty much anything related to it.

Thanks.

My First Alchemy Plugin - Publication Panel Search

Over the past few weeks, I have been noticing these four words "My First Alchemy Plugin" many places in the SDL community. So in my free time, I started my first Alchemy plugin as well and believe me it is a kind of addiction. Once you start it, you get involved with it more and more, so many plugin ideas starts hitting your mind, you don't mind waking up at 3 am to finish up your plugin. hmmm.. it's like Coke-en my friends :)

To start to build an Alchemy plugin, I reached out to the quick start guide at http://a4t-api.alchemywebstore.com, and after setting the project and test deployment to my local Tridion environment, it was just coding in Javascript (using Anguilla) all the way until my plugin was finished.

Coming to my plugin, what is this all about?

So I was working for a client, who has 300+ publications to manage in Tridion and it is always a pain to navigate to the different publications in a "230 x 275" GUI box, using mouse. You always need be alert to spot your publication while scrolling, because it does pass in a split second. This goes even worse when you operate on a remote system and there is some lagging involved.
Imagine about a customer having some 1000+ publications, now who wants to be Tridion content editor ? :)

So to address this issue, I developed an alchemy plugin named "Publication Panel Search". The plugin introduces a Search Box in the publication panel as shown below in the image. On typing in the search box, the publication panel gets updated and publications are filtered based on the search string. So no more scrolling to find a publication :)

To summarize it in technical terms:

1. Extend the dashboard resource
2. On dashboard load event, get the tree control by  var treeControl = $display.getView().getTreeControl();
3. Add event handler function "AddSearchBox" on "Draw" event of the tree control. like: $evt.addEventHandler(treeControl, "draw", addSearchBox); where addSearchBox function is responsible to add the search box.

The plugin can be downloaded from Alchemy Web Store and after installing on CMS, it's ready to use. It requires Alchemy as a prerequisite on your CMS server.

If you want to have a look at the plugin code, I've put it on Github here at https://github.com/saurabhgangwar/Alchemy-PublicationPanelSearch .

Thanks

Installing Alchemy Plugins for Tridion

Before installing an Alchemy Plugin, you must install Alchemy on your CMS server. Once finished, an Alchemy Plugin could be installed in two ways:


1. First one is to access the web store inside your Tridion GUI and install it clicking on install button. 

•     Go to the Web Store by clicking the tab "web store" on Alchemy landing page, Search for the plugin you want to install.

•     On the search result page, click the plugin you want to install

• It will redirect you to the Plugin page, Locate to the "Install Plugin" button and click it

• Watch the Tridion notifications about the progress

• Great, your Plugin is installed and ready to use 

2. The other way to install a Plugin is to go to  www.alchemywebstore.com and download the plugin (a4t file) and drag and drop it on the Alchemy landing page inside the Tridion GUI.

Installing Alchemy for Tridion (A4T)

As a Tridion developers we all know, Developing a Tridion GUI Extension is not a piece of cake. Form developing the code to the configuration, It's a complex process that requires some good technical skills and time.


So here comes Alex Klock and his team to rescue. They developed a system called Alchemy at Content Bloom, and the Beta version is announced recently.

Alchemy is basically a system set to revolutionize the way Tridion Extensions are built and installed. The system comprises of a open source extension framework to develop the extension plugins and a web store to upload/download and manage plugins.

So to use the Alchemy Plugins, First We need to install this awesome thing named Alchemy.

• Go to www.alchemywebstore.com,  register yourself and download the installer.

• Run the installer on your CMS server

 Installation wizard starts

Specify the installation location for Alchemy

Specify the system admin credentials (Optional) needed for plugins like "Servicer", which performs some system administrative task like restating a window service. If you skip this, you can update this information post-install as well, these are stored in the "impersonation" node of the Alchemy.xml file found at: [Tridion Home]\web\Alchemy\Configuration\ 

Click Close once installation is complete

• Refresh Tridion in browser. Boom!!! Welcome to the world of alchemy.

• Click on the Alchemy link in left panel, it will show you the Alchemy landing page. And yeah, you are all set to install Alchemy plugins for the environment.