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
The macro type is determined by the character at the beginning and end of the macro. Macros look like:
{<type><expression><parameters><type>}
Where type character can be one of:
| • | $ - Localization macro |
| • | % - Context (data) macro |
| • | ? - QueryString macro |
| • | @ - Cookie macro |
| • | # - Custom macro |
Entering macros
Macros can either be entered manually, or you can use the macro selector dialog, which facilitates entering of macro expressions and offers a complete range of macros to be entered.
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 three drop-down lists, inserted into the field above using the Insert button and finally added to the property using the Save button.
The same three drop-downs are also available when creating or editing:
| • | E-mail templates |
| • | Newsletter issues |
| • | Newsletter templates |
| • | E-commerce invoice templates |
Localization macros
There are two types of locatization macros:
Basic – In format “{$string.key$}” uses the ResHelper.GetString(“string.key”) and replaces the macro with the resource string.
Example: “The weather is {$General.OK$}” will be resolved as “The weather is OK”
In-place locatization – String and its localized equivalents are stored within the macro specification. The macro is in format “{$=Default string|cs-cz=Czech string|de-de=German string$}”. It uses localized string in case it is available or default (the first string) if 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
“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.
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. 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 parametrize the controls by the querystring parameters.
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 parametrize the web parts with client-based persistent values like styles or user options.
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:
/// <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 the 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 can be used to resolve current document Alias path the same way like in the Path property of the controls. Macro is replaced by the resolved path.
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.
This macro is intended mostly for including the document structure context into the controls WHERE condition, but can be used for many more purposes.
Macro parameters
From version 4.0 there is possibility to create macros with parameters to get better or specific functionality, especially for the 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}%}
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>” – Processes the result with HTMLHelper.HTMLEncode |
e.g. {%DocumentName|(encode)true%} or {%DocumentName|(encode)%} writes the HTML encoded document name, such as Black & 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 qurystring 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 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 comparisson |
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 comparisson |
e.g. {%UserName|(equals)administrator|(truevalue)Yes|(falsevalue)No%} writes No if the user is not administrator
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 |
|||||
API methods for evaluating macros
There is an easy way to resolve the macros in the .NET code. To resolve all the macros (recommended), use static method:
string CMS.CMSHelper.CMSContext.CurrentResolver.ResolveMacros(string inputText) |
To resolve just the localization macros use static method:
string CMS.GlobalHelper.ResHelper.LocalizeString(string inputText) |