Merge pull request #13 from kdambekalns/yaml-documentation

TASK: Document YAML-based form configuration

Documentation/configuring-form-yaml.rst

@@ -0,0 +1,90 @@
+.. _configuring-form-yaml:
+
+Configuring form rendering with YAML
+====================================
+
+Setup
+-----
+
+To render a form based on a YAML configuration file, simply use the TYPO3.Form ``render`` ViewHelper.
+It uses the ``TYPO3\Form\Factory\ArrayFormFactory`` by default, which needs to know where the form
+configuration is stored. This is done in ``Settings.yaml``:
+
+.. code-block:: yaml
+
+    TYPO3:
+      Form:
+        yamlPersistenceManager:
+          savePath: 'resource://AcmeCom.SomePackage/Private/Form/'
+
+From now on, every YAML file stored there can be loaded by using the filename as the persistence
+identifier given to the ``render`` ViewHelper. So if you have a file named ``contact.yaml``, it
+can be rendered with:
+
+.. code-block:: html
+
+    <form:render persistenceIdentifier="contact"/>
+
+Form configuration
+------------------
+
+Generally speaking, the configuration is a nested structure that contains the keys ``type``, ``identifier`` and
+``renderables`` and further options (e.g. ``label``) depending on the type of the current level.
+
+The element types referenced below (``TYPO3.Form:SingleLineText`` and ``TYPO3.Form:MultiLineText``)
+are just element types which are delivered by default by the framework. All available types can be
+found in the settings of the TYPO3.Form package under ``TYPO3.Form.presets.default.formElementTypes``.
+
+On the top level, the ``finishers`` can be configured as an array of ``identifier`` and ``options`` keys. The
+available options depend on the finisher being used.
+
+Let us examine the configuration for a basic contact form with the following structure:
+
+* Contact Form *(Form)*
+    * Page 01 *(Page)*
+        * Name *(Single-line Text)*
+        * Email *(Single-line Text)*
+        * Message *(Multi-line Text)*
+
+The following YAML is stored as ``contact.yaml``:
+
+.. code-block:: yaml
+
+    type: 'TYPO3.Form:Form'
+    identifier: 'contact'
+    label: 'Contact form'
+    renderables:
+      -
+        type: 'TYPO3.Form:Page'
+        identifier: 'page-one'
+        renderables:
+          -
+            type: 'TYPO3.Form:SingleLineText'
+            identifier: name
+            label: 'Name'
+            validators:
+              - identifier: 'TYPO3.Flow:NotEmpty'
+          -
+            type: 'TYPO3.Form:SingleLineText'
+            identifier: email
+            label: 'Email'
+            validators:
+              - identifier: 'TYPO3.Flow:NotEmpty'
+              - identifier: 'TYPO3.Flow:EmailAddress'
+          -
+            type: 'TYPO3.Form:MultiLineText'
+            identifier: message
+            label: 'Message'
+            validators:
+              - identifier: 'TYPO3.Flow:NotEmpty'
+    finishers:
+      -
+        identifier: 'TYPO3.Form:Email'
+        options:
+          templatePathAndFilename: resource://AcmeCom.SomePackage/Private/Templates/Form/Contact.txt
+          subject: '{subject}'
+          recipientAddress: 'info@acme.com'
+          recipientName: 'Acme Customer Care'
+          senderAddress: '{email}'
+          senderName: '{name}'
+          format: plaintext

Documentation/index.rst

@@ -35,6 +35,7 @@ reference, although there will be links to the in-depth API reference at various
    :maxdepth: 2
 
    quickstart
+   configuring-form-yaml
    adjusting-form-output
    extending-form-api
    configuring-form-builder
@@ -43,7 +44,7 @@ reference, although there will be links to the in-depth API reference at various
 Credits
 =======
 
-This work has been generously sponsored by `AKOM360 - Multi Channel Marketing <http://akom360.de>`_.
+The initial implementation has been generously sponsored by `AKOM360 - Multi Channel Marketing <http://akom360.de>`_.
 
 It has been implemented by:
 

Documentation/quickstart.rst

@@ -52,8 +52,12 @@ Create your first form
 
 Now, let's try to create the basic contact form from above.
 For this we need to implement a so-called :api-factory:`FormFactory <AbstractFormFactory>`,
-which is responsible for creating the form. The skeleton for building a form
-looks as follows::
+which is responsible for creating the form.
+
+ .. note:: The package comes with a ready-to-use factory for building forms based on YAML
+   files describing the forms. See :ref:`configuring-form-yaml` for details.
+
+If you want to build a form with PHP, the skeleton for building a form looks as follows::
 
 	namespace Your\Package;