Macro syntax

The system identifies macros using special parentheses. You need to enclose macro expressions into curly brackets and the percentage symbol: {% expression %}

Kentico provides an object-oriented language named K#, which defines the syntax of macro expressions. The macro language is very similar to the C# programming language. This page provides an overview of the features available in K# and describes the differences from C#.

The K# syntax is case-insensitive – the system does not differentiate between upper and lower case letters in commands. However, letter case may have an effect in the values of constants and variables (for the purposes of comparisons and similar).

In addition to the primary macro syntax, the system also supports several special macro types:

Values and objects

When the system resolves a macro expression, the result is an object (value). Macros support the following types of objects:

• Standard scalar C# types (int, double, string, DateTime etc.).

• Kentico system types (objects representing pages, users etc.).

  Note: Kentico objects in macros provide properties according to the underlying database structure. This does not always match the properties available in the API of the corresponding Info classes.

• Collections based on the IEnumerable interface, which contain various types of objects. For example, InfoObjectCollection stores sets of Kentico objects.

• Context objects containing data related to the currently processed request (information about the current user, the currently viewed page, etc.). For example: CMSContext, SiteContext, DocumentContext, ECommerceContext.

• Macro namespaces that allow you to access other properties or methods (a namespace object itself does not return any data).

To work with fixed values (literals) in macro expressions:

• numbers - type the numbers directly. You can use integers or numbers with decimal points (double type).
• text - enclose text (string) values into quotes, for example: “administrator”
• booleans - use the true and false keywords.
• date and time - enclose date and time values into quotes. The date format depends on the culture context. For example: “1/1/2014”, “9/3/2014 9:20:00 AM”

Operators

K# uses the same basic operators as C#. See the Reference of C# operators to learn more.

The following table summarizes the differences in operator behavior that you need to keep in mind when writing macros.

Macro methods

Methods allow you to perform tasks (execute code) inside macro expressions. You typically call methods with at least one argument.

The recommended K# syntax for method calls is infix notation for the first argument. Prefix notation is also supported. For example:

// Returns "WORD"
{% "word".ToUpper() %}

// Returns "The sky is red on red planets"
{% "The sky is blue on blue planets".Replace("blue", "red") %}

// Alternative method calls with prefix notation (not supported by the autocomplete help)
{% ToUpper("word") %}
{% Replace("The sky is blue on blue planets", "blue", "red") %}

Kentico provides an extensive set of default methods that you can use in macro expressions. See: Reference - Macro methods

Developers can also extend the macro engine and register custom macro methods.

Compound expressions and declaring variables

K# allows you to write compound expressions, containing any number of simple macro expressions. You need to terminate each expressions (except for the last) using a semicolon. The overall result of a compound expression is the result of the last expression.

Variables allow you to store and manipulate values inside macro expressions. You do not need to explicitly declare the type of variables.

// returns "12"
{% x = 5; x + 7 %}

// returns "10"
{% x = 5; y = 3; x += 2; x + y %}

The scope of variables spans from the point of declaration to the end of the area containing the macro (such as text fields, e-mail templates or Text / XML transformations), including all separate macro expressions in the given area.

Conditional statements

Use the if command to create conditions in format: if (<condition>) {<expressions>}. The condition statement returns the value of <expressions> if the condition is true, and a null value if false.

// returns "z is less than 3"
{% z = 1; if (z<3) {"z is less than 3"} %}

To create conditions with a result for the false branch, use the following syntax: if (<condition>) {<expressions 1>} else {<expressions 2>}

// returns "z is greater than or equal to 3"
{% z = 5; if (z<3) {"z is less than 3"} else {"z is greater than or equal to 3"} %}

The ternary operator allows you to create compact conditions with a different result for each branch. Use the following syntax: <condition> ? <expressions 1> : <expressions 2>

If the condition is true, the statement returns the value of <expressions 1>. In the case of a false condition, the return value is <expressions 2>.

// returns "The second parameter is greater"
{% x=1; y=2; x > y ? "The first parameter is greater" : "The second parameter is greater" %}

// Displays a message including the current date if the year is 2014 or more
{% date = CurrentDateTime; if (date.Year > 2013) { %}
The current date is: {% date %}. The registration period has ended.
{% } %}

Iteration (loops)

K# provides several types of loop commands:

• while (<condition>) {<executed expressions>}
• for (<init expression>; <condition>; <increment expression>) {<executed expressions>}
• foreach (<variable> in <enumerable object>) {<executed expressions>}

If a loop command is the last expression in a macro, the return value is a concatenated list containing the results of the sub-expressions executed by all iterations of the loop.

// returns "10"
{% z = 1; while (z<10) {++z}; z %}

// returns "2 3 4 5 6 7 8 9 10"
{% z = 1; while (z<10) {++z} %}

// returns "5"
{% z = 0; for (i = 0; i < 5; i++) { z += 1 }; z %}

// returns "1 2 3 4 5"
{% z = 0; for (i = 0; i < 5; i++) { z += 1 } %}

// returns "HELLO"
{% z = ""; foreach (x in "hello") {z += x.toupper()}; z %}

// returns "H HE HEL HELL HELLO"
{% z = ""; foreach (x in "hello") {z += x.toupper()}%}

Use the break command to terminate loops. For nested loops, the command closes the innermost loop.

// returns "1 2 3 4 5"
{% z = 0; while (z < 10) {if (z > 4) {break}; ++z} %}

The continue command skips to the next iteration of the current loop.

// returns "0 1 2 4 5"
{% for (i=0; i<=5 ; i++) {if (i == 3) {continue}; i} %}

Nested loops and advanced expressions

Do not use the automatic return value for loops that are nested inside another loop or in compound expressions. Instead, choose one of the following approaches:

• Use console output (the print(…) method) to directly output the results of individual loop iterations
  OR
• Concatenate the iteration results into a variable that you return at the end of the expression

// Returns an HTML list of all items from all orders made by the current customer
{%
    orders = ECommerceContext.CurrentCustomer.AllOrders;
    if (orders.Count > 0) {
        print("<ul>");
        foreach (order in orders) {
            foreach (item in order.OrderItems)
                { print("<li>" + item.OrderItemSKUName + "</li>") }
        };
        print("</ul>");
    }
%} 

// Returns an HTML list of all items from all orders made by the current customer
{%
    orders = ECommerceContext.CurrentCustomer.AllOrders;
    if (orders.Count > 0) {
        result = "<ul>";
        foreach (order in orders) {
            foreach (item in order.OrderItems)
                { result += "<li>" + item.OrderItemSKUName + "</li>" }
        };
        return result + "</ul>";
    }
%}

Return command

Use the return command to terminate the processing of a macro, and set the attached expression as the macro’s final result. You can use the return command inside loops, or anywhere in compound macro expressions.

// returns green
{% "red"; "yellow"; return "green"; "blue" %}

// returns "ignore the loop"
{% z = ""; foreach (x in "hello") {return "ignore the loop"; z += x } %}

Console output

Console output allows you to build the results of macro expressions without declaring variables. Use the print(<expressions>) or println(<expressions>) syntax. Each console output expression adds to the macro’s return value, and the system continues processing the macro.

Console output has higher priority than the standard result of macro expressions, but lower than the return command.

// returns "123"
{% i = 1; while (i < 4) {print(i++)}; "ignored" %}

// returns "result"
{% i = 1; while (i < 4) {print(i++)}; return "result" %}

Indexing

K# supports indexing for collections and objects that serve as containers for other data:

• DataRow, DataRowView, DataRowContainer (returns the value at the specified index)
• DataTableContainer (returns the row at the specified index)
• DataSetContainer (returns the table at the specified index)
• String (returns the character at the specified index)
• IEnumerable collections, such as InfoObjectCollection (returns the object at the specified index in the collection)

// returns "e"
{% "hello"[1] %}

// returns the value of the FirstName column from the DataRow
{% dataRow["FirstName"] %}

Comments

To add explanatory text inside macro expressions, use one-line, multi-line or inline comments.

{%
// This is a one-line comment. Initiated by two forward slashes, spans across one full line.

/* 
This is a multi-line comment.
Opened by a forward slash-asterisk sequence and closed with the asterisk-forward slash sequence.
Can span across any number of lines.
*/

x = 5; y = 3; /* This is an inline comment nested in the middle of an expression. */ x+= 2; x + y
%}

Lambda expressions

Lambda expressions are ad-hoc declarations of inline functions that you can use inside macro expressions.

// returns "4"
{% lambdaSucc = (x => x + 1); lambdaSucc(3) %}

// returns "6"
{% lambdaMultiply = ((x, y) => x * y); lambdaMultiply(2,3) %}

The scope of lambda expressions spans from the point of declaration to the end of the area containing the macro (such as text fields, e-mail templates or Text / XML transformations), including all separate macro expressions in the given area.

Macro parameters

Macro parameters allow you to modify how the system resolves individual expressions. To append parameters to macro expressions, use the following syntax:

{% ...|(<parameter>)<value> %}

You can add multiple parameters to a single expression. Use backslashes to escape the | separator in parameter values if necessary.

The following macro parameters are available:

<add key="CMSMacrosCaseSensitiveComparison" value="true">