Plugin API » Forms » Value path handling

Value path handling

Values and documents

Each form element gets and sets a value in the JSON document. The path property in the specification defines where it goes in the document.

The path is a "." separated list of property names. For example, in this document,

{
    "name": "Joe Bloggs",
    "info": {
        "age": 35,
        "favouriteColour": "Green"
    }
}

a path of "info.age" would refer to the value 35.

When defining nested data structures, you don’t have to ensure that the all the nested objects exist. When getting a value, if a containing section doesn’t exist, the value will be treated as not existing in the document, and when setting a value, missing nested sections are automatically created.

This means you can safely use the empty document of {} to output a form using the default values for every form element, and to receive the data from a submitted form.

Context

The path property does not necessarily refer to a path from the root of the document. It’s actually relative to the current context.

At the root of the specification, the context is the root of the document. However, the context may change when you define a Section.

If the path property is defined for a Section, then the context is moved to that value. For example, in the above document, if there was a Section with a path of "info", then form elements enclosed in that Section would refer to the age property with a path of "age".

Repeating sections

Repeating sections work slightly differently, because they need to create an Array of all the repeats. A path must be specified for a Repeating section, and this refers to an array in the document.

The context for the elements in a repeating section is each entry in the array.

For example, here’s a document containing information about multiple people.

{
    "people": [
        {
            "name": "Joe Bloggs",
            "info": {
                "age": 35,
                "favouriteColour": "Green"
            },
        },
        {
            "name": "Jane Bloggs",
            "info": {
                "age": 34,
                "favouriteColour": "Purple"
            }
        }
    ]
}

The path of the repeating section is "people", and a form element editing the age of each person would use a path of "info.age".

Arrays of values

If you just want to have one element in your repeating section, for example, to allow multiple phone numbers, then forcing the values to be enclosed in an object with a single property may make your document a little annoying to handle.

There is a special case which cleans this up. If there is just one form element in a repeating section, it may use the special path of ".". When used, this will mean the array is a simple array of values.

For example, the telephone numbers in this document

{
    "name": "Joe Bloggs",
    "info": {
        "age": 35,
        "favouriteColour": "Green",
        "telephoneNumbers": [
            "+44 20 7047 1111",
            "+44 7777 123456"
        ]
    }
}

could be edited by using a repeating section with a path of "info.telephoneNumbers" which contains a single element with a path of ".".