FormElement model

Every form element in the editor is represented by a FormElement model object. This model is the single source of truth for all element properties during an editing session; it is separate from the YAML form definition on disk (which is only written on save).

Model structure

A FormElement model carries all YAML properties of the element plus two internal bookkeeping properties:

Property	Description
`__identifierPath`	Slash-separated path from the root element to this element (e.g. `'example-form/page-1/name'`). Used as a unique key for API lookups.
`__parentRenderable`	Reference to the parent FormElement model (filtered for display).

Example model in memory:

// Illustrative snapshot of a FormElement model as it exists in memory at runtime.
// The actual object is managed by the FormElement class – access it via
// formEditorApp.getFormElementByIdentifierPath() and the get()/set() API.
export const formElementSnapshot = {
    identifier: 'name',
    defaultValue: '',
    label: 'Name',
    type: 'Text',
    properties: {
        fluidAdditionalAttributes: {
            placeholder: 'Name',
        },
    },
    __parentRenderable: 'example-form/page-1 (filtered)',
    __identifierPath: 'example-form/page-1/name',
    validators: [
        { identifier: 'NotEmpty' },
    ],
};

get()

Reads a property by its dot-separated path. All intermediate levels must be objects.

export function bootstrap(formEditorApp) {
    // Returns 'Name'
    const placeholder = formEditorApp
        .getFormElementByIdentifierPath('example-form/page-1/name')
        .get('properties.fluidAdditionalAttributes.placeholder');
}

For property collections (validators / finishers), whose position in the array is unknown, use buildPropertyPath() first:

export function bootstrap(formEditorApp) {
    const formElement = formEditorApp
        .getFormElementByIdentifierPath('example-form/page-1/name');

    const propertyPath = formEditorApp
        .buildPropertyPath('options.minimum', 'StringLength', 'validators', formElement);
    // propertyPath = e.g. 'validators.0.options.minimum'

    const value = formElement.get(propertyPath); // '1'
}

For renderables (child elements), get('renderables') returns a plain array of FormElement models. To access a specific child, use formEditorApp.getFormElementByIdentifierPath() with the full path.

set()

Writes a property by its dot-separated path. Every set() call automatically publishes all events registered for that path via on(), including the built-in core/formElement/somePropertyChanged.

export function bootstrap(formEditorApp) {
    formEditorApp
        .getFormElementByIdentifierPath('example-form/page-1/name')
        .set('properties.fluidAdditionalAttributes.placeholder', 'New Placeholder');
}

To modify property collection properties or add child renderables, use the dedicated API methods on formEditorApp / getViewModel() instead of setting array positions directly:

createAndAddFormElement()
addFormElement()
moveFormElement()
removeFormElement()

unset()

Removes a property at the given dot-separated path.

export function bootstrap(formEditorApp) {
    formEditorApp
        .getFormElementByIdentifierPath('example-form/page-1/name')
        .unset('properties.fluidAdditionalAttributes.placeholder');
}

For property collection properties, use buildPropertyPath() in the same way as for get().

To remove a child renderable, call formEditorApp.removeFormElement().

on()

Registers an additional publish/subscribe event name that is fired whenever set() is called for a given property path.

export function bootstrap(formEditorApp) {
    const element = formEditorApp
        .getFormElementByIdentifierPath('example-form/page-1/name');

    element.on('properties.fluidAdditionalAttributes.placeholder', 'my/custom/event');

    // The next set() on that path will also publish 'my/custom/event'.
    element.set('properties.fluidAdditionalAttributes.placeholder', 'New Placeholder');
}

By default EXT:form registers core/formElement/somePropertyChanged for every known property path of every form element.

off()

Removes an event registration created with on().

export function bootstrap(formEditorApp) {
    formEditorApp
        .getFormElementByIdentifierPath('example-form/page-1/name')
        .off('properties.fluidAdditionalAttributes.placeholder', 'my/custom/event');
}

getObjectData()

Returns a deep-cloned plain object of all properties. Used internally for Ajax serialisation. Provides read access to data set via set() from outside the model without breaking encapsulation.

clone()

Returns a fully dereferenced clone of the FormElement model.

export function bootstrap(formEditorApp) {
    const formElement = formEditorApp
        .getFormElementByIdentifierPath('example-form/page-1/name');
    const copy = formElement.clone();
}

toString()

Returns the model data as a JSON string. Intended for debugging.

export function bootstrap(formEditorApp) {
    const formElement = formEditorApp
        .getFormElementByIdentifierPath('example-form/page-1/name');
    console.log(formElement.toString());
}