Validatious 2.0

Easy form validation with unobtrusive JavaScript

Custom error display

If configuring the error reporting extension doesn't get you the error reporting you're after, you can do it all yourself. Please note that until the core API docs are out, this feature may seem a little bit under-documentet (and until the docs are out - it is).

Callbacks

Validatious does error reporting through callbacks. Every validatable object (the generic v2.CompositeFormItem, v2.Fieldset (used primarily by the HTML extension and v2.Field) has two callbacks: onSuccess, which is called when the object passes validation, and onFailure, which is called when the object fails validation.

Custom for all?

As always; when specifying the callbacks on the prototype objects the reporting is active on all objects. By specifying callbacks on single instances, you can provide completely custom reporting for certain fields.

How to make a reporter

The callbacks are carried out on the validated objects, and so they have access to the inner state of the objects. This is where the core API docs will help out. In the meantime, an example will show alot of the potential. The following is the callbacks on v2.Field and v2.Fieldset from the reporting extension with lots of comments along the way.

v2.Field.prototype.onFailure = function() {
  // this.parent is a reference to the containing object, not parent element.
  // This test assures that errors are only reported for fields added directly
  // to a form, not grouped in a fieldset (in which case reporting is done at
  // the fieldset level).
  if (this.parent && this.parent.type === 'fieldset') {
    return;
  }

  // This "parent" is the parent element containing the field and label elements
  // The onSuccess method is set up to return it for a small optimization. There
  // is no requirement for onSuccess to return anything.
  // The onSuccess method is called here in order to make sure there are no
  // visible error messages when we start - to avoid duplicate messages.
  var parent = this.onSuccess();

  var str = '', i, error, validation, listElement;
  var used = [];

  // The getMessages() method returns all messages generated for this object. In
  // case of grouped objects (such as a fieldset), this returns a list of all
  // messages from all child objects (fields, or nested grouped validators)
  //
  // A corresponding method exists, getInvalid(), which will be an array of
  // complete objects instead of just the messages.
  var messages = this.getMessages();

  parent.addClassName(this.failureClass);
  parent.removeClassName(this.successClass);

  // __getId is just a private helper method which generates an id to use for
  // the error list.
  var list = document.createElement('ul');
  list.id = this.__getId();
  list.className = this.messagesClass;

  // Set number of errors to display. -1 is all, maximum is all
  var count = this.displayErrors;
  var max = this.__errors.length;
  count = count < 0 || count > max ? max : count;

  for (i = 0; i < count; i++) {
    error = messages[i];

    // Filter out duplicate error messages
    if (!error || used.indexOf(error.toString()) >= 0) {
      continue;
    }

    used.push(error.toString());

    // Create an 
 element for the error message
    listElement = document.createElement('li');
    listElement.innerHTML = error.toString();
    list.appendChild(listElement);
  }

  if (this.positionErrorsAbove) {
    parent.insertBefore(list, parent.firstChild);
  } else {
    parent.appendChild(list);
  }
}

v2.Field.prototype.onSuccess: function() {
  // See onFailure for explanation
  if (this.parent && this.parent.type === 'fieldset') {
    return null;
  }

  // getParent returns the immediate parent element of the input/select/textarea
  // in most cases. For radio buttons and checkboxes, if these appear in a list,
  // the parent element returned is instead the parent of the list itself, which
  // allows for structures like
  //
  // 

  //   
Make a pick
  //   

  //     

  //       
  //       Apple
  //     
  //     
  //   
  // 
  var parent = v2.$(this.getParent());

  // Remove error if it exists
  var list = v2.$(this.__getId());

  if (list && parent === list.parentNode) {
    parent.removeChild(list);
  }

  parent.removeClassName(this.failureClass);
  parent.addClassName(this.successClass);

  return parent;
}

Next: Validating radio buttons and checkboxes | Back to Core API features index