.. _variable-resolvers:

==================
Variable resolvers
==================

Target group: **Integrators**, **Developers**

.. contents:: Table of Contents
   :depth: 3
   :local:

Variables
=========

You can use variables in the common process parameters, such as :yaml:`summary`
or :yaml:`initiator`, and in the process table fields.

Variables look like: :yaml:`{__variableName}` or
:yaml:`{__variableName.subKey}` − in curly brackets with a double underscore
at the beginning.

Example:

.. code-block:: yaml

   finishers:
      -
         identifier: JobRouterStartInstance
         options:
            handle: 'start_website_contact'
            summary: '{__LLL:EXT:your_ext/Resources/Private/Language/forms.xlf:demo.summary} ({__language.navigationTitle})'
            initiator: '{__correlationId}'
            processtable:
               name: '{preName} {lastName}'
               company: '{company}'
               email_address: '{email}'
               phone_number: '{phone}'
               message: '{message}'
               from_website: '{__language.base}'

.. hint::
   You can build own variable resolvers. Have a look in the section
   :ref:`developer-variable-resolvers`.


Correlation ID
--------------

The correlation ID is generated from the form identifier and a unique key
to identify associated transfers – as you can start multiple instances from one
form and transmit data to a JobData table. The correlation ID is stored in a
column in the transfer tables together with the form data. This is useful if you
want to check the data from the instance against the original data from the
form.

The correlation ID looks like this: `form_demo-20_63fca23b1accb` where `form`
indicates the ID is generated by a from finisher, `demo-20` is the form
identifier with the content element uid of the form plugin and `63fca23b1accb`
is the unique key.

Use the :yaml:`{__correlationId}` variable to add the correlation ID.

.. note::
   The correlation ID is the same for every JobRouter form finisher in a form
   instance.

.. tip::
   The correlation id can be used to set the initiator for a process instance
   start (if the initiator is not used to assign a step to a JobRouter® user).
   This way the correlation id is easy to spot in the step overview.


Localisation labels
-------------------

Values can be localised with the help of the localisation labels known from
various parts in TYPO3. The variable starts with :yaml:`{__LLL:` and holds
the path to the translation file and the according key, for example,
:yaml:`{__LLL:EXT:your_ext/Resources/Private/Language/locallang.xlf:your.label}`.

If the label is not found and therefore cannot be translated the value is
untouched.

You can use multiple localisation labels in one form value.


.. _variable-resolvers-language:

Language information
--------------------

.. versionchanged:: 4.0
   `{__language.twoLetterIsoCode}` has been removed, use
   `{__language.locale.languageCode}` instead.
   `{__language.direction}` has been removed without substitution.

The language information defined in the Site Configuration can be used, namely:

{__language.base}
   The base URL for the language, for example, `https://example.org/en/`.

{__language.flagIdentifier}
   The defined TYPO3 flag identifier used in TYPO3's backend, for example,
   `flags-gb`.

{__language.hreflang}
   Language tag for the language defined by RFC 1766 / 3066 for `lang`
   `hreflang` attributes, for example, `en-gb`.

{__language.languageId}
   The language ID defined in the site configuration.

{__language.locale}
   The used locale, for example, `en_GB.UTF-8`.

{__language.locale.countryCode}
   .. versionadded:: 4.0
   The `ISO-3166-1 alpha-2 <https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes>`__
   country code, for example `US`.

{__language.locale.languageCode}
   .. versionadded:: 4.0
   The `ISO-639-1 <https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes>`__
   language ISO code, for example, `en`.

{__language.navigationTitle}
   The navigation title defined in the site configuration, used as label
   within language menus, for example, `English`.

{__language.title}
   The title defined in the site configuration, for example, `English`.

{__language.typo3Language}
   `default` for English, otherwise one of TYPO3's internal language keys.

Multiple language variables can be used in one form value.


JobRouter language information
------------------------------

Sometimes it is necessary to use not the language code of the page in your form
but instead the language string JobRouter® uses (for example, ``german`` instead
of ``de``). This can be useful for sending localised emails from the process in
the relevant language.

Use the :yaml:`{__jobRouterLanguage}` variable for that. The following languages
are supported by JobRouter® in recent version:

+----------------+---------------------+
| ISO 639-1 code | JobRouter® language |
+================+=====================+
| ar             | arabic              |
+----------------+---------------------+
| cs             | czech               |
+----------------+---------------------+
| da             | danish              |
+----------------+---------------------+
| de             | german              |
+----------------+---------------------+
| en             | english             |
+----------------+---------------------+
| es             | spanish             |
+----------------+---------------------+
| fi             | finnish             |
+----------------+---------------------+
| fr             | french              |
+----------------+---------------------+
| hr             | croatian            |
+----------------+---------------------+
| hu             | hungarian           |
+----------------+---------------------+
| it             | italian             |
+----------------+---------------------+
| ja             | japanese            |
+----------------+---------------------+
| lt             | lithuanian          |
+----------------+---------------------+
| nl             | dutch               |
+----------------+---------------------+
| pl             | polish              |
+----------------+---------------------+
| pt             | portuguese          |
+----------------+---------------------+
| ro             | romanian            |
+----------------+---------------------+
| ru             | russian             |
+----------------+---------------------+
| sk             | slovak              |
+----------------+---------------------+
| sl             | slovenian           |
+----------------+---------------------+
| sr             | serbian             |
+----------------+---------------------+
| tr             | turkish             |
+----------------+---------------------+
| zh             | chinese             |
+----------------+---------------------+

If the language is not available, an empty string is returned by the variable
resolver.


Page properties
---------------

The properties of the page where the form is located can be retrieved. The
variable starts with `__page.`. Any existing page property, such as uid or
title, can be used, for example: `{__page.title}`.

If a page property is not present, the variable is used unchanged.