Creating a back link using a custom macro in Kentico CMS 6

In Kentico CMS 6.0 macros are used all over the place. And available ALL over the place. This functionality allows you to get system/context/user/document information very quickly and create dynamic, fluid content. While Kentico does a great job of providing many macros out of the box, sometimes a custom macro is in store to get/do what you want. This blog details how to implement a custom macro and call it within your code.

For our example, we’re going to make a custom macro that returns
 

Create a custom macro class

The first step to a custom macro is to create a custom macro class. This class will go in the "App_Code" folder. We typically will make a folder specific to our client to keep our custom code together.

This class needs to contain all the overloads that you need. In this example, we only have 1. Here is our sample overload to get the Referrer URL:

        /// <summary>
        /// Returns the current referrer
        /// </summary>
        /// <returns></returns>
        public static string GetUrlReferrer()
        {
            return HTTPHelper.GetUrlReferrer();
        }
 

Create a wrapper for the overload

The next step is to create a wrapper for the new overload. This makes the code suitable for the MacroResolver.  Here is code to generate the wrapper:

        public static object GetUrlReferrer(params object[] parameters)
        {
            return GetUrlReferrer();
        }

Register the Custom Macro

The next step is to register the custom macro within the system. This bit of code allows you to have your custom macro in the drop down when building up your macro expressions. Additionally, you can specify default code blocks and tool tip information.

MacroMethods.RegisterMethod("GetUrlReferrer", GetUrlReferrer, typeof(string), "Returns the referrer.", null, 0, null, null, new List<Type>() { typeof(string) }, "GetUrlReferrer();", false);

Implement the RegisterMethod in a CMSModuleLoader class

You will need to make a new CMSModuleLoader class (or use the sample in App_Code/Sample/Modules/SampleMacroModule.cs). This ensures your custom macro registration gets called when the site builds/runs.

        /// <summary>
        /// Registers module methods.
        /// </summary>
        public override void Init()
        {
            // -- Custom macro methods
            MySite.MySiteCustomMacros.RegisterMethods();
            //CustomMacroMethods.RegisterMethods();

            // -- Custom macro resolving
            //MacroResolver.OnResolveCustomMacro += MacroResolver_OnResolveCustomMacro;

            // -- Custom output substitution resolving
            //OutputFilter.OnResolveSubstitution += OutputFilter_OnResolveSubstitution;
        }
 

Adding a back link

The next part of the demo is to add a link to your page template for the “back” link. Add a “Static HTML” web part to your template and select “Edit Value” for the “Text" property.
   

Selecting the macro

After adding the custom macro and registering it, your code should be available within the site. In your macro builder window for the "Text: property, confirm your custom macro is listed.
 

Confirm the macro works

After setting the macro, browse to your site to confirm the macro is properly resolving to the referrer value. The following images show the original page having a specified QS value, then the next page showing the "back" link to the previous page.
 
That’s it!  Using custom macros you can do all sorts of things and really expose a lot of functionality to your application.

For more information on custom macros within Kentico CMS 6.0, check out the the documentation here.

Good luck!