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!

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.

Tridion Custom Tools Example Projects – Event Handler

In the blogpost series of Tridion Custom Tools Example Projects, this blog covers the Event Handler Extension. The Example Code Project could be found here on GIT. I've also shared the Visual Studio Extension here, If you want to install the project template in visual studio for event handler.

An Event Handler is a piece of functionality that is triggered when a certain type of event happens to a certain Content Manager item, for example when a Component being saved.

In Technical terms, It is a .NET assembly that uses the Event System to hook into events occurring in the Content Manager.The Event System is part of the TOM.NET (.NET Tridion Object Model) API. 

To create an Event Handler, create a class that extends Tridion.ContentManager.Extensibility.TcmExtension. You then need to compile your Event Handler into an assembly (DLL) and register it.

Procedure (Copied From SDL Documentation)

1. In Visual Studio, create a class that extends Tridion.ContentManager.Extensibility.TcmExtension. This class must have a unique class attribute, say,[TcmExtension("MyUniqueEventHandlerExtension")].
2. In the constructor of this class, execute code that subscribes to one or more events using the following methods:

SubscribeAsync

Subscribe asynchronously to an event. Select this method if your Event Handler code does not affect the data being handled in the Content Manager. For example, if your Event Handler saves data to a backup system or a log file, you can select this method.

Subscribe

Subscribe synchronously to an event. Select this method if your Event Handler code changes the data being handled. For example, if your Event Handler analyzes a Component and then adds metadata to it, ensure that you select this method.

Both methods have the following signatures:

Subscribe<TSubject, TEvent>(TcmEventHandler<TSubject, TEvent> eventHandler, EventPhases phases, EventSubscriptionOrder order)

SubscribeAsync<TSubject, TEvent>(TcmEventHandler<TSubject, TEvent> eventHandler, EventPhases phases, EventSubscriptionOrder order)

where the parameters mean the following:

TSubject (type parameter)

This is the type(s) of the object you are checking events for. This can be any item of class Tridion.ContentManager.IdentifiableObject or any of its subclasses, which includes any kind of content item (such as Component, Schema or Target Group), organizational item (such as Folder or Structure Group) or system-wide object (such as User or Group).

TEvent (type parameter)

This indicates the type(s) of event that trigger this code if applied to an item of the object type specified in TSubject. This can be any event of classTridion.ContentManager.Extensibility.TcmEventArgs or any of its subclasses.

TcmEventHandler<TSubject, TEvent> eventHandler

The name of the method that contains the code you want to be triggered when the event occurs. This method should be contained in the same class and should have parameters that are the same as the type parameters of this Subscribe or SubscribeAsync method.

EventPhases phases

The exact moment during the event at which the event code should be triggered. Note that this parameter is an enum with FlagsAttribute, meaning that you can select multiple moments, which in turn means that a single event could trigger the same code multiple times.

EventSubscriptionOrder order

This optional parameter specifies when the event code should be executed if the same event triggers multiple Event Handlers.

3. Now, in the same class, implement your event code in a method with the name specified in the eventHandler parameter of the Subscribe or SubscribeAsync method. In this method, you can perform any action you wish, including any type of querying, modification or other manipulation of items in the Content Manager. Include any namespace you need to access these items.

When you write this code, note the following:

• You can make changes to the members of the TEvent parameter (the members are different depending on the event type) by exchanging information between Event Handlers.
• When executed, the code you write may result in other event code being triggered.
• From your event handling method, you can identify the specific user who triggered the event through the Session property of your first parameter of type <TSubject>. For example, if your method has a signature HandlerForSave(Component subject, SaveEventArgs args, EventPhases phase), get the name of the user by checking subject.Session.User.Title.
3. Once you are satisfied with your code, shut down the following services on your Content Manager server:
• IIS
• Any Tridion-related COM+ services
• If your code is related to publishing, the Publisher service of SDL Tridion
4. Compile your class to a .NET assembly.

Note: If your event code contains a bug that raises an exception, it can cause the event that triggered it to hang. Especially if your event code is likely to be triggered very often, this can easily cause the system to freeze. Always test your event code before deploying it.

6. Open the configuration file called Tridion.ContentManager.config, located in the config/ subfolder of %TRIDION_HOME% (defaults to C:\Program Files (x86)\Tridion\), in a plain-text or XML editor. Find the extensions element in this file. If the element is empty (that is, if it reads <extensions/>), replace it with<extensions></extensions>. Then add a line of the following format:

<add assemblyFileName="C:\Projects\Events\MyCustomEventHandlerExample\bin\Debug\MyCustomEventHandler.dll" />

where MyCustomEventHandler.dll is the full path and name of your compiled class. If the element was empty, the fragment should now read:

<extensions>

  <add assemblyFileName="C:\Projects\Events\MyCustomEventHandlerExample\bin\Debug\MyCustomEventHandler.dll" />

</extensions>

7. Save and close Tridion.ContentManager.config.
8. Restart the services you stopped.

Tridion Custom Tools Example Projects – Custom Resolver

I noticed many questions on Tridion SE, where new developers face issues with setting up projects for Tridion Custom Tools. So in this series of blog posts I am sharing some code examples and extensions for the same.

To start with, I am explaining to set up the Custom Resolver. I've set up a simple Example Code Project and could be found here , I've also shared the the Visual Studio Extension for it, if anyone wants to install a project template for custom resolver it could be found here.

Setting up the project:

1. Create a library project in Visual studio.

2. Add the following dlls as reference:

• Tridion.Common
• Tridion.ContentManager
• Tridion.ContentManager.Common
• Tridion.ContentManager.Publishing

3. Create a class say “MyCustomResolver” by extending from interface “IResolver”, which is found in “Tridion.ContentManager.Publishing.Resolving” namespace.

4. Implement the method public void Resolve(IdentifiableObject item, ResolveInstruction instruction, PublishContext context, Tridion.Collections.ISet<ResolvedItem> resolvedItems)

5. Sign the Assembly with a Strong Name.

6. Build and add the assembly to GAC on CMS and Publisher Servers, In case you have a separate publisher server.

Installation Process (To be done on CMS and Publisher Boxes):

1. Copy the assembly “ExampleTridionCustomResolver.dll” in to the server.

2. Add the assembly to the GAC.

3. Open “Tridion.ContentManager.config” file from the path “%TridionInstall% \config”.

4. Locate xml element <add itemType="Tridion.ContentManager.ContentManagement.Component"> inside element <resolving> ---> <mappings>. Since we only want to override resolving behavior for components in this example.

5. Inside the child element <resolvers>, add element <add type=" ExampleTridionCustomResolver.MyCustomResolver" assembly=" ExampleTridionCustomResolver, Version=1.0.0.0, Culture=neutral, PublicKeyToken={PublicKeyToken}" /> as a LAST child.

6. Finally, save and close the Tridion.ContentManager.config file and from your list of Windows Services, restart all Windows services that start with Tridion Content Manager. Also restart IIS and the SDL Tridion Content Manager COM+ application. This applies your changes.