Boost-Web Forms

What is it?

An opinionated, small form generator library for javascript objects.

It basically turns this object:

let obj = {
    userName: "",
    password: "",
    rememberMe: true
}

without any configuration or schema, into this:

Why boost-web-forms?

• Works with vanilla JS
• React and svelte support
• No schema or configuration needed to generate forms (although supported)
• Plugins for popular UI kits (bootstrap, bulma, etc.)
• API is as close to the DOM API as possible

Installation

npm i boost-web-forms

or

yarn add boost-web-forms

You may want to include plugins

• boost-web-forms-react for react
• boost-web-forms-svelte for svelte

Visit boost-web-forms-plugins for all plugins.

Quick Start

To generate the above login form,

1. Create your model:

let forObj = {
    email: '',
    password: '',
    rememberMe: false
}

2. Render the form on the DOM:

For vanilla javascript:

import {renderForm} from 'boost-web-forms'

renderForm(forObj, document.body)

For React:

import {ReactForm} from 'boost-web-forms-react'

<ReactForm forObject={forObj} />

Look at boost-web-forms-react

For Svelte:

import SvelteForm from 'boost-web-forms-svelte'

<SvelteForm forObject={forObj} />

Look at boost-web-forms-svelte

This will automatically render the following HTML:

<form>
  <div>
    <label for="userName">User Name</label> 
    <input name="userName" colspan="1" id="userName" type="name" value="">
  </div>
  <div>
    <label for="password">Password<span style="color: red;">*</span></label> 
    <input name="password" colspan="1" id="password" required="" type="password" value="">
  </div>
  <div>
    <input type="checkbox" name="rememberMe" colspan="1" id="rememberMe" checked=""> 
    <label for="rememberMe" style="display: inline-block;">Remember Me</label>
  </div>
  <div> 
    <input type="submit" name="$$submit" colspan="1" id="$$submit">
  </div>
</form>

Quick Start 2

Let's generate form for a more complicated registration model:

let forObj = {
    name: '',
    email: '',
    password: '',
    confirmPassword: '',
    birthDate: '',
    packages: ['newsLetter', 'premiumSupport'],
    preferredTime: '00:00:00',
    rating: 0
}

Will automatically render:

You can see that:

• Field types were auto guessed from field names
• Humanizes label texts (confirmPassword becomes Confirm Password)
• Generates native <input> tags
• Sets required fields for password inputs

Configuring the Form

While the library includes good set of defaults, the form can be configured as needed.

All valid HTML <form> tag attributes can be used. For example:

const formConfig = {
    method: 'POST',
    enctype: 'multipart/form-data',
    class: 'form columns',
    onsubmit: e => {alert('Submitting...')}
}

Then create a complete config and pass the configuration to renderForm:

renderForm(forObj, document.body, formConfig)

All available form configuration options

| Option | Type | Description | Default Value | | --- | ----------- | --- | ---------| | readonly | boolean | Makes all fields readonly | false | | hideLabels | boolean | Hides labels of all fields | false | | excludeSubmitButton | boolean | Doesn't include a submit button automatically | false | | scale | number | Zoom factor for fields. Shows large or small fields | 1 | | All valid html <form> attributes | - | Will show up in the <form> tag. These include id, action, style, class, onsubmit, etc. | - |

Configuring Fields

Every individual field can be configured in the form configuration using fieldsConfig key. For example, to make the password field readonly:

const options = {
    fieldsConfig: {
        password: {readonly: true}
    }
}

Note: All valid HTML input attributes can be used here.

All available field configuration

| Option | Description | Type | Default Value | | --- | ----------- | ---------| ---- | | readonly | Makes the field not editable | boolean | false | | label | Text that's shown in the label | string | Automatically guessed | | hideLabel | Whether to generate label for the input | boolean | false | | type | Specify the type of value for the field | string | Automatically guessed | helpText | Specify a description for the input | string | '' | validate | Specify validations for the field | - | Refer section: Validation | scale | Specify whether to show big or small input controls. | number | 1 | colSpan | Column span, if the form has more than 1 column | number | 1 | maxlength | Maximum length of text allowed | string | '' | | multiple | If multiple values are allowed (only for select and radio types) | boolean | false | | choices | Sets of choices the user can pick from (only for select and radio types) | string[] or Object with key-value pairs | null | | readonly | Whether the field is read-only | boolean | false | | All valid html <input> attributes | - | Will show up in the <input> tag. These include id, placeholder, style, class, onchange, etc. | - |

Field Types

The type of a field can be specified using type attribute in the field config. All <input> tag's type attribute values are supported. For example, to set types for 'confirm password' and comment fields:

const forObj = {
    name: '',
    password: '',
    confirmPassword: '',
    comment: ''
}

const formConfig = {
    fieldsConfig: {
        confirmPassword: {type: 'password'},
        comment: {type: 'textarea', label: 'Any Comments?'}
    }
}

Supported field types are:

'text' | 'email' | 'password' | 'file' | 'files' | 'select' | 'autocomplete' |
'checkbox' | 'toggle' | 'number' | 'date' | 'time' | 'textarea' | 'markdown' | 'reCaptcha' |
'radio' | 'html' | 'color' | 'datetime-local' | 'month' | 'year' | 'range' | 'reset' | 'tel' | 'url' | 'week' |
'multiselect-checkbox' | 'composite' | 'version' | 'avatar' | 'city' | 'country' | 'ipv4' | 'ipv6' | 'guid' |
'isbn' | 'location' | 'language' | 'money' | 'timezone' | 'title' | 'gallery' | 'submit'

Note: Not all the above types can be rendered right now. It is a work in progress.

Select types

To use select (drop-down) field type use choices field to specify options:

let options = {
    fieldsConfig: {
        userType: {
            type: 'select',
            placeholder: '-- Select User Type --',
            choices: ['Admin', 'Guest', 'Member']
        }
    }
}

Will render a select input like:

<select id="userType" name="userType">
  <option value="">-- Select User Type --</option>
  <option value="Admin">Admin</option>
  <option value="Guest">Guest</option>
  <option value="Member">Member</option>
</select>

To use different values and labels for the options, use an object with key-value pairs:

choices: {AD: 'Admin', GU: 'Guest', ME: 'Member'}

Will render a select input like:

<option value="AD">Admin</option>
<option value="GU">Guest</option>
<option value="ME">Member</option>

Radio types

To use radio (choices) field type use:

let options = {
    fieldsConfig: {
        userType: {
            type: 'radio',
            choices: ['Admin', 'Guest', 'Member']
        }
    }
}

Will render radio inputs like:

<label>
  <input name="userType" type="radio" value="Admin"> Admin
</label>
<label>
  <input name="userType" type="radio" value="Guest"> Guest
</label>
<label>
  <input name="userType" type="radio" value="Member"> Member
</label>

To use different values and labels for the options, use an object with key-value pairs:

choices: {AD: 'Admin', GU: 'Guest', ME: 'Member'}

Multiple choices (select and radio types)

To enable multiple values for both select and radio types, just set multiple to true

let options = {
    fieldsConfig: {
        packages: {
            type: 'radio',
            choices: ['Newsletter', 'PremiumSupport'],
            multiple: true
        }
    }
}

This will change the field type to set of checkboxes as:

Validation

Validation specs can be added to either on the form level or individual fields. There are good set of validation functions already included in this library:

import {notEmpty, validName} from 'boost-web-forms'

const options = {
    fieldsConfig: {
        name: {validate: [notEmpty, validName]}
    }
}

The validate field would accept:

• A custom method that returns an error message
• A built-in validate method (like notEmpty)
• A built-in validator generator (like getMinLenValidator(4))
• An array of, any of the above
• An async server side validator, like:

async (val) => {
    return 'true' == await (await fetch('http://server.com/username-taken/' + val)).json()
        ? 'User name already taken'
        : ''
}

Then this validation result can be rendered:

import {validateForm} from 'boost-web-forms'

let validationResult = validateForm(forObj)
renderForm(forObj, document.body, formConfig, validationResult)

Note: If your validator is an async method (includes api calls for example), you should you validateFormAsync() instead.

let validationResult = await validateFormAsync(forObj)

Built-in validation methods:

| Method | Description | For input types | Usage | | --- | ----------- | ---------| ---- | | notEmpty | Checks if input is empty, null or whitespace | any | notEmpty | | validName | Check if string is a valid personal name | string | validName | | getMinLenValidator | Returns a validator that checks minimum string length | string | getMinLenValidator(4) | | getStrongPasswordValidator | Returns a validator that checks for a password's strength | string | getStrongPasswordValidator({minLength: 6, specialChars: true}) | fileTypeValidator | Returns a file type validator | file | fileTypeValidator('image/png') | imgTypeFile | Checks if an uploaded file is a valid image | file | imgFileType | maxFileSize | Checks if an uploaded file size exceeds the given size | file | maxFileSize

Using custom validation functions is also easy. Just return an error message if it should fail, empty string otherwise.

const options = {
    fieldsConfig: {
        age: {validate: val => (val < 18 ? 'Age must be 18 or above' : '')}
    }
}

Validations can also be done on the form level as:

const options = {
    validate: form => (form.password != form.confirmPassword ? 'Passwords do not match.' : '')
}

To run validations manually:

import {validateForm} from 'boost-web-form'

let validationResult = await validateForm(forObj, formConfig)

Would give a validation result such as:

validationResult = {
    hasErrors: true,
    message: '', // Form level validation errors, if any
    fields: {
        email: {hasError: true, message: 'Please, fill in this field.'},
        password: {hasError: true, message: 'Password is too weak.'},
        name: {hasError: false, message: ''}
    }
}