Templates

Templates let you work with your data like a spreadsheet formula: filter lines, calculate new values, and build the names of fixtures, groups and layout rows from any field. prepare uses the Jinja2 template language.

You can use templates in these places:

Where	What the template does
Show Data → Filter	Shows only the lines for which the template is true.
Show Data → Edit Data	Calculates a new value for every selected line.
Create Patch / Update Patch → Set Name	The label of each fixture.
Sorted Groups / Sub-ID Groups → Set Name	The name of the groups of one level.
Sorted Groups / Sub-ID Groups → Set Grouping	With Group by: Template, the lines with the same result end up in one group.
Multi Layout → Set Grouping	One layout per result.
Straight Layout, FX Layout, Function ID FX → Set Grouping	One row per result.

Syntax

Form	Use it for
{{ expression }}	Insert a value, e.g. {{ short_type }}
{% if … %}…{% else %}…{% endif %}	Branches, e.g. {% if z > 2 %}High{% else %}Low{% endif %}
value | filter	Change a value, e.g. {{ position | upper }}. Useful filters: lower, upper, replace, round, join, length, map, max, min

The helpers abs, round, min, max, len, int, float and str are available in every template.

Typographic quotes (e.g. „Front” from a German keyboard) are converted automatically, so {{ position == „Front" }} works the same as {{ position == 'Front' }}.

Variables

Every field of a line is available by its name:

Variable	Field
id	Fixture ID
sub_id	Sub-fixture index
ma3_id	grandMA3 ID
ft_name	Model (symbol name)
universe, address	DMX patch
x, y, z	Position in meters
rotx, roty, rotz	Rotation in degrees
short_type	Model Short
func	Function
position	Position
function_id	Function ID
appearance	Appearance color
stage	Stage (grandMA3)
active, dummy	True or false
your custom fields	e.g. {{ truss_name }} — also available as user_fields['truss_name']

And some extras:

Variable	Description
line	The current line
lines	All lines
selected	The selected lines (Show Data)
i	Index of the current line, starting at 0
n	Number of lines (selected lines, if any)
name	The default name prepare would use (Set Name dialogs)
nr	The running number of the fixture (labels)
level	The hierarchy level of the group, starting at 0 (groups)
module	The module name of a multi-module fixture (groups and layouts)

In the Set Name dialog, open Available variables and click a badge to insert it. A live Preview below the editor shows the result for the first fixture, or the error if the template is broken. Leave the template empty to use the default name; Reset clears it.

Filters: true or false

A filter template has to result in true or false. A result counts as false if it is empty, False, 0, none, no, [] or {} — everything else is true.

{{ universe == 1 }}
{{ position == 'Front' and z > 2 }}
{{ short_type in ['LEDBar', 'Spot'] }}
{{ id >= 100 and id < 200 }}
{{ not dummy }}
{{ x < 0 }}
{{ 'key' in func | lower }}
{{ i % 3 == 0 }}
{{ x == (lines | map(attribute='x') | max) }}
{{ line in selected }}

Edit: calculating values

In the Edit Data dialog, every field accepts a template. It is calculated for every selected line and stored in the field:

• x, y, z and the rotations accept decimal commas (1,5).
• ID, universe, address and function ID are rounded to whole numbers.
• All other fields are stored as text.
• An empty result leaves the line unchanged.

{{ position }}_{{ short_type }}
{{ x * -1 }}
{{ i + 100 }}
{{ position | replace(' ', '_') | lower }}
{{ 1 + (i // 10) }}
{% if z > 2 %}High{% else %}Low{% endif %}

Everything is checked against the first line before anything is written. If the template has an error, nothing is changed.

Names: examples

The Set Name dialog has some Predefined templates to start with:

Template	Result
{{ position }} {{ short_type }} {{ func | replace(' ', '-') }} {{ nr }}	Stage Spot LX-1 1
{% if dummy %}D {% endif %}{{ position }} {{ short_type }} {{ nr }}	D Stage Spot 1 (for dummies)
{{ short_type }} {{ nr }}	Spot 1
{{ name | upper }}	The default name in uppercase
{{ position }} {{ short_type }}	Stage Spot (groups, layouts)
{{ short_type }} {{ func }}	Spot LX 1 (layouts)