TYPO3 v15 dev-main snapshot ()

Documentation/I/Concepts/FormManager/Index.rst

@@ -0,0 +1,133 @@
+.. include:: /Includes.rst.txt
+
+
+.. _concepts-formmanager:
+
+Form manager
+============
+
+
+.. _concepts-formmanager-general:
+
+What does it do?
+----------------
+
+You will find the ``form manager`` in the backend :guilabel:`Web > Forms` backend
+module. Editors can use the ``form manager`` to administer forms stored on file
+mounts that they have access to. The ``form manager``:
+
+- lists all forms
+- allows users to create, edit, duplicate, and delete forms
+- identifies the storage folder
+- gives an overview of which pages the forms are on.
+
+Creation and duplication of forms is made easier by a ``form wizard``.
+The wizard guides the editor through form creation and offers a
+variety of settings, such as the file
+mount, the prototype, 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
+---------------
+
+Editors can select a ``Start template`` when they are creating a new form. A
+``Start template`` is a ``form definition`` which hasn't been assigned a
+``prototypeName`` (the ``prototypeName`` property is normally used as the
+foundation of a new form).
+
+An integrator can create as many ``Start templates`` as they wish for a particular
+``prototype``. After the ``Start templates`` have been defined the integrator can then:
+
+- open :guilabel:`Web > Forms`
+- create a new form by clicking on the appropriate button
+- enter the 'Form name' and click the 'Advanced settings' checkbox
+- select a ``Start template`` during the next steps
+
+Integrators have to define ``Start templates`` so that they can be selected
+by editors. Also, the same ``Start template``
+can be used for several ``prototypes``. To do this, make sure the
+``start template`` form elements are defined in the corresponding ``prototypes``.
+
+For example, imagine an integrator has :ref:`configured<formmanager.selectablePrototypesConfiguration>`
+a prototype called 'routing' which contains a form element of type
+``<formElementTypeIdentifier>`` 'locationPicker'. The element is only
+defined in this prototype. The integrator has created a ``Start template``
+which contains the 'locationPicker' form element. A backend editor could now
+select and use this ``Start template`` with the 'locationPicker' form element,
+as long as the ``prototype`` is 'routing'. If the integrator
+adds this form element to another ``prototype``, the process would
+crash. The 'locationPicker' form element is only known to the 'routing'
+``prototype``.
+
+The following example shows a ``Start template``. A
+``Start template`` requires 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'
+
+The ``form manager`` form wizard displays
+a list of all :ref:`pre-configured<formmanager.selectableprototypesconfiguration.*.newformtemplates>`
+``Start templates``.When a backend editor creates a form using a
+``Start template``, a new ``form definition`` is generated based on that
+``Start template``. The ``form definition`` ``propertyName`` will be that of the
+chosen ``prototype``.The ``identifier`` of the root form element ('Form') is set
+to the entered "Form name". This name is also 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 below the ``form editor`` key in the form configuration can be
+translated:
+
+.. code-block:: yaml
+
+   formManager:
+
+The ``form manager`` translation files 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.
+
+For the following option value:
+
+.. code-block:: yaml
+
+   ...
+   label: 'formManager.selectablePrototypesConfiguration.standard.label'
+   ...
+
+the process searches for the translation key ``formManager.selectablePrototypesConfiguration.standard.label``
+in the file under key 20  ``20: 'EXT:my_site_package/Resources/Private/Language/Form/Database.xlf'``
+and then the file in EXT:form ``10: 'EXT:form/Resources/Private/Language/Database.xlf'``
+(loaded by default). If nothing is found, the option value will be
+displayed unmodified.