Kentico CMS 7.0 Developer's Guide

Available macro methods

Available macro methods

Previous topic Next topic Mail us feedback on this topic!  

Available macro methods

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

You can use a large variety of methods in your macro expressions. This topic lists all methods intended specifically for use in Kentico CMS macro expressions that are members of the GlobalHelper.MacroMethods.cs. They are listed in the following categories according to the type of functionality they provide:

 

Boolean methods

Comparison methods

Conversion methods

Data manipulation methods

DateTime methods

GlobalHelper methods

Mathematical methods

Membership methods

String methods

Transformation methods

Other methods

 

Boolean methods

 

Boolean (Boolean left) && (Boolean right)

Returns logical product of given parameters.

Boolean left: Left operand.

Boolean right: Right operand.

 

Boolean (Boolean left) || (Boolean right)

Returns logical addition of given parameters.

Boolean left: Left operand.

Boolean right: Right operand.

 

Boolean Not (Boolean value)

Boolean ! (Boolean value)

Returns logical negation of the provided value.

Boolean value: Value to negate.

 

Boolean And (Boolean left, Boolean right)

Returns logical product of given parameters.

Boolean left: Left operand.

Boolean right: Right operand.

 

Boolean Or (Boolean left, Boolean right)

Returns logical addition of given parameters.

Boolean left: Left operand.

Boolean right: Right operand.

 

Int32 LogicalAnd (Int32 left, Int32 right)

Int32 (Int32 left) & (Int32 right)

Returns bit logical product of given parameters.

Int32 left: Left operand.

Int32 right: Right operand.

 

Int32 LogicalOr (Int32 left, Int32 right)

Int32 (Int32 left) | (Int32 right)

Returns bit logical addition of given parameters.

Int32 left: Left operand.

Int32 right: Right operand.

 

Int32 LogicalXor (Int32 left, Int32 right)

Int32 (Int32 left) ^ (Int32 right)

Returns bit logical exclusive addition of given parameters.

Int32 left: Left operand.

Int32 right: Right operand.

 

Int32 LeftShift (Int32 left, Int32 right)

Int32 (Int32 left) << (Int32 right)

Shifts its first operand left by the number of bits specified by its second operand.

Int32 left: Left operand.

Int32 right: Right operand.

 

Int32 RightShift (Int32 left, Int32 right)

Int32 (Int32 left) >> (Int32 right)

Shifts its first operand right by the number of bits specified by its second operand.

Int32 left: Left operand.

Int32 right: Right operand.

 

Comparison methods

 

Boolean GreaterThan(Double left, Double right)

Boolean (Double left) > (Double right)

Returns true if the first parameter is greater than second. The method also accepts DateTime values as operands.

Double left: Left operand.

Double right: Right operand.

 

Boolean LowerThan(Double left, Double right)

Boolean (Double left) < (Double right)

Returns true if the first parameter is lower than second. The method also accepts DateTime values as operands.

Double left: Left operand.

Double right: Right operand.

 

Boolean GreaterThanOrEqual(Double left, Double right)

Boolean (Double left) >= (Double right)

Returns true if the first parameter is greater than or equal to second. The method also accepts DateTime values as operands.

Double left: Left operand.

Double right: Right operand.

 

Boolean LowerThanOrEqual(Double left, Double right)

Boolean (Double left) <= (Double right)

Returns true if the first parameter is lower than or equal to second. The method also accepts DateTime values as operands.

Double left: Left operand.

Double right: Right operand.

 

Boolean Equals(Object left, Object right)

Boolean (Object left) == (Object right)

Returns true if the first parameter is equal to the second. The method also accepts DateTime values as operands.

Object left: Left operand.

Object right: Right operand.

 

Boolean NotEquals(Object left, Object right)

Boolean (Object left) != (Object right)

Returns true if first parameter is not equal to the second.

Object left: Left operand.

Object right: Right operand.

 

Conversion methods

 

Int32 ToInt(Object value, Int32 defaultValue)

Converts value to int, if it is not possible, returns default value. This method is overloaded, while the Int32 defaultValue parameter is optional.

Object value: Object to convert.

Int32 defaultValue: Default value.

 

Boolean ToBool(Object value, Boolean defaultValue)

Converts value to bool, if it is not possible, returns default value. This method is overloaded, while the Boolean defaultValue parameter is optional.

Object value: Object to convert.

Boolean defaultValue: Default value.

 

Double ToDouble(Object value, Double defaultValue, String culture)

Converts value to double, if it is not possible, returns default value. This method is overloaded, while the Double defaultValue and String culture parameters are optional.

Object value: Object to convert.

Double defaultValue: Default value.

String culture: Culture to use.

 

Guid ToGuid(Object value, Guid defaultValue)

Converts value to Guid, if it is not possible, returns default value. This method is overloaded, while the Guid defaultValue parameter is optional.

Object value: Object to convert.

Guid defaultValue: Default value.

 

DateTime ToDateTime(Object value, DateTime defaultValue, String culture)

Converts value to DateTime, if it is not possible, returns default value. This method is overloaded, while the DateTime defaultValue and String culture parameter are optional.

Object value: Object to convert.

DateTime defaultValue: Default value.

String culture: Culture to use.

 

DateTime FromOADate(Double value)

Converts double representation of DateTime (OLE Automation Date) to DateTime.

Double value: OADate double representation to convert.

 

TimeSpan ToTimeSpan(Object value)

Parses the provided string value and converts it to TimeSpan.

 

Data manipulation methods

 

Object GetValue(ISimpleDataContainer container, String column)

Gets value of the specified column from the object.

ISimpleDataContainer container: Data container.

String column: Column name.

 

Object GetProperty(IHierarchicalObject collection, String property)

Gets value of the specified property from the object.

IHierarchicalObject collection: DataContainer.

String property: Property name.

 

Object GetItem(IEnumerable collection, Int32 index)

Gets the item stored at the specified index from the collection.

IEnumerable collection: Collection.

Int32 index: Index of the item.

 

AbstractObjectCollection OrderBy(AbstractObjectCollection collection, String orderBy)

Applies an Order by clause to the collection.

AbstractObjectCollection collection: Collection to order.

String orderBy: ORDER BY column(s).

 

AbstractObjectCollection Where(AbstractObjectCollection collection, String where)

Can be used to filter the objects in a collection by applying a Where condition.

AbstractObjectCollection collection: Collection to filter.

String where: WHERE condition.

 

AbstractObjectCollection TopN(AbstractObjectCollection collection, Int32 parameters)

Limits how many objects should be included in the collection.

AbstractObjectCollection collection: Collection to filter.

Int32 parameters: TOP N parameter.

 

AbstractObjectCollection Columns (AbstractObjectCollection collection, String columns)

Specifies which object data columns should be included in the collection.

AbstractObjectCollection collection: Collection to filter.

String columns: Columns parameter.

 

InfoObjectCollection Filter(InfoObjectCollection collection, String condition)

Returns the collection filtered by given condition.

InfoObjectCollection collection: Collection of items.

String condition: Filtering macro condition to evaluate for each item.

 

TreeNodeCollection ClassNames(TreeNodeCollection collection, String classNames)

Filters a collection of tree nodes (documents) to only include the specified document types.

TreeNodeCollection collection: Collection of documents.

String classNames: A list of document types that should be returned in the filtered collection (specified by their code names and separated by semicolons).

 

ArrayList List(Object items)

Creates an ArrayList from given list of items.

Object items: List of items to add.

 

Boolean InList(Object object, IEnumerable collection)

Returns true if specified object exists within the given collection.

Object object: Object which should be checked for existence within the collection.

IEnumerable collection: Collection of items.

 

Boolean Exists(InfoObjectCollection collection, String condition)

Returns true if there is at least one object in the collection which matches given condition.

InfoObjectCollection collection: Collection of items.

String condition: Filtering macro condition to evaluate for each item.

 

Object Cache(Object expression, Int32 cacheMinutes, Boolean condition, String cacheItemName, String cacheItemNameParts, CMSCacheDependency cacheDependency)

Evaluates the given expression and puts it to the cache. The expression is evaluated only when not found in cache.

Object expression: Expression to be evaluated and cached.

Int32 cacheMinutes: Cache minutes

Boolean condition: Cache condition

String cacheItemName: Cache item name.

String cacheItemNameParts: Cache item name parts.

CMSCacheDependency cacheDependency: Cache dependency object (use GetCacheDependency method to get the object).

 

CMSCacheDependency GetCacheDependency(String dependencies)

Returns CacheDependency object created from given string.

String dependencies: Cache dependency strings.

 

DateTime methods

 

DateTime AddMilliseconds(DateTime datetime, Int32 milliseconds)

Adds the specified number of milliseconds to the specified base DateTime value.

DateTime datetime: Base DateTime value to which the milliseconds should be added.

Int32 milliseconds: Number of milliseconds to be added to the base DateTime value.

 

DateTime AddSeconds(DateTime datetime, Int32 seconds)

Adds the specified number of seconds to the specified base DateTime value.

DateTime datetime: Base DateTime value to which the seconds should be added.

Int32 seconds: Number of seconds to be added to the base DateTime value.

 

DateTime AddMinutes(DateTime datetime, Int32 minutes)

Adds the specified number of minutes to the specified base DateTime value.

DateTime datetime: Base DateTime value to which the minutes should be added.

Int32 minutes: Number of minutes to be added to the base DateTime value.

 

DateTime AddHours(DateTime datetime, Int32 hours)

Adds the specified number of hours to the specified base DateTime value.

DateTime datetime: Base DateTime value to which the hours should be added.

Int32 hours: Number of hours to be added to the base DateTime value.

 

DateTime AddDays(DateTime datetime, Int32 days)

Adds the specified number of days to the specified base DateTime value.

DateTime datetime: Base DateTime value to which the days should be added.

Int32 days: Number of days to be added to the base DateTime value.

 

DateTime AddWeeks(DateTime datetime, Int32 weeks)

Adds the specified number of weeks to the specified base DateTime value.

DateTime datetime: Base DateTime value to which the weeks should be added.

Int32 weeks: Number of weeks to be added to the base DateTime value.

 

DateTime AddMonths(DateTime datetime, Int32 months)

Adds the specified number of months to the specified base DateTime value.

DateTime datetime: Base DateTime value to which the months should be added.

Int32 months: Number of months to be added to the base DateTime value.

 

DateTime AddYears(DateTime datetime, Int32 years)

Adds the specified number of years to the specified base DateTime value.

DateTime datetime: Base DateTime value to which the years should be added.

Int32 years: Number of years to be added to the base DateTime value.

 

GlobalHelper methods

 

String UrlEncode (String url)

Encodes the URL.

String url: URL to be encoded.

 

String ResolveBBCode (String text)

Resolves BB code in the provided string.

String text: Text to be resolved.

 

String JSEscape (String text)

Escapes the string for usage in JavaScript to avoid XSS.

String text: Text to be processed.

 

String SQLEscape (String text)

Escapes the string for usage in SQL to avoid SQL injection. Single quotes are replaced by two single quotes.

String text: Text to be processed.

 

String StripTags (String text)

Removes all HTML tags from the provided string.

String text: Text to be processed.

 

String ResolveUrl (String url)

Resolves the URL.

String url: URL to be resolved.

 

String UnresolveUrl (String url)

Unresolves the URL.

String url: URL to be unresolved.

 

String MapPath (String path)

Maps the virtual path to the disk.

String path: Virtual path.

 

String LimitLength (String text, Int32 length)

Limits the length of the string to specified number of characters.

String text: Text to be processed.

Int32 length: Length of the result.

 

String RegexReplace (String text, String regex, String replacement)

Replaces the string using regular expressions.

String text: Text to be processed.

String regex: Regular expression.

String replacement: Replacement string.

 

String GetMatch (String text, String regex)

Matches the string provided in the first parameter to the regular expression and returns the match.

String text: Text to be processed.

String regex: Regular expression.

 

Boolean Matches (String text, String regex)

Matches the string provided in the first parameter to the regular expression and returns true if the it matches, false if not.

String text: Text to be processed.

String regex: Regular expression.

 

String Localize (String inputText, String culture)

Localizes given text (resolves localization macros). This method is overloaded, while the String culture parameter is optional.

String inputText: Text to be localized.

String culture: Required culture of the translation.

 

String GetResourceString (String resourceStringKey, String culture)

Translates given resource string. This method is overloaded, while the String culture parameter is optional.

String resourceStringKey: Name of the resource string.

String culture: Target culture of the translation.

 

Mathematical methods

 

The following methods are only offered under the Math namespace by macro autocompletion (type e.g. Math.Add(2,3)). However, if you enter them manually without the namespace, they are functional as well.

 

Double Multiply (Double[] parameters)

Double (Double parameters) * (Double parameter) * ...

Returns product of the parameters.

Double[] parameters: List of numbers to multiply.

Double parameter: Number to multiply.

 

Double Divide (Double left, Double right)

Double (Double left) / (Double right)

Divides two number values.

Double left: Left operand.

Double right: Right operand.

 

Double Percent (Double percent)

Double (Double percent) %

Returns the 0.01 multiple of the first argument.

Double percent: Number of percent (number to be multiplied by 0.01).

 

Int32 Modulo (Int32 left, Int32 right)

Int32 mod (Int32 left, Int32 right)

Returns modulo of two values.

Int32 left: Left operand.

Int32 right: Right operand.

 

Double Max (Double[] parameters)

Returns maximum from given numbers.

Double parameters: List of numbers.

 

Double Min (Double[] parameters)

Returns minimum from given numbers.

Double parameters: List of numbers.

 

Double Abs (Double number)

Returns the absolute value of a specified number.

Double number: Number to do the operation on.

 

Double Acos (Double number)

Returns the angle whose cosine is the specified number.

Double number: Number to do the operation on.

 

Double Asin (Double number)

Returns the angle whose sine is the specified number.

Double number: Number to do the operation on.

 

Double Atan (Double number)

Returns the angle whose tangent is the specified number.

Double number: Number to do the operation on.

 

Double Ceiling (Double number)

Returns the smallest whole number greater than or equal to the specified number.

Double number: Number to do the operation on.

 

Double Cos (Double number)

Returns the cosine of the specified angle.

Double number: Number to do the operation on.

 

Double Cosh (Double number)

Returns the hyperbolic cosine of the specified angle.

Double number: Number to do the operation on.

 

Double Exp (Double number)

Returns e raised to the specified power.

Double number: Number to do the operation on.

 

Double Floor (Double number)

Returns the largest whole number less than or equal to the specified number.

Double number: Number to do the operation on.

 

Double Log (Double number)

Returns the logarithm of the specified number.

Double number: Number to do the operation on.

 

Double Log10 (Double number)

Returns the base 10 logarithm of the specified number.

Double number: Number to do the operation on.

 

Double Pow (Double base, Double exp)

Returns a specified number raised to the specified power.

Double base: Base.

Double exp: Exponent.

 

Double Round (Double number)

Returns the nearest whole number to the specified number.

Double number: Number to do the operation on.

 

Double Sign (Double number)

Returns a value indicating the sign of a number.

Double number: Number to do the operation on.

 

Double Sin (Double number)

Returns the sine of the specified angle.

Double number: Number to do the operation on.

 

Double Sinh (Double number)

Returns the hyperbolic sine of the specified angle.

Double number: Number to do the operation on.

 

Double Sqrt (Double number)

Returns the square root of a specified number.

Double number: Number to do the operation on.

 

Double Tan (Double number)

Returns the tangent of the specified angle.

Double number: Number to do the operation on.

 

Double Tanh (Double number)

Returns the hyperbolic tangent of the specified angle.

Double number: Number to do the operation on.

 

Int32 ~ (Int32 number)

Returns a bitwise complement.

Int32 number: Number to do the operation on.

 

Boolean IsOdd (Int32 number)

Returns true if the given number is odd.

Int32 number: Number to do the operation on.

 

Boolean IsEven (Int32 number)

Returns true if the given number is even.

Int32 number: Number to do the operation on.

 

Double Average(InfoObjectCollection collection, String columnName)

Returns an average of all collection items over specified column.

InfoObjectCollection collection: Collection of items.

String columnName: Name of the column.

 

Double Sum(InfoObjectCollection collection, String columnName)

Returns a sum of all collection items over specified column.

InfoObjectCollection collection: Collection of items.

String columnName: Name of the column.

 

Int32 GetRandomInt(Int32 minValue, Int32 maxValue, Int32 seed)

Returns a random integer within a specified range.

Int32 minValue: The inclusive lower bound of the number.

Int32 maxValue: The inclusive upper bound of the number.

Int32 seed: Seed for the pseudorandom generator - default is system time.

 

Double GetRandomDouble(Int32 minValue, Int32 maxValue, Int32 seed)

Returns a random double within a specified range.

Int32 minValue: The inclusive lower bound of the number.

Int32 maxValue: The inclusive upper bound of the number.

Int32 seed: Seed for the pseudorandom generator - default is system time.

 

Membership methods

 

Boolean IsInRole(Object User, String userRole)

Returns true if user is in role.

Object User: User info object

String userRole: Name of the role to test whether user is in.

 

Boolean HasMembership(Object User, String userMembership)

Returns true if user is in membership.

Object User: User info object

String userMembership: Name of the membership to test whether user is in.

 

Boolean IsInGroup(Object User, String userGroup)

Returns true if user is in group.

Object User: User info object

String userGroup: Name of the group to test whether user is in.

 

String methods

 

String ToLower (String text)

Converts the string to lower case letters.

String text: Text to convert.

 

String ToUpper (String text)

Converts the string to upper case letters.

String text: Text to convert.

 

Boolean EndsWith (String text, String findText)

Determines whether the end of the first string matches the second string.

String text: Text to check.

String findText: Text to find.

 

Boolean StartsWith (String text, String findText)

Determines whether the beginning of the first string matches the second string.

String text: Text to check.

String findText: Text to find.

 

String Substring (String text, Int32 index, Int32 length)

Retrieves a substring from the base string. The method is overloaded, while the Int32 length parameter is optional.

String text: Base text.

Int32 index: The index of the start of the substring.

Int32 length: The number of characters in the substring.

 

String[] Split (String text, String delimiters)

Identifies the substrings in this instance that are delimited by one or more characters specified in an array, then places the substrings into a string array.

String text: String to split.

String delimiters: Delimiters string. Each character of this string will be taken as a delimiter.

 

String Join (IEnumerable list, String separator)

Concatenates a specified separator string between each element of a specified string array, yielding a single concatenated string.

IEnumerable list: IEnumerable to be joined.

String separator: Separator string.

 

Boolean Contains (String text, String search)

Returns a value indicating whether the string specified in the second parameter occurs within the string specified in the first one.

String text: Text to search in.

String search: Text to search.

 

String Trim (String text, String charsToTrim)

Removes all occurrences of white space characters from the beginning and end of the string specified in the first parameter. The method is overloaded, while the String charsToTrim parameter is optional.

String text: Text to be trimmed.

String charsToTrim: String divided to individual characters which are then trimmed.

 

String TrimEnd (String text, String charsToTrim)

Removes all occurrences of a set of characters specified in an array from the end of the string specified in the first parameter. The method is overloaded, while the String charsToTrim parameter is optional.

String text: Text to be trimmed.

String charsToTrim: String divided to individual characters which are then trimmed.

 

String TrimStart (String text, String charsToTrim)

Removes all occurrences of a set of characters specified in an array from the beginning of the string specified in the first parameter. The method is overloaded, while the String charsToTrim parameter is optional.

String text: Text to be trimmed.

String charsToTrim: String divided to individual characters which are then trimmed.

 

String Replace (String text, String replace, String replacement)

Replaces all occurrences of a specified Unicode character or string in the string specified in the first parameter with another specified Unicode character or string specified in the third paramter.

String text: Base text.

String replace: Text to be replaced.

String replacement: Replacement text.

 

String Remove (String text, Int32 position, Int32 length)

Deletes a specified number of characters from the string specified in the first parameter, beginning at the specified position.

String text: Base text.

Int32 position: The position in the base text where to begin deleting characters.

Int32 length: The number of characters to delete.

 

String PadLeft (String text, Int32 length, String paddingString)

Left-aligns the characters in the string, padding on the right with a specified Unicode character, for a specified total length. This method is overloaded, while the String paddingString parameter is optional.

String text: Base text.

Int32 length: The number of characters in the resulting string, equal to the number of original characters plus any additional padding characters.

String paddingString: A Unicode padding character (if not specified, space is used).

 

String PadRight (String text, Int32 length, String paddingString)

Right-aligns the characters in this string, padding on the left with a specified Unicode character, for a specified total length.  This method is overloaded, while the String paddingString parameter is optional.

String text: Base text.

Int32 length: The number of characters in the resulting string, equal to the number of original characters plus any additional padding characters.

String paddingString: A Unicode padding character (if not specified, space is used).

 

Int32 IndexOf (String text, Object searchFor)

Reports the index of the first occurrence of a string within this instance.

String text: Base text.

Object searchFor: The string to seek.

 

Int32 LastIndexOf (String text, Object searchFor)

Reports the index position of the last occurrence of a specified Unicode character or string within the string specified in the first parameter.

String text: Base text.

Object searchFor: The string to seek.

 

String Format (Object formattedObject, String format)

Formats given value to requested format.

Object formattedObject: Object to format.

String format: Formatting string.

 

String LoremIpsum (Int32 length)

Generates Lorem Ipsum text of given length. This method is overloaded, while the Int32 length parameter is optional. If the parameter is not used, the returned text is 1002 characters long (including white spaces).

Int32 length: Length of the text.

 

Transformation methods

 

String ApplyTransformation (IEnumerable collection, String transformationName)

Applies the specified transformation to list of items.

IEnumerable collection: Collection of items.

String transformationName: Transformation name.

 

String Transform (IEnumerable parameters, String transformationText)

Applies ad-hoc text transformation to the provided list of items.

IEnumerable parameters: Collection of items.

String transformationText: Text of the transformation.

 

For more information and practical examples demonstrating how the ApplyTransformation method can be used, please refer to the Transformations in macro expressions topic.

 

In addition to the methods mentioned above, you can also use all methods usable in transformation text. The methods are listed and described in Context Help -> General -> Methods in transformations. These methods are only offered under the Transformation namespace by macro autocompletion (type e.g. Transformation.Eval(DocumentName)) when entered elsewhere than in transformation text. However, if you enter them manually without the namespace, they will be functional as well.

 

Other methods

 

void LogToDebug (params object[] valuesToLog)

Logs values of provided parameters into the macro debug in Site Manager -> Administration -> System -> Debug -> Macros.

params object[] valuesToLog: Array of parameters whose values will be logged into the macro debug.