Framework

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

# Kanso API Documentation

Index | View on single page

## widgets

Widgets define the way a Field object is displayed when rendered as part of a Form. Changing a Field's widget will be reflected in the admin app.

### Widget(type, [options])

Widget constructor, creates a new Widget object.

#### Parameters

type | String |
options | Object |

Returns: Widget Object

### Widget.toHTML(name, value, raw, field, options)

Converts a widget to HTML using the provided name and parsed and raw values

#### Parameters

name | String |
value |  |
raw |  |
field |  |
options |  |

Returns: String

### Widget.clientInit(path, value, raw, field, options)

Initializes a widget on the client-side only, using the browser's script interpreter. This function is guaranteed to be called after toHTML, and any DOM elements created by toHTML are guaranteed to be accessible

#### Parameters

path | Array |
value |  |
raw |  |
field |  |
options |  |

Returns: Boolean

### Widget.updateName(path)

Called by Kanso when it becomes necessary to rename this widget instance. The widget should respond by updating the id and name attributes.

#### Parameters

elt | String | An element that contains one ormore instances of the widget referenced by `this'.,{String} path The widget's new path; combine this usingthe _name or _id function to generate a usable string.,{Object} options A new set of toHTML/clientInit options.This may or may not influence the widget's name.

### Widget.updateValue(elt, path, value, options)

Called by Kanso when it becomes necessary to rename this widget instance. The widget should respond by updating the value attribute.

#### Parameters

elt | String | An element that contains one ormore instances of the widget referenced by `this'.
path | String | The path to the widget.
value | Object | The new value for the widget, unencoded.
options | Object | An up-to-date set of toHTML/clientInit options.

### Widget.getValue(elt, path, options)

Called by Kanso when it becomes necessary to interrogate this widget to determine its value. The widget should respond by returning an unencoded value (typically as an object).

#### Parameters

elt | String | An element that contains one ormore instances of the widget referenced by `this'.
path | String | The path to the widget.
options | Object | An up-to-date set of toHTML/clientInit options.

### Widget.validate(elt, path, options)

Called by Kanso when it becomes necessary to validate the contents of this widget -- i.e. to ensure it's in a consistent state before using its value or proceeding. Most widgets will not implement this method; its primary use is complex widgets that host validation-enabled forms and/or types. Returns true if the contents is consistent and valid; false otherwise.

#### Parameters

elt | String | An element that contains one ormore instances of the widget referenced by `this'.
path | String | The path to the widget.
options | Object | An up-to-date set of toHTML/clientInit options.

### text([options])

Creates a new text input widget.

#### Parameters

options |  |

Returns: Widget Object

### password([options])

Creates a new password input widget.

#### Parameters

options |  |

Returns: Widget Object

### hidden([options])

Creates a new hidden input widget.

#### Parameters

options |  |

Returns: Widget Object

### textarea([options])

Creates a new textarea widget.

#### Parameters

options |  |

Returns: Widget Object

### checkbox([options])

Creates a new checkbox widget.

#### Parameters

options |  |

Returns: Widget Object

### select([options])

Creates a new select widget.

#### Parameters

options |  |

Returns: Widget Object

### computed([options])

Creates a new computed widget. Computed widgets display a string, but are uneditable, working as a hidden field behind the scenes.

#### Parameters

options |  |

Returns: Widget Object

### creator([options])

Creates a new computed input widget which sets the value of the field to the current user on new documents, responding to sessionChange events

#### Parameters

options |  |

Returns: Widget Object

### embedded([options])

Creates a new field for storing/displaying an embedded object. This is automatically added to embed and embedList field types that don't specify a widget.

#### Parameters

options |  |

Returns: Widget Object

### defaultEmbedded([options])

Creates a new field for storing/displaying an embedded object. This is automatically added to embed and embedList field types that don't specify a widget.

#### Parameters

options |  |

Returns: Widget Object

### embedForm([options])

Creates a new instance of an embedded form for the specified type. This is the basis for the presentation of complex data types in Kanso, and is used within an embedList to add and/or edit items.

#### Parameters

options |  |

Returns: Widget Object