Home

This document covers the planning for a new, simple yet effective tool for handling forms in node.js.

Aims of the library are to:

• create a form (in HTML) from JavaScript objects (with and without errors)
• read form values from a JavaScript object and validate
• return a validation object, stating errors

Heirachiral view

form
	fieldset(s)
		field groups
			fields
		fields
	fields
	field group
		fields

certain objects can contain only certain objects

form can contain:

• fieldset
• fieldGroup
• field

fieldset can contain:

• field group
• field

fieldGroup can contain:

• field

Objects

The following outlines each object and how they work.

form

The following can be defined on a form:

- action			String
- method			String
- attributes		Object
- theme				Object

fieldset

The following can be defined on a fieldset:

- legend			String
- attributes		Object

fieldGroup

Nothing can be defined on a fieldGroup.

field

The following can be defined on a field:

- name				String
- type				String
- value				String
- widget			Object
- attributes		Object
- errors			Array
- validators		Array
- validates			Boolean

Adding and removing fields

The following will exist on form, fieldset and formGroup.

• unshift
• push
• addAfter (name, index)
• addBefore (name, index)

Themes

Themes would control how the form is rendered. A default theme will be provided by formist. Other themes will exist in seperate modules (i.e. formist-bootstrap).

A theme should provide methods for each type of object that can be rendered, and specific rendering methods for any object as required.

Defining a custom theme

	{
		form: function () {
			// ...
			return '<form>{{content}}</form>';
		},
		fieldset: function () {
			// ...
			return '<fieldset>{{content}}</fieldset>';
		},
		particularField: function () {
			// ...
			return '<input type="text"></input>';
		}
	}

Customisation API

A simple API would be provided for customising the form at any level. By passing in a render method, this will be executed with the following signature:

renderFn(type, object);

Example

Creating a form

	var f = new forms.form({
		action, method, attributes
	});

	f.add([

		form.fieldset({
			legend, attributes
		});

	]);

or

	var f = new forms.form({
		action, method, attributes
	}, [

		form.fieldset({
			legend, attributes
		});

	]);

Rendering a form

	var f = new forms.form({
		action, method, attributes, render
	});

	var formHTML = f.render();

Rendering errors with values

	var f = new forms.form({
		action, method, attributes
	});

	var formHTML = f.render(formResult);

Return a validation object

	var f = new forms.form({
		action, method, attributes
	});

	var validated = f.validate(formResult);