Formulas

Formulas are an easy way of quickly inserting an expression in your template. They don't offer the same flexibility as pseudo-fields, but they make up for it in ease-of-use.

Tip Not sure whether you need a formula or a pseudo-field? The difference is explained here.

Concept

Here's how you use formulas in Smart Flows:

Place the cursor where you want to insert the formula.
Select the Formula button.
Define the formula's value.

In step 2, you can use other fields' values so that your formula is actually a modification of other fields' values. For instance, you can use a formula for:

Calculating totals, subtotals and percentages.
Editing names in full caps (JOHN) to make them less shouty (John).
Defining a new constant value for use in your templates.

The possibilities are endless as you can combine all fields and all functions the template builder has to offer.

Creating a formula

To create a formula, follow these steps:

Place the cursor where you want the formula to appear in the template.

Select the Formula button in the ribbon.

Define your formula's value by editing the expression. For more information on how to edit expressions, please read this page.

Select OK to confirm the expression.

The XperiDo mapping window for this formula opens, asking you to define the formula's formatting. Change the settings if you want and select OK.

Your formula is now defined and mapped. By default, it will be named {Formula}.

Editing a formula

After you've created a formula, you can edit its expression or formatting by following these steps:

In the data set tab of the pane, select your formula and select Settings:

In the mapping window that opens, go to the General tab. To change the formula's value, select the pencil in the expression box:

This opens a window where you can change the formula's expression.

Select OK to confirm the expression, and then select OK to close the mapping window.

Understanding the Key Differences Between Formulas and Pseudo-Fields in Template Builder

The Template builder add-in gives you the possibility of using calculations/text editing functions in your templates. There are 2 ways of doing this:

By using a Formula
By using a Pseudo-field

Both these features allow the same calculations, but there are a few differences that you should know about.

Properties

Formulas are intended to provide a fast means for calculating something. They offer the same powerful expressions and functions as pseudo-fields, but they are a bit easier to insert. Pseudo-fields, on the other hand, are newly created fields in your data set, which can then be referred to later on. Setting them up takes a bit longer than setting up a formula, but because you define a field, you can use that in other calculations, or use it multiple times in your template.

Advantages

Formulas are fast to set up.
You can map pseudo-fields in different places in your document.
You can sort your loops on pseudo-fields that are defined in that loop.
You can refer to previously created pseudo-fields in further calculations.

Especially the last bit here is important: being able to refer to previously created pseudo-fields allows chain calculations, such as the following example:

Use multiple pseudo-fields to calculate multiple subtotals,
Calculate the sum of all those pseudo-fields in a new pseudo-field,
Subtract a customer discount from that sum and show it as the grand total by using another pseudo-field.

This is just one example that shows why pseudo-fields are useful, since you can't do this with formulas without defining the same calculations multiple times.

Suggested use

Use formulas when you only require one calculation that you won't need anywhere else - be it in your template or further calculations.
Use pseudo-fields when you want to re-use the calculated value in further calculations or when you want to use the calculated value in multiple places in your document.

How to use them

Inserting a formula

Place your cursor where you want to insert the formula,
Select the formula button in the ribbon,
Type in your expression or use the expression wizard,
Set your formula's formatting,
Select OK to finalize everything.

Inserting a pseudo-field

In the pane's data set tab, select the pseudo-field's parent field (the pseudo-field will be created as a child element of this field),
Select the Add pseudo-field button in the pane's data set tab,
Set your pseudo-field's settings, such as the name, the type and most importantly: the calculations,
Select OK. A new field has now been created under the selected parent field,
Place your cursor where you want to insert the pseudo-field,
Double-click the field in the pane's data set tab to insert the field in your template.

Editing a formula

In the pane's mapping tab, double-click the formula you want to edit. A window will pop up,
In this window, in the Field Selection section, hover over the value and select the pencil that appears,
This opens the expression editor where you can change your formula.

Editing a pseudo-field

In the pane's data set tab, select the pseudo-field you want to edit,
Select the Edit pseudo-field button in the pane's data set tab,
This opens the pseudo-field window which includes the expression editor where you can change your formula.