Task options

Every task script has access to an options object, which contains all of the merchant-configurable options for a task. This object can be referenced in the task script, and in the task's online store or order status JavaScript (if configured). For more on using options in Liquid, see The options object.

The simple act of referencing keys within this object – e.g. {{ options.foo }} – will cause Mechanic to make the referenced keys available to the merchant in an automatically-generated graphical form. In this way, we make it easy to generate merchant-friendly configuration, without having to do anything other than write the code you'd write anyway. (For a visualization of this, see Automatic options.)

Format

Option keys must only contain numbers, lowercase letters, and underscores.
Because option keys are registered via static analysis, option keys must each be used at least once within standard Liquid tags (e.g. {% assign foo = options.bar %} or {{ options.baz }}). Feel free to make dynamic use of them elsewhere (e.g. {% assign foo = options[bar] %}).

Flags

Mechanic supports several flags, which control what sort of data merchants may provide. Depending on the flags used for a specific options variable, Mechanic will enforce validations and/or construct the form element differently.

A option that uses a flag consists of the original option key, plus a double underscore, plus a set of underscore-delimited flags. This format looks like options.foo__bar_baz , where foo is the option name, and bar and baz are the flags.

Mechanic supports these flags:

required – Guarantees that the merchant must fill in this option before the task can be saved
boolean – Renders a checkbox, resulting in values that are either true or false
multiline – Renders a textarea, into which multiple lines of text can be entered
email – Renders an input element of type email
number – Renders an input element of type number , with step="1"
code – Renders a textarea that's formatted for code
keyval – Allows the merchant to add labeled values, which are made available to the script as a key => value data structure, where each value is evaluated with the option's other flags
array – allows the merchant to add a series of values, where each value is evaluated with the option's other flags; if the merchant adds a fifth element, a "Manage in bulk" option will appear, allowing for a larger set of elements to be pasted into a simple text box (for an illustration, see Can I manage task options in bulk?)

Parsing

Each option is parsed for Liquid, before the task script is rendered. (This means that any variables created in the task script are not available to Liquid in your task options.) During this rendering pass, the task's standard set of Liquid variables are available: e.g. event, shop, cache, and any automatic variables related to the current event. (For more on variables in task Liquid, see Task scripts.)

Option values are typed according to flags on each option. By default, option values are strings; if an option has the "number" flag, its value will be converted to an integer or decimal; "keyval" options are hashes, and "array" values are arrays.

Using configured options

The merchant's configuration choices are available in the task script (and any configured JavaScript) using lookups resembling {{ options.xyz }}. The "options" object is always a hash. Its keys exactly match the keys used in referencing this object – including any flags used for each key.

For example, consider this task script:

{% if options.send_email__boolean %}
  {% action "email" %}
    {
      "subject": {{ options.email_subject | json }}
      ...
    }<br>  {% endaction %}<br>{% endif %}

If the merchant doesn't touch the resulting configuration form at all, the options object will contain this value when the task is run:

{
  "send_email__boolean": false,
  "email_subject": null
}

These defaults will be replaced by any merchant-configured values.