Formulationist-core NPM

Formulationist Core

Formulationist rewritten as a standalone component

The Story So Far...

Formulationist was conceived as a way of presenting forms for filling, with the forms defined as an extended JSON Schema Form (RJSF). However the RJSF project was old, messy, limiting, and flawed. JSON Schema has a weird feel, a dual nature... it's all at once both over- and under-engineered, and has complex ways of expressing simple things, whereas complex things require huge complexity of expression. RJSF makes it hard to introduce the level of dynamism we wanted, where everything is data-driven and very much a moving part. So we decided to ditch it and create a new dynamic forms engine based around Formik, with a new way of defining forms as data. One of the main design goals was to make it a generic forms engine component usable within any React app. And that's what this is.

A New Hope

The new Formulationist Core has a completely new form definition schema. The new Formulationist schema is simple and object-based.

Field hierarchy is simply expressed by making a field an object with a fields attribute containing a dictionary of field objects
Field attributes and validation are mingled.
Validations can be expressed by simple boolean flags, complex boolean MathJs compatible expressions, or regular expressions.
Every validation can have its own custom error message.
Token interpolation is implemented throughout all form text, with tokens expressed as ${variable}
All items of form text, defaults and validation values can be expressed as MathJs formula expressions
Data for token interpolation and expressions is drawn from form data values and passed-in data
Markdown can be used for all text attributes by including the prefix md~ (prefix is also customisable per form).
Each form row has 12 column divisions. You can control inline layout and field width by specifying a twelfths attribute for each field.

A Simple Form

{
    "fields": {
        "name": {
            "type": "string",
            "min": 3,
            "required": true,
            "matches": "^([A-Z][a-z]+([ ]?[a-z]?['-]?[A-Z][a-z]+)*)$"
        },
        "email": {
            "type": "string",
            "required": true,
            "email": true
        }
    }
}

A more complex form

{
    "fields": {
        "name": {
            "type": "string",
            "min": 3,
            "required": true,
            "matches": "^([A-Z][a-z]+([ ]?[a-z]?['-]?[A-Z][a-z]+)*)$"
        },
        "age": {
            "title": "Age",
            "placeholder": "How old are you?",
            "type": "number",
            "required": true,
            "positive": true,
            "integer": true,
            "min": [18, "Must be an adult"],
            "max": [123, "Must be younger than the longest lived person recorded"],
            "twelfths": 3
        },
        "address": {
            "fields": {
                "line1": {
                    "type": "string",
                    "min": 3,
                    "required": true,
                },
                    "line2": {
                    "type": "string"
                },
                "town": {
                    "type": "string",
                    "min": 3,
                    "required": true
                },
                "county": {
                    "type": "string"
                },
                "postcode": {
                    "type": "string",
                    "min": 3,
                    "required": true,
                    "uppercase": true
                }
            }
        },
        "email": {
            "type": "string",
            "required": true,
            "email": true
        }
    }
}

Known Issues

When designing a form spec, don't specify a positive rule along with a min rule, or Yup will ignore the min rule in favour of the positive rule.