Framework

- About
- Guides
- Community
- API
- Code
- Download

# Kanso API Documentation

Index | View on single page

## forms

Functions for the rendering, parsing and validation of forms.

### Form(fields | type, [doc])

Form object, presents fields and parses responses.

#### Options

exclude | Array | a list of field names to exclude
fields | Array | a subset of fields to use (inverse of excluded)

#### Parameters

fields | Object | an object literal containing fields or a Type
doc | Object | (optional) the original document being edited
options | Object | (optional) see available options above

### override(excludes, field_subset, fields, doc_a, doc_b, path)

Overrides values in doc_a with values in doc_b, only when a field is present for that value. This means properties not in fields (or in excluded fields) are retained, while properties which are covered by the fieldset are replaced.

This is used when updating the form's values with a request when its been initiated with a previous document. You shouldn't normally need to call this directly.

Returns the updated doc_a object.

#### Parameters

excludes | Array | null |
field_subset | Array | null |
Fields | Object |
doc_a | Object |
doc_b | Object |
path | Array |

Returns: Object

### Form.validate(req)

Parses a request and validates the result, binding values and errors to the form instance.

#### Parameters

req | Object |

Returns: Form

### Form.isValid()

After a form has called validate, this function will return true if the form is valid, false otherwise.

Returns: Boolean

### Form.toHTML(req, [RendererClass])

Converts current form to a HTML string, using an optional renderer class.

#### Parameters

req | Object | Kanso request object; null for most recent. (optional),{Renderer} RendererClass (optional),{Object} options An object containing widget options, whichwill ultimately be provided to each widget's toHTML method.,{Boolean} create_defaults (optional) Set this to true if you'veprovided a document in {doc}, but would still like defaultvalues to be merged in to it via createDefaults. For a field f,the default value is added to {doc} if and only if doc[f]is undefined, null, or not present. Defaults to off.

Returns: String

### Form.renderFields(renderer, fields, values, raw, err, path)

Iterates over fields and sub-objects calling the correct renderer function on each. Returns a HTML representation of the fields. Used internally by the toHTML method, you should not need to call this function directly.

#### Parameters

renderer,{Object} | Object | fields,{Object} values,{Array} errs,{Array} path,{Object} options An object containing widget options, whichwill ultimately be provided to each widget's toHTML method.

Returns: String

### formValuesToTree(form)

Transforms a flat object from a request query to a proper hierarchy of properties.

    {'one.two': 'val'} --> {one: {two: 'val'}}

#### Parameters

query | Object |

### parseRaw(fields, raw)

Transforms a raw query object from formValuesToTree to a document which follows the schema for the given type.

#### Parameters

fields | Object |
raw | Object |

Returns: Object