Options
Tasks accept user configuration via options. Options are created dynamically, by reference: each option referenced in a task's code results in that option being added to the task's configuration form. In the option reference {{ options.foo_bar__required }}, the option key is foo_bar__required. The appearance and behavior of the option's form element is based on flags in in the option key – in this example, only the "required" flag is in use.
Mechanic flags provide only limited option validation. A task may define custom validation, by rendering error objects according to the task's its own validation logic.
Options are made available in the options variable, which is a hash having key-value pairs for each option key and option value. The option key must only contain ASCII numbers, lowercase letters, and underscores. The option key is reformatted for use as the option name presented to the user – underscores are replaced by spaces, and the entire line is sentence-cased.
{% action "echo", options.some_value_to_echo__required_multiline %}
Because option keys are registered via static analysis, options must each be referenced using a standard lookup (e.g. options.foobar) at least once.
Options are displayed to the user in the order in which they are first referenced in the task code.
Because this may not result in a natural sequence, it can be useful to prefix task code with a comment block, explicitly referencing each option so as to force the overall order.
{% comment %}Preferred option order:{{ options.foo }}{{ options.bar__required }}{{ options.baz__boolean }}{% endcomment %}
Option flags control how an option appears and behaves in a task's configuration form, and also control the type and format of the option value.
Most flags may be combined with other flags, for more nuanced control.
If no flags are used for an option, an option will be made available as a plain text field, and the option value will be a string.
Flag | Effect |
required | Requires the user to populate this option before the task can be saved |
boolean | Renders a checkbox; the option value is a boolean |
multiline | Renders a multiline text field; the option value is a string |
Renders a text field of type "email"; the option value is a string | |
number | Renders a text field of type "number", configured for value steps of 1; the option value is a number |
code | Renders a text field that's formatted for code; the option value is a string |
keyval | Renders a compound form element, allowing the user to provide zero or more key-value pairs; the option value is a hash, containing these key-value pairs |
array | Renders a compound form element, allowing the user to provide zero or more values; the option value is an array, containing these values |
Array options have a hidden feature: once the user-configured array reaches 5 elements in size, a new "Manage in bulk" button will appear for that option. Clicking it will open a modal which allows the user to manage the array's input using a single multiline text field, in which each line represents an array element. This is a convenient way to configure larger arrays.
Options that allow text input are evaluated for Liquid when a task processes an event. Liquid evaluation for options occurs before it occurs for task code, which means that any Liquid variables created by task code are not available to task options.
Liquid code in task options have access to the same set of environment variables that are made available to the task code, including event, shop, cache, and any event subject variables.
