---
title: Reference - Macro methods
related:
- https://docs.kentico.com/k8/macro-expressions/macro-syntax.md
- https://docs.kentico.com/k8/macro-expressions/extending-the-macro-engine/registering-custom-macro-methods.md
- https://docs.kentico.com/k8/developing-websites/loading-and-displaying-data-on-websites/writing-transformations/reference-transformation-methods.md
---
> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).
Macro expressions allow you to use a large variety of methods. The following categories list the methods according to the type of provided functionality:
> **Info:** 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. |
| 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 documents according to the specified [document types](https://docs.kentico.com/k8/developing-websites/defining-website-data-structure/document-types.md). The second parameter must contain a list of allowed document 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.
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.
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](https://docs.kentico.com/k8/macro-expressions/caching-the-results-of-macros.md) |
| 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](https://docs.kentico.com/k8/configuring-kentico/optimizing-website-performance/configuring-caching/setting-cache-dependencies.md)
[Caching the results of macros](https://docs.kentico.com/k8/macro-expressions/caching-the-results-of-macros.md) |
[> Back to the list of macro method categories](#referencemacromethods-macromethodstop)
## 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](http://en.wikipedia.org/wiki/Guid). 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 documents. 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](#referencemacromethods-macromethodstop)
## 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](http://msdn.microsoft.com/library/txafckwd%28v=vs.110%29.aspx). |
| 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](http://msdn.microsoft.com/library/txafckwd%28v=vs.110%29.aspx). |
| 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](http://en.wikipedia.org/wiki/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). |
> **Tip:** **Tips**: To perform lexicographical comparison of strings, use the basic comparison operators (==, , =). Add [macro parameters](https://docs.kentico.com/k8/macro-expressions/macro-syntax.md#macro-parameters) to specify case sensitivity and the culture context of text operations.
[> Back to the list of macro method categories](#referencemacromethods-macromethodstop)
## Advanced text processing
| Method | Return type | Parameters | Description |
| ----------------------- | ----------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GetResourceString | string | string resourceStringKey
_string culture_ | Translates the specified [resource (localization) string](https://docs.kentico.com/k8/multilingual-websites/setting-up-a-multilingual-user-interface/working-with-resource-strings.md). 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 | Escapes the string for safe usage in JavaScript (to avoid XSS vulnerabilities). |
| Localize | string | string inputText
_string culture_ | Resolves [localization expressions](https://docs.kentico.com/k8/multilingual-websites/setting-up-a-multilingual-user-interface/localizing-text-fields.md) 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](#referencemacromethods-macromethodstop)
## 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](#referencemacromethods-macromethodstop)
## Mathematical operations
> **Info:** The [macro autocomplete help](https://docs.kentico.com/k8/macro-expressions/entering-macro-expressions.md) 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](#referencemacromethods-macromethodstop)
## User membership and permissions
| Method | Return type | Parameters | Description |
| ------------------------ | ----------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CheckPrivilegeLevel | bool | object user (UserInfo)
UserPrivilegeLevelEnum privilegeLevel | Checks the user's [privilege level](https://docs.kentico.com/k8/managing-users/user-management.md). 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 _ ()_ if the user has a nickname, otherwise _ ()_.
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](https://docs.kentico.com/k8/managing-users/membership-management.md) in the system. |
| HasMembership | bool | object user (UserInfo)
string userMemberships
_bool allMemberships_ | Checks if a user belongs to the specified [memberships](https://docs.kentico.com/k8/managing-users/membership-management.md).
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](https://docs.kentico.com/k8/managing-users/configuring-permissions.md) 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](https://docs.kentico.com/k8/community-features/groups.md) (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](#referencemacromethods-macromethodstop)
## Transformations
| Method | Return type | Parameters | Description |
| ------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ApplyTransformation | string | IEnumerable collection
string transformationName
_string contentBeforeTransformationName_
_string contentAfterTransformationName_ | Applies **Text / XML** [transformations](https://docs.kentico.com/k8/developing-websites/loading-and-displaying-data-on-websites/writing-transformations.md) to a collection of items.
See also: [Using transformations in macro expressions](https://docs.kentico.com/k8/developing-websites/loading-and-displaying-data-on-websites/writing-transformations/using-transformations-in-macro-expressions.md) |
| Transform | string | IEnumerable collection
string transformationText | Applies ad-hoc transformation code (Text / XML type) to a collection of items. |
> **Info:** When writing **Text / XML** transformations, you can use most [ASCX transformation methods](https://docs.kentico.com/k8/developing-websites/loading-and-displaying-data-on-websites/writing-transformations/reference-transformation-methods.md) 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](#referencemacromethods-macromethodstop)