nos-forms-jquery v2.2.0

Nos-Forms-jQuery

Quickly generate and validate html forms with jQuery, Bootstrap and json.

This is a simple json form builder that will build and validate your forms for you. It will also handle serializing your data and spit out a nice json object to your submit function. This plugin is meant to be used with Bootstrap.

This plugin is intended for people who spend a lot of time building tedious forms. Copying and pasting from this file is encouraged, as well as saving and reusing json files to build your forms.

• IE 8 supported

Dependencies

• jQuery - minimum version 1.9

• Bootstrap - minimum version 3.0

Getting Started

1. Include js and css file from 'dist' directory

2. Create empty form element with a unique id

3. Call nosForm function, specifying your data and options

Quick Example

A simple contact form built with Bootstrap. This form will be sanitized and validated.

index.html

<form id="myform" class="form">
    <h2>My Form</h2>
</form>

js file

$.get('contact-form.json', function (jsonData) {

    $("#myform").nosForm({
        fields: jsonData,
        submit: function (formdata, $form, evt) {
            console.log(formdata); // JSON form data
            console.log($form); // jQuery Form Object
            console.log(evt); // Original submit event
        }
    });

})

contact-form.json

Note: you don't have to store your config in a json file. You can just write this in your plugin initilization as JavaScript.

[
    {
        "name": "name",
        "id": "nameId",
        "type": "text",
        "label": "Name",
        "required": true,
        "placeholder": "Your Name",
        "minlength": 1,
        "maxlength": 60
    },
    {
        "name": "email",
        "type": "email",
        "label": "Email Address",
        "required": true,
        "placeholder": "Your Email",
        "minlength": 1,
        "maxlength": 100
    },
    {
        "name": "message",
        "type": "textarea",
        "label": "Message",
        "required": true,
        "placeholder": "Your message",
        "minlength": 5,
        "maxlength": 500,
        "rows": 8
    },
    {
        "name": "submitButton", // NEVER NAME THIS 'submit'!!!
        "type": "submit",
        "classname": "btn btn-success",
        "formGroup": true,
        "value": "Submit"
    }
]

Options

All options with default values

$("#myform").nosForm({
    fields: null, // Your json data {},
    ajax: true, // receive data in your submit function and send it with ajax (if false, a classic submit occurs)
    validate: true, // toggle javascript validation
    htmlValidation: false, // toggle html browser validation
    animationSpeed: 100, // change speed of js animations (error message animations)
    honeypot: false, // adds two honeypot fields to filter out bots
    onlySubmitWithValue: false, // if true, will only send form fields that have been filled out (empty fields don't get submitted)
    messages: { // these are the messages that will appear on the bottom of the form when an unsuccessful submit has occurred
        required: 'Please fill out all required fields', // warning about required fields
        invalid: 'Invalid fields' // warning about invalid fields (pattern, minlength, min, max)
    },
    messageLocation: { // places required/invalid error messages on the form
        top: false, // specifies the messages to be displayed on the top
        bottom: true  // specifies the messages to be displayed on the bottom
    },
    submit: function (formdata, form, evt) {
        // your submit function
        // this will pass back the entered form data as a formatted json object, your form as a jQuery Object, and the original submit event
    },
    init: function (form) {
        // fires after form is rendered
        // passes back the form
    }
});

fields

Accepts an object with your form element structure. This was originally intended to be imported from a json file (for easy reuse of forms), but you can write the object in your js file as well. This allows you to write your own functions that return the correct values to individual fields.

ajax

Accepts a boolean value. If set to true, your form will send a serialized object to your submit function, where you will be responsible for sending an ajax request with your form data. If set to false, a classic form submit will occur and your submit function will not be necessary. If you set ajax to false and a submit function is still present, you will still receive the form data as usual and you will have to manually submit the form. This can be useful for deleting out fields you don't want to send to the server (e.g.: confirm password fields) or if you need to manually check something before sending the form. Worth noting:: never name your submit button 'submit' or your form will not submit properly.

validate

Accepts a boolean value. Toggles the build-in validation on or off. If for some reason you don't need validation, turn this off.

htmlValidate

Accepts a boolean value. Toggles the html5 validation on or off. Basically, this is just adding and removing a 'novalidate' tag from the form.

animationSpeed

Accepts a number value (milliseconds). Controls the speed of the validation messages popping in and out of form fields.

honeypot

Accepts a boolean. Optionally, there are two honeypot text fields rendered on each form (one is empty and one has a preset value). Both are hidden by CSS and JS. If either are modified, your submit object will contain an extra property "{ honeypot: true }". You are free to handle this however needed in your submit function.

onlySubmitWithValue

Accepts a boolean. When this field is set to true, only fields that have a value will be sent to your submit function. This essentially will ignore any field that a user has not filled out. This can be useful when you have a lot of optional fields and you don't want to post all of them all the time.

messages

Accepts two properties with string values: 'required' and 'invalid'. These are the two messages that are positioned below each form. On an unsuccessful form submit, the appropriate message will be displayed to the user. If not modified, they will display the default values shown above.

messageLocation

Accepts two properties with boolean values: 'top' and 'bottom'. These settings determine the location of the user error messages to be displayed on an invalid form submit attempt.

submit

Accepts a function that receives the form data passed to it. Passes three arguments: the form data, the form, and the original submit event.

init

Function that will fire as soon as the form renders. Passes the form as it's only argument.

Events

nos.submit

Triggered on submit. Callback parameters are the event, followed by an object containing the formdata, form element, and original submit event.

Structure

Single Columns

These are pretty standard.

[
    {
        // form element here
    },
    {
        // form element here
    }
]

Multiple Columns

If you would like a form to work with multiple columns, you just have to format your json data a little different.

[
    {
       "classname": "col-md-4",
       "column": [
           {
               // form element here
           }
       ]
    },
    {
       "classname": "col-md-4",
       "column": [
           {
               // form element here
           }
       ]
    },
    {
       "classname": "col-md-4",
       "column": [
           {
               // form element here
           }
       ]
    }
]

Nesting Columns

Nesting columns can be accomplished by declaring a row where needed.

[
    {
        "row": true, // wraps a row class div around this column
        "classname": "col-md-6 col-md-offset-3", // centers this form on the page in a col-6
        "column": [
            {
                "row": true, // adds another row
                "classname": "col-md-12", // nests a col-12 class inside the col-6
                "column": [
                    {
                        // form element here
                    }
                ]
            },
            {
                "row": true,
                "column": [
                    {
                        "classname": "col-md-6",
                        "column": [
                            {
                                // form element here
                            }
                        ]
                    },
                    {
                        "classname": "col-md-6",
                        "column": [
                            {
                                // form element here
                            }
                        ]
                    }
                ]
            },
            {
                "row": true,
                "classname": "col-md-12",
                "column": [
                    {
                        // form element here
                    }
                ]
            }
        ]
    }
]

This format allows you to create your form elements in blocks. Adding Bootstrap classes makes it easy for you to display your form in a column layout. Add as many columns and nest them as deep as you like.

Types

Properties

Validation

By default, validation will happen when you specify certain properties in your json file. All fields will be checked for values and sanitized. Error messages will be generated, and it will basically take care of itself.

• required - adds required tag and ensures a value is in place

• minlength - adds minlength tag and checks with javascript

• maxlength - adds maxlength tag and double checks it with javascript

• pattern - will validate input against a regex of your choosing

• min - adds min tag and checks

• max - adds max tag and checks

• match - enter in the id of an element to check against. This will check that these values match (Mostly for password confirmation). You can customize the error message with the 'invalid' message.

Validation Messages

By default, there are messages in place that warn the user about missing/invalid fields. They are inside hidden Bootstrap alert divs. If you do not specify a value, they will name each field by whatever value you have on the label. If you don't have a label, they will find a placeholder value.

These messages can be customized for each field, if you need. See the examples below.

There are five specific types of message that can appear for each field:

• required - "field name is a required field"

  • triggered (on submit) when a required field is left blank

• minlength - "field name must have a minimum of * characters"

  • triggered (as you type) when a minlength has not been met

• invalid - "field name must be valid"

  • triggered (as you type) when certain criteria have not been met. (email/zip/phone not valid, regex pattern not matching, passwords not matching, etc.)

• min - "field name must have a minimum value of *."

  • triggered (as you type) when a minimum has not been met (numbers, dates)

• max - "field name must have a maximum value of *."

  • triggered (as you type) when a max has been overshot

There are also some default form messages that will display on the bottom of the form if the user tries to submit unsuccessfully. These can be customized in the plugin initilization, as mentioned in the 'Options' section.

Destroy Method

NosForm does come with a destroy method:

$('#myform').nosForm('destroy')

This will empty the form, keeping your actual form tag intact, while removing all options and event listeners.