wizard.rst

General Wizard Functionality Demo

This wizard aims to demonstrate the general REX ACTION capabilities including defining new wizard, changing basic action fields, using states etc. Here is the complete source code of it.

.. literalinclude:: ../../static/urlmap/wizard.yaml
   :language: yaml
   :caption: static/urlmap/hello.yaml
   :linenos:

Simple Action

The following code example shows very minimal and simple action configuration. 2 selected lines emphasize type and title fields you would be specifying for any action when defining it. Technically, title is optional, but unlikely the default title would ever be enough for the real use-case. So, it is recommended to specify the title explicitely.

.. literalinclude:: ../../static/urlmap/wizard.yaml
   :language: yaml
   :emphasize-lines: 2,3
   :start-after: actions:
   :end-before: icon:

Changing Icon

Another visual property you may find useful to customize is the icon. This field can be customizaed for any action. Link with icon names is TBD.

.. literalinclude:: ../../static/urlmap/wizard.yaml
   :language: yaml
   :emphasize-lines: 4
   :start-after: .. _here: http://docutils.sourceforge.net/docs/user/rst/quickref.html
   :end-before: use-states:

Using States

In REX ACTION terminology state stands for the entity's boolean attribute which can influence the wizard flow. There are plenty of use-cases for using states. For instance, if study is not configured then configure it else show study statistic information. Pretty reasonable requirement, isn't it?

First of all, you have to declare states of your entities in the states section in the wizard configuration as shown below.

.. literalinclude:: ../../static/urlmap/wizard.yaml
   :language: yaml
   :start-after: - included:
   :end-before: individual:

The state section is the mapping in a form of <entity type> => <state description>. <entity type> should be treated as the database table name here. <state description> has 2 properties: the human-readable title (title) and the boolean HTSQL expression (expression) which evaluates in the context of the respective <entity type>.

Note

When configuring state expression (or any other action field containing HTSQL), consider using YAML multiline strings (|) or double quotes ("). Otherwise you may interfere with YAML special characters (for instance '!' or '&').

Once states are configured, we need to use them in the wizard. States are used by all the standard actions in entity and input fields as following:

entity: study[not-configured]

This statement says: use 'study' entity only if it is in the 'not-configured' state. In other words (HTSQL):

study[$study].filter(!is_configured)

An action with such configuration will be displayed only in case if the state expression is evaluated to true. See the part of wizard's path right here:

.. literalinclude:: ../../static/urlmap/wizard.yaml
   :language: yaml
   :start-after: - icon:
   :end-before: - states-context:

And the definitions of related actions:

.. literalinclude:: ../../static/urlmap/wizard.yaml
   :language: yaml
   :start-after: expression: if(is_configured, 'Yes', 'No')
   :end-before: states-context:

This can be translated to following list of steps:

1. Pick the study (use-states action)
2. With the selected study do one of the following:
   • Edit if it is not configured (configure-study)
   • View study details if it is configured (view-study)
   • Pick individual to the study if study is configured (pick-recruited)

Using States With Context

Using Replace

Included Wizard