Form DSL

The Models form DSL is used to customise the create and edit forms that are generated for each model. The form DSL has quite a few options as the model create and edit forms are highly customizable.

The form DSL is used to construct create and edit form controls (for example checkboxes, or text inputs) for a model record. Each key in the form object represents one of your model's fields.

The type of form control used for each field can be defined explicitly, or determined by Linz (the default) based on the fields data type, as specificed when defining the field with Mongoose.

Each form control comes in the form of a widget, and can be explicitly altered by providing a different Linz widget, or creating your own widget.

form should be an object. It should contain a key, labelled with the name of the model field you're providing information for.

For example, if you had a model with the fields name and email your form DSL might look like:

form: {
    name: {
        // configure the edit widget for the name field
    },
    email: {
        // configure the edit widget for the name field
    }
}

Each field object can contain the following top-level keys:

label
placeholder
helpText
type
default
list
visible
disabled
fieldset
widget
required
query
transform
transpose

These allow you to describe how the model create and edit forms should function.

Specialized contexts#

There are two specialized contexts in which the form DSL operates:

When creating a model
When editing a model

From time to time, you'll want to have different settings for one field, based on the context. Linz supports this through use of create and edit keys. Each of the above top-level keys can also be provided as a child of either create and edit. For example:

form: {
    username: {
        create: {
            label: 'Create a username',
            helpText: 'You can\'t change this later on, so choose wisely.'
        },
        edit: {
            label: 'The person\'s username',
            disabled: true,
            helpText: 'Once created, you can\'t edit the username.'
        }
    }
}

You can also use a combination of the default context and the specialized contexts create and edit contexts, for example:

form: {
    username: {
        label: 'The person\'s username',
        edit: {
            label: 'Uneditable username'
        }
    }
}

On the create form, the label for the username field will be The person's username, but Uneditable username on the edit form.

The specialized create and edit contexts always supersede the default context.

{field-name}.label#

The label property is optional. If not provided, it takes the label from the Models label DSL. If a label hasn't been provided for that particular model field, it simply shows the name of the field itself.

The label property gives you an opportunity to customize it explicitly for the create and edit views.

{field-name}.placeholder#

When you have the field of an appropriate type (such as text field), you can define the placeholder which sets the content of the HTML's <input> tag placeholder attribute.

When used in conjunction with a ref field, it can be used to create optional references. For example, a select in which the first option has no value but contains the placeholder value as the label.

{field-name}.helpText#

The helpText property can be used to supply additional text that sits below the form input control, providing contextual information to the user filling out the form.

{field-name}.type#

The type property is intended to help Linz with two things:

Manage the data that the field contains in an appropriate manner.
To determine which widget to use if the widget property wasn't provided.

type accepts the following strings:

array to render checkboxes for multiple select.
boolean to render radio inputs.
date to render a date input.
digit to render a text input with a regex of [0-9]*.
documentarray to render a custom control to manage multiple sub-documents.
email to render an email input.
enum to render a select input.
hidden to render a hidden input.
number to render a text input with a regex of [0-9,.]*.
password to render a password input.
string to render a text input.
tel to render a tel input with a regex of ^[0-9 +]+$.
text to render a text input.
url to render a url input.

The default widget, and the widget for all other types is the text widget.

{field-name}.default#

The default property can be supplied to define the default value of the field. The default if provided, will be used when a field has no value.

If the default property is not provided, Linz will fallback to the default value as provided when defining the Mongoose schemas.

{field-name}.list#

The list property is a special property for use with the enum type. It is used to provide all values from which a list field value can be derived.

Please bear in mind, that the list property is not involved in Mongoose validation.

The list property can either be an array of strings, or an array of objects.

For example, an array of strings:

list: ['Dog', 'Cat', 'Sheep'];

If an array of objects is supplied, it must be in the format:

form: {
    sounds: {
        list: [
            {
                label: 'Dog',
                value: 'woof.mp3',
            },
            {
                label: 'Cat',
                value: 'meow.mp3',
            },
            {
                label: 'Sheep',
                value: 'baa.mp3',
            },
        ];
    }
}

There is also a more advanced use case in which you can provide a function which Linz will execute. This will allow you to generate at run time rather than start time, after Linz has been initialized:

form: {
    sounds: {
        list: function (cb) {
            return cb(null, {
                label: 'Dog',
                value: 'woof.mp3'
            },
            {
                label: 'Cat',
                value: 'meow.mp3'
            },
            {
                label: 'Sheep',
                value: 'baa.mp3'
            });
        }
    }
}

{field-name}.visible#

The boolean visible property can be set to a value of false to stop the field from being rendered on the form.

{field-name}.disabled#

The boolean disabled property can be set to a value of true to render the input field, with a disabled attribute.

{field-name}.fieldset#

The fieldset property should be supplied to control which fields are grouped together under the same fieldset.

The fieldset property should be human readable, such as:

form: {
    username: {
        fieldset: 'User access details';
    }
}

{field-name}.widget#

The widget property can be set to one of the many built-in Linz widgets. For example:

form: {
    sounds: {
        widget: linz.formtools.widget.multipleSelect();
        list: [
            {
                name: 'Dog',
                value: 'woof.mp3',
            },
            {
                name: 'Cat',
                value: 'meow.mp3',
            },
            {
                name: 'Sheep',
                value: 'baa.mp3',
            },
        ];
    }
}

{field-name}.required#

The boolean required property can be set to true to require that a field has a value before the form can be saved (using client-side) validation.

{field-name}.query#

The query property can be used to directly alter the Mongoose query object that is generated while querying the database for records to display.

query should be an object with the following keys:

filter
sort
select
label

{field-name}.transform#

The transform property will accept a function with the signature:

transform(field, record);

If provided, it will be executed before a record is saved to the database. It is useful if you need to manipulate client side data before it is stored in the database.

In some instances, client side data requirements are different from that of data storage requirements. transform in combination with transpose can be used effectively to manage these scenarios.

{field-name}.transpose#

The transpose property will accept an object with context.

Currently, the following contexts are accepted:

form Used within context of forms and creating and editing model records.
export Only used for exporting records.

{field-name}.transpose.form#

The transpose.form property will accept a function with the signature:

transpose.form(field, record);

If provided, it will be executed before a field's value is rendered to a form. It is useful if you'd like to manipulate the server-side data that is rendered to a form.

In some instances, data storage requirements are different form that of client side data requirements. transpose in combination with transform can be used effectively to manage these scenarios.

{field-name}.transpose.export#

The transpose.export property can accept a function with the signature:

transpose.export (val) => Promise

If provided, it will be executed before a field's value is exported. It is useful if you'd like to manipulate the server-side data that is rendered to the export csv.