Template Settings

Settings let the user generating a document change what it contains without editing the Template. A Draft summary might offer a "Include Forms?" tick box, or a choice of the order to list Forms in.

Settings are defined on the Settings tab of the Document Template editor. Each one becomes a control in the generation dialog, and its value arrives in the Template through the settings dictionary.

Defining a Setting

Each row on the Settings tab describes one control:

Column	Meaning
Name	The key used to read the value inside the Template, e.g. `settings.get("form_order")`. Required, and must be unique within the Template. Case is preserved, so a Setting named `Form_Order` must be read as `Form_Order`.
Display Name	The label shown next to the control in the generation dialog. Required, and must be unique within the Template. This is not the name used in the Template — see Name and Display Name.
Description	Help text shown with the control, to explain to the user what the Setting does.
Type	One of Boolean, Text or Choice. See Setting Types below.
Possible Values	For Choice Settings only, the comma separated list of options to offer.
Default	The value used when the user does not change the control.

Setting Types

The type decides both the control the user is offered and the Python type the Template receives.

Type

Control

Value in the Template

Boolean

A tick box

A real Python True or False, so it can be tested directly:

{% if settings.get("do_forms") %}...{% endif %}

The Default must be True or False.

Text

A text box

A string, empty rather than missing when the user clears the box:

<para>{{ settings.get("preamble") }}</para>

Choice

A drop-down of the Possible Values

The chosen option as a string, with surrounding spaces removed:

{% for form in draft.als_forms_set.all().order_by(settings.get("form_order")) %}

Possible Values is required, and any Default must be one of them.

Reading Settings in a Template

settings is an ordinary Python dictionary keyed by the Setting's Name:

Ordered by: {{ settings.get("form_order") }}
{% if settings.get("do_forms") %}
    {% for form in draft.als_forms_set.all().order_by(settings.get("form_order")) %}
    <heading level="2">{{ form.DraftFormName }}</heading>
    {% endfor %}
{% endif %}

Every Setting defined on the Template is always present in the dictionary. If the user does not change a control, its Default is used, so there is no need to supply a fallback for the ordinary case:

{# Both work, but the Default has already been applied — the "Ordinal" here is never reached #}
{{ settings.get("form_order", "Ordinal") }}
{{ settings.get("form_order") }}

A second argument to get() is still worth having if you want a Template to survive a Setting being renamed or removed, because a name that is not defined is simply absent:

{{ settings.get("subtitle", "") }}

Note

Settings are shared by every scope. A Draft Object List Template reads its Settings exactly as a Draft Home Template does.

Name and Display Name

The two are easy to confuse because the generation dialog only ever shows the Display Name.

Display Name is what the user sees — "Order forms by".
Name is what the Template reads — form_order.

Reading a Setting by its Display Name finds nothing. It does not fail: get() returns Python's None for a key that is not there, and the document ends up with the word "None" printed in it rather than the value or a blank:

{{ settings.get("Order forms by") }}   {# prints "None" #}
{{ settings.get("form_order") }}       {# the value the user chose #}

Passing a fallback as the second argument turns that into something a reader can act on:

{{ settings.get("Order forms by", "") }}

Choosing a Name that looks like a variable, and a Display Name written for a reader, keeps the two apart.

Note

The same names are used when generating documents through the API, where Settings are supplied by Name. See Generating Document Templates via the API.

Testing Settings

The Test tab of the Document Template editor offers no Setting controls: it runs the Template with the saved Default of every Setting. To exercise the other branches of a Template, either save a different Default temporarily, or generate the document from the page it belongs to, where the user controls are offered.