Logo Docs
Logo Docs

DT_CHOICES

This function is only useful as value to the choices: parameter of the @PICK_ONE_QUESTION and @PICK_MANY_QUESTION actions.

Generate a list of choices from a data table to display in the question.

The variable of the @PICK_ONE_QUESTION or @PICK_MANY_QUESTION action will contain the entire row of the data table. See “More information” below.

Usage

DT_CHOICES(table_identifier, code_for_choice)

Parameters

table_identifier

(Required) The identifier of the data table to use
code_for_choice

(Code) This is a special parameter. It is evaluated for each row of the data table. Each result is used as the displayed choice for that row. If not provided, the first column of the data table will be used. See “More information” below.

More information

The second parameter of DT_CHOICES is special:

  • It’s code that will be evaluated for each row in the data table
  • The result of each execution will be shown as a choice when filling the form to generate a document
  • To access the values of the columns for the current row, use their identifier with a dot (.) as a prefix
  • Since this happens before you filled the form, normal variables are not available
  • You can use any function

Here is a full example:

<# @PICK_ONE_QUESTION(assignee,
label: "Assignee",
choices: DT_CHOICES("employees", CONCAT(.first_name, " ", .last_name))) #>

This will provide choices based on the data table employees. The choices displayed in the form will be the “first_name last_name”, such as “Anna Logwatch”. This requires the data table to have columns with identifiers first_name and last_name.

When generating, the value of the variable assignee (set by the @PICK_ONE_QUESTION above) will be the whole row of the data table. To use values from that row, there are 2 options:

  1. Use a dot (.) and the identifier of the column.
  2. Use a dot and parentheses (.() to execute code similarly to DT_CHOICES’s second parameter. Between the parentheses, you can use any column with its identifier prefixed by a dot (.).

An example of each:

If you have questions, contact: <# UPPER(assignee.first_name) #> at <# assignee.email #>.

If you have questions, contact: <# assignee.(UPPER(.first_name) & " at " & .email)) #>.

Both have the same result, here it is for the choice “Anna Logwatch”:

If you have questions, contact: ANNA at [email protected] #>.

You can find more examples of using the dot and parentheses (.() in the “Operator . (dot)” documentation.

See also