Reference - Transformation methods

This reference provides information about the default methods specifically designed for use in transformations:

Notes

  • All transformation methods return string values (unless otherwise specified).
  • The examples of methods below are formatted for ASCX transformations. For Text / XML transformations, macro method equivalents with identical signatures are available for most transformation methods.
  • In addition to the listed method, ASCX transformations allow you to call any type of inline code, including ASP.NET system methods, Kentico API or custom API.
  • For Text / XML transformations, you can also use general macro methods. See: Reference - Macro methods

Data loading

Method

Parameters

Description and examples

Eval

  • string columnName
  • bool encode

Loads the value from the specified column of the transformed object’s data. Returns the value as an object data type. Use only for ASCX transformations.

The optional boolean parameter specifies whether the method HTML encodes the loaded value. When not specified, the encoding depends on the value of the CMSHTMLEncodeEval web.config key (false by default).

<%# Eval(“NewsTitle”) %>
<%# Eval(“NewsTitle”, true) %>

Eval<ReturnType>

  • string columnName

Loads the value from a column of the transformed object’s data, and returns it as an object of the specified type. Use only for ASCX transformations.

<%# Eval<string>(“NodeAliasPath”) %>

EvalCDATA

  • string columnName
  • bool encapsulate

Loads the value from the specified column of the transformed object’s data and escapes all occurrences of the ]]> sequence in the returned string.

Depending on the optional boolean parameter (true by default), the method wraps the whole string in the <![CDATA[“wrapped text”]]> enclosure.

<%# EvalCDATA(“NewsText”) %>
<%# EvalCDATA(“NewsText”, true) %>

EvalJSString

  • string columnName

Loads the value from the specified column of the transformed object’s data. Encodes the returned text to be used in JavaScript code and encapsulates it into ’ characters.

GetEditableValue

  • string controlId

Loads the content of an editable region on the page. Specify the region using the control ID (web part control ID).

<%# GetEditableValue(“mainText”) %>

GetNotEmpty

  • object columnsOjb

Returns the value of the first data column that is not empty or null. The parameter must provide a list of column names separated by semicolons.

<%# GetNotEmpty(“FullName;UserName”) %>

GetColumnName

  • string columns
  • bool allowEmptyColumn

Returns the value of the first column that is present in the data of the transformed object. The parameter must provide a list of column names separated by semicolons.

By default, the method only returns columns that are not null or empty. Set the optional second parameter to true to allow empty values.

Property

Description and examples

DataItem

Gets the currently transformed data item.

<%# DataItem %>

DataItemIndex

Gets the data item index for the current transformation container. You have to use Container.DataItemIndex to get the index in the current binding context.

<%# DataItemIndex %>

DataItemCount

Gets the total number of data items in the current transformation container.

<%# DataItemCount %>

DataRowView

Gets a DataRowView of the transformed record’s data.

<%# DataRowView[“UserName”] %>

DisplayIndex

Gets the current position of the data item as displayed in a control.

<%# DisplayIndex %>

DocumentCustomData

Gets the value of custom page data fields (culture specific). Use the [“nodename”] notation to retrieve data stored in the specified node of the XML.

See also: Storing custom data for all page types

<%# DocumentCustomData[“myproperty”] %>

EditableItems

Gets the content of the specified editable region on the page.

<%# EditableItems[“mainText”] %>

NodeCustomData

Gets the value of custom page data fields (shared for all culture versions). Use the [“nodename”] notation to retrieve data stored in the specified node of the XML.

See also: Storing custom data for all page types

<%# NodeCustomData[“myproperty”] %>

> Back to the list of transformation method categories

Boolean operations

Method

Parameters

Description and examples

If

  • object value
  • object trueResult
  • object falseResult

Returns a result according to the boolean value of the first parameter.

<%# If(Eval(“IsSecuredNode”), “The page requires authentication”, “The page is publicly available”) %>

IfCompare

  • object value
  • object comparableValue
  • object falseResult
  • object trueResult

Compares the values of the first and the second parameter.

  • If the parameters are different or are both null, the method returns the third parameter.
  • If the parameters are equal, the fourth parameter is returned.

<%# IfCompare(1, 2, “The values are different”, “The values are equal”) %>

IfEmpty

  • object value
  • object emptyResult
  • object nonEmptyResult

Checks for emptiness of the value in the first parameter.

  • If the first parameter is null, the method returns the second parameter.
  • If the first parameter is not null, the third parameter is returned.

<%# IfEmpty(Eval(“ProductPhoto”), “No image”, GetImage(“ProductPhoto”)) %>

IfTrue

  • object value
  • object trueResult

Checks whether the first parameter contains a true boolean value.

  • If true, the method returns the second parameter.
  • If false, an empty string is returned.

IsFirst

-

Returns a true value if the transformed data item is the first in the provided data.

<%# IsFirst() %>

IsLast

-

Returns a true value if the transformed data item is the last in the provided data.

<%# IsLast() %>

IsCurrentDocument

-

Returns a true value if the transformed page is equal to the page where the transformation is being displayed.

<%# IsCurrentDocument() %>

IsDocumentOnSelectedPath

-

Returns a true value if the transformed page is present on the alias path of the page where the transformation is being displayed (i.e. if the transformed page is an ancestor of the current page).

<%# IsDocumentOnSelectedPath() %>

> Back to the list of transformation method categories

Method

Parameters

Description and examples

GetAbsoluteUrl

  • string relativeUrl
  • int siteId
  • object siteNameObj
  • string domainName

Converts relative URLs to absolute URLs. You can specify the target domain name in the absolute URL using either a site ID, site code name or explicitly.

If you leave all optional parameters empty, the method generates the absolute URL using the domain of the current site.

<%# GetAbsoluteUrl(“~/Home.aspx”) %>
<%# GetAbsoluteUrl(“~/Home.aspx”, Eval<int>(“NodeSiteID”)) %>

GetAttachmentIcon

  • object attachmentGuidColumn

Returns the attachment file type icon according to the extension of the file identified by the given GUID column.

<%# GetAttachmentIcon(“AttachmentGUID”) %>

GetAttachmentUrl

  • string attachmentFileName
  • string nodeAliasPath

Returns the URL of the attachment file specified by name in the first parameter, loaded from the page whose alias path matches the second parameter.

The method returns the same URL as the GetFileUrl method, but without loading the whole page, which results in better performance.

<%# GetAttachmentUrl(Eval<string>(“AttachmentName”), Eval<string>(“NodeAliasPath”)) %>

GetDocumentLink

  • bool encodeName

Returns a HTML link (<a> tag) that leads to the transformed page. By default, the method HTML encodes the page name in the link title. Set the optional parameter to false to disable the encoding.

<%# GetDocumentLink() %>
<%# GetDocumentLink(false) %>

GetDocumentUrl

  • object documentIdObj

Returns the URL of the specified page. If called without parameters, the method returns the URL of the transformed page. You can optionally specify the page using a page ID.

<%# GetDocumentUrl() %>
<%# GetDocumentUrl(Eval(“DocumentID”)) %>

Note: The overload with the document ID parameter is not available as a macro method for Text / XML transformations. Instead, use: {% GetDocumentUrlByID(DocumentID) %}

GetDocumentUrl

  • object nodeGuidColumn
  • object nodeAlias

Returns a permanent URL of the specified page (with the NodeGUID in the query string).

<%# GetDocumentUrl(Eval(“NodeGUID”), Eval(“NodeAlias”)) %>

GetFileIcon

  • object fileExtension

Returns the file type icon according to the specified extension.

<%# GetFileIcon(Eval(“FileExtension”)) %>

GetFileUrl

  • object attachmentFileName
  • object attachmentDocumentId

Returns the URL of the attachment file specified by name in the first parameter, loaded from the page whose ID matches the second parameter.

<%# GetFileUrl(Eval(“AttachmentFileName”), Eval(“AttachmentDocumentID”)) %>

GetFileUrl

  • object attachmentGuid
  • string fileName

Returns the URL of the attachment file, specified by an attachment GUID.

<%# GetFileUrl(“ProductPhoto”) %>

GetForumPostUrl

  • object postIDPath
  • object fourmID

Returns the URL of the forum post specified by the path in the first parameter, from the forum specified by the identifier in the second parameter.

<%# GetForumPostUrl(Eval(“PostIDPath”), Eval(“ForumID”)) %>

GetMediaFileUrl

  • object fileGUID
  • object fileName

Returns the URL of the specified media file. The media file is specified by the file GUID in the first parameter and the file name in the second parameter.

<%# GetMediaFileUrl(Eval(“FileGUID”) ,Eval(“FileName”)) %>

GetMetaFileUrl

  • object fileGUID
  • object fileName

Returns the URL of the specified meta file. The file is specified by the file GUID in the first parameter and the file name in the second parameter.

GetProductUrl

  • object skuId

Returns the URL of the product specified by an identifier (primary key).

<%# GetProductUrl(Eval(“SKUID”)) %>

GetProductUrl

  • object skuGUID
  • object skuName
  • object siteName

Returns the URL of the product specified by the GUID in the first parameter, SKU name in the second parameter.

<%# GetProductUrl(Eval(“SKUGUID”), Eval(“SKUName”), Eval(“SiteName”) %>

GetUrl

  • object aliasPath
  • object urlPath
  • object siteName

Returns the URL of the page specified by the alias path in the first parameter or the URL path in the second parameter.

<%# GetUrl(Eval(“NodeAliasPath”), Eval(“DocumentUrlPath”)) %>
<%# GetUrl(Eval(“NodeAliasPath”), Eval(“DocumentUrlPath”), Eval(“SiteName”)) %>

> Back to the list of transformation method categories

Text manipulation

Method

Parameters

Description and examples

EnsureMaximumLineLength

  • object textObj
  • int maxLength

Allows you to insert line breaks into long sequences of characters without whitespace (such as URLs). The method places the line break after the number of characters specified by the second parameter.

<%# EnsureMaximumLineLength(“VeryLongStringWithoutAnyBlankSpaces”, 21) %>

HTMLEncode

  • string text

Encodes HTML tags in the specified text.

<%# HTMLEncode(“Sample text <br />”) %>

LimitLength

  • object textObj
  • int maxLength
  • string padString
  • bool wholeWords

Limits text to the length specified in the second parameter. The third parameter is the trimming suffix, i.e. the string appended to the end of shortened strings. The suffix is included in the maximum length. For example, if you use the “…” suffix and a maximum length of 100 characters, the returned string contains the first 97 characters of the original string, followed by an ellipsis.

Set the last parameter to true to avoid trimming in the middle of words.

<%# LimitLength(“Example of long text”, 10 , “…”, true) %>

Localize

  • object text

Resolves all localization expressions inside the specified text.

RemoveDiscussionMacros

  • object inputText

Removes all BBCode tags from the provided text.

<%# RemoveDiscussionMacros(“[quote]Sample text[/quote]”) %>

RemoveDynamicControls

  • object inputText

Removes all controls from the specified text (such as inline widgets).

<%# RemoveDynamicControls(Eval(“NewsText”) ) %>

StripTags

  • object inputText

Completely removes HTML tags from the specified text.

<%# StripTags(“Sample text <br />”) %>

> Back to the list of transformation method categories

Images

Method

Parameters

Description and examples

GetEditableImage

  • string controlId
  • object maxSideSize
  • object width
  • object height
  • object alt

Returns an image tag that displays the content of an editable image control or web part on the page. Specify the editable image using the control ID (web part control ID).

<%# GetEditableValue(“mainImage”) %>

GetEditableImageUrl

  • string controlId

Returns the URL of the image selected inside the specified editable image control or web part. Specify the editable image using the control ID (web part control ID).

<%# GetEditableImageUrl(“mainImage”) %>

GetImage

  • object attachmentGuidColumn
  • object (int) maxSideSize
  • object (int) width
  • object (int) height
  • object alt

Returns an image tag that displays the image file whose GUID is stored in the specified column of the transformed object’s data.

<%# GetImage(“NewsTeaser”) %>
<%# GetImage(“NewsTeaser”, 200) %>
<%# GetImage(“NewsTeaser”, 200, 100) %>
<%# GetImage(“NewsTeaser”, 200, 200, 100) %>
<%# GetImage(“NewsTeaser”, 200, 200, 100, “image alternate text”) %>

GetImageByUrl

  • object imageUrl
  • object (int) maxSideSize
  • object (int) width
  • object (int) height
  • object alt

Returns an image tag that displays the image stored under the specified URL.

<%# GetImageByUrl(“~/Images/Image1.aspx”) %>
<%# GetImageByUrl(“~/Images/Image1.aspx”, 100, 200) %>
<%# GetImageByUrl(“~/Images/Image1.aspx”, 200) %>
<%# GetImageByUrl(“~/Images/Image1.aspx”, 200, 100, 200, “image alternate text”) %>

IfImage

  • object attachmentGuidColumn
  • object isImage
  • object notImage

Checks whether the page attachment specified by the GUID in the first parameter is an image file. If the file is an image, the method returns the value of the second parameter, otherwise the value of the third parameter.

<%# IfImage(“NewsTeaser”, “The file is an image”, “The file is not an image”) %>

> Back to the list of transformation method categories

Membership and community

Method

Parameters

Description and examples

GetAge

  • object dateOfBirth
  • string unknownAge

Returns age calculated according to the date of birth given in the first parameter. If the date of birth is not available, the method returns the string specified in the second parameter.

<%# GetAge(Eval(“UserDateOfBirth”),“Unknown age”) %>

GetBadgeImage

  • int badgeId

Returns an image tag that displays the specified user badge.

<%# GetBadgeImage(Eval<int>(“UserBadgeID”)) %>

GetBadgeName

  • int badgeId

Returns the display name of the specified badge.

<%# GetBadgeName(Eval<int>(“UserBadgeID”)) %>

GetGender

  • object genderObj

Returns the gender of users according to the value specified in the parameter. Load the value from the user’s gender field.

  • 1 = Male
  • 2 = Female
  • unspecified (0) = N/A

<%# GetGender(Eval(“UserGender”)) %>

GetGroupAvatarImage

  • object avatarId
  • int maxSideSize
  • int width
  • int heigth
  • object alt

Returns an image tag that displays the avatar of a group. The group is either identified automatically using the AvatarGuid field of the transformed group, or you can optionally specify an identifier value using the first parameter.

<%# GetGroupAvatarImage(200, “Alternate text”) %>
<%# GetGroupAvatarImage(Eval(“GroupAvatarID”), 200, “Alternate text”) %>
<%# GetGroupAvatarImage(Eval(“GroupAvatarID”), 200, 150, 150, “Alternate text”) %>

GetGroupProfileUrl

  • object groupNameOjb
  • string siteName

Returns the URL of the specified group’s profile page.

<%# GetGroupProfileUrl(Eval(“GroupName”) %>

GetMemberProfileUrl

  • object memberNameObj
  • string siteName

Returns the URL of the user profile page for the specified group member.

<%# GetMemberProfileUrl(Eval(“UserName”)) %>

GetUserAvatarImage

  • object avatarId
  • object userId
  • int maxSideSize
  • int width
  • int heigth
  • object alt

Returns an image tag that displays the avatar of a user. The user is either identified automatically using the AvatarGuid field of the transformed user, or you can specify either an avatar identifier or user identifier.

<%# GetUserAvatarImage(200, “Alternate text”) %>
<%# GetUserAvatarImage(Eval(“UserID”), 200, 150, 150, “Alternate text”) %>
<%# GetUserAvatarImage(Eval(“UserAvatarID”), Eval(“UserID”), 200, “Alternate text”) %>
<%# GetUserAvatarImage(Eval(“UserAvatarID”), Eval(“UserID”), 200, 150, 150, “Alt”) %>

GetUserAvatarImageUrl

  • object avatarId
  • object userId
  • string userEmail
  • int maxSideSize
  • int width
  • int heigth

Returns the URL of the specified user’s avatar image. If the user does not have an avatar, the method returns the URL of the default avatar image.

<%# GetUserAvatarImageUrl(Eval(“UserAvatarID”), Eval(“UserID”), 200, 150, 150) %>

GetUserFullName

  • int userId

Returns the full name of the specified user.

<%# GetUserFullName(Eval<int>(“UserID”)) %>

GetUserProfileUrl

  • object userNameObj
  • string siteName

Returns the URL of the user profile page for the specified user.

<%# GetUserProfileURL(Eval(“UserName”)) %>

TrimSitePrefix

  • object userName

Removes the site prefix from user names (if site prefixes are enabled in Settings -> Security & Membership -> Use site prefix for user names).

> Back to the list of transformation method categories

Date & time

Method

Parameters

Description and examples

FormatDate

  • object dateTime

Displays the specified date without the time component. The method automatically formats the date according to the current culture.

<%# FormatDate(DateTime.Now) %>

FormatDateTime

  • object dateTime
  • string format

Displays the date and time value according to a format string. The method formats the date and time according to the current culture.

<%# FormatDateTime(DateTime.Now, “MM/dd/yyyy HH:mm”) %>

GetDate

  • string dateTimeField

Loads a date value from the specified field of the transformed object’s data.

<%# GetDate(“NewsReleaseDate”) %>

GetDateTime

  • string dateTimeField
    OR
  • object dateTime
    OR
  • DateTime dateTime
  • string format

Loads a date and time value from the specified field of the transformed object’s data. The value uses the time zone set for the server.

Optionally, you can format the date and time value according to a format string.

<%# GetDateTime(“NewsReleaseDate”) %>

GetCustomDateTime

  • object dateTime
  • string timeZoneName

Converts a date and time value to the specified time zone.

<%# GetCustomDateTime(DateTime.Now, “GreenwichMeanTime”) %>

GetDateTimeString

  • object dateTime
  • bool showTooltip

Converts the specified date and time value to the time zone set for the server. The second parameter determines whether the displayed date and time has a tooltip.

<%# GetDateTimeString(“NewsReleaseDate”, true) %>

GetSiteDateTime

  • object dateTime

Converts the specified date and time value to the current site’s time zone.

<%# GetSiteDateTime(Eval(“NewsReleaseDate”)) %>

GetUserDateTime

  • object dateTime

Converts the specified date and time value to the time zone set for the user viewing the page.

<%# GetUserDateTime(Eval(“NewsReleaseDate”)) %>

> Back to the list of transformation method categories

See Setting up search on your website for more information.

Method

Parameters

Description and examples

SearchResultUrl

  • bool absolute

Returns the URL of the page containing the details of the search result. The optional parameter indicates if the returned URL is absolute.
<%# SearchResultUrl(true) %>

SearchHighlight

  • string text
  • string startTag
  • string endTag

Wraps the text of the first parameter into the tags specified by the other two parameters.

<%# SearchHighlight(SearchResultUrl(),“<strong>”,“</strong>”)%>

GetSearchImageUrl

  • string noImageUrl
  • int maxSideSize

Returns the URL of the current search result’s image.

The first parameter specifies the URL used if no image is found – enter either the full relative path starting from the application root (~/), or a partial path starting from the ~/App_Themes/<skin_folder>/Images/ directory. The second parameter specifies the maximum side size to which the method resizes the image.

<%# GetSearchImageUrl(“~/App_Themes/Default/Images/CMSModules/CMS_SmartSearch/no_image.gif”, 90) %>

<%# GetSearchImageUrl(“/CMSModules/CMS_SmartSearch/no_image.gif”, 90) %>

GetSearchValue

  • string columnName

Returns the value of the specified field for the current search result. Allows you to access both the general fields of the given objects type (page, custom table etc.) and any other fields included in the search index.

<%# GetSearchValue(“DocumentName”) %>

GetSearchedContent

  • string content

Parses the searched content as XML if required, and removes dynamic controls and macro expressions.

> Back to the list of transformation method categories

Syndication (RSS, Atom, XML)

Method

Parameters

Description and examples

GetAtomDateTime

  • object dateTime

Returns the specified date and time value in a format suitable for Atom feeds (according to RFC 3339).

<%# GetAtomDateTime(Eval(“DocumentCreatedWhen”)) %>

GetRSSDateTime

  • object dateTime

Returns the specified date and time value in a format suitable for RSS feeds (according to RFC 882).

<%# GetRSSDateTime(Eval(“DocumentCreatedWhen”)) %>

GetBlogCommentUrlForFeed

  • object documentIdObj

Returns the URL of the comments added to the blog post specified by a page identifier. Includes the feed query string parameter in the URL.

<%# GetBlogCommentUrlForFeed(Eval(“DocumentID”)) %>

GetDocumentUrlForFeed

-

Returns the URL of the transformed document with the feed query string parameter in the URL. The method takes the feed name from the Feed name property of the syndication web part used to generate the feed.

Note: Since the method adds the feed query string parameter, please use a different parameter name in the Feed querystring key property of the syndication web part.

<%# GetDocumentUrlForFeed() %>

GetForumPostUrlForFeed

  • object postIDPath
  • object forumId

 Returns the URL of the forum post specified by the path in the first parameter and the forum identifier in the second parameter. Includes the feed query string parameter in the URL.

<%# GetForumPostUrlForFeed(Eval(“PostIDPath”), Eval(“PostForumID”)) %>

GetMediaFileUrlForFeed

  • object fileGUID
  • object fileName

Returns the URL of the media file specified by the GUID in the first parameter and the file name in the second parameter. Includes the feed query string parameter in the URL.

<%# GetMediaFileUrlForFeed(Eval(“FileGUID”), Eval(“FileName”)) %>

GetMessageBoardUrlForFeed

  • object documentIdObj

Returns the URL of the message board specified by the identifier of the page containing the message board. Includes the feed query string parameter in the URL.

<%# GetMessageBoardUrlForFeed(“DocumentIdObj”) %>

GetProductUrlForFeed

  • object skuGUID
  • object skuName
  • object siteName

Returns the URL of the specified product with the feed query string parameter in the URL. The product is specified by the SKU GUID in the first parameter and SKU name in the second parameter. The site name provided in the last parameter ensures that the correct domain is used in the returned URL.

<%# GetProductUrlForFeed(Eval(“SKUGUID”),Eval(“SKUName”),Eval(“SiteName”)) %>

> Back to the list of transformation method categories

Microsoft SharePoint

Method

Parameters

Description and examples

GetSharePointFileUrl

OR

GetSPFileUrl

  • string server
  • string name

Returns the URL of the specified page or picture from the SharePoint server. The first parameter is the SharePoint server URL, the second one is the path and name of the page to download.

<%# GetSharePointFileUrl(“server”, SharePointFunctions.SplitSharePointField((string)Eval(“ows_FileRef”), 1)) %>

SplitSharePointField

OR

SplitSPField

  • string value
  • int index

Helper function for splitting combined fields returned by SharePoint.

For example, ows_LastModified=“1;#2009-03-17T10:32:17Z”. The first parameter is the original combined field, the second is the index of the returned part.

<%# SplitSharePointField((string)Eval(“ows_FileRef”), 1)) %>

> Back to the list of transformation method categories

Placeholders for sublevels in hierarchical data

If you are writing transformations for items from a hierarchical data source (for example page data from the Universal viewer web part), you can add a placeholder that sets the position of sublevels:

For ASCX transformations:




<cms:SubLevelPlaceHolder runat="server" ID="plcSub" />

For Text transformations:




{^SubLevelPlaceHolder^}

When displaying items that have descendants in the hierarchy, the placeholder is replaced by the child level under the given item. If you do not add the sublevel placeholder, the system automatically renders child levels after the code of parent items.

You can use the sublevel placeholder in hierarchical transformations, as well as standard transformations applied to hierarchical data.

Note: The sublevel placeholder only works if the Hierarchical display mode property of the viewer web part is set to Inner.

> Back to the list of transformation method categories

Editing buttons for pages displayed by listing web parts

You can configure listing web parts (such as the Repeater) to display special buttons in editing mode (on the Page tab of the Pages application). The buttons allow users to edit or delete individual items displayed in the list.

To set the exact position of the editing buttons, add the following expression into the code of ASCX item transformations:




##editbuttons##

> Back to the list of transformation method categories