DynamicForms library

How to use it

DynamicForms is designed to be simple and straightforward - no complex setup or configuration required.

The library offers 2 main functions that handle all the heavy lifting for you, including completing the Form Configuration with defaults and the form initialisation.

For 90% of use cases, makeForm is all you need!

First, import the module (see loading guide)

<script type="module">
    import { makeForm, getForm } '@simomosi/dynamic-forms';
</script>

TypeScript

The package exports the configuration types, so Form and Field Configurations can be written in their own files without casts. Only the form id is required, the library completes the rest.

import { makeForm, type FormConfiguration, type FieldConfiguration } from '@simomosi/dynamic-forms';

const city: FieldConfiguration = {
    name: 'city',
    fetch: { makeUrl: (data) => `/cities?country=${data.country}` },
    select: { clearOnParentVoid: false },
};
const configuration: FormConfiguration = {
    id: 'checkout',
    fields: [city],
    rules: [{ name: 'country', update: ['city'] }],
    behavior: { afterInit: () => console.log('ready') },
};
makeForm(configuration);

Exported types: FormConfiguration, FormHooks, UpdateRule, InitialisationRule, FieldConfiguration, FieldIoHooks, FieldFetchConfiguration, FieldHooks, SelectConfiguration, CheckboxConfiguration, UpdateData and DynamicForm. The package also exports the RemoteCallError class, the error of a failed remote call.

Properties

makeForm (formConfiguration)

Creates a form. An html form has at most one Form at a time: makeForm throws Form "id" already exists when the previous Form for that id has not been destroyed (see destroy).

Parameters

• {object} formConfiguration: the Form Configuration

Returns

• {DynamicForm} the form

getForm (id)

Returns the form with the given id, if it exists.

Parameters

• {string} id: the form id

Returns

• {DynamicForm | null} the form, or null if it does not exist

destroy ()

A method of the Form returned by makeForm. It removes the Form's listeners, so the fields no longer update each other, unregisters it from getForm, and aborts its remote calls in progress. Destroying it again does nothing.

A notify(), manualUpdate() or ready() still pending rejects with Form "id" was destroyed, and so do notify() and manualUpdate() called afterwards. A custom updateStatus Field Hook receives the abort signal, to stop its own remote calls.

Fields added after makeForm

Fields are discovered when the Form is created. To pick up fields added to the html form later, destroy the Form and create it again:

let form = makeForm(configuration);
// ...the page adds <input name="notes"> to the form...
form.destroy();
form = makeForm(configuration);

The new Form runs the Initialisation again, so its Initialisation Rules set the initial Values again. To keep the Values the user has changed meanwhile, create it without them:

form.destroy();
form = makeForm({ ...configuration, init: [] });