---
title: Using transformations in macro expressions
related:
- https://docs.kentico.com/k8/macro-expressions.md
---
> 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).
You can apply [transformations](https://docs.kentico.com/k8/developing-websites/loading-and-displaying-data-on-websites/writing-transformations.md) of the **Text/XML** and **HTML** type to documents and other objects retrieved via [macro expressions](https://docs.kentico.com/k8/macro-expressions.md). Transformations in macro expressions allow you to display dynamically loaded data inside text and HTML content, where you cannot add [listing web parts or controls](https://docs.kentico.com/k8/developing-websites/loading-and-displaying-data-on-websites.md). Typical examples include:
- [E-mail templates](https://docs.kentico.com/k8/configuring-kentico/managing-e-mail-templates.md) that define the content of system e-mails
- [Newsletter templates](https://docs.kentico.com/k8/on-line-marketing-features/e-mail-marketing/working-with-newsletters/preparing-newsletter-templates.md)
You can also use transformations in all locations where macro resolving is supported.
To apply transformations to data inside macros, call the following macro method:
```csharp
ApplyTransformation(String transformationName)
```
The parameter must match the full name of the transformation that you wish to use. An overload with three parameters is also possible, which allows you to place additional transformations before and after the displayed data:
```csharp
ApplyTransformation(String transformationName, String contentBeforeTransformationName, String contentAfterTransformationName)
```
You can call the 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.
> **Note:** **Security considerations**
>
> When you save a macro expression, the system automatically adds a security signature. The signature is used to check access permissions for the data collections loaded by the expression. Macro security depends on the user who entered and saved the macro expression, not on the user viewing the resolved result.
>
> As a result, the system does not resolve macro expressions if their author does not have permissions to access the requested data.
>
> See also: [Working with macro signatures](https://docs.kentico.com/k8/macro-expressions/macro-troubleshooting/working-with-macro-signatures.md)
## Examples - transformations in macro expressions
- **Preparing the environment**
- [Using transformations in macro expressions](#displaying-the-current-user)
- [Using transformations in macro expressions](#displaying-documents-from-the-content-tree)
- [Using transformations in macro expressions](#retrieving-and-displaying-site-objects)
> **Info:** This scenario is intended primarily for demonstration purposes. The recommended way to display data on standard website pages is using [listing web parts or controls](https://docs.kentico.com/k8/developing-websites/loading-and-displaying-data-on-websites.md), which provide support for transformations.
### Preparing the environment
1. Open the **Pages** application and select the root of the website.
2. Click **New** ().
3. Select the **Page (menu item)** document type.
4. Type _Macros_ as the **Page name** and select the **Create a blank page** template option.
5. Click **Save** to create the page.
6. Switch to the **Design** tab of the new page and [add](https://docs.kentico.com/k8/developing-websites/developing-websites-using-the-portal-engine/using-and-configuring-web-parts.md) an **Editable text** web part.
You can now insert the macro expressions described below into the editable region on the document's **Page** tab. The system resolves the macros on the live versions of the page.
### Displaying the current user
First you need to create the transformation:
1. Open the **Document types** application.
2. **Edit** () the **Root** document type and open the **Transformations** tab.
3. Click **New transformation** and enter the following data:
- **Transformation name**: _UsersInText_
- **Transformation type**: _Text / XML_
- **Code**:
```html
```
4. Click **Save**.
Your transformation is now registered in the system. You can apply the transformation to user objects inside macro expressions:
1. Open the **Pages** application.
2. Edit the previously created _Macros_ document on the **Page** tab.
3. Enter the following expression into the editable region.
```csharp
{% CurrentUser.ApplyTransformation("CMS.Root.UsersInText") %}
```
4. Click **Save**.
The macro expression above retrieves an object containing the data of the user currently viewing the page, which is then formatted according to the specified transformation. You can view the page on the live website to see how the macro is resolved.
### Displaying documents from the content tree
First you need to create the transformation.
1. Open the **Document types** application.
2. **Edit** () the **Root** document type and open the **Transformations** tab.
3. Click **New transformation** and enter the following data:
- **Transformation name**: _NewsInText_
- **Transformation type**: _Text / XML_
- **Code**:
```html
```
4. Click **Save**.
Your transformation is now registered in the system. You can apply the transformation to collections of news documents inside macro expressions:
1. Open the **Pages** application.
2. Edit the previously created _Macros_ document on the **Page** tab.
3. Enter the following expression into the editable region.
```csharp
{% Documents["/News"].Children.WithAllData.ApplyTransformation("CMS.Root.NewsInText") %}
```
> **Info:** In the expression above, the document under the _/News_ path is selected from the **Documents** collection. Through its **Children** property, the system then accesses a collection containing all child documents. Using the **WithAllData** property ensures that the retrieved document objects include their coupled data, i.e. the specific fields defined for the given document type.
4. Click **Save**.
If you view the page on the live website, you can see how the macro is resolved.
### Retrieving and displaying site objects
In this example, you first need to create three separate _Text / XML_ transformations.
1. Open the **Document types** application.
2. **Edit** () the **Root** document type and open the **Transformations** tab.
3. Click **New transformation** and enter the following data:
- **Transformation name**: _ProductTableHeader_
- **Transformation type**: _Text / XML_
- **Code**:
```html
| Product name |
Price |
```
4. Click **Save**.
5. Reload the document type's **Transformations** tab.
6. Click **New transformation** and enter data for the second transformation:
- **Transformation name**: _ProductTableRow_
- **Transformation type**: _Text / XML_
- **Code**:
```html
| {% SKUName %} |
{% SKUPrice %} |
```
7. Click **Save**.
8. Reload the document type's **Transformations** tab again.
9. Click **New transformation** and enter data for the third transformation:
- **Transformation name**: _ProductTableFooter_
- **Transformation type**: _Text / XML_
- **Code**:
```html
```
10. Click **Save**.
All three transformations are now registered in the system. You can apply the transformation to collections of SKU objects (products) inside macro expressions:
1. Open the **Pages** application.
2. Edit the previously created _Macros_ document on the **Page** tab.
3. Enter the following expression into the editable region.
```html
{% SiteObjects.SKUs.Where("SKUDepartmentID = 4").OrderBy("SKUPrice").ApplyTransformation ("CMS.Root.ProductTableRow", "CMS.Root.ProductTableHeader", "CMS.Root.ProductTableFooter") %}
```
> **Info:** The system retrieves product objects (SKUs) from the **SiteObjects** collection. The **Where** macro method is then used to filter the collection according to a standard SQL condition specified as the parameter. In this case, only products from the Smartphones department are loaded. The **OrderBy** method sorts the objects according to the values in their **SKUPrice** field.
>
> You can apply the **Where** and **OrderBy** methods to all types of collections, including documents.
4. Click **Save**.
The **ApplyTransformation** method is called with additional parameters to add the header and footer transformations before and after the main data items. This ensures that the transformations are combined to achieve the desired result:
