---
title: Writing transformations for macros
---
> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).
Transformations are pieces of code that define how raw data is structured into output (HTML). They serve as reusable templates which you can apply to data within [macro expressions](https://docs.kentico.com/13/macro-expressions.md). When the system resolves such macros, transformations convert the data of objects or entire collections into corresponding output code.
The purpose of transformations is to help users format data in the following types of macro-based HTML content:
- [Email templates](https://docs.kentico.com/13/configuring-xperience/managing-email-templates.md) that define the content of system emails and notifications
- [E-commerce invoices](https://docs.kentico.com/13/e-commerce-features/configuring-on-line-stores/configuring-invoices.md)
- [Marketing email templates](https://docs.kentico.com/13/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/configuring-email-marketing/preparing-email-templates.md)
## Managing transformations
Create and edit transformations via [Page types](https://docs.kentico.com/13/developing-websites/defining-website-content-structure/managing-page-types.md).
1. Open the **Page types** application
2. Edit a page type
3. Select the **Transformations** tab.
4. Click **New transformation** or edit an existing transformation.
5. Enter the **Transformation name**.
- Transformation names cannot contain the period '.' character, which is used as a separator in the full transformation name.
6. Write the transformation's code.
- The standard transformation type is **Text / XML** – the code is basic HTML with support for macro expressions and methods to insert dynamic values into the content.
- To access the fields of the transformed data object, use expressions in format: _{% ColumnName %}_
> **Info:** If a field of the transformed data object contains characters that conflict with the [macro syntax](https://docs.kentico.com/13/macro-expressions/macro-syntax.md), use the _DataItem_ macro object and indexing to access the field value.
>
> For example: _{% DataItem\["column-name"] %}_
- The **HTML** transformation type works the same way as _Text/XML_ transformations, but you edit the content through the [WYSIWYG editor](https://docs.kentico.com/13/configuring-xperience/configuring-the-environment-for-content-editors/configuring-the-editor-for-rich-text-fields.md). The editor shows the rendered output of the transformation's HTML code.
7. Click **Save**.
The transformation can now be applied within macros.
> **Tip:** **Tip**: You can create "container" [page types](https://docs.kentico.com/13/developing-websites/defining-website-content-structure/managing-page-types/creating-page-types-without-fields.md) that do not represent actual pages on the website, but only hold transformations.
## Applying transformations
To apply transformations inside macros, call the **ApplyTransformation** macro method.
```csharp
ApplyTransformation("Ecommerce.Transformations.Address")
```
The parameter must match the full name of the transformation that you wish to use. The full name that identifies transformations is in format:\
_**.**_
An advanced versions of the method with three parameters is also available, which allows you to specify a header and footer transformation (i.e. add additional content before and after the displayed data).
```csharp
ApplyTransformation(transformationName, contentBeforeTransformationName, contentAfterTransformationName)
```
You can call the _ApplyTransformation_ method for collections of objects that implement the _IEnumerable_ interface, or for single instances of an object. When the system resolves such macro expressions, they return the objects of the given collection, formatted into the output code defined by the transformation.
## Transformation example
The following is the code of basic transformations that display product items from an [E-commerce order](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/orders.md) in a table, for example in order notification emails sent to customers.
```xml title="Order item transformation"
| {% Localize(SKUName)|(encode)true %}
{% (CartItemText != "" ? " '" + CartItemText + "' " : "")|(encode)true %}
{% SKUNumber|(encode)true %} |
{% Units %} |
{% UnitPrice.Format(Currency.CurrencyFormatString)|(encode)true %} |
{% TotalPrice.Format(Currency.CurrencyFormatString)|(encode)true %} |
```
```xml title="Header transformation"
| Product name |
Units |
Unit price |
Subtotal |
```
```xml title="Footer transformation"
```
Within an [order notification email template](https://docs.kentico.com/13/e-commerce-features/configuring-on-line-stores/configuring-e-commerce-email-notifications.md), the transformations could be applied in the following way:
```csharp
{% ContentTable.ApplyTransformation("Ecommerce.Transformations.OrderItem", "Ecommerce.Transformations.OrderItemHeader", "Ecommerce.Transformations.OrderItemFooter") %}
```
When resolved for the data of an order, the output HTML of the email contains values returned for the given order. For example:
```xml title="HTML output"
| Product name |
Units |
Unit price |
Subtotal |
| Panama Los Lajones Honey (2 lb) CO-PAN-LAJONES-2-lb |
2 |
$38.00 |
$76.00 |
| Mazzer Super Jolly DR MAZ-GR-JOLLY |
1 |
$674.90 |
$674.90 |
```