README

A lightweight Javascript Form Library to handle HTML forms and their inputs.

Installation

npm install forma

Also available as download or CDN:

// Referencing downloaded file
<script type='application/javascript' src="path/to/[email protected]"></script>

// Or referencing CDN
<script type='application/javascript' src="https://www.tools.rjdesignmanagement.ch/forma/downloads/[email protected]"></script>

If you are planning on using Forma's LightBox, then make sure to add the Forma CSS:

// Referencing downloaded file
<script type='application/javascript' src="path/to/[email protected]"></script>

// Or referencing CDN
<script type='application/javascript' src="https://tools.rjdesignmanagement.ch/forma/downloads/[email protected]"></script>

Usage

Setup

<form id="someForm" class="forma" action="/request/path/or/file.php">

    <label class="forma-label">Some input
    
        <input name="my-email-input"
               type="email">

    </label>
    
    <label class="forma-label">Some input
        
        <input name="myPasswordInput"
               data-forma-strict-password
               type="password">
    
    </label>
    
    <!-- some more inputs here... -->

</form>

Basic Usage

let myForma = new Forma('#someForm'); // any selector possible

myForma.onServerSubmit({
    lightbox: true,
    
    // more settings here ...
    
    validation: true
});

// or

myForma.onSubmit((data, event) => {
    
    // Do something here on submit 
    // (no request sent to server)
    
});

Accessing Form Elements

Forma makes it easier to access your inputs directly by references them with their name tag.

// references name tag
let passwordInput = myForma.inputs.myPasswordInput;

// or
let emailInput = myForma.inputs['my-email-input'];

If an input (or textarea) doesn't have a name it will be accessible as myForma.inputs.noName[<index>] .

Forma Properties

| Property | Description | | ----------- | ------------------------------------------------------------ | | action | Get the action attribute of the <form> element. It is mainly used to set the default path of the form submission. | | formatype | Collection of all data-formatype attributes that are set in the <form> element. If you for instance had an element in your <form> with data-formatype="foo" , you could access it like this: myForm.formatype["foo"] . Otherwise it will be accessible like this: myForm.formatype.noName . | | inputs | Collection of all <input> elements in the <form> . If the inputs have a name tag with a valid name (such as foo ), you can access any specific input like this: myForm.inputs["foo"] . Otherwise the input will be accessable like this: myForm.inputs.noName . | | options | Collection of all <option> elements in the <form> . If the options have a name tag with a valid name (such as foo ), you can access any specific option like this: myForm.options["foo"] . Otherwise the option will be accessable like this: myForm.options.noName . | | radios | Collection of all <input type="radio"> elements in the <form> . If the radios have a name tag with a valid name (such as foo ), you can access any specific radio like this: myForm.radios["foo"] . Otherwise the radio will be accessable like this: myForm.radios.noName . | | selects | Collection of all <select> elements in the <form> . If the selects have a name tag with a valid name (such as foo ), you can access any specific select like this: myForm.selects["foo"] . Otherwise the select will be accessable like this: myForm.selects.noName . | | types | Collection of all <input> elements in the <form> sorted by type . | | setup | Accepts an object with settings (see chapter Settings). For example: this.setup = { lightbox: true, path: /foobar } |

Forma Methods

| Method | Description | | ---------------------------------- | ------------------------------------------------------------ | | showSubmitButton(show) | show : true , false | | onServerSubmit(settings) | Registers an EventListener to the form and sends the form request to the server with custom settings on form submitsettings : see chapter Settings for all possible settings (must be given as an object) | | onSubmit(callback) | Listens to form submission and executes the given callback function. | | reset() | Resets the <form> to it's default state (does not effect the Forma settings, only HTML) | | selectedOption(selectionName) | Returns the selected <option> in the <form> , where the parent (<select>) has the given name attribute. | | selectedRadio(radioName) | Returns the selected <input type="radio"> with the given name attribute. | | unselectedOptions(selectionName) | Returns the unselected <option> elements, where the parent (select) has the given name attribute. | | unselectedRadios(radioName) | Returns the unselected <input type="radio"> elements with the given name attribute. |

Settings

| Setting | Description | | ------------------------------------------------------------ | ------------------------------------------------------------ | | baseURL | Base URL of the current server. Retracted from window.location.origin if nothing else is set. | | before | Callback for any custom actions that should be executed before submitting the form. | | buttonHide | 0 : Default setting, submit button is left alone on submit 1 : Hides the submit button on submit (shows after submit) 2 : Hides the submit button on submit (keeps it hidden) | | data | Data that should be send to the server when form is submitted. As default it takes the data from the form (FormData). | | error | Callback for any custom actions that should be executed if an error occurs after submitting the form to the server. | | finally | Callback for any custom actions that should always be executed after submitting the form to the server. | | formaActiveClass | If you use custom classes to define if an element is visible or not, you can define that class here. It will then be toggled everytime an element needs to be visible. | | globalMessageDisplayTime | The amount of milliseconds before the global message is hidden after being shown (only works if messageBox = 'global'). Default 5000 | | headers | HTTP headers that should be sent along with the form submit. | | jmode | true , then default settings are overriden and the jmode preset is used (see chapter jmode) | | lightbox | If this setting is set to true , then Forma creates a lightbox that is toggled whenever you submit the form. | | lightboxSource | Set your own spinner by passing the reference to the spinner image as a String (e.g. "/assets/png/spinner.png"). Default: undefined (with own spinner). | | loadingGIF | You can pass a query selector to locate your custom loading GIF in the DOM. The loading GIF is then toggled when the form is submitted. Is ignored if loadingGIF not found are setting is set to false. | | messageBox | false : default, server response ignored"global" : server response shown in global divselector : server response shown in custom divOnly the first response message is displayed in global div. | | messageDisplayTime | The amount of milliseconds the message box (see messageBox) should be displayed, before being hidden again. If 0 or false it will stay unhidden. | | method | post : defaultupdate : sends an update request instead of postpath : sends a path request instead of post | | path | You can define the path that the form should submit to here. Otherwise Forma looks for the path in the action attribute of the <form> . If Forma can't find any path it will submit to the base url. | | reloadOnError | true if the page should reload on error. | | reloadOnFinally | true if the page should reload on finally. | | reloadOnSuccess | true if the page should reload on success. | | success | Callback for any custom actions that should be executed after submitting the form to the server, if no errors occured. | | timeout | Number of milliseconds before the request times out. Default: 20000 | | trash | true if you want specific inputs to have a trash can to easily clear the input. The inputs need to be wrapped in the <label> tags to make it work properly. To enable it on your inputs add data-forma-trash to each of them. Only works on the following input types: email, password, search, tel, text, url, and also all <textarea> tags. | | trashPosition: { bottom: "10px", left: "10px", right: false, top: "calc(50% - 4px)", zIndex: 10000} | Pass an object to trashPosition with the properties bottom, left, right, top, zIndex. Default: all properties false | | validation | true if you want real-time validation on your input forms. You can then add attributes such as maxLength="5" to any input or data-forma-mixed-cases to your type="password" input. See chapter Validation for more. |

JMode

JMode is a setting that defines some settings as a preset. These settings were defined by R. J. Design Management and are listed here:

{
    baseURL: window.location.origin,
    before: () => {},
    buttonHide: 2,
    data: undefined,
    error: () => {},
    finally: () => {},
    formaActiveClass: '.active',
    globalMessageDisplayTime: 5000,
    headers: {},
    jmode: true,
    lightbox: false,
    loadingGIF: '.loadinggif',
    messageBox: '.formsuccess',
    messageDisplayTime: 0,
    method: 'post',
    path: form.action || '',
    reloadOnError: false,
    reloadOnFinally: false,
    reloadOnSuccess: false,
    success: () => {},
    timeout: 20000,
    trash: false,
    trashRight: false,
    trashTop: false,
    validation: false
}

To switch jmode on just enable it in the onServerSubmit(settings) like this:

myForma.onServerSubmit({
    jmode: true
});

Validation

Forma offers a more extensive real-time client-side validation than the HTML5 standard. To enable the validation just set the validation setting to true in the onServerSubmit(settings), like this:

myForma.onServerSubmit({
    validation: true
});

To make it work though you need to let Forma know which inputs need to be validated. In the next part, we will explain how this is done.

Inputs / Textareas

All inputs and textareas can add the following attributes to enable the real-time validation:

| Attribute | Description | | ----------- | ------------------------------------------------------- | | maxLength | Maximum amount of characters allowed | | minLength | Minimum amount of characters allowed | | required | Inputs that are required for correct submission of form |

Email

If the validation setting is set to true then Forma automatically validates all email inputs.

Password Inputs

Password inputs have more attributes that are listed below:

| Attribute | Description | | ----------------------------- | ------------------------------------------------------------ | | data-forma-mixed-characters | Checks if password has at least 1 normal and 1 special character ($, @, %, ...) | | data-forma-mixed-cases | Checks if password has lower- and uppercase characters | | data-forma-strict-password | Enables all of the listed attributes here (instead of listing all the attributes separatly) | | data-forma-with-number | Checks if password has at least 1 number |

All other validation attributes that were listed in the beginning of this chapter also apply to the password input.

<label>Some password

    <input type="password" data-forma-strict-password required>
        
</label>

Trash

The trash setting allows you to put a trash can in some of the inputs so that they can be cleared easily. The following inputs are supported:

• email
• password
• search
• tel
• text
• url
• textarea

To make this work you need to enable the trash setting in the onServerSubmit(settings) method like this:

myForma.onServerSubmit({
    trash: true
});

Then you need to add the data-forma-trash attribute to the inputs you want to be affected.

<label>Some password

    <input type="password" data-forma-trash>
        
</label>