Skip to content

Model API

Jump to bottom
Peter Jekel edited this page Nov 1, 2013 · 9 revisions

Content

* [Model Properties](#model-properties) * [Model Functions](#model-functions) * [Model Callbacks](#model-callbacks)

Model Properties

Model properties define specific features or characteristics of a store model. The property names also represent properties in the keyword object passed to the model constructor. For example:

require(["cbtree/model/TreeStoreModel", ... ], function (TreeStoreModel, ... ) {
  var keywordArgs = { store:myStore, checkedAll:true, query:{type:"Monarch"} };
  var model = new TreeStoreModel( keywordArgs );
}

checkedAll:

> **_TYPE_**: Boolean

If true, every store object will receive a so-called 'checked' state property. The name of the actual property is defined by the value of the model property checkedAttr. If the 'checked' state property is added to a store object, its initial state is defined by the value of the model property checkedState (see also checkedAttr)

DEFAULT: true

checkedAttr:

> **_TYPE_**: String

The property name of a store object that holds its checked state. On store load it specifies the object's initial checked state. For example: { name:"Egypt", type:"country", checked: true } If a store object has no checked property it depends on the model property checkedAll if one will be added in which case the initial value is set according to the value of checkedState.

DEFAULT: "checked"

If a store object has no 'checked' state property and checkedAll is false no checkbox will be created by the tree for the object.

checkedState:

> **_TYPE_**: Boolean

The default checked state applied to every store item unless otherwise specified in the object store (see also: checkedAttr)

DEFAULT: false

checkedRoot:

> **_TYPE_**: Boolean

If true, the tree root node will receive a checked state even though it may not represent an actual entry in the store. This property is independent of the tree property showRoot. If the tree property showRoot is set to false the checked state for the root will not show either.

DEFAULT: false

checkedStrict:

> **_TYPE_**: Boolean | String

If true, a strict parent-child relation is maintained. For example, if all children of an object are checked the parent will automatically receive the same checked state. If any of the children are unchecked the parent will, depending on, if multi state is enabled, receive either a mixed or unchecked state. If set to "inherit", children will inherit the parent checked state when changed. However, the parent checked state is NOT updated when a child's checked state changes.

DEFAULT: true

If set to true, the model will request a full store load which may impact performance on very large object stores like a File Store.

enabledAttr:

> **_TYPE_**: String

The name of the store object property that holds the enabled state of the checkbox or alternative widget. Note: Even though it is referred to as the enabled state the tree will only use this property to set the readOnly property of a checkbox or alternative widget. This because disabling a widget (DOM element) will exclude it from HTTP POST operations.

DEFAULT: null

iconAttr:

> **_TYPE_**: String

The name of the store object property whose value is considered a tree node icon (css class name). If specified, get the icon from an object using this property name. (see Tree Styling)

DEFAULT: ""

labelAttr:

> **_TYPE_**: String

The name of the store object property whose value is returned as the label for the tree node.

DEFAULT: "name"

labelType:

> **_TYPE_**: String

Specifies how to interpret the labelAttr in the data store items. Can be "html" or "text".

DEFAULT: "text"

multiState:

> **_TYPE_**: Boolean

Determines if the object checked state is to be maintained as multi state or as dual state, that is, {"mixed", true, false} versus {true, false}. If true multi state is enabled.

DEFAULT: true

normalize:

> **_TYPE_**: Boolean

If true, the checked state of any non branch (leaf) checkbox is normalized, that is, true or false. When normalization is enabled checkboxes associated with tree leafs (e.g. nodes without children) can never have a "mixed" state.

DEFAULT: true

options:

> **_TYPE_**: Object

A JavaScript key:value pairs object used as the query options. Please refer to the Query Options for details.

DEFAULT: null

parentProperty:

> **_TYPE_**: String

The property name of a store object whose value represents the object's parent id or ids. If the store assigned to the model has a parentProperty property the store property value is used.

DEFAULT: "parent"

query:

> **_TYPE_**: Object

A JavaScript key:value pairs object used to query the store to determine the tree root object or, in case the query returns multiple objects, the children of the fabricated root object. For example: {type:"parent"}. If not specified, a wildcard search is performed using the store's idProperty property value. (See also Tree Store Model and Forest Store Model)

DEFAULT: null

rootLabel:

> **_TYPE_**: String

Label of the fabricated tree root object (Forest Store Model only) or the alternative label in case the tree root is represented by a store object (Tree Store Model only)

DEFAULT: null

rootId:

> **_TYPE_**: String

ID of the fabricated root item, Only valid for a Forest Store Model.

DEFAULT: "$root$"

store:

> **_TYPE_**: Object

The underlying object store.

DEFAULT: null

Model Functions

The following section list the default functions available with the CheckBox Tree store models.

getChecked ( item )

> Get the current checked state from the object store. The checked state > in the store can be: 'mixed', true, false or undefined. Undefined in this > context means the object has no checked property (see checkedAttr).

item: Object

A valid store object.

returns: Boolean | String | undefined

getChildren( parent, onComplete, onError? )

> Calls onComplete() with an array of child items of given parent item. > Note: Only the immediate descendents are returned.

parent: Object

A valid store object.

onComplete: Function (optional)

If an onComplete callback is specified, the callback function will be called just once, as onComplete( children ).

onError: Function (optional)

Called when an error occured.

returns: void

getEnabled( item )

> Returns the current 'enabled' state of an item as a boolean. See the *enabledAttr* > property description for more details.

item: Object

A valid store object.

returns: Boolean

The state returned is the value of the checked widget "readOnly" property.

getIcon( item )

> If the *iconAttr* property of the model is set, get the icon for *item* from > the store otherwise *undefined* is returned.

item: Object

A valid store object.

returns: Object | String

Returns an icon object or a string

getIdentity( item )

> Get the identity of an item.

item: Object

A valid store object.

returns: String | Number

getLabel( item )

> Get the label for an item. If the model property *labelAttr* is set, the > associated property of the item is retrieved otherwise the default value > *name* is used.

item: Object

A valid store object.

returns: String

getParents ( item )

> Get the parent(s) of a store item. Returns an array of store items.

item: Object

A valid store object.

returns: dojo/promise/Promise

Returns a promise. If resolved the result of the promise is an array of parent objects.

example:

var promise = model.getParents(item);
promise.then( function (parents) {
  parents.forEach( ... );
});

getRoot( onItem, onError? )

> Calls onItem with the root item for the tree, possibly a fabricated item. > Calls onError on error.

onItem: Function

Callback function. On successful completion called as onItem( root ).

onError: Function

Called when an error occured.

returns: void

isItem( something )

> Returns true if *something* is an item and came from this model instance. > Returns false if *something* is a literal, an item from another model instance, > or is any object other than an item.

something: Any

returns: Boolean

mayHaveChildren( item )

> Returns true if an item has or may have children.

item: Object

A valid store object.

returns: Boolean

ready( callback?, errback?, scope? )

> Execute the callback when the model is ready. If an error is detected that > will prevent the model from getting ready errback is called instead. > The model is considered ready when the underlaying store is ready and loaded > and optionally had its data validated. The store can be empty when ready.

callback: Function

Optional, function called when the model enters the ready or active state.

errback: Function

Optional, function called if an error occurred preventing the model from entering the ready or active state.

scope: Object

Optional, the scope or context in which the callback and errback functions are executed. If omitted both functions will be executed in the scope of the model.

returns: dojo/promise/Promise

example:

model.ready( function () {
  console.log( "Bingo" );
});
          or
model.ready().then( function () {
  console.log( "Bingo" );
});

setChecked ( item, newState )

> Update the checked state of a store item. If the model property *checkedStrict* > is true, the items parent(s) and children, if any, are updated accordingly.

item: Object

A valid store object.

newState: Boolean | String

The new checked state. The state can be either a boolean (true | false) or a string ('mixed')

returns: void

setEnabled( item, value )

Set the new 'enabled' state of an item. See the enabledAttr property description for more details.

item: Object

A valid store object.

value: Boolean

returns: void

Model Callbacks

The CheckBox Tree models, although not widgets, offer the same on() functionality as widgets do. Therefore you can simple register a model event listener using the event name like model.on( "dataValidated", myEventHandler );

The tables below list the event names and associated callback. If for any given event type a callback is specified, the arguments column specifies the list of arguments passed to the event listener.

Event Type Callback Arguments Description
change onChange (item, propertyName, newValue, oldValue) Property of a store item changed.
childrenChange onChildrenChange (parent, newChildrenList) The children of a node changed.
dataValidated onDataValidated (void) The store data has been validated.
delete onDelete (item) An item was removed from the store.
pasteItem onPasteItem (item, insertINdex, before) Item was pasted at a new location.
reset onReset (void) The model is being reset. Typically due to a store closure.
rootChange onRootChange (item, action) The children of the tree root changed.

See Working with Events for a detailed description.

Clone this wiki locally