Kentico CMS 6.0 Developer's Guide

Macro parameters

Macro parameters

Previous topic Next topic Mail us feedback on this topic!  

Macro parameters

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

It is possible to create macros with parameters to get better or specific functionality, especially for data (context) macros. Each parameter of a 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.

 

 

 

Please note

 

The same results that can be achieved using macro parameters can be achieved using macro methods. Macro parameters are still functional due to backward compatibility with previous versions of Kentico CMS, but they are now obsolete and using macro methods is recommended instead.

 

 

Currently available parameters are:

 

|(culture)<code> - specifies culture that should be used for the macro result.

 

|(format)<format> – formats the macro result according to the provided formatting string.

 

|(default)<value> or |<value> - saying what should be returned when the macro returns an empty value.

 

|(encode)<true/false> – processes the macro result result with HTMLHelper.HTMLEncode.

 

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

 

|(tolower)<true> – converts the macro result to lowercase.

 

|(toupper)<true> – converts the macro result to uppercase.

 

|(toint)<default value> – converts the macro result to integer, if not successful, uses the default value.

 

|(tobool)<default value> – converts the macro result to Boolean.

 

|(toguid)<default value> – converts the macro result to GUID.

 

|(todouble)<default value> – converts the macro result to Double.

 

|(todatetime)<default value> – converts the macro result to DateTime.

 

|(resolvebbcode)<true/false> – resolves the BB code in the result of the macro.

 

|(equals)<value> – returns true if the resolved value matches the given value, otherwise returns false.

 

|(notequals)<value> - returns false if the resolved value matches the given value, otherwise returns true.

 

|(truevalue)<value> – output settings for the positive output of comparison.

 

|(falsevalue)<value> – output settings for the negative output of comparison.

 

|(add)<number> - adds the provided number to the macro result.

 

|(multiply)<number> - multiplies the macro result by the specified number.

 

|(divide)<number> - divides the macro result by the specified number.

 

|(sin) - returns sinus of the macro result.

 

|(cos) - returns cosinus of the macro result.

 

|(tan) - returns tangens of the macro result.

 

|(sqrt) - returns square root of the macro result.

 

|(pow)<number> - returns the <number>-th power of the macro result.

 

|(startswith)<string> - returns true if the macro result starts with the specified string.

 

|(endswith)<string> - returns true if the macro result ends with the specified string.

 

|(contains)<string> - returns true if the macro result contains the specified string.

 

|(not) - returns logical negation of the macro result.

 

|(append)<string> - appends the specified string to the macro result.

 

|(prepend)<string> - prepends the specified string to the macro result.

 

|(trim)<chars> - removes all characters contained in the <chars> string from the beginning and end of the macro result if they are present there.

 

|(trimend)<chars> - removes all characters contained in the <chars> string from the end of the macro result if they are present there.

 

|(trimstart)<chars> - removes all characters contained in the <chars> string from the beginning of the macro result if they are present there.

 

|(padleft)<totalwidth>(with)<char> - returns the macro result with the beginning of the string padded with the <char> character to the total length of <totalwidth>.

 

|(padright)<totalwidth>(with)<char> - returns the macro result with its end padded with the <char> character to the total length of <totalwidth>.

 

|(substring)<start>;<length> - returns a <length>-long substring of the macro result beginning on the <start> index.

 

|(replace)<src>(with)<dest> - replaces all occurrences of the <scr> string in the macro result with the <dest> string.

 

|(matches)<regex> - returns true if the macro result matches the provided regular expression.

 

|(getmatch)<regex> - returns match of the provided regular expression from the macro result.

 

|(regexreplace)<regex>(with)<dest> - replaces matches of the provided regular expression in the macro result with the <dest> string.

 

|(striptags) - strips the macro result of HTML tags.

 

|(limitlength)<length> - limits length of the macro result to the specified number of characters.

 

|(resolveurl) - resolves URL returned by the macro expression.

 

|(unresolveurl) - unresolves URL returned by the macro expression.

 

|(mappath) - maps the virtual path returned by the macro expression to a disk path.

 

|(lowerthan)<number> - returns true if the macro result is lower than the provided number.

 

|(greaterthan)<number> - returns true if the macro result is greater than the provided number.

 

|(jsescape) - escapes the macro result for usage in JavaScript to avoid XSS.

 

|(sqlescape) - escapes the macro result for usage in SQL to avoid SQL injection.

 

|(resolve) - resolves macros again in the result of the macro expression.

 

|(casesensitive) - by default, string comparison is performed as case insensitive, unless it is switched to case sensitive by adding the <add key="CMSMacrosCaseSensitiveComparison" value="true"> key to the appSettings section of the web.config file. You can use this parameter to switch string compariton to case sensitive. You can also use the |(casesensitive)false and |(casesensitive)true notation to turn case sensitive string comparison on or off when the opposite default way of comparison is configured.

 

Disabling resolving of macro parameters

 

It is possible to disable resolving of macro parameters. This can be done by adding the following key to the appSettings section of your project's web.config file:

 

<add key="CMSDisableMacroParameters" value="true" />

 

With this key added, macro parameters will be ignored, so that e.g. {%"HELLO"|(tolower)%} will be resolved as HELLO and not as hello.