`process-form` processor

The process-form data processor is the core of the extension. It resolves each key in its TypoScript configuration through content objects in the context of the top-level renderable (FormRuntime), producing a plain PHP array that becomes the Handlebars template context.

The data processor is registered under the identifier process-form and can be used inside a dataProcessing block:

plugin.tx_form.handlebarsForms.default {
    dataProcessing {
        10 = process-form
        10 {
            # processor configuration
        }
    }
}

Key resolution

The processor iterates all keys in its configuration block and resolves each one by the following rules, applied in order:

Array value (no string sibling) – the sub-tree is processed recursively. The result is stored as a nested array under the key name (without trailing dot).
String value matching a registered content object – the content object is rendered with the dotted sub-tree as its configuration. The return value is stored under the key name.
String value not matching any content object – the raw string is stored as-is.

These rules mean the structure of the TypoScript block directly mirrors the structure of the resulting PHP array:

10 = process-form
10 {
    # Rule 1: nested array
    formData {
        id = HBS_TAG
        id.attribute = id

        method = HBS_TAG
        method.attribute = method
    }

    # Rule 2: content object
    label = HBS_LABEL

    # Rule 3: literal string
    staticKey = staticValue
}

Produces:

[
    'formData' => [
        'id'     => '…',   // resolved by HBS_TAG
        'method' => '…',   // resolved by HBS_TAG
    ],
    'label'     => '…',    // resolved by HBS_LABEL
    'staticKey' => 'staticValue',
]

Note

A key is only written to the output array if its resolved value is not null. Content objects that cannot resolve a value (e.g. HBS_TAG used on a view model that is not a TagAwareViewModel) return null and the key is silently omitted.

Content object configuration

Configuration for a content object is placed in the dotted sub-tree below the key:

id = HBS_TAG
id.attribute = id

subject = HBS_PROPERTY
subject.path = type
subject.subject = renderable

The dotted sub-tree also supports stdWrap, which is applied to the resolved value after the content object returns:

label = HBS_LABEL
label.stdWrap.case = upper

Conditions

if is supported at two levels and behaves like the built-in TypoScript function.

It can be placed directly in the processor configuration (or in any nested sub-tree). When the condition evaluates to false, the entire block is skipped and null is returned for its parent key:

fields = HBS_RENDERABLES
fields {
    Fieldset {
        if.isTrue = 0
    }
}

The currentValue extension in if allows the condition to be evaluated against a value resolved by the processor itself rather than a static TypoScript value. It accepts a content object expression using the same syntax as the main configuration:

someField {
    if {
        currentValue = HBS_PROPERTY
        currentValue.path = required
        isTrue.current = 1
    }

    label = HBS_LABEL

    value = HBS_TAG
    value.attribute = value
}

TypoScript references

TypoScript copy (<) and reference (=<) operators are fully supported. References are resolved before any key in a block is processed, so the merged configuration is what the content objects see:

Email < .Text

navItems = HBS_NAVIGATION
navItems {
    previousPage {
        # ...
    }
    nextPage < .previousPage
    submit < .previousPage
}

fields =< plugin.tx_form.handlebarsForms.default.dataProcessing.10.fields

Renderable context

Each key in the processor configuration is resolved in the context of the current renderable. At the top level this is the FormRuntime (i.e. the whole form). When HBS_RENDERABLES iterates children, each child key is resolved in the context of that child renderable and its view model.

The active renderable and view model are accessible to all HBS_* content objects through the ValueResolutionContext they receive. This is what allows HBS_TAG to read from the rendered tag of the current element rather than a global one, and why the same HBS_LABEL call returns a different label for each iteration of HBS_RENDERABLES.

process-form processor