@PICK_ONE_QUESTION

Specifies that a variable will be a value out of a list of choices.

Before generating a document, DocuMold will display a dropdown to choose the value.

Usage

<# @PICK_ONE_QUESTION(variable, **see parameters below**) #>

variable	(Required) The variable this applies to. Do not use double quotes (`"`) around it, just write it as a usage of the variable.
choices:	(Named, Required) The choices to display. Can be a list of values, a list of list of two values, or a DT_CHOICES. See “More information” below.
example_value:	(Named) The initial value in the form when preparing a template (via “Prepare a template”). If not given, the value of `initial_value` is used.
help_text:	(Named) Displays a clickable (?) bubble beside the label. Clicking it will reveal this text. Useful to give directions to the user of the DocuMold template.
initial_value:	(Named) The initial value in the form when using a template (via “Use a template”). This is also the default value of the `example_value` parameter.
label:	(Named) The text to display beside the dropdown box that asks for the value. Defaults to variable’s name.
optional:	(Named) Set this to `TRUE` to allow the user to pick no choices (value would then be `NOTHING`)
placeholder:	(Named) If specified, this is the text in the dropdown box when nothing is selected. Default is “Pick one”

Parameters with “Named” mean that you must specify the name of the parameter and a colon before its value. Ex: choices: "its value"

Example	Result
<# @PICK_ONE_QUESTION(country, label: “Country of the participants”, choices: [“Belgium”, “Canada”, “Other”]) #>
<# @PICK_ONE_QUESTION(listing_order, label: “Order of participants”, choices: [[“By name”, “name”], [“By age”, “age”]], help_text: “This is the order that the participants will be listed in”) #>
<# @PICK_ONE_QUESTION(employee, label: “Employee”, choices: DT_CHOICES(“employees”, CONCAT(.first_name, “ “, .last_name))) #>
<# @PICK_ONE_QUESTION(discount, label: “Discount to apply”, choices: [[“Student”, 0.1], [“Senior”, 0.15]]) #>

This action does nothing to the document itself; it gets erased when generating a document.

The choices can be:

A list of values: each value will be displayed as a choice, and that’s the value the variable will have.
A list of list of 2 values: Basically a list of pairs. For each pair, the first value is the text to display in the dropdown and the second value is the one the variable will have when this is selected. So [["By name", "name"], ["By age", "age"]] means the choices are By name and By age, and the variable will be set to either "name" or "age". This is useful to provide a clearer choice to the user, without having to write the longer text everywhere. Values can be non-text, such as numbers, dates, etc.
DT_CHOICES is a function that allows getting choices from a data table. See DT_CHOICES for more details.

If no value is selected in the form for this question, the variable will be set to NOTHING.

All @..._QUESTION actions are normally placed at the end of the template to avoid overwhelming unfamiliar users.

The @IF action has no effect on the @...QUESTION actions. The @...QUESTION actions have an effect even when they is hidden.