Registering custom macro methods

In addition to the default macro methods, you can also create your own methods. Users can then run custom functionality by calling the methods inside macro expressions.

Use the following process to add macro methods into the system:

1. Define the methods inside a container class
2. Register your macro method container for a certain object type or macro namespace
3. If you are using the MVC development model, deploy the custom classes to both your Kentico administration project and the separate MVC application. This ensures that the custom macro method can be resolved by both applications. For more information, see Customizing MVC projects.

Defining macro methods

1. Open your project in Visual Studio.

2. Create a new class within a custom assembly (Class Library project).

   Important: The assembly project must contain the [assembly: AssemblyDiscoverable] attribute (the recommended location is in the Properties/AssemblyInfo.cs file). To use the attribute, your assembly's project must contain a reference to the CMS.Core.dll library.

3. Edit the class and add a reference to the CMS.MacroEngine namespace:

   C#

   Copy

   using CMS.MacroEngine;

4. Make the class inherit from MacroMethodContainer:

   C#

   Copy

   /// <summary>
   /// Sample MacroMethodContainer class.
   /// </summary>
   public class CustomMacroMethods : MacroMethodContainer
   {
   
   }

using CMS.MacroEngine;
using CMS.Helpers;

public class CustomMacroMethods : MacroMethodContainer
{
    [MacroMethod(typeof(string), "Combines two strings, or appends a culture suffix when called with one parameter.", 1)]
    [MacroMethodParam(0, "param1", typeof(string), "First part of the string.")]
    [MacroMethodParam(1, "param2", typeof(string), "Second part of the string (optional).")]
    public static object ConnectStrings(EvaluationContext context, params object[] parameters)
    {
        // Branches according to the number of the method's parameters
        switch (parameters.Length)
        {
            case 1:
                // Overload with one parameter
                return ValidationHelper.GetString(parameters[0], "") + " - Resolved in culture: " + context.Culture;

            case 2:
                // Overload with two parameters
                return ValidationHelper.GetString(parameters[0], "") + " - " + ValidationHelper.GetString(parameters[1], "");

            default:
                // No other overloads are supported
                throw new NotSupportedException();
        }
    }
}

Registering macro method containers

After you prepare your macro methods in a container class, register the container by extending an object type or macro namespace.

1. Edit the class containing your macro method container.
2. Add a RegisterExtension assembly attribute above the class declaration for each type that you wish to extend (requires a reference to the CMS namespace).

Specify the type parameters for the RegisterExtension attribute in the following format:

[assembly: RegisterExtension(typeof(<macro method container class>), typeof(<extended type>))]

You can extend the following types:

• General system types (string, int, ...)
• Kentico API object types (UserInfo, TreeNode, ...)
• Macro namespaces (SystemNamespace, StringNamespace, MathNamespace, ...)
• Custom types

using CMS;

using CMS.MacroEngine;
using CMS.Helpers;

// Makes all methods in the 'CustomMacroMethods' container class available for string objects
[assembly: RegisterExtension(typeof(CustomMacroMethods), typeof(string))]
// Registers methods from the 'CustomMacroMethods' container into the "String" macro namespace
[assembly: RegisterExtension(typeof(CustomMacroMethods), typeof(StringNamespace))]

public class CustomMacroMethods : MacroMethodContainer
{
...

Result - Calling custom methods in macros

Once you have your custom macro methods implemented and registered, you can call them in macro expressions.

Open any macro code editor in the administration interface. The autocomplete help offers the new methods for the extended types or namespaces.

For example:

• Append the method to a macro object of the data type that you extended (string in the sample code):

  Text

  Copy

  {% CurrentUser.UserName.ConnectStrings() %}

  The recommended K# syntax is to use infix notation for the first parameter of methods. You can call the method in the following forms:

  • {% "String1".ConnectStrings("String2") %} - recommended and supported by the autocomplete help
  • {% ConnectStrings("String1", "String2") %}

OR

• Enter the extended macro namespace, and then call the method:

  Text

  Copy

  {% String.ConnectStrings("First part", "Second part") %}

Macro method code samples

The Kentico installation includes code examples of custom macro method registration, which you can add directly to your web project.

Access the samples in your Kentico installation directory (by default C:\Program Files\Kentico\<version>), under the CodeSamples\CustomizationSamples\ sub-directory.

You can find the macro method examples in the following classes:

• Macros/CustomMacroMethods.cs – class containing the sample macro methods.
• Modules/SampleMacroModule.cs – initializes the custom method registration.