Reform.js
Modern forms finally made easy.
Note: In order to use this JavaScirpt plugin an instance of jQuery 3.0 or higher is required. You can get jQuery here.
Table of Contents
- Installation
- Sample Useage
- Input / Textarea
- Checkbox / Radio
- Select
- JavaScript Settings
- Events
- Information
Installation
Reform.js is available as a classic download, via CDN and via NPM.
Download
Download latest Reform.js (compressed)
CDN
<script src="https://cdn.jsdelivr.net/npm/reform.js@1/dist/reform.min.js"></script>
NPM
npm install reform.js
Sample Useage
This chapter shows some exsamples how to correctly use Reform.js.
Setup and passing Settings
Besides adding the reform.js file at the end of your HTML-file right before closing the body-Tag after the jQuery file you have to add the following line into your JavaScript file:
$(document).ready(function() { $('form').reform(); })
You can also pass some settings for reform by simply changing the code above like this:
$(document).ready(function() { $('form').reform({ debugMode: true }); })
Input / Textarea
Sample Build
<!-- basic input --> <label> <p>Sample</p> <input type="text" name="sample"> </label> <!-- basic textarea --> <label> <p>Sample</p> <textarea name="sample"></textarea> </label> <!-- full example--> <label class="rf-req rf-val" rf-val="email"> <p>Sample</p> <input type="email" name="sample"> </label>
CSS / LESS Rules
// default label {} label > p {} label > input {} // error label.rf-error {} label.rf-error > p {} label.rf-error > input {} // error information label.rf-error > p.rf-error-info {}
Class List
Class | Description |
---|---|
.rf-req | Require this input field. (see minLength setting) |
.rf-val | After passing the required minLength the value gets validated for the setting. You can either pass the validation type via the attribute rf-val="" or Reform.js takes the input type for validation. This is the importance-ranking:
|
Attribute List
Attribute | Description |
---|---|
rf-val=" {string} " | This attribute contains the validation type you want the value to be validated for. These are all types:
|
Checkbox / Radio
Sample Build
<!-- basic checkbox --> <label class="rf-checkbox"> <input type="checkbox" name="sample"> <p>Sample</p> </label> <!-- basic radio --> <label class="rf-radio"> <input type="radio" name="sample"> <p>Sample</p> </label> <!-- required checkbox or radio --> <label class="rf-checkbox rf-req"> <input type="checkbox" name="sample"> <p>Sample</p> </label>
CSS / LESS Rules
// default checkbox and radio label.rf-checkbox, label.rf-radio {} label.rf-checkbox > p, label.rf-radio > p {} label.rf-checkbox > input, label.rf-radio > input {} // checkbox styling label.rf-checkbox > p::before {} label.rf-checkbox > p::after {} // radio styling label.rf-radio > p::before {} label.rf-radio > p::after {} // checked checkbox styling label.rf-checkbox > input:checked + p::before {} label.rf-checkbox > input:checked + p::after {} // checked radio styling label.rf-radio > input:checked + p::before {} label.rf-radio > input:checked + p::after {} // error label.rf-checkbox.rf-error, label.rf-radio.rf-error {} label.rf-checkbox.rf-error p, label.rf-radio.rf-error p {} label.rf-checkbox.rf-error p::before, label.rf-radio.rf-error p::before {}
Class List
Class | Description |
---|---|
.rf-req | Require this checkbox or radio field. |
.rf-radio | This is for a radio field. |
.rf-checkbox | This is for a checkbox field. |
Grouping
You can group checkboxes or radios with required fields. With that, only one of the checkboxes or radios have to be checked to pass the requirement. In addition, checkboxes behave like radio buttons but a checked element can be unchecked by an user.
This for example can be used to request genders optionally with radio-button styling:
<p>Gender</p> <div class="rf-group"> <label class="rf-radio rf-req"> <input type="checkbox" name="gender" value="female"> <p>Female</p> </label> <label class="rf-radio rf-req"> <input type="checkbox" name="gender" value="male"> <p>Male</p> </label> </div>
Select
Sample Build
<label class="rf-select"> <p>Sample</p> <select name="sample" placeholder="Please select ..."> <option>Option 1</option> <option>Option 2</option> <option>Option 3</option> </select> </label>
Note: As you can see in the code sample above Reform.js adds the posibility to add a placeholder to your select. Adding the
placeholder=""
attribute to your select will act just like you expect to.
CSS / LESS Rules
// default select label.rf-select {} label.rf-select > p {} label.rf-select > select {} label.rf-select::after {} // error label.rf-select.rf-error{} label.rf-select.rf-error > p {} label.rf-select.rf-error > select {}
Class List
Class | Description |
---|---|
.rf-req | Require this checkbox or radio field. |
.rf-select | Defines that this label contains an select. |
JavaScript Settings
General Settings
this.defaults = { ajax: {}, convert: 'serialize', debugMode: false, lang: 'en', localization: { ... }, type: 'post', url: null, validation: { ... } };
Setting | Type | Default | Description |
---|---|---|---|
ajax | object | {} | Since Reform is build uppon the jQuery.ajax() function you can fully manipulate the ajax as noted in the jQuery.ajax() documentation. This excludes settings Reform.js overwrites. ( data , type and url ) |
convert | string | 'serialize' | This setting determines how the input-data within your reform element should be converted for sending. These are the default convertion types:
|
debugMode | boolean | false | If true, Reform.js logs every single step it processes. (initalizing, validating, sending) |
lang | string | 'en' | Every message your user can see can be manipulated via the localisation setting. Read more about Localisation. |
localisation | object | { ... } | See more about in the sub-section Localisation Settings Description |
type | string | 'post' | The send-type can be manipulated with this setting. It is the type-setting of the jQuery.ajax() function and can be manipulated with this setting. The send-type can be overwritten by the form's mthod setting and additionally can also be overwritten by the rf-type attribute. This is the ranking:
|
url | string | null | The destination url the data should be sent to. This could be overwritten with action or rf-url attribute. This is the ranking:
|
validation | object | { ... } | See more about in the sub-section Validation Settings Description |
Localisation Settings
this.defaults = { localization: { en: { errorMinLength: 'Please enter at lease 2 characters.', errorValidationUrl: 'Web url not valid.', errorValidationEmail: 'Email address not valid.', errorValidationPhone: 'Phone number not valid.', errorValidationCustom: 'Field could not be validated.' } } };
Key | Default |
---|---|
errorMinLength | Please enter at lease 2 characters. |
errorValidationUrl | Web url not valid. |
errorValidationEmail | Email address not valid. |
errorValidationPhone | Phone number not valid. |
errorValidationCustom | Field could not be validated. |
Validation Settings
this.defaults = { validation: { minLength: 2, displayRequireErrorInfo: false, displayValidationErrorInfo: true, submitOnRequireError: false, submitOnValidationError: false } };
Setting | Type | Default | Description |
---|---|---|---|
minLength | integer | 2 | The minimum length of characters a required field has to contain. |
displayRequireErrorInfo | boolean | false | If true any field that does not pass the required parameters gets a p.error-info element added. |
displayValidationErrorInfo | boolean | true | If true any field that can not be validated gets a p.error-info element added. |
submitOnRequireError | boolean | false | Also submits a form if some input fields does not pass the required parameters. |
submitOnValidationError | boolean | false | Also submits a form if some input fields can not be validated. |
Events
Example code for calling an event
var reform = $(element).reform(); reform.on('rf-validation-after', function(reformParent) { console.log('Reform is validated.'); });
All events
Event | Parameters and Description |
---|---|
rf-initialize | Gets called after Reform got initialized.
|
rf-send-before | Gets called after a user started submitting the Reform form.
|
rf-validation-before | Gets called after successfull submit-start and before the validation.
|
rf-validate-custom | Gets called if a custom value is placed in the rf-val attribute.
|
rf-validation-after | Gets called after the validation is completed.
|
rf-send-after | Gets called if the submit request via ajax was successfull.
|
Information
Browser support
Reform.js supports Internet Explorer 10+ and the latest two versions of Google Chrome, Mozilla Firefox, Opera, Apple Safari and Microsoft Edge. (earlier versions may work but aren't tested)
Dependencies
jQuery 3.0+ (earlier versions may work but aren't tested)
Copyright and License
Copyright © 2018 Daniel Neubert
Licensed under the MPL 2.0 license.