Framework

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

# Kanso API Documentation

Index | View on single page

## fields

The building blocks of Types and Forms, Fields help to validate and authorize changes to docuemnt values.

### Field

Field objects are used when constructing content types and forms.

#### Options

- omit_empty Boolean - whether to omit the field from a document when the field is empty
- permissions Object - a permissions check function or an object containing separate functions to run on create, edit and update operations.
- validators Array - an array of validation functions (default: [])
- required Boolean - whether the field is required (default: true)

#### Parameters

options | Object |

### Field.parse(raw)

Parses a raw value returning the correct JavaScript type for this field. This will usually be overridden by other field types.

#### Parameters

raw |  |

### Field.isEmpty(value, raw)

Test values to see if field is considered empty.

This function accepts the raw value even though by default it only checks the parsed value, so that other field types overridding this method have the raw data available.

#### Parameters

value |  | the parsed value for the field
raw |  | the raw value for this field

Returns: Boolean

### Field.validate(doc, value, raw)

Run the field's validation functions against a value. Returns an array of validation errors, or an empty array if valid.

#### Parameters

doc | Object |
value |  |
raw |  |

Returns: Array

### Field.authorize(newDoc, oldDoc, newVal, oldVal, userCtx)

Check relevant field permissions to see if user is authorised to make changes. Returns an array of permissions errors, or an empty array if the changes are permissible.

#### Parameters

newDoc | Object |
oldDoc | Object |
newVal |  |
oldVal |  |
userCtx | Object |

Returns: Array

### Embedded

Embedded objects represent a Type embedded within another Type or set of Fields. Its not a true field, but like the Field constructor it acts as a marker when walking through the sub-objects that make up a schema.

Exposes the same methods as Field objects.

#### Options

- type Type Object - Required, the Type definition to embed
- omit_empty Boolean - whether to omit the field from a document when the field is empty
- permissions Object - a permissions check function or an object containing separate functions to run on create, edit and update operations.
- validators Array - an array of validation functions (default: [])
- required Boolean - whether the field is required (default: true)

#### Parameters

options | Object |

### Embedded.isEmpty(value, raw)

Test values to see if field is considered empty.

This function accepts the raw value even though by default it only checks the parsed value, so that other field types overridding this method have the raw data available.

#### Parameters

value |  | the parsed value for the field
raw |  | the raw value for this field

### Embedded.validate(doc, value, raw)

Run the type's validate function against a value. Returns an array of validation errors, or an empty array if valid.

#### Parameters

doc | Object |
value |  |
raw |  |

Returns: Array

### Embedded.authorize(newDoc, oldDoc, newVal, oldVal, user)

Check relevant type permissions to see if user is authorised to make changes. Returns an array of permissions errors, or an empty array if the changes are permissible.

#### Parameters

newDoc | Object |
oldDoc | Object |
newVal |  |
oldVal |  |
user | Object |

Returns: Array

### EmbeddedList

EmbeddedList objects represent multiple instances of a Type embedded within another Type or set of Fields. Its not a true field, but like the Field constructor it acts as a marker when walking through the sub-objects that make up a schema.

Exposes the same methods as Field objects.

#### Options

- type Type Object - Required, the Type definition to embed
- omit_empty Boolean - whether to omit the field from a document when the field is empty
- permissions Object - a permissions check function or an object containing separate functions to run on create, edit and update operations.
- validators Array - an array of validation functions (default: [])
- required Boolean - whether the field is required (default: true)

#### Parameters

options | Object |

### EmbeddedList.isEmpty(value, raw)

Test values to see if field is considered empty.

This function accepts the raw value even though by default it only checks the parsed value, so that other field types overridding this method have the raw data available.

#### Parameters

value |  | the parsed value for the field
raw |  | the raw value for this field

### EmbeddedList.missingIDs(list)

Detects embedded documents with missing _id properties and returns an array of Error objects for each occurence. Returns an empty array if all documents have a populated _id property.

#### Parameters

list | Array |

Returns: Array

### EmbeddedList.duplicateIDs(list)

Detects embedded documents with duplicate _id properties and returns an array of Error objects for each occurence. Returns an empty array if all documents have a unique _id property.

#### Parameters

list | Array |

Returns: Array

### EmbeddedList.validate(doc, value, raw)

Checks for missing or duplicate _ids then runs the type's validate function against each embedded document. Returns an array of validation errors, or an empty array if valid.

#### Parameters

doc | Object |
value |  |
raw |  |

Returns: Array

### EmbeddedList.authorize(nDoc, oDoc, nVal, oVal, user)

Check relevant type permissions to see if user is authorised to make changes. Returns an array of permissions errors, or an empty array if the changes are permissible.

#### Parameters

nDoc | Object |
oDoc | Object |
nVal |  |
oVal |  |
user | Object |

Returns: Array

### string([options])

Creates a new string Field

#### Parameters

options | Object |

### number([options])

Creates a new number Field

#### Parameters

options | Object |

### boolean([options])

Creates a new boolean Field

#### Parameters

options | Object |

### url([options])

Creates a URL Field

#### Parameters

options | Object |

### email([options])

Creates an email Field

#### Parameters

options | Object |

### creator([options])

Creates a creator Field

#### Parameters

options | Object |

### createdTime([options])

Creates a createdTime timestamp Field

#### Parameters

options | Object |

### choice([options])

Creates a choice Field

Required option: values - an array of possible choices, each an array with the first item as the value and the second as its label.

#### Parameters

options | Object |

### numberChoice([options])

Creates a number choice Field

#### Parameters

options | Object |

### embed([options])

Creates an Embedded Field

Required option: type - the Type definition to embed

#### Parameters

options | Object |

### embedList([options])

Creates an EmbeddedList Field

Required option: type - the Type definition to embed

#### Parameters

options | Object |

### array([options])

Creates a array Field. The default parse function expects a single row of comma separated values.

To accept an array of values other than strings, add a function to options called parseEach which accepts the string value for each item and performs the transformation.

#### Parameters

options | Object |

### numberArray([options])

Creates a number array Field, same as the array field only each value is parsed as a number instead of a string.

#### Parameters

options | Object |