Appendix A - Macro expressions

This appendix describes macros that can be used within the Kentico CMS system. Macros are strings that are automatically resolved into their value equivalents and they represent a powerful option that often eliminates writing custom .NET code.

Types of macros

•	Localization macros – There are two types of locatization macros:

o	Basic – in format {$string.key$}. It calls the ResHelper.GetString(“string.key”) method and replaces the macro with the resource string (see International and RTL support for more details on resource strings). Example: “The weather is {$General.OK$}” will be resolved as “The weather is OK”

In-place locatization – String and its localized equivalents are stored in the macro specification. The macro is in format {$=Default string|fr-fr=French string|de-de=German string$}. It uses the localized string in case it is available in the current content culture or the default default string (the first string) in other cases.

Example:

“The weather is {$=OK|cs-cz=dobre|de-de=gut$}” will be resolved into:

“The weather is dobre” in Czech culture

“The weather is gut” in German culture

“The weather is OK” in any other culture

These macros are usually used on multilingual web sites to help localize the system strings.

•

Context (data) macros – This type of macros evaluates the data of current context. The format of the macro is {%ColumnName%} and the value is replaced with the appropriate data from the context. You can use all the column names from current site data, current user data and current document data.

Example: “Welcome {%FullName%}” will be resolved as “Welcome Global administrator” when administrator is logged in.

These macros can be used for example to parametrize the web parts parameters with current document or user values.

•

QueryString macros – These macros evaluate the query parameters information. The macro is in format {?querystringkey?} and it is replaced by the query parameter value.

Example: “Current node ID: {?nodeid?}” will be resolved as “Current node ID: 10” with URL like “default.aspx?nodeid=10”

These macros can be used for example to dynamically parameterize the controls by the querystring parameters. The querystring values are automatically secured against SQL injection attacks in places when they may occur (e.g. in the WHERE condition property) by replacing an apostrophe with double apostrophes.

•

Cookie macros – These macros evaluate the cookie values. The macro is in format {@CookieName@} and it is replaced by the cookie value.

Example: “Current style: {@StyleCookie@}” will be resolved as “Current style: Red” if StyleCookie value is set to “Red”

These macros can be used for example to parameterize the web parts with client-based persistent values like preferred color styles.

•

Path macros - These macros evaluate the path or its parts. You will typically use them in the Where condition of the web parts.

Example: WhereCondition: “NodeAliasPath LIKE {&../%&}”

The macro will be resolved as parent document path and will result in selecting all the siblings of current document and their child documents.

•

Custom macros - These macros can be used to define your own macro. The macro is in format “{#Expression#}” and when the macro is needed to be resolved, it will call the method ResolveCustomMacro located in the class ~/App_Code/Global/CMS/CMSCustom.cs

Example: “Current time: {#CurrentTime#}” will be resolved to “Current time: 1/1/2008 10:30“ with following custom macro handler:

[C#]

/// <summary>

/// Custom macro handler

/// </summary>

/// <param name="sender">Sender (active macro resolver)</param>

/// <param name="expression">Expression to resolve</param>

/// <param name="match">Returns true if the macro matches (was resolved)</param>

public static string ResolveCustomMacro(MacroResolver sender, string expression, out bool match)

{

match = false;

string result = expression;

// Add your custom macro evaluation

switch (expression.ToLower())

{

case "currenttime":

match = true;

result = DateTime.Now.ToString();

break;

}

return result;

}

Coverage of Macros

The following table shows where the macros can be used:

	Locatization	Context	Query	Cookie	Custom	Path
Web part properties
Web part containers
Page layouts	Supported by API
Document metadata
Editable regions
Newsletters
Reporting
Forums
Polls
E-Commerce
BizForms
Transformations	Supported by API
.NET code	Supported by API