Skip to Content
Skip to Content

Macro engine examples

On this page, you can find some examples of Kentico CMS macro engine features and the K# language. Detailed documentation of the macro engine and syntax of the K# language can be found in Kentico CMS Developer's Guide -> Development -> Macro expressions.

Each of the following examples consists of a macro expression on the left and its result on the right. The expressions on the left are intentionally written with a blank space between their encapsulating characters (e.g. { % expression % } ) to prevent them from being resolved. On the right, the same expression without the blank spaces is used and therefore resolved.

  • K# is case insensitive. Therefore, the following macros return the same value.

    { % currentdocument.documentname % } -> Macro engine
    { % CurrentDocument.DocumentName % } -> Macro engine

  • There is no need to use parameters in macros anymore (even though they are still supported, so all the macros which worked in previous versions of Kentico CMS still work). You can use C#-like syntax to concatenate strings, perform arithmetic operations, indexing operator [] i, etc.

    { % "MyPrefix" + CurrentDocument.DocumentName % } -> MyPrefixMacro engine
    { % 2 * 3 - 5 % } -> 1
    { % CurrentDateTime.Year % } -> 2020
    { % "Test"[2] % } -> s

  • There is a lot of predefined methods you can use in your macros (for a complete list, please see the Developers Guide -> Development -> Macro expressions -> Available macro methods). Classic postfix notation of calling any method on a data member as you know it from C# is supported. You can also call the method directly with a data member as a parameter. These two types of method calls are equivalent.

    { % CurrentDocument.DocumentName.ToUpper() % } -> MACRO ENGINE
    { % ToUpper(CurrentDocument.DocumentName) % } -> MACRO ENGINE
    { % CurrentDocument.DocumentName.Substring(0,5) % } -> Macro
    { % Substring(CurrentDocument.DocumentName, 0, 5) % } -> Macro

  • K# supports compound expressions and variable declaration. The scope of a variable declaration is the whole document (transformation, e-mail template, ...). The result of the compound expression is the result of the last expression.

    { % x = 10; x % } -> 10

  • K# has it's own "console output". You can write to the console using the print and println commands. If anything is written to the console (even an empty string), the content of the console is always used as the result of a macro.

    { % print("this will be the output"); "ignored" % } -> this will be the output

  • K# supports all flow control commands such as if-else statements, for, foreach, while loops and ternary operators.

    { % result = 0; i = 0; while (i < 10) {if (i > 3) { break; }; result += i; i++; }; result % } -> 6
    { % z = ""; foreach (x in "test") { z += x.toupper() }; z % } -> TEST
    { % z = 0; for (i = 0; i < 5; i++) { z += 1 }; z %} -> 5

  • K# supports lambda expressions - you can define your own ad-hoc methods and use them afterwards.

    { % myMul = ((x, y) => x * y); myMul(2,3) % } -> 6
    { % mySucc = (x => x + 1); mySucc(3) % } -> 4

Except for data macros written in K# (format { %expression% }), the following simple macros can be used as well:

  • QueryString macros
    These macros evaluate query parameter information. These macros can be used for example to dynamically parametrize controls by querystring parameters. The macros are entered in the { ?querystring_key? } format. Alternatively, you can also enter them as data macros like the following: { %QueryString.querystring_key% }. The macro is replaced by the querystring parameter value.

  • Cookie macros
    These macros evaluate cookie values. These macros can be used for example to parametrize web parts with client-based persistent values like styles or user options. The macros are entered in the { @cookie_name@ } format. Alternatively, you can also enter them as data macros like the following: { %Cookies.cookie_name% }. The macros are replaced by the cookie value.

  • Custom macros
    These macros can be used to define your own macros. The macros are in the { #Expression# } format. Alternatively, you can also enter them as data macros like the following: { %Custom.Expression% }. When the macro needs to be resolved, it calls the ResolveCustomMacro method located in the ~/App_Code/Global/CMS/CMSCustom.cs class (or ~/Old_App_Code/Global/CMS/CMSCustom.cs if you installed the project as a web application).

  • Path macros
    These macros are entered in the { &path& } format. Alternatively, you can also enter them as data macros like the following: { %Path.path% }. They can be used to resolve Alias path of the current document the same way as the Path property of controls. The macros are replaced by the resolved path.

  • Control macros
    These macros can be used to replace parts of text with inline controls. The macros are in format { ^BizFormControl^ } and can (usually must) contain parameters for the control in a standard way of parametrized macros, such as { ^BizFormControl|(FormName)ContactForm^ }. The macros will be resolved to inline controls which will use the parameters to initialize themselves.

  • Localization macros
    These macros are usually used on multilingual websites to help localize system strings. The macros can be entered in two formats. Basic localization macros are entered in the { $string.key$ } format. This macro loads the specified localization string from the current culture and replaces the macro with it. Another option is to define translations for individual languages directly in the macro, e.g. { $=OK|cs-cz=dobre|de-de=gut$ }. This macro gets replaced with "dobre" in Czech culture, "gut" in German culture and "OK" in any other culture.