Reference - Transformation methods

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

Data loading
Boolean operations
URLs and document links
Text manipulation
Images
Membership and community
Date & time
Smart search
Syndication (RSS, Atom, XML)
Microsoft SharePoint
Placeholders for sublevels in hierarchical data
Editing buttons for documents displayed by listing web parts

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 (true by default). <%# Eval(“NewsTitle”) %> <%# Eval(“NewsTitle”, false) %>
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 document 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 document types <%# DocumentCustomData[“myproperty”] %>
EditableItems	Gets the content of the specified editable region on the page. <%# EditableItems[“mainText”] %>
NodeCustomData	Gets the value of custom document 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 document 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 document requires authentication”, “The document 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 document is equal to the document where the transformation is being displayed. <%# IsCurrentDocument() %>
IsDocumentOnSelectedPath	-	Returns a true value if the transformed document is present on the alias path of the document where the transformation is being displayed (i.e. if the transformed document is an ancestor of the current document). <%# IsDocumentOnSelectedPath() %>

> Back to the list of transformation method categories

URLs and document links

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 document whose alias path matches the second parameter. The method returns the same URL as the GetFileUrl method, but without loading the whole document, 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 document. By default, the method HTML encodes the document 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 document. If called without parameters, the method returns the URL of the transformed document. You can optionally specify the document using a document 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 document (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 document 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 document 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 document 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

Smart search

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 (document, 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)

Microsoft SharePoint

Placeholders for sublevels in hierarchical data

If you are writing transformations for items from a hierarchical data source (for example document 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 documents 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

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 document 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 document 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”)) %>