formio.rst

Core: form.io integration

Open Forms uses form.io under the hood to build and render forms, and then adds its own layers on top of that, such as:

• implementing multi-step forms where every step is a form.io definition
• evaluating backend logic using data from earlier steps
• dynamically adapting form.io definitions as needed

This means that we process the form.io datastructures in the backend, using Python. All the code for this is organized in the openforms.formio package.

2.1.0

openforms.custom_field_types was refactored into 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:

{
    "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:

{
    "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

openforms.formio.service

Formatting values for display

Value formatting is done for displaying form submission data summaries, rendering confirmation PDFs and emails... It is aware if it's in a HTML context or not. It is heavily used in the renderers <developers_backend_core_submission_renderer>.

Whenever a component plugin is registered, the openforms.formio.registry.BasePlugin.formatter class attribute must be specified.

format_value

Normalizing input data

Data for a component can be sourced from external systems that employ different formatting rules compared to what form.io expects. Normalizing this data helps to be able to make proper comparisons at different stages in the submission life-cycle.

You can opt-in to this by configuring openforms.formio.registry.BasePlugin.normalizer.

normalize_value_for_component

Dynamically modifying component configuration

Certain component types require on-the-fly configuration rewriting, such as applying global configuration options that may change independently from when the form is actually being designed.

Dynamic rewriting is enabled by implementing openforms.formio.registry.BasePlugin.mutate_config_dynamically. It receives the current openforms.submissions.models.Submission instance and a mapping of all the variable names and values at the time.

get_dynamic_configuration

For an example of a custom field type, see openforms.formio.components.custom.Date.

Finally, the resulting resolved component definitions are evaluated with the template engine where variable values are evaluated for compoment labels, descriptions... and configuration based on the HTTP request is performed (see openforms.formmio.service.rewrite_formio_components_for_request).

Reference

Public API - openforms.formio.service

openforms.formio.service

openforms.formio.registry.BasePlugin

Extending

Using our usual extension pattern <developers_extending> you can register your own types.

Extensions should inherit from openforms.formio.registry.BasePlugin or implement the same protocol(s) and be registered with their form.io type:

from openforms.formio.formatters.formio import DefaultFormatter
from openforms.formio.registry import BasePlugin

@register("myCustomType")
class MyComponent(BasePlugin):
    formatter = DefaultFormatter

You can find some examples in openforms.formio.components.custom.

Private API

Module: openforms.formio.dynamic_config

openforms.formio.dynamic_config

Module: openforms.formio.formatters

openforms.formio.formatters

Module: openforms.formio.rendering

openforms.formio.rendering