Is this really the version you are looking for? Kentico Xperience 9 Documentation is no longer updated. Use the switcher in the header to choose your product version.
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:
Open your project in Visual Studio.
Create a new class. In web site projects, you can either add the class into the App_Code folder or as part of a custom assembly.
Edit the class and add a reference to the CMS.MacroEngine namespace:
using CMS.MacroEngine;Make the class inherit from MacroMethodContainer:
/// <summary>
/// Sample MacroMethodContainer class.
/// </summary>
public class CustomMacroMethods : MacroMethodContainer
{
}Define your methods inside the container class. Macro methods must always have the following signature:
public static object MyMethod(EvaluationContext context, params object[] parameters)The EvaluationContext parameter allows you to get information about the context in which the macro containing the method was resolved. For example, you can check the username in the macro signature (for security purposes) or the values of macro parameters, such as the culture or case sensitivity of string comparisons.
The parameters array stores the method's parameters. When the system resolves the method, the values of the arguments pass into the array. You need to define individual parameters via attributes (see below).
Note
We strongly recommend that you ensure the following in the code of your methods:
Add the MacroMethod attribute above the method declaration. Specify the following parameters for the attribute:
Add a MacroMethodParam attribute for each of the method's parameters. For every parameter, you must specify:
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();
}
}
}After you prepare your macro methods in a container class, register the container by extending an object type or macro 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:
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
{
...Important: If your macro method container class is defined within a custom assembly, 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.
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):
{% 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:
OR
Enter the extended macro namespace, and then call the method:
{% String.ConnectStrings("First part", "Second part") %}The Kentico installation includes code examples of custom macro method registration, which you can add directly to your web project. To access the samples:
Open your Kentico installation directory (by default C:\Program Files\Kentico\<version>).
Expand the CodeSamples\App_Code Samples\ sub-directory.
Copy the Samples folder into the CMS\App_Code folder of your web project.
Web application installations
If your project was installed in the web application format, copy the samples into the Old_App_Code folder instead.
You must also manually include the sample class files into the project:
You can find the macro method examples in the following classes: