Appendix A - Macro expressions

  Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic! Mail us feedback on this topic!  

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 ca often eliminate writing custom .NET code.

 

Types of macros

 

The macro type is determined by the character at the beginning and end of the macro. Macros look like:

 

{<type character><expression><parameters><type character>}

 

Where the type character can be one of:

 

$ - Localization macro
% - Context (data) macro
?  - QueryString macro
@ - Cookie macro
# - Custom macro
^ - Control macro
& - Path macro

 

Macros of the same type can be nested using the "index parentheses" syntax, e.g. {(1)%FullName|(default){(2)%Username%(2)}%(1)}. Click particular macro types in the listing above to get redirected to their detailed explanation.

 

Coverage of macros

 

The following table shows where particular types of macros can be used:

 

 

Localization

Context

Query

Cookie

Custom

Path

BizForms

please see Modules -> BizForms -> Using macros with BizForms

Document metadata

E-commerce

 

Editable regions

 

Forums

 

 

 

 

 

Newsletters

 

Polls

 

 

 

 

 

Reporting

Web part containers

Web part properties

 

 

 

.NET code

Supported by API

Page layouts

Supported by API

Transformations

Supported by API

 

Entering macros

 

Macros can either be entered manually, or you can use the macro selector dialog, which allows entering of macros via drop-down lists and offers a complete range of available macros.

 

In web part properties, it can be accessed by clicking the little black arrow icon next to fields in web part properties, as you can see in the screenshot below. The expression can be selected by the highlighted drop-down lists, inserted into the field above using the Insert button and finally added as a value of the property using the Save button.

 

devguide_clip0768

 

The same drop-downs are also available when creating or editing:

 

E-mail templates
Newsletter issues
Newsletter templates
E-commerce invoice templates

 

devguide_clip0770

 

Localization macros

 

These macros are usually used on multilingual websites to help localize system strings. There are two types of locatization macros:

 

Basic

 

Basic localization macros are entered in the {$string.key$} format. The system uses the ResHelper.GetString(“string.key”) method and replaces the macro with the appropriate resource string.

 

Example: "The weather is {$General.OK$}" will be resolved as "The weather is OK".

 

In-place locatization

 

The string and its localized equivalents are included within the entered macro. The macro is entered in the {$=Default string|cs-cz=Czech string|de-de=German string$} format. It uses a localized string in case it is available or the default (first) string if it is not.

 

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 and “The weather is OK” in any other culture.

 

Context (data) macros

 

This type of macros evaluates data based on current context. These macros can be used for example to parametrize web parts' parameters with current document or user values.

 

The format of the macro is {%ColumnName%} and the value is replaced with the appropriate value of the column based on current context. You can use all 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 the current user.

 

There are also data macros with selectors to precisely identify the source of the data, these macros look like {%CurrentDocument.DocumentName%} and can be used for accurate determination of the data source. Availability of the selectors depends on the context where the macros are evaluated.

 

QueryString macros

 

These macros evaluate the query parameters information. These macros can be used for example to dynamically parametrize the controls by the querystring parameters.

 

The macros are entered in the {?<querystring key>?} format and it is replaced by the query parameter value.

 

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

 

Cookie macros

 

These macros evaluate the cookie values. These macros can be used for example to parametrize the web parts with client-based persistent values like styles or user options.

 

The macro is entered in the {@<cookie name>@} format 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

 

Custom macros

 

These macros can be used to define your own macro. The macro is in the {#Expression#} format. When the macro is needed 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).

 

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;

}

 

Control macros

 

These macros can be used to resolve parts of text to the inline controls. The macro is in format {^BizFormControl^} and can (usually must) contain parameters for the control in a standard way of parametrized macros, such as {^BizFormControl|(FormName)ContactForm^}. It will be resolved to inline control which will get those parameters to initialize itself.

 

Path macros

 

These macros are entered in the {&path&} format. They can be used to resolve current document Alias path the same way as the Path property of controls. The macro is replaced by the resolved path.

 

Example: WhereCondition: NodeAliasPath LIKE {&../%&}. In this case, the macro will be resolved as parent document path and will result in selecting all siblings of the current document and their child documents. This macro is intended mostly for including the document structure context into the controls WHERE condition, but can be used for many more purposes.

 

See Appendix B - Path expressions for more details on how paths can be entered.

 

Macro parameters

 

It is possible to create macros with parameters to get better or specific functionality, especially for data (context) macros. Each parameter of the macro is separated with the “|” character located after the macro expression. You can use multiple macro parameters.

 

Examples: {%SKUPrice|(culture)en-us%}, {%SKUPrice|(culture)en-us|(format){0:f1}%}

 

The "|" character can be escaped using the "\|" sequence, e.g. {%SKUPrice|(default)N\|A%} will display "N|A", i.e. the "|A" sequence will not be interpreted as a new parameter.

 

Currently available parameters are:

 

Culture - “|(culture)<code>” - saying that the specified culture should be used for the

e.g. {%SKUPrice|(culture)en-us%} writes the product price in an English culture formatting

 

Format - “|(format)<format>” – saying how the value should be formatted
e.g. {%SKUPrice|(format){0:f1}%} writes the product price with precision for one decimal place

 

Default value -  “|(default)<value>” or “|<value>” - saying what should be returned when the value is not found.

e.g. {%SKUPrice|N/A%} writes product price or N/A if the document is not a product

 

Encode – “|(encode)<true/false>” – sprocesses the result with HTMLHelper.HTMLEncode

e.g. {%DocumentName|(encode)true%} or {%DocumentName|(encode)%} writes the HTML encoded document name, such as Black &amp; white; the default encoding settings can be enabled, in that case, the settings may be |(encode)false to disable it

 

URLEncode – “|(urlencode)<true/false>” – processes the result with HttpUtility.UrlEncode

e.g. {%DocumentName|(urlencode)true%} or {%DocumentName|(urlencode)%} writes the URL encoded document name, such as All%20items; the default encoding settings can be enabled, in that case, the settings may be |(urlencode)false to disable it

 

ToLower – “|(tolower)<true>” – converts the result to lowercase

e.g. {%DocumentName|(tolower)true%} or {%DocumentName|(tolower)%} writes black & white

 

ToUpper - “|(toupper)<true>” – converts the result to uppercase

e.g. {%DocumentName|(toupper)true%} or {%DocumentName|(toupper)%} writes BLACK & WHITE

 

ToInt - “(toint)<default value>” – converts the result to integer, if not successful, uses the default value

e.g. {?tagid|(toint)0?} writes the valid tagid from querystring or 0 if not valid

 

ToBool - “(tobool)<default value>” – conversion to Boolean, uses the (truevalue), (falsevalue) settings as a result, see below

e.g. {?onlyvalid|(tobool)true?} writes false if onlyvalid querystring parameter is false, else returns true

 

ToGuid - “(toguid)<default value>” – conversion to GUID

e.g. {?userguid|(toguid)?} converts the userguid query parameter to Guid or Guid.Empty

 

ToDouble - “(todouble)<default value>” – conversion to Double, uses the (culture) settings

e.g. {?price|(todouble)10.2?} converts the price query parameter to double or 10.2

 

ToDateTime - “(todatetime)<default value>” – conversion to DateTime, uses the (culture) settings

e.g. {?targettime|(todatetime)?} converts the targettime query parameter to date time or DateTime.MinValue

 

ResolveBBCode - “(resolvebbcode)<true/false>” – resolves the BB code in the result of the macro

e.g. {%MessageText|(resolvebbcode)true%} or {%MessageText|(resolvebbcode)%} writes the resolved BB code such as conversion of [url]… to <a href="…

 

Equals - “(equals)<value>” – returns “true” if the resolved value matches the given value, else returns “false”; uses the (truevalue), (falsevalue) settings for the output

e.g. {%UserName|(equals)administrator%} writes true if the user is administrator

 

NotEquals - “(notequals)<value>” - returns “false” if the resolved value matches the given value, else returns “true”; uses the (truevalue), (falsevalue) settings for the output

e.g. {%UserName|(notequals)administrator%} – writes false if the user is administrator

 

TrueValue - “(truevalue)<value>” – Output settings for the positive output of the comparison

e.g. {%UserName|(equals)administrator|(truevalue)Yes|(falsevalue)No%} writes Yes if the user is administrator

 

FalseValue - “(falsevalue)<value>” – Output settings for the negative output of the comparison

e.g. {%UserName|(equals)administrator|(truevalue)Yes|(falsevalue)No%} writes No if the user is not administrator

 

API methods for evaluating macros

 

There is an easy way to resolve macros in .NET code. To resolve all the macros (recommended), use the following static method:

 

string CMS.CMSHelper.CMSContext.CurrentResolver.ResolveMacros(string inputText)

 

To resolve just the localization macros, use another static method:

 

string CMS.GlobalHelper.ResHelper.LocalizeString(string inputText)

 

Page url: http://devnet.kentico.com/docs/5_5r2/devguide/index.html?appendix_a___macro_expressions.htm