Dynamic Forms

https://simomosi.github.io/dynamic-forms/
Admin
Dynamic Forms is a lightweight TypeScript client library that automates progressive filtering,...
Tokens:5,295
Snippets:73
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install via package manager

Source: https://simomosi.github.io/dynamic-forms/start/installation

Use these commands to add the library to your project dependencies.

```bash
npm i @simomosi/dynamic-forms
```

```bash
yarn add @simomosi/dynamic-forms
```

```bash
pnpm i @simomosi/dynamic-forms
```

--------------------------------

### Install via CDN

Source: https://simomosi.github.io/dynamic-forms/start/installation

Include the library directly in your HTML file using the UNPKG CDN.

```html
<script src='https://unpkg.com/@simomosi/dynamic-forms@latest'></script>
```

--------------------------------

### Example Initialisation Rule Sequence

Source: https://simomosi.github.io/dynamic-forms/configurations/init-rules

A simple sequence of integers representing rule order.

```text
1
2
3
4
```

--------------------------------

### Initialize dynamic form

Source: https://simomosi.github.io/dynamic-forms/tutorial/create_instance

Create the form instance using the configuration object.

```javascript
const form = makeForm(formConfiguration);
```

--------------------------------

### Wait for Initialization with Async/Await

Source: https://simomosi.github.io/dynamic-forms/tutorial/initial_status

Use async/await syntax with the 'ready' function to handle the asynchronous initialization process. This allows for cleaner, more synchronous-looking code execution after the form is ready.

```javascript
async function initialiseForm() {
    let form = makeForm(formConfiguration);
    await form.ready();
    /* Your code here */
}
initialiseForm();
```

--------------------------------

### Single Initialisation Rule Configuration

Source: https://simomosi.github.io/dynamic-forms/configurations/init-rules

Configuration object for a single initialisation rule.

```APIDOC
## Single Initialisation Rule Configuration

### Description
These rules are used to manage fields initialization. Parameters in init rules can reference to form fields and external data.

### Method
Not Applicable (Configuration Object)

### Endpoint
Not Applicable (Configuration Object)

### Parameters
#### Request Body
- **name** (string) - Required - The field name.
- **value** (any) - Required - The field value. It can be any primitive value. This attribute has 2 purposes: It's passed to all other fields during initialisation; It will be the value automatically selected as the current field value; if the field type is _select_, the value must be available to be selected.

### Request Example
```json
{
  "name": "fieldName",
  "value": "someValue"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Define Initialisation Rule Configuration

Source: https://simomosi.github.io/dynamic-forms/configurations/init-rules

Structure for defining a field name and its initial value.

```javascript
const initialisationRuleConfiguration = {
    name: 'fieldName',
    value: any
};
```

--------------------------------

### Import dynamic-forms library

Source: https://simomosi.github.io/dynamic-forms/tutorial/create_instance

Import the makeForm function from the CDN.

```javascript
<script type="module">
        import { makeForm } from 'https://unpkg.com/@simomosi/dynamic-forms@latest';
    </script>
```

--------------------------------

### Import via ES6 Module

Source: https://simomosi.github.io/dynamic-forms/start/loading

Recommended method for modern environments using ES6 modules.

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

--------------------------------

### makeForm

Source: https://simomosi.github.io/dynamic-forms/dynamic-forms-module

Instantiates a new DynamicForm based on the provided configuration object.

```APIDOC
## makeForm

### Description
Instantiates a DynamicForm.

### Parameters
- **formConfiguration** (object) - Required - The form configuration object.

### Returns
- **DynamicForm** - A DynamicForm instance.
```

--------------------------------

### Import via CommonJS

Source: https://simomosi.github.io/dynamic-forms/start/loading

Standard method for Node.js or CommonJS-based environments.

```javascript
const { makeForm } = require('@simomosi/dynamic-forms');
```

--------------------------------

### Wait for Initialization with Promises

Source: https://simomosi.github.io/dynamic-forms/tutorial/initial_status

Execute code after the form initialization is complete by using the 'ready' function, which returns a Promise. This is useful for performing actions that depend on the initial state of the form.

```javascript
const form = makeForm(formConfiguration);
form.ready().then(() => {
    /* Your code here */
});
```

--------------------------------

### Import DynamicForms module

Source: https://simomosi.github.io/dynamic-forms/dynamic-forms-module

Import the necessary functions from the library using an ES module script.

```javascript
1
2
3
```

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

--------------------------------

### Fetch Configuration

Source: https://simomosi.github.io/dynamic-forms/configurations/fields-configuration

Defines remote data retrieval logic for DynamicSelect instances.

```APIDOC
## Fetch Configuration

### Description
Configures remote API calls for fields that depend on other form data.

### Properties
- **method** (string) - Optional - HTTP verb (default: 'GET').
- **makeUrl(data)** (function) - Required - Generates the URL for the remote call.
- **makeBody(data)** (function) - Optional - Generates the request body.
- **fullFetchConfig(data)** (function) - Optional - Provides a complete Fetch API configuration object.
```

--------------------------------

### Import via CDN Script Tag

Source: https://simomosi.github.io/dynamic-forms/start/loading

Direct inclusion using a script tag from the unpkg CDN.

```html
<script src = 'https://unpkg.com/@simomosi/dynamic-forms@latest'></script>
```

--------------------------------

### Import via CDN ES6 Module

Source: https://simomosi.github.io/dynamic-forms/start/loading

Loading the library as an ES6 module directly from the CDN.

```javascript
<script type="module">
    import { makeForm } from 'https://unpkg.com/@simomosi/dynamic-forms@latest';
</script>
```

--------------------------------

### IO Configuration

Source: https://simomosi.github.io/dynamic-forms/configurations/fields-configuration

Defines how the library interacts with the DOM element for reading and writing values.

```APIDOC
## IO Configuration

### Description
Defines the event listener and custom getter/setter functions for the field.

### Properties
- **event** (string) - Optional - The HTML event triggering status changes (default: 'change').
- **get(htmlElement)** (function) - Optional - Fetches the field value from the DOM node.
- **set(htmlElement, value)** (function) - Optional - Sets the field value on the DOM node.
```

--------------------------------

### Configure form fields and rules

Source: https://simomosi.github.io/dynamic-forms/tutorial/create_instance

Define the form configuration object including field fetching logic and update rules.

```javascript
const formConfiguration = {
    id: 'form_id',
    fields: [
        {
            name: 'field_two',
            fetch: {
                makeUrl: (data) => `https://url/to/api/`,
            }
        }
    ],
    rules: [
        {
            name: 'field_one',
            update: ['field_two']
        },
    ]
};
```

--------------------------------

### Configure Initial Field Values

Source: https://simomosi.github.io/dynamic-forms/tutorial/initial_status

Use the 'init' array in the form configuration to specify the name and initial value for fields that require initialization. Ensure API endpoints are defined in 'fields' for remote data retrieval.

```javascript
const formConfiguration = {
    id: 'form_id',
    fields:[/* ... */],
    rules: [/* ... */],
    init: [
        {
            name: 'field_one',
            value: '1'
        },
    ]
};
```

--------------------------------

### Define a select element configuration

Source: https://simomosi.github.io/dynamic-forms/configurations/fields-configuration

Extends the base configuration with specific properties for handling select elements, such as post-processing data and managing parent-child dependencies.

```javascript
const fieldConfiguration = {
    name: 'fieldName',
    io: /* ... */,
    fetch: /* ... */,
    behavior: /* ... */,
    select: { // Only for select elements
        postProcessData: (htmlElement, data) => { }, // Process data retrieved by remote call
        saveData: (htmlElement, data) => { }, // Manually save data in html (e.g. creating `<option value="value">'text'</option>` nodes)
        clearOnParentVoid: true, // True (default) to clear field content when subject is empty; false to trigger a remote call
    }
};
```

--------------------------------

### Select Element Configuration

Source: https://simomosi.github.io/dynamic-forms/configurations/fields-configuration

Properties and methods for handling select-option elements.

```APIDOC
## select.postProcessData(htmlElement, data)

### Description
Function to process data retrieved by remote call, useful for filtering or ordering data.

### Parameters
- **htmlElement** (node | NodeList) - Required - The html node.
- **data** (JSON | object[]) - Required - Data retrieved from the remote call.

### Returns
- **JSON | object[]** - Post-processed data.

## select.saveData(htmlElement, data)

### Description
Function to physically save post-processed data retrieved by a remote call as HTML.

### Parameters
- **htmlElement** (node | NodeList) - Required - The html node where data will be saved.
- **data** (JSON | object[]) - Required - Data retrieved from the remote call.

## select.clearOnParentVoid

### Description
Property which tells to clear field content when subject value is empty instead of triggering a remote call.
- **Type**: boolean
- **Default**: true
```

--------------------------------

### Complete Form Configuration Object

Source: https://simomosi.github.io/dynamic-forms/configurations/form-configuration

Defines the structure for configuring a dynamic form, including its ID, debug mode, behavior callbacks, and collections for fields, rules, and initialization.

```javascript
const formConfiguration = {
    id: 'form_id',
    debug: true,
    behavior: {
        beforeUpdate: (subjectName) => { }, // Executed before the update related events. Return false to block all updates
        afterUpdate: (subjectName) => { }, // Executed after the update related events
        beforeInit: () => { }, // Executed before form initialization
        afterInit: () => { } // Executed after form initialization
    },
    fields: [], // Collection of fields objects
    rules: [], // Collection of rules objects
    init: [] // Collection of init objects
};
```

--------------------------------

### Define a generic field configuration

Source: https://simomosi.github.io/dynamic-forms/configurations/fields-configuration

Use this structure to define custom input/output, remote fetch options, and field behaviors for standard form elements.

```javascript
const fieldConfiguration = {
    name: 'fieldName',
    io: {  // Customize field input/output
        event: 'change',
        get: (htmlElement) => { },
        set: (htmlElement, value) => { },
    },
    fetch: { // Remote call options
        method: 'GET',
        makeUrl: (data) => { },
        makeBody: (data) => { }, // JSON.stringify, formData, text...
        fullFetchConfig: {}, // Fetch complete configuration
    },
    behavior: {
        clear: (htmlElement) => { }, // Clear field from its content
        beforeUpdate: (htmlElement, data, subjectName) => { return true; }, // Executed before the remote call. Return false to block the update
        updateStatus: (htmlElement, data, subjectName) => { },
        afterUpdate: (htmlElement, data, subjectName) => { } // Executed after the remote call
    }
};
```

--------------------------------

### Field Configuration Structure

Source: https://simomosi.github.io/dynamic-forms/configurations/fields-configuration

The base configuration object for defining custom field behavior in dynamic forms.

```APIDOC
## Field Configuration Object

### Description
The field configuration object defines how a specific form field interacts with the dynamic-form system. Standard fields are discovered automatically; this configuration is only required for fields with custom behavior.

### Properties
- **name** (string) - Required - The HTML element name.
- **io** (object) - Optional - Groups properties for field input and output.
- **fetch** (object) - Optional - Groups properties for remote calls (required for DynamicSelect observers).
- **behavior** (object) - Optional - Groups properties related to field lifecycle and updates.
- **select** (object) - Optional - Specific configuration for select elements.
- **checkbox** (object) - Optional - Specific configuration for checkbox elements.
```

--------------------------------

### Form Configuration Object

Source: https://simomosi.github.io/dynamic-forms/configurations/form-configuration

The primary configuration object passed to the dynamicForms module for form instantiation.

```APIDOC
## Form Configuration Object

### Description
The formConfiguration object defines the structure, behavior, and rules for dynamic form generation.

### Properties
- **id** (string) - Required - The form identifier (plain text).
- **debug** (boolean) - Optional - Flag to enable console logging of rules before execution.
- **behavior** (object) - Optional - Lifecycle hooks for form events.
- **fields** (array) - Optional - Collection of field configurations.
- **rules** (array) - Optional - Collection of update rules.
- **init** (array) - Optional - Collection of initialization rules.

### Behavior Methods
- **beforeUpdate(subjectName)**: Called before form updates. Return false to abort.
- **afterUpdate(subjectName)**: Called after form updates complete.
- **beforeInit()**: Called before form initialization.
- **afterInit()**: Called after form initialization.
```

--------------------------------

### Define a checkbox element configuration

Source: https://simomosi.github.io/dynamic-forms/configurations/fields-configuration

Extends the base configuration with specific properties for checkbox elements, allowing toggling between boolean and value-based retrieval.

```javascript
const fieldConfiguration = {
    name: 'fieldName',
    io: /* ... */,
    fetch: /* ... */,
    behavior: /* ... */,
    checkbox: { // Only for checkbox elements
        booleanValue: true // True (default) to get element's value as boolean, based on the checked property; false to get the value property
    }
};
```

--------------------------------

### Checkbox Element Configuration

Source: https://simomosi.github.io/dynamic-forms/configurations/fields-configuration

Properties for handling checkbox elements.

```APIDOC
## checkbox.booleanValue

### Description
Property which tells if the field's value is boolean. When true, the field considers its value as boolean based on the html checked attribute; when false, it considers its value as string based on the value attribute.
- **Type**: boolean
- **Default**: true
```

--------------------------------

### getForm

Source: https://simomosi.github.io/dynamic-forms/dynamic-forms-module

Retrieves an existing DynamicForm instance by its unique identifier.

```APIDOC
## getForm

### Description
Returns a DynamicForm instance corresponding to the form id, if it exists.

### Parameters
- **id** (string) - Required - The form id.

### Returns
- **DynamicForm | null** - The DynamicForm instance or null if it does not exist.
```

--------------------------------

### Lifecycle Methods

Source: https://simomosi.github.io/dynamic-forms/configurations/fields-configuration

Methods used to manage the lifecycle and status updates of form fields.

```APIDOC
## beforeUpdate(htmlElement, data, subjectName)

### Description
Method called before triggering the field's status update. If the return value is false, the update is aborted.

### Parameters
- **htmlElement** (node | NodeList) - Required - The html node.
- **data** (JSON) - Required - Data obtained from additionalData and externalData functions in Update Rule Config.
- **subjectName** (string) - Required - The name of the subject who triggered the update (can be null if triggered manually).

### Returns
- **boolean** - false to abort the update, true otherwise.

## updateStatus(htmlElement, data, subjectName)

### Description
Method to update the field status, useful for updating attributes (display, disabled) and content.

### Parameters
- **htmlElement** (node | NodeList) - Required - The html node.
- **data** (JSON) - Required - Data obtained from additionalData and externalData functions in Update Rule Config.
- **subjectName** (string) - Required - The name of the subject who triggered the update.

### Returns
- **Promise<void>**

## afterUpdate(htmlElement, data, subjectName)

### Description
Method called after triggering the field's status update.

### Parameters
- **htmlElement** (node | NodeList) - Required - The html node.
- **data** (JSON) - Required - Data obtained from additionalData and externalData functions in Update Rule Config.
- **subjectName** (string) - Required - The name of the subject who triggered the update.

### Returns
- **boolean** - Currently unused.
```

--------------------------------

### Define Update Rule Configuration

Source: https://simomosi.github.io/dynamic-forms/configurations/update-rules

Structure for configuring field update rules, including field name, dependent fields, and external data functions.

```javascript
const updateRuleConfiguration = {
    name: 'fieldName',
    update: [],  // Array of form fields names to notify when events occour
    additionalData: [], // Array of other form field names to send to server
    externalData: (data, subjectName) => { } // Function which returns a json of data
};
```

--------------------------------

### Single Update Rule Configuration

Source: https://simomosi.github.io/dynamic-forms/configurations/update-rules

Defines the structure for a single update rule, specifying how fields should be updated based on various conditions and data sources.

```APIDOC
## Single Update Rule Configuration

These rules are used to manage fields update.

### `updateRuleConfiguration` Object

This object defines the configuration for a single update rule.

#### Fields

- **`name`** (string) - Required - The field name inside the form.
- **`update`** (array) - Optional - An array of form fields names to notify when events occur.
- **`additionalData`** (array) - Optional - An array of other form field names to send to the server.
- **`externalData`** (function) - Optional - A function which returns a JSON of data.

### `externalData (data, subjectName)` Function

A function to collect other data used in the update function but external to the form (e.g. a timestamp).

#### Parameters

- **`data`** (object) - Required - Data obtained from the additional data function.
- **`subjectName`** (string | null) - Optional - The name of the subject who triggered the update. It can be null if the update is triggered manually.

#### Returns

- **`object`** - An object with external data values (key-value format).

### Request Example

```json
{
  "name": "fieldName",
  "update": ["field1", "field2"],
  "additionalData": ["field3", "field4"],
  "externalData": "(data, subjectName) => { return { timestamp: new Date().toISOString() }; }"
}
```

### Response Example

```json
{
  "message": "Update rule configured successfully"
}
```
```

--------------------------------

### Define HTML form structure

Source: https://simomosi.github.io/dynamic-forms/tutorial/create_instance

The base HTML form structure containing select elements to be managed by the library.

```html
<form id='form_id'>
    <label for="field_one">Field one</label>
    <select id="field_one" name='field_one'>
        <option value="" selected></option>
        <option value="1">One</option>
        <option value="2">Two</option>
    </select>

    <label for="field_two">Field two</label>
    <select id="field_two" name='field_two'>
        <option value="" selected></option>
    </select>
</form>
```
Tokens:
Raw