Writing transformations

Transformations are a crucial part of the process used to display pages and other data in Kentico. A transformation is a code template that determines how listing web parts and controls render content. Data sources provide a collection of items containing raw data, and transformations convert the data into appropriately formatted page output code (HTML).

The functionality of transformations is very similar to that of item templates used by standard ASP.NET list controls, such as the Repeater. The main difference is that the system stores transformations as virtual objects in the database, and you can easily reuse transformations for different components.

Transformations are categorized under the objects whose data they display. You can manage transformations for:

Page types (Page types -> Edit a page type -> Transformations)
- Container page types do not represent actual objects on the website, but only serve as containers for transformations. Use container page types to store transformations that you want to share among multiple page types.
Custom tables (Custom tables -> Edit a table -> Transformations)

To assign transformations to listing web parts or controls, use the available Transformation properties. Transformations are supported by all data listing web parts, as well as by listing controls that are designed to work with Kentico pages. The full name that identifies transformations is in format <parent object code name>.<transformation name>.

Note that transformation names can not contain the dot '.' character. Including dots in transformation names could cause unwanted system behavior.

The Kentico sample sites include many transformations for all built-in page types.

Transformation types

You can use several different approaches when writing the code of transformations. The following transformation types are available:

Transformation type	Description
ASCX	The code of the transformation supports ASCX markup, i.e. the same syntax that you would use to edit standard web forms or user controls. This includes: Embedded controls (user controls or server controls, see the Writing transformations) Inline code (Kentico API, standard ASP.NET data binding expressions, special methods designed for use in transformations) To access the fields of the transformed page or custom table, use data binding expressions in format: <%# Eval("ColumnName") %> Notes For security reasons, only users who have the Edit ASCX code permission for the Design module may edit the code of ASCX transformations. This permission can only be assigned by users with the Global administrator privilege level. ASCX transformations need to be compiled, so you cannot create or edit them on precompiled applications. ASCX transformations do NOT support macro expressions. We do NOT recommend using web parts within the code of transformations. This could lead to poor performance and certain web parts may not work correctly within transformations due to their life cycle.
Text/XML	The system processes the code of Text/XML transformations as basic HTML. ASCX markup (controls or inline code) does not work. You can use Kentico macro expressions and methods to insert dynamic values into the content. To access the fields of the transformed page or custom table, use expressions in format: {% ColumnName %} Text transformations have the following advantages: No compilation required. You can create and edit text transformations even in environments where compilation of virtual objects is not possible, for example on precompiled websites. Text transformations do not allow users to execute inline code, so they cannot be used to compromise the security of the website.
HTML	Work the same way as Text/XML transformations, but you edit the content through the WYSIWYG editor. The editor shows the rendered output of the transformation's HTML code.
XSLT	Use XSL elements to render the data. The code must be in valid XML format. When creating XSLT transformations for displaying pages, set the match attribute of the <xsl:template> element to Table. XML `<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:output method="xml" omit-xml-declaration="yes" /> <xsl:template match="Table"> ... </xsl:template> </xsl:stylesheet>`
jQuery	Provide a way to define the jQuery templates used by: The Chat application Integrated Strands recommendations

ASCX

The code of the transformation supports ASCX markup, i.e. the same syntax that you would use to edit standard web forms or user controls. This includes:

Embedded controls (user controls or server controls, see the Writing transformations)
Inline code (Kentico API, standard ASP.NET data binding expressions, special methods designed for use in transformations)

To access the fields of the transformed page or custom table, use data binding expressions in format: <%# Eval("ColumnName") %>

Notes

For security reasons, only users who have the Edit ASCX code permission for the Design module may edit the code of ASCX transformations. This permission can only be assigned by users with the Global administrator privilege level.
ASCX transformations need to be compiled, so you cannot create or edit them on precompiled applications.
ASCX transformations do NOT support macro expressions.
We do NOT recommend using web parts within the code of transformations. This could lead to poor performance and certain web parts may not work correctly within transformations due to their life cycle.

Text/XML

The system processes the code of Text/XML transformations as basic HTML. ASCX markup (controls or inline code) does not work. You can use Kentico macro expressions and methods to insert dynamic values into the content.

To access the fields of the transformed page or custom table, use expressions in format: {% ColumnName %}

Text transformations have the following advantages:

No compilation required. You can create and edit text transformations even in environments where compilation of virtual objects is not possible, for example on precompiled websites.
Text transformations do not allow users to execute inline code, so they cannot be used to compromise the security of the website.

HTML

Work the same way as Text/XML transformations, but you edit the content through the WYSIWYG editor. The editor shows the rendered output of the transformation's HTML code.

XSLT

Use XSL elements to render the data. The code must be in valid XML format.

When creating XSLT transformations for displaying pages, set the match attribute of the <xsl:template> element to Table.

XML

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output method="xml" omit-xml-declaration="yes" />

<xsl:template match="Table">

...

</xsl:template>

</xsl:stylesheet>

jQuery

Provide a way to define the jQuery templates used by:

The Chat application
Integrated Strands recommendations

Writing transformations

Writing transformations

Transformation types

Transformation types

Transformation example

Adding CSS styles to transformations

Cookie consent

Transformation types

Transformation types

Transformation example

Adding CSS styles to transformations