Reference - Macro methods

Macro expressions allow you to use a large variety of methods. The following categories list the methods according to the type of provided functionality:

Data manipulation
Data conversion
Text manipulation
Advanced text processing
Date and time modification
Mathematical operations
User membership and permissions
Transformations

Keep in mind that the recommended macro syntax is to use infix notation for the first parameter of methods.

For example: {% “word”.ToUpper() %} instead of {% ToUpper(“word”) %}

Data manipulation

Method	Return type	Parameters	Description
GetValue	object	ISimpleDataContainer container string column object defaultValue	Gets the value of the specified data column of an object that implements the ISimpleDataContainer interface. You can specify a default value used if the requested data is null.
GetProperty	object	IHierarchicalObject object string property object defaultValue	Gets the value of the specified property of an IHierarchicalObject object. You can specify a default value used if the requested property is null.
GetItem	object	IEnumerable collection int index object defaultValue	Gets the object at the specified index of a collection. You can specify a default value used if the requested object is null.
OrderBy	AbstractObjectCollection	AbstractObjectCollection collection string orderBy	Returns the collection of objects, with the order defined by the specified SQL ORDER BY clause.
Where	AbstractObjectCollection	AbstractObjectCollection collection string where	Filters a collection of objects according to the specified SQL Where condition. If the macro is saved by a user without the Administrator privilege level, the method only allows the following SQL syntax in the where condition: column names, values and basic operators: =, !=, >, < AND & OR operators, parentheses column BETWEEN value AND value column LIKE value column IN (values) column IS NULL *[only available after applying hotfix 8.1.8 or newer]* NOT keyword for the above expressions (NOT BETWEEN, NOT LIKE, NOT IN, IS NOT NULL) Other expressions and SQL functions are not supported.
TopN	AbstractObjectCollection	AbstractObjectCollection collection int topn	Returns only the specified number of objects in the collection.
Columns	AbstractObjectCollection	AbstractObjectCollection collection string columns	Returns the collection of objects containing only the specified data columns. Separate the columns using commas.
Filter	InfoObjectCollection	IEnumerable collection string condition	Filters a collection of objects according to the specified macro condition.
ClassNames	TreeNodeCollection	TreeNodeCollection collection string classNames	Filters a TreeNodeCollection of pages according to the specified page types. The second parameter must contain a list of allowed page type code names, separated by semicolons.
InList	bool	object object IEnumerable collection	Returns a true value if the object exists within the specified collection.
All	bool	IEnumerable collection string condition	Returns a true value if all of the objects in the collection match the given condition. Specify the condition as a macro expression.
Any	bool	IEnumerable collection string condition	Returns a true value if at least one object in the collection matches the given condition. Specify the condition as a macro expression. If you leave out the condition parameter, the method returns true if the collection contains at least one object. Throws an exception if the collection is null.
Exists	bool	IEnumerable collection string condition	Returns a true value if at least one object in the collection matches the given condition. Specify the condition as a macro expression. If you leave out the condition parameter, the method returns true if the collection contains at least one object. Returns false if the collection is null.
RandomSelection	IList	IEnumerable items int numberOfItems	Returns randomly selected objects from the collection. You can optionally specify the number of items.
SelectInterval	IList	IEnumerable items int lowerBound int upperBound	Returns the specified interval of objects from the collection.
Cache	object	object expression int cacheMinutes bool condition string cacheItemName string cacheItemNameParts CMSCacheDependency cacheDependency	Evaluates the specified macro expressions and stores the result in the server-side application cache. The system only evaluates the expression if the result is not found in the cache. See also: Caching the results of macros
GetCacheDependency	CMSCacheDependency	string[] dependencies	Returns a CMSCacheDependency object based on the specified dummy cache keys (one or more string parameters). See also: Setting cache dependencies Caching the results of macros

> Back to the list of macro method categories

Data conversion

Method	Return type	Parameters	Description
ToString	string	object value string defaultValue string culture string format	Converts an object to a string. Returns the optional default value if the conversion is not possible. You can also specify the culture context and a formatting string used for the conversion.
ToInt	int	object value int defaultValue	Converts an object to an integer number. Returns the optional default value if the conversion is not possible.
ToBool	bool	object value bool defaultValue	Converts an object to a boolean value. Returns the optional default value if the conversion is not possible.
ToDouble	double	object value double defaultValue string culture	Converts an object to a double number. Returns the optional default value if the conversion is not possible. You can also specify a culture code to determine the formatting of the decimal number.
ToGuid	guid	object value Guid defaultValue	Converts an object to a GUID value. Returns the optional default value if the conversion is not possible.
ToDateTime	DateTime	object value DateTime defaultValue string culture	Converts an object to a DateTime value. Returns the optional default value if the conversion is not possible. You can also specify a culture code to determine the date format.
FromOADate	DateTime	double value	Converts a double representation of a date and time value (OLE Automation Date) to a DateTime object.
ToTimeSpan	TimeSpan	object value	Converts an object to a TimeSpan value. Returns null if the conversion is not possible.
ToBaseInfo	BaseInfo	object value BaseInfo defaultValue	Converts an object to a BaseInfo — the general type for Kentico system objects and pages. Returns the optional default value if the conversion is not possible.
List	ArrayList	object items	Converts a list of objects to an ArrayList.

> Back to the list of macro method categories

Text manipulation

Method	Return type	Parameters	Description
Contains	bool	string text string search	Returns a true value if the string specified by the second parameter occurs within the first string.
EndsWith	bool	string text string findText	Indicates whether the string specified by the second parameter occurs at the end of the first string.
Format	string	string value string format	Replaces all formatting expressions in a string using the text equivalents specified in the second parameter. Based on composite formatting.
FormatNotEmpty	string	string value string format string emptyResult	If the first parameter is not empty or null, replaces all formatting expressions in the string using the text equivalents specified in the second parameter. Returns the optional third parameter if the value is null or empty. Based on composite formatting.
GetMatch	string	string text string regex	Matches the string value to the specified regular expression and returns the match.
IndexOf	int	string text string searchFor	Returns the index of the first occurrence of the second string within the first string.
LastIndexOf	int	string text string searchFor	Returns the index of the last occurrence of the second string within the first string.
LimitLength	string	string text int length string padString bool wholeWords	Limits the length of the string to the specified number of characters. The padString parameter allows you to set a string that the method appends to the end of the limited result. The length of the parameter is included in the maximum length. If you set the wholeWords parameter to true, the method preserves the last word in the string.
LoremIpsum	string	string length	Generates lorem Ipsum text (1000 characters by default). To change the number of generated characters, call the method with a string parameter containing a number. For example: LoremIpsum(“100”)
Matches	bool	string text string regex	Indicates whether the string matches the specified regular expression.
NotContains	bool	string text string search	Returns a true value if the string specified by the second parameter does NOT occur within the first string.
PadLeft	string	string text int length string paddingString	Adds leading characters to the string until the total length matches the second parameter. By default, the method uses spaces as the padding character, but you can optionally specify a different character.
PadRight	string	string text int length string paddingString	Adds trailing characters to the string until the total length matches the second parameter. By default, the method uses spaces as the padding character, but you can optionally specify a different character.
RegexReplace	string	string text string regex string replacement	Replaces strings that match the regular expression pattern within the first string using the replacement string.
Remove	string	string text int position int length	Deletes characters from the string, starting at the specified index. By default, the method removes all remaining characters from the specified position. You can optionally specify the number of characters to be removed.
Replace	string	string text string replace string replacement	Replaces all occurrences of the second string within the first string using the replacement string.
Split	string[]	string text string delimiters bool removeEmpty	Separates the string into an array of substrings according to the specified delimiting characters. If the optional third parameter is true, the method removes empty substrings from the result.
StartsWith	bool	string text string findText	Indicates whether the string specified by the second parameter occurs at the start of the first string.
Substring	string	string text int index int length	Returns a substring starting at the specified index. By default, the method returns all remaining characters from the specified index. You can optionally specify the number of characters to be returned.
ToLower	string	string text	Converts the entire string to lower case.
ToUpper	string	string text	Converts the entire string to upper case.
Trim	string	string text string charsToTrim	Removes all leading and trailing occurrences of characters from the string. By default, the method trims white space characters, but you can optionally specify a different set of characters (as a string).
TrimEnd	string	string text string charsToTrim	Removes all trailing occurrences of characters from the string. By default, the method trims white space characters, but you can optionally specify a different set of characters (as a string).
TrimStart	string	string text string charsToTrim	Removes all leading occurrences of characters from the string. By default, the method trims white space characters, but you can optionally specify a different set of characters (as a string).

Tips: To perform lexicographical comparison of strings, use the basic comparison operators (==, <, >, <=, >=). Add macro parameters to specify case sensitivity and the culture context of text operations.

> Back to the list of macro method categories

Advanced text processing

Method	Return type	Parameters	Description
GetResourceString	string	string resourceStringKey string culture	Translates the specified resource (localization) string. By default, the target language of the localization depends on the current culture. You can specify the target language using the optional parameter.
JSEscape	string	string text	Encodes apostrophe and quote characters in the string parameter into the corresponding HTML entities: ’ to ' ” to "
Localize	string	string inputText string culture	Resolves localization expressions within the specified text. By default, the target language of the localization depends on the current culture. You can specify the target language using the optional parameter.
MapPath	string	string path	Returns the physical file path that matches the specified virtual path.
ResolveBBCode	string	string text	Resolves BBCode tags in the specified text, for example: {% ResolveBBCode(“[quote]Sample text[/quote]”) %}.
ResolveMacroExpressions	string	string expression	Resolves the specified macro expression (without the {% %} parentheses).
ResolveMacros	string	string inputText	Resolves all macros within the specified text.
ResolveUrl	string	string url	Converts relative URLs starting with ~/ to relative URLs containing the current application path (so they can be resolved by clients). Absolute URLs remain unchanged.
StripTags	string	string text	Removes all HTML tags from the specified text.
SQLEscape	string	string text	Escapes the string for safe usage in SQL commands (to avoid SQL injection).
UnresolveUrl	string	string url	Converts relative URLs containing the application path to relative URLs starting with ~/. Absolute URLs remain unchanged.
UrlEncode	string	string url	Applies URL encoding to the specified string.

> Back to the list of macro method categories

Date and time modification

Method	Return type	Parameters	Description
AddMilliseconds	DateTime	DateTime datetime int milliseconds	Adds the specified number of milliseconds to a DateTime value.
AddSeconds	DateTime	DateTime datetime int seconds	Adds the specified number of seconds to a DateTime value.
AddMinutes	DateTime	DateTime datetime int minutes	Adds the specified number of minutes to a DateTime value.
AddHours	DateTime	DateTime datetime int hours	Adds the specified number of hours to a DateTime value.
AddDays	DateTime	DateTime datetime int days	Adds the specified number of days to a DateTime value.
AddWeeks	DateTime	DateTime datetime int weeks	Adds the specified number of weeks to a DateTime value.
AddMonths	DateTime	DateTime datetime int months	Adds the specified number of months to a DateTime value.
AddYears	DateTime	DateTime datetime int years	Adds the specified number of years to a DateTime value.
ToShortDateString	string	DateTime datetime	Converts the value of the DateTime parameter to an equivalent short date string representation.
ToShortTimeString	string	DateTime datetime	Converts the value of the DateTime parameter to an equivalent short time string representation.

> Back to the list of macro method categories

Mathematical operations

The macro autocomplete help only shows the mathematical methods as members of the Math namespace, for example {% Math.Abs(-2) %}. However, the system resolves the methods even without the namespace.

Method	Return type	Parameters	Description
Abs	double	double number	The absolute value of the specified number.
Acos	double	double number	The angle whose cosine is the specified number.
Asin	double	double number	The angle whose sine is the specified number.
Atan	double	double number	The angle whose tangent is the specified number.
Average	double	InfoObjectCollection collection string columnName	The average of all numbers in the specified data column of the objects in the collection.
Ceiling	double	double number	The smallest whole number greater than or equal to the specified number.
Cos	double	double number	The cosine of the specified angle.
Cosh	double	double number	The hyperbolic cosine of the specified angle.
Exp	double	double number	e raised to the specified power.
Floor	double	double number	The largest whole number lesser than or equal to the specified number.
GetRandomInt	int	int minValue int maxValue int seed	Generates a random positive integer. You can use the optional parameters to specify the range of possible numbers, and the seed number for the generator.
GetRandomDouble	double	int minValue int maxValue int seed	Generates a random positive decimal number. You can use the optional parameters to specify the range of possible numbers, and the seed number for the generator.
IsOdd	bool	int number	Returns a true value if the specified number is odd.
IsEven	bool	int number	Returns a true value if the specified number is even.
Log	double	double number	The base e logarithm of a specified number.
Log10	double	double number	The base 10 logarithm of a specified number.
Max	double	double parameters	The maximum from the given list of numbers.
Maximum	double	InfoObjectCollection collection string columnName	The maximum of all numbers in the specified data column of the objects in the collection.
Min	double	double parameters	The minimum from the given list of numbers.
Minimum		InfoObjectCollection collection string columnName	The minimum of all numbers in the specified data column of the objects in the collection.
Modulo	int	int left int right	The modulo of two integer numbers.
Pow	double	double base double exp	The number raised to the specified power.
Percent	double	double percent	Multiples the specified number by 0.01.
Round	double	double number int digits string mode	The number nearest to the specified value. The optional second parameter sets the number of fractional digits in the rounded value. You can use the third parameter to set the rounding mode for numbers half-way between two other numbers. Supported variants are: AwayFromZero - rounds to the nearest number away from zero ToEven - rounds toward the nearest even number
Sign	double	double number	Returns a value indicating the sign of a number: -1 (the number is less than zero) 0 (the number is zero) 1 (the number is greater than zero)
Sin	double	double number	The sine of the specified angle.
Sinh	double	double number	The hyperbolic sine of the specified angle.
Sqrt	double	double number	The square root of a specified number.
Sum	double	InfoObjectCollection collection string columnName	The sum of all numbers in the specified data column of the objects in the collection.
Tan	double	double number	The tangent of the specified angle.
Tanh	double	double number	The hyperbolic tangent of the specified angle.

> Back to the list of macro method categories

User membership and permissions

Method	Return type	Parameters	Description
CheckPrivilegeLevel	bool	object user (UserInfo) UserPrivilegeLevelEnum privilegeLevel	Checks the user’s privilege level. Returns a true value if the user’s privilege level matches the required UserPrivilegeLevelEnum value or is higher. You can check the following levels: {% CurrentUser.CheckPrivilegeLevel(UserPrivilegeLevelEnum.Editor) %} {% CurrentUser.CheckPrivilegeLevel(UserPrivilegeLevelEnum.Admin) %} {% CurrentUser.CheckPrivilegeLevel(UserPrivilegeLevelEnum.GlobalAdmin) %}
GetFormattedUserName	string	object user (UserInfo) bool isLiveSite	Returns the formatted username of the specified user object. The default format is <full name> (<nickname>) if the user has a nickname, otherwise <full name> (<username>). The isLiveSite parameter determines whether the macro displays the username on the live website.
HasAnyMembership	bool	object user (UserInfo)	Checks whether the user belongs to any membership in the system.
HasMembership	bool	object user (UserInfo) string userMemberships bool allMemberships	Checks if a user belongs to the specified memberships. Enter the code names of memberships through the userMemberships parameter. When checking multiple memberships, use semicolons (;) to separate the code names. If the allMemberships parameter is true, the user must belong to all specified memberships for the check to succeed. To check whether the user belongs to a membership on a global level, add the period character (.) prefix before the membership code name.
IsAuthorizedPerResource	bool	object user (UserInfo) string resource string permission	Evaluates whether a user has a specific permission for a resource (module). Use code names to identify the resource and permission.
IsAuthorizedPerUIElement	bool	object user (UserInfo) string resource string elementName	Evaluates whether a user is allowed to access a specific UI element of a resource (module). Use code names to identify the resource and element.
IsInGroup	bool	object user (UserInfo) string userGroup	Checks if a user belongs to a group (community or workgroup).
IsInRole	bool	object user (UserInfo) string userRole bool allRoles	Checks if a user belongs to the specified roles. Enter the code names of roles through the userRole parameter. When checking multiple roles, use semicolons (;) to separate the code names. If the allRoles parameter is true, the user must belong to all specified roles for the check to succeed. To check whether the user belongs to a role on a global level, add the period character (.) prefix before the role code name.

> Back to the list of macro method categories

Transformations

ApplyTransformation

string

IEnumerable collection
string transformationName
string contentBeforeTransformationName
string contentAfterTransformationName

Applies Text / XML transformations to a collection of items.

Transform

string

IEnumerable collection
string transformationText

Applies ad-hoc transformation code (Text / XML type) to a collection of items.

When writing Text / XML transformations, you can use most ASCX transformation methods inside macro expressions.

Outside of transformations, the macro autocomplete only offers the methods under the Transformation namespace, for example Transformation.GetDocumentUrl(). However, you can manually enter the methods even without the namespace.

> Back to the list of macro method categories