Macro parameters

Macro parameters provide additional functionality to the macros and also allow modification of the macro results. Some of the parameters are functional, imagine them as function calls on the result. Such are applied in the order in which they appear in the particular macro. Others are just flagsthat influence the result in the end or specify settings of the particular resolver. Both of them provide more flexibility to the macros by transforming the result to the wanted output or evaluating the result value for depending input, such as visibility settings of a web part or other conditions.

Query string macros

Get values from URL parameters, e.g. /Home.aspx?myparam=abc. You can get the value of myparam with the {?myparam?} macro. This way, you can parameterize the page dynamically from the URL. Typical example is hiding or showing web parts or providing dynamic parameters to where conditions (be careful about SQL injection and convert the values to particular types using parameters).

Path macros

These macros are typically used to direct your displayed content to specific locations based on your current context or to restrict them somehow.

Path expressions are also resolved in the Path properties of all the controls and web parts that display documents.

Custom macros

Implement your own logic in macros using custom macros. Your handler gets the full expression and it is up to you how you resolve it. Anything that cannot be provided by standard macros can be done through custom macros with your own custom code.

Cookie macros

Getting values from cookies may be useful in case you want to maintain some persistent user state. For instance, you can take advantage of them if you want to provide your site visitors with color profiles and include some envelope with a CSS class in the pages based on the cookie.

Data & Context macros

Get values from current context with these general data macros. They offer most data from all macros and can get access to particular properties of context objects. The available objects are based on the current context. This kind of macros is also heavily used in modules, where they provide data for text templates of various types, e.g. e-mails etc.

Cookie macrosHttpContext.Current.Request.Cookies

CookieHelper.GetValue("CookieName")

Don't forget: Sanitize user input if harmful

toint, todouble, ...

Custom macrosEvaluated in:

~/App_Code/Global/CMS/CMSCustom.cs

Method:

string ResolveCustomMacro(sender, expression, out match)

Resource string macros

Uses currently set culture. Returns default culture if localization is not present.

ResHelper.GetString("ResouceKey")Query string

?

Data & Context

%

Cookie

@

Custom

#

Path

&

Localization

$

Kentico CMS 5.5 Macro Reference

Copyright 2010, Kentico software s.r.o, www.kentico.com

In-place localization macrosFormat:

{$=DefaultText|culture=LocalizedText$}

Example:

{$=Hello|de-de=Hallo|cs-cz=Ahoj$}

Uses currently set culture. Returns default text if localization is not present.

Query string macrosHttpContext.Current.Request.QueryString

QueryHelper.GetString("ParameterName")

Don't forget: Sanitize the user input if harmful

toint, todouble, ...

Macros

{$=InPlaceExpression$} {?ParameterName?}

{@CookieName@}{#Expression#}

{$ResourceKey$}

Localization macros

Localize your strings with localization macros. You have the choice of using either in-line macros with texts directly in the macros, or resource string macros to get the resource strings from physical files or DB.

Path macrosPath expressions

•{level} - Specific level of current path (first level = 0)

•. - Current path

•.. - Parent path

•% - Match anything

Examples

•/% - All documents

•/News/% - All documents under News

•./Teaser - Document teaser under the current document

•./% - All documents under the current document

•../% - All documents under the parent document of the current path

•../Product - Document product under the parent document of the current path

•/{0}/Teaser - Teaser document under current section (second level )

•/{2} - Document in the root with the same name as the document in level 2 on current path

•/{0}/{1}/% - All documents under the second level of the current path

•/{0}/Home/{2} - The same path as current except level 2 of the path is Home

{&PathExpression&}

Data & Context macros

Simple context values

•ApplicationPath - Current application path

•CurrentTime - Current time of the day

•CurrentDateTime - Current date and time

•CurrentDate - Current date

•Domain - Current domain

•IP - IP address of the client

•Campaign - Current user campaign

•URLReferrer - Page prior to this request

•ViewMode - View mode of the user (Preview etc.)

•PreferredCulture - User content culture

•PreferredUICulture - User UI culture

•ClassName - ClassName of current document

Forum context data

•ForumContext.CurrentPost. - Displayed post, available if querystring contains "postid".

•ForumContext.CurrentThread. - Displayed thread, available if querystring contains "threadid" or post is available.

•ForumContext.CurrentForum. - Displayed forum, available if querystring contains "forumid" or post is available.

•ForumContext.CurrentGroup. - Displayed forum group, available if current forum is available.

{%Expression%}

Community context data

•CommunityContext.CurrentGroup. - Displayed group, available if querystring contains "groupid", "groupguid" or "groupname".

•CommunityContext.CurrentFriendship. - Displayed friendship, available if querystring contains "friendid" or "friendguid".

•CommunityContext.CurrentFriend. - User data on the other side of the current friendship. The first side is CurrentUser.

Media library context data

•MediaLibraryContext.CurrentMediaFile. - Displayed media file, avaiable if querystring contains "fileid" or "fileguid".

•MediaLibraryContext.CurrentMediaLibrary. - Displayed media library, available if querystring contains "libraryid", libraryguid" or "libraryname" or media file is available.

E-commerce context values

•ECommerceContext.CurrentCustomer. - Customer of current user

•ECommerceContext.CurrentShoppingCart. - Customer shop. cart

•ECommerceContext.CurrentCurrency. - Current selected currency

•ECommerceContext.CurrentProduct. - Product of current doc.

•ECommerceContext.CurrentProductDepartment. - Product dep.

•ECommerceContext.CurrentProductSupplier. - Product suppplier

•ECommerceContext.CurrentProductInternalStatus.

•ECommerceContext.CurrentProductPublicStatus.

•ECommerceContext.CurrentCustomerCountry. - Country of cust.

•ECommerceContext.CurrentCustomerState. - State of customer

CMS context data

•CMSContext.CurrentDocumentParent.

•CMSContext.CurrentDocumentCulture.

•CMSContext.CurrentDocumentOwner.

•CMSContext.CurrentAttachment.

Constants

•Zero = 0

•EmptyString = ""

•PI = Math.PI

Page context data These red data groups are page (request) specific, available in the context of any content page or request in general, based on which particular contexts are available. Simple context values and structured values related to the site or user are always available.

Structured context values

• - Property of any context object, serves first match available

•CurrentUser. - Current user data

•CurrentDocument. - Current document data (complete data)

•CurrentPageInfo. - Curent page information (basic data)

•CurrentTemplate. - Current document template data

•CurrentSite. - Current site data

Site context data

•SiteContext.CurrentUser. - Currently viewed user profile, available if querystringcontains "userid", "username" or "userguid".

Process specific data These orange data groups are process specific, available only in the context of processing particular e-mail templates or values.

Web part properties

• - Web part property, available in Web part containers and properties

E-commerce invoice & e-mails

•ShoppingCart.

•Order.

•OrderStatus.

•BillingAddress.

•BillingAddress.Country.

•BillingAddress.State.

•ShippingAddress.

•ShippingAddress.Country.

•ShippingAddress.State.

•CompanyAddress.

•CompanyAddress.Country.

•CompanyAddress.State.

•ShippingOption.

•PaymentOption.

•Currency.

•Customer.

•DiscountCoupon.

Workflow e-mails

•ApplicationURL

•ApprovedWhen

•Comment

•Document.

•User.

•OriginalStep.

•CurrentStep.

Notification e-mails

•NotificationSubscription.

•NotificationGateway.

•NotificationUser.

•NotificationCustomData.

Nested macros

{(0)%UserName|(equals)administrator|(falsevalue){(1)%UserName%(1)}|(truevalue)%(0)}

• Brackets of nested macros of the same type must be properly paired with numbers.

Macro parameters

Parameters syntax:

{%expression|(name)value%}

Multiple parameters:

{%exp|(name1)val1|(name2)val2|...%}

Values are optional:

{%exp|(toint)%}

Text manipulation

•(tolower) - Lowercases the result

•(toupper) - Uppercases the result

•(append) - Appends the string to the result

•(prepend) - Prepends the result with the string

•(trim) - Trims the result

•(trimend) - Trims the end of the result

•(trimstart) - Trims the start of the result

•(padleft)(with) - Pads the result with given character on the left

•(padright)(with) - Pads the result with given character on the right

•(substring); - Gets substring of the result

•(clear) - Clears the result

Conversion

•(default) - Default when no data available

•(culture) - Culture for formatting

•(format) - Formats the result to string

•(toint) - Converts result to integer

•(tobool) - Converts result to boolean

•(toguid) - Converts result to GUID

•(todouble) - Converts result to double

•(todatetime) - Converts result to DateTime

•(tosearchdatetime) - Converts result to date and time format for search

Special

•(saveas) - Saves the current value under given name

•(notrecursive) - Disables recursion of the macro

•(handlesqlinjection) - Handles SQL injection in the result

•(resolve) - Resolves macros in the result

Mathematical

•(add) - Adds specific value to the result

•(multiply) - Multiplies the result by specific value

•(divide) - Divides the result by specific value

•(sin) - Computes sinus of the result

•(cos) - Computes cosinus of the result

•(tan) - Computes tangent of the result

•(sqrt) - Computes square root of the result

•(pow) - Powers the result to the given exponent

Escaping, resolving and replacing

•(encode) - HTML encodes the result

•(striptags) - Removes HTML tags from the result

•(resolvebbcode) - Resolves the discussion macros in the result

•(replace)(with) - Replaces src string with dest string

•(getmatch) - Gets the part of the string matched to the given RegEx

•(regexreplace)(with) - Replaces the parts matched by RegEx with dest

•(limitlength) - Limits the length of the text to specified number of characters

•(urlencode) - Encodes the result as a URL

•(resolveurl) - Resolves the result as a URL

•(unresolveurl) - Unresolves the result as a URL

•(mappath) - Maps the result as a URL to the physical path

•(jsescape) - Escapes the result as a javascript string

•(sqlescape) - Escapes the result as a SQL string

Comparison

•(truevalue) - True value for comparison

•(falsevalue) - False value for comparison

•(equals) - Gives the true value if equals, otherwise false value

•(notequals) - Opposite of the equals

•(startswith) - Gives the true value if result starts with given string

•(endswith) - Gives the true value if result ends with given string

•(contains) - Gives the true value if result contains given string

•(matches) - Gives the true value if result matches given RegEx

•(lowerthan) - Gives the true value if result is lower than value

•(greaterthan) - Gives the true value if result is larger than value

•(not) - Negates current result