.. include:: /Includes.rst.txt


.. _concepts-formmanager:

Form manager
============


.. _concepts-formmanager-general:

What does it do?
----------------

The ``form manager`` can be accessed by opening the backend module 'Forms'.
It allows the editor to administer all of the existing forms stored on the
accessible file mounts. The central element of the ``form manager`` is a
table view which...

- lists all forms
- allows users to create, edit, duplicate, and delete forms
- names the storage folder
- gives a broad overview on which pages the listed forms are used in.

The creation and duplication of forms is supported by a so-called ``form
wizard``. The wizard guides the editor through the process and offers a
variety of settings depending on the form configuration. Those settings
include choosing file mounts, prototypes, and start templates.

.. figure:: ../../Images/form_manager.png
   :alt: The form manager

   TYPO3 Backend with opened module 'Forms' displaying the form manager.


.. _concepts-formmanager-starttemplate:

Start templates
---------------

This is a very nifty feature. When creating a new form, the ``form manager``
allows the backend editor to select a so-called ``Start template``. Such a
template is a predefined ``form definition`` without the property
``prototypeName`` which is normally used as a foundation of a new form.

As an integrator, you can specify as many ``Start templates`` as you desire
for a given ``prototype``. After you have defined such a template, follow
these easy steps to use your defined ``Start templates`` as a foundation:

- open the ``Forms`` module
- create a new form by clicking on the appropriate button
- enter the 'Form name' and click the checkbox 'Advanced settings'
- during the next steps you can select a ``Start template``

For each ``prototype``, you have to define a ``Start template`` in order to
enable the editor to choose one. Additionally, the same ``Start template``
can be used for several ``prototypes``. To do so, make sure the included
form elements of the template are defined in the corresponding ``prototype``.

For example, imagine your integrator has :ref:`configured<formmanager.selectablePrototypesConfiguration>`
a prototype called 'routing' which contains a custom form element with the
``<formElementTypeIdentifier>`` 'locationPicker'. The element is only
defined for this prototype. The integrator has created a ``Start template``
which carries the 'locationPicker' form element. A backend editor could now
select and use this ``Start template``, including the custom form element,
as long as the ``prototype`` is set to 'routing'. If the integrator also
adds this custom form element to another ``prototype``, the process would
crash. The custom form element is only known by the ``prototype`` 'routing'.

The following code block shows the minimal configuration of a ``Start
template``. You need at least the root form element ('Form') and a 'Page'.

.. code-block:: yaml

   type: 'Form'
   identifier: 'blankForm'
   label: '[Blank Form]'
   renderables:
     -
       type: 'Page'
       identifier: 'page-1'
       label: 'Page'

As mentioned previously, the form wizard within the ``form manager`` offers
a list of all existing, :ref:`pre-configured<formmanager.selectableprototypesconfiguration.*.newformtemplates>`
``Start templates``. As soon as the backend editor creates a form with the
help of such a template, a new ``form definition`` is generated based on the
one of the selected ``Start template``. The ``form definition`` will be
enriched by the property ``propertyName`` defining the chosen ``prototype``.
The ``identifier`` of the root form element ('Form') is automatically set
based on the entered "Form name". Additionally, this name is used for the
property `` label`` of the 'Form' element. Finally, the ``form editor`` is
loaded and displays the newly created form.


.. _concepts-formmanager-translation-starttemplate:

Translation of the form manager
-------------------------------

All option values which reside below the following configuration keys can be
translated:

.. code-block:: yaml

   formManager:

The translation files of the ``form manager`` are loaded as follows:

.. code-block:: yaml

   formManager:
     translationFiles:
       # custom translation file
       20: 'EXT:my_site_package/Resources/Private/Language/Form/Database.xlf'

The process searches for each option value within all of the defined
translation files. If a translation is found, the translated option value
will be used in preference.

Imagine, the following is defined for an option value:

.. code-block:: yaml

   ...
   label: 'formManager.selectablePrototypesConfiguration.standard.label'
   ...

First of all, the process searches for the translation key ``formManager.selectablePrototypesConfiguration.standard.label``
within the file ``20: 'EXT:my_site_package/Resources/Private/Language/Form/Database.xlf'``
and after it inside the file ``10: 'EXT:form/Resources/Private/Language/Database.xlf'``
(loaded by default). If nothing is found, the option value will be
displayed unmodified.