Writing transformations for macros

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. 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 that define the content of system emails and notifications
• E-commerce invoices
• Marketing email templates

Managing transformations

Create and edit transformations via Page types.

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 %}

     If a field of the transformed data object contains characters that conflict with the macro syntax, 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. The editor shows the rendered output of the transformation's HTML code.

7. Click Save.

The transformation can now be applied within macros.

Applying transformations

To apply transformations inside macros, call the ApplyTransformation macro method.

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:
<page type code name>.<transformation name>

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).

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 in a table, for example in order notification emails sent to customers.

<tr>
    <td style="text-align: left;">{% Localize(SKUName)|(encode)true %}
    {% (CartItemText != "" ? " '" + CartItemText + "' " : "")|(encode)true %}
    {% SKUNumber|(encode)true %}</td>
    <td style="text-align: right; vertical-align: top;">{% Units %}</td>
    <td style="text-align: right; vertical-align: top;">{% UnitPrice.Format(Currency.CurrencyFormatString)|(encode)true %}</td>
    <td style="text-align: right; vertical-align: top;">{% TotalPrice.Format(Currency.CurrencyFormatString)|(encode)true %}</td>
</tr>

<table class="productsList" width="100%" cellspacing="0" cellpadding="2" style="text-align: right">
  <thead>
    <tr>
      <th style="text-align: left; padding-top: 21px;">Product name</th>
      <th style="text-align: right; padding: 21px 2px 2px 2px;">Units</th>
      <th style="text-align: right; padding-top: 21px;">Unit price</th>
      <th style="text-align: right; padding-top: 21px;">Subtotal</th>
    </tr>
  </thead>
  <tbody>

</tbody>
</table>

Within an order notification email template, the transformations could be applied in the following way:

{% 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:

<table class="productsList" width="100%" cellspacing="0" cellpadding="2" style="text-align: right">
    <thead>
      <tr>
        <th style="text-align: left; padding-top: 21px;">Product name</th>
        <th style="text-align: right; padding: 21px 2px 2px 2px;">Units</th>
        <th style="text-align: right; padding-top: 21px;">Unit price</th>
        <th style="text-align: right; padding-top: 21px;">Subtotal</th>
      </tr>
    </thead>
    <tbody>            
      <tr>
        <td style="text-align: left;">Panama Los Lajones Honey (2 lb) CO-PAN-LAJONES-2-lb</td>
        <td style="text-align: right; vertical-align: top;">2</td>
        <td style="text-align: right; vertical-align: top;">$38.00</td>
        <td style="text-align: right; vertical-align: top;">$76.00</td>
      </tr>
      <tr>
        <td style="text-align: left;">Mazzer Super Jolly DR MAZ-GR-JOLLY</td>
        <td style="text-align: right; vertical-align: top;">1</td>
        <td style="text-align: right; vertical-align: top;">$674.90</td>
        <td style="text-align: right; vertical-align: top;">$674.90</td>
      </tr>           
    </tbody>
</table>