Overview

Fields.js creates collections of fields. Each field is constantly evaluated for validity, and is accessible through the collection.

A field is any uniquely named text-based input, select, textarea, group of radio inputs, or group of checkbox inputs.

TODO Make this awesome. This is a work in progress and I would love to make working with, and validating, fields and forms a much more simple process. If you would like to offer your help making this tool and its documentation better, I would graciously accept it.

How to Use

1. Add any evaluations to the evaluationRegistry

NOTE As the user interacts with fields in the DOM, those fields will be evaluated by any evaluations with a selector that matches the field being interacted with.

> FieldsUtils.evaluationRegistry.add({
    context: 'errors',
    selector: '[type="email"], 
    statement: function(field){
      if (emailRegexComparison(field)) {
        return 'Invalid Email'
      }
    }
  });
  EvaluationCollection

2. Create a collection of fields.

> formOneFields = Fields.in('#form-one')
  Fields

3. Use the collection to interact with the form.

> formOneFields.isValid()
  false
> email = formOneFields.get('email_field')
  Field
> email.errors()
  ['Invalid Email']
> email.on('change:valid', function(val){
    doSomething(val)
  });

Example

As an example, this set of fields is an instance of Fields.in('#form-one'). There is also one 'errors' context evaluation added to the registry for email validation.

NOTE The tool currently does not contain a method of displaying errors and other evaluation results. For the time being, it is up to the implementer.

NOTE Fields that return evaluations of the context 'errors', or that are required and blank, are considered not valid.

Text field:

Valid:
Value:
Errors:

Email field:

Valid:
Value:
Errors:

Select field:

Valid:
Value:
Errors:

Radio field:

One Two

Valid:
Value:
Errors:

Checkbox field:

One Two Three

Valid:
Value:
Errors:

Textarea field:

Valid:
Value:
Errors:

Clear form

Form Validity:

Available Classes and Methods

Fields

Class Methods

@all()

Creates an instance of the Fields class with a collection of all of the fields on the page

> Fields.all()
  Fields

@in(selector)

Creates an instance of the Fields class with a collection of fields scoped to the passed selector.

If the selector you pass is an input, select, or textarea, @in will return a Field model instance instead of an instance of Fields.

> Fields.in('#form-one')
  Fields

> Fields.in('[name="email_field"]')
  Field

@within(selector), @at(selector)

Aliases for @in(selector)

Instance Methods

get(name)

Gets a Field model by the field's name.

> Fields.in('#form-one').get('email_field')
  Field

clear()

Clears the value of all of the field models. Internal event bindings then update the fields in the DOM to reflect the blank state.

> Fields.in('#form-one').clear()
  Fields

collect(attribute)

Collect a single attribute of all of the models into an object keyed on the name of the Field.

> Fields.in('#form-one').collect('value')
  { text_field: ''
    email_field: 'example@email.com'
    select_field: ''
    radio_field: '1'
    checkbox_field: ['2','3']
    textarea_field: "This is example text that is in a textarea." }

isValid()

Boolean that is true when all of the collection's models are valid.

> Fields.in('#form-one').isValid()
  false

Events

change:valid

A 'change:valid' event will fire when all of the collection's models are valid. It will also fire if it is valid and any of its models become invalid.

> Fields.in('#form-one')
    .on('change:valid' function(val){
      doSomething(val)
    });

change:value

A 'change:value' event will fire if any of the collection's models values change.

> Fields.in('#form-one')
    .on('change:value' function(val){
      doSomething(val)
    });

Field

There are no class methods for the Field model class because the instances are automatically generated when you create an instance of the Fields collection class.

Instance Methods

get(attribute)

Get an attribute specified by the attribute's name.

> email = Fields.at('[name="email_field"]')
  Field
> email.get('required')
  true

value(value), val(value)

A getter and setter for the Field value. With no argument, val() will return the current value of the field. This does the same thing as field.get('value').

If an argument is passed, the Field's value will be set and the field in the DOM will be updated with the new value.

> email.val()
  'example@email.com'

> email.val('other@email.com')
  Field

clear()

A convenience method for field.val(''). Sets the value of the field to be an empty string.

> email.clear()
  Field

evaluate()

Manual trigger to have the field evaluated by the EvaluationRegistry.

> email.evaluate()
  { errors: ['Invalid Email'] }

errors()

Convenience method for email.get('evaluations').errors

> email.errors()
  ['Invalid Email']

isValid()

Returns false if there are any evaluations with context 'errors', or if the field is both required and empty.

> email.isValid()
  false

isRequired()

Convenience for email.get('required').

> email.isRequired()
  true

isEmpty()

Convenience for email.val() == ''.

> email.isEmpty()
  false

Events

change:valid

A 'change:valid' event will fire when the Field's valid attribute changes.

> email.on('change:valid' function(val){
    doSomething(val)
  });

change:value

A 'change:value' event will fire when the Field's value changes.

> email.on('change:value' function(val){
    doSomething(val)
  });

EvaluationCollection

The EvaluationCollection class is instanced into FieldsUtils.evaluationRegistry. The only point you should really be interacting with it is adding evaluation objects to the registry.

An evaluation object consists of three parts:

selector: The css selector you want to apply this evaluation to.
context: The context of the evaluation. Most typical would be 'errors'.
statement: The function that will run on the field when it is evaluated. It takes one argument, which is representitive of the field being evaluated.

Instance Methods

add(evaluations)

Allows you to add evaluations to an EvaluationCollection instance. Accepts a single object or an array of objects.

> FieldsUtils.evaluationRegistry.add({
    context: 'errors',
    selector: '[type="email"], 
    statement: function(field){
      if (emailRegexComparison(field)) {
        return 'Invalid Email'
      }
    }
  });
  EvaluationCollection

evaluate(field)

Checks the evaluation registry for evaluations with selectors matching the passed in field.

> FieldsUtils.evaluationRegistry.evaluate( $('[type="email"]') )
  { errors: ['Invalid email'] }

Tests

TODO Write tests.