Initialisation and basic usage

Initialising ioForm

To use ioForm's JavaScript form handling, you simply need to include the script file (see Requirements and installation), and then initialise the form with the following code:

    var form = new ioForm( '#my-form' );

Note that the selector (in this case, '#my-form') can be any of the following:

However you should also be aware that if the submitted argument returns (or contains) more than one element, then all but the first element will be ignored and a warning will be issued via the console.

Once you've called this method on a form, the result is cached so that further calls to the same method will return the same object. So while it would usually make most sense to store the returned object if you're going to use it again later, there's very little penalty in terms of performance (and none in terms of functionality) to do something like this:

    // First call
    var form = new ioForm( '#my-form' );

    // ... some stuff happens

    // Second call
    var form2 = new ioForm( '#my-form' ); // form and form2 are the same object

Getting a value

The main purpose of ioForm is to make form interactions simpler, more logical, and more consistent. This is most obvious when getting (and setting, as we'll see later) a form's values.

In plain JavaScript, some field types, such as input type="text" fields, single select fields, and textarea fields, support element.value:

    console.log( document.getElementById( 'my_input' ).value );

But how do you get the selected value of a radio button? Or all selected values in a multiple select element? That requires some more complex logic.

With ioForm, getting and a value for all field types uses the same method: GetValue(). So for example, a radio button:

See the Pen ioForm: Getting a radio button value by Taeon (@Taeon) on CodePen.

A multiple select field will return an array:

See the Pen ioForm: Get multiple select value by Taeon (@Taeon) on CodePen.

When using a date field, instead of a string you get a date object:

See the Pen ioForm: Get date field value by Taeon (@Taeon) on CodePen.

If you pass a second parameter of true to GetValue(), then the 'raw' value of the field will be returned -- so for example, a date field will return a string instead of a Date object.

Setting a value

If you want to set a field's value the following will work (in pretty much all reasonably modern browsers) for some field types, such as input type="text" fields, single select fields, and textarea fields:

    var my_input = document.getElementById( 'my_input' );
    input.value = 'Hello world';

If you want to set the value of a radio button, or pass an array of values to a multiple select element then you'd have to start fiddling around with finding individual elements, and setting a particular attribute (checked, selected or whichever is appropriate). [Yes some browsers support setting a multiple select's value with .value, but not all].

Again, With ioForm setting values for all field types uses the same method: SetValue(). So for example, you can set the value of a radio button like this:

See the Pen ioForm: Setting a radio button's value by Taeon (@Taeon) on CodePen.

Or you could pass an array of values to a multiple select field:

See the Pen ioForm: Set multiple select value by Taeon (@Taeon) on CodePen.

Or what if you're using a date field, and you don't want to mess about converting a date object to a string? No problem:

See the Pen ioForm: set date field value by Taeon (@Taeon) on CodePen.

Events

In addition to providing consistent methods for getting and setting values, ioForm also implements a simple system for listening for field events. Like jQuery's event handling, it uses the on() method.

For example, if you want to know when a radio field's value changes:

See the Pen ioForm: Listen for change event by Taeon (@Taeon) on CodePen.