Merge pull request #4091 from open-formulieren/docs/improve-dev-doc-2

[#4044] Improve dev documentation regarding forms and submissions

docs/conf.py

@@ -40,6 +40,7 @@
     "sphinx.ext.todo",
     "sphinx.ext.intersphinx",
     "sphinx_tabs.tabs",
+    "sphinxcontrib.mermaid",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/developers/backend/core/_assets/forms-models.mmd

@@ -0,0 +1,46 @@
+---
+Forms model relationship
+---
+erDiagram
+Category {
+    UUIDField uuid
+    CharField path
+    CharField name
+}
+Form {
+    UUIDField uuid
+    SlugField slug
+    CharField name
+    ForeignKey category
+}
+FormDefinition {
+    UUIDField uuid
+    CharField name
+    SlugField slug
+    JSONField configuration
+    BooleanField login_required
+    BooleanField is_reusable
+}
+FormStep {
+    UUIDField uuid
+    SlugField slug
+    ForeignKey form
+    ForeignKey form_definition
+    BooleanField is_applicable
+}
+FormVariable {
+    ForeignKey form
+    ForeignKey form_definition
+    TextField name
+    TextField key
+    CharField source
+    CharField data_type
+    CharField data_format
+    BooleanField is_sensitive_data
+    JSONField initial_value
+}
+Form }|--|| Category : category
+FormStep }|--|| Form : form
+FormStep }|--|| FormDefinition : form_definition
+FormVariable }|--|| Form : form
+FormVariable }|--|| FormDefinition : form_definition

docs/developers/backend/core/formio.rst

@@ -20,6 +20,62 @@ the code for this is organized in the ``openforms.formio`` package.
     and all of the separate registries (formatters, normalizers...) were merged into a
     single compoment registry.
 
+Form.io configuration
+=====================
+
+A form.io configuration is an object containing a ``"components"`` key mapped to an array of objects
+representing the definition of form components for a specific form step.
+The following is an example of such a configuration:
+
+.. code-block:: json
+
+    {
+        "display": "form",
+        "components": [
+            {
+                "type": "textfield",
+                "key": "field_1",
+                "label": "Field 1"
+            },
+            {
+                "type": "number",
+                "key": "field_2",
+                "label": "Field 2"
+            }
+        ]
+    }
+
+Whenever a submission is created, submission data will be attached to it. The layout of this submission
+data will depend on the components configuration. For instance, with the example configuration given above,
+submission data will look like:
+
+.. code-block:: json
+
+    {
+        "field_1": "some_value",
+        "field_2": 1
+    }
+
+
+Components can be roughly categorised as layout and data components. Layout components don't have
+a matching entry in the submission data.
+
+Every component has two required properties:
+
+* ``"key"``: A unique identifier across the form. The key represents a structured path "into" the submission
+  data. A period (``.``) represents a level of nesting in this data.
+* ``"type"``: The corresponding component type.
+
+.. note::
+
+    Submission data should be interpreted along with components configuration, as it is impossible
+    to determine how data needs to be handled without this context. At times, the submission data
+    can also influence the component configuration, e.g. with conditionals expressing when a component
+    is visible or not.
+
+The `form.io playground`_ can be used to play with the different components and how the submission data will
+look like.
+
 Supported features
 ==================
 
@@ -132,3 +188,4 @@ Module: ``openforms.formio.rendering``
     :members:
 
 .. _form.io: https://www.form.io/
+.. _form.io playground: https://formio.github.io/formio.js/app/builder

docs/developers/backend/core/index.rst

@@ -25,3 +25,21 @@ The following Django apps are considered core functionality:
   operations
 
 .. _form.io: https://www.form.io/
+
+Data model
+==========
+
+The following is a simplified relationship diagram of the Django models that relates to forms:
+
+.. mermaid:: _assets/forms-models.mmd
+
+Each :class:`~openforms.forms.models.Form` can have multiple :class:`~openforms.forms.models.FormStep`'s
+defined, which acts as a proxy model to a :class:`~openforms.forms.models.FormDefinition`
+(as these can be reusable across forms). The :class:`~openforms.forms.models.FormDefinition` model
+has a ``configuration`` JSON field, holding the form.io configuration.
+
+The submissions data model mirrors this model in some way:
+
+- A :class:`~openforms.submissions.models.Submission` is tied to a :class:`~openforms.forms.models.Form`.
+- A :class:`~openforms.submissions.models.SubmissionStep` is tied to a :class:`~openforms.forms.models.FormStep`.
+- A :class:`~openforms.submissions.models.SubmissionValueVariable` is tied to a :class:`~openforms.forms.models.FormVariable`.

requirements/ci.txt

@@ -962,6 +962,8 @@ sphinxcontrib-jquery==4.1
     # via sphinx-rtd-theme
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
+sphinxcontrib-mermaid==0.9.2
+    # via -r requirements/docs.in
 sphinxcontrib-qthelp==1.0.7
     # via sphinx
 sphinxcontrib-serializinghtml==1.1.10

requirements/dev.txt

@@ -1106,6 +1106,10 @@ sphinxcontrib-jsmath==1.0.1
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
     #   sphinx
+sphinxcontrib-mermaid==0.9.2
+    # via
+    #   -c requirements/ci.txt
+    #   -r requirements/ci.txt
 sphinxcontrib-qthelp==1.0.7
     # via
     #   -c requirements/ci.txt

requirements/docs.in

@@ -4,3 +4,4 @@
 sphinx
 sphinx-rtd-theme
 sphinx-tabs
+sphinxcontrib-mermaid