Skip to content

CheckBox Tree API

Jump to bottom
Peter Jekel edited this page Oct 30, 2013 · 16 revisions

Content

* [Tree Properties](#tree-properties) * [Tree Node Properties](#tree-node-properties) * [Tree Functions](#tree-functions) * [Tree Callbacks](#tree-callbacks)

Tree Properties

CheckBox Tree properties enable or disable specific features and/or define characteristics of the tree. The property names also represent properties in the keyword object passed to the CheckBox Tree constructor. The following example illustrates how to apply the CheckBox Tree properties:

require(["cbtree/Tree", ... ], function ( Tree, ... ) {
  var keywordArgs = { model:myModel, persist:false, openOnClick:true };
  var myTree = new Tree( keywordArgs );
}

Additional CheckBox Tree Properties are available when the Tree Styling extension is loaded, see Tree Styling Properties for details.

attachToForm:

> **_TYPE_**: Boolean | Object

Include CheckBox Tree checkboxes in the form data set to be submitted. If boolean true, all eligible checkboxes will be included. The form data set is submitted as a series of parameters in either the HTTP GET URL Query String or the HTTP POST request body. If boolean false, no Checkbox Tree checkboxes will be included in the from data set.

If specified as a JavaScript key:value pairs object, some or all store objects checked states are included in the form data set as a single parameter. The parameter value is a JSON encoded array of objects, each object representing the checked state of a store object.

The attachToForm value object has tree properties all of which are optional:

Property Type Default Description
name String? "checkedStates" The parameter name in the form data set
checked (String|Boolean)? undefined The checked state(s) to be included in the form submission. Possible values are: "mixed", true or false. The checked property can also be specified as an array of checked states, as is ["mixed", true]. If undefined (default) all store objects are included regardless of their checked state.
domOnly Boolean? false If true, only the store objects associated with visible tree nodes will be included. See also openOnChecked
extension String? "./extensions/TreeOnSubmit" Pathname of the extension to be loaded. Only valid when no other extension has been loaded.

Please see the usage section Checkboxes in HTML forms and the TreeOnSubmit extension for additional details and examples.

DEFAULT: false

autoExpand:

> **_TYPE_**: Boolean

Fully expand the tree on load. Overrides persist

DEFAULT: false

branchCheckBox:

> **_TYPE_**: Boolean

If true, the checkbox associated with a tree branch will be displayed, otherwise the checkbox will be hidden but still available for checking its state. This property only affects the checkbox visibility and has no affect when the checkBoxes property is set to false. See also: Hidden Checkboxes and branchReadOnly

DEFAULT: true

branchIcons:

> **_TYPE_**: Boolean

Determines if the FolderOpen/FolderClosed icon or their custom equivalent is displayed. If false, the branch icon is hidden.

DEFAULT: true

branchReadOnly:

> **_TYPE_**: Boolean

Determines if branch checkboxes are read only. If true, the user must explicitly check/uncheck every child checkbox individually. This property overrides the per store item 'enabled' features for any store item associated with a tree branch.

DEFAULT: false

checkBoxes:

> **_TYPE_**: Boolean

If true it enables the creation of checkboxes, If a tree node actually gets a checkbox depends on the configuration of the model properties If false no checkboxes will be created regardless of the model configuration.

DEFAULT: true

If checkBoxes is true, the model for the tree MUST support the getChecked() and setChecked() methods.

clickEventCheckBox:

> **_TYPE_**: Boolean

If true, both the click and checkBoxClick events are generated when a checkbox is clicked. If false, only the checkBoxClick event is generated.

DEFAULT: true

closeOnUnchecked:

> **_TYPE_**: Boolean

If true, unchecking a branch node checkbox will close/collapse the branch. In addition, when all children of a given branch are unchecked the branch will also collapse, that is, if the model property checkedStrict is enabled (default).

DEFAULT: false

deleteRecursive:

> **_TYPE_**: Boolean

Determines if a delete operation, initiated from the keyboard, should include all descendants of the selected item(s). If false, only the selected item(s) are deleted from the store. This property has only effect when the store property enableDelete is true.

DEFAULT: false

enableDelete:

> **_TYPE_**: Boolean

Determines if deleting tree nodes using the keyboard is allowed. By default items can only be deleted using the store interface. If set to true the user can also delete tree items by selecting the desired tree node(s) and pressing the CTRL+DELETE keys.

DEFAULT: false

leafCheckBox:

> **_TYPE_**: Boolean

If true, the checkbox associated with a tree leaf will be displayed, otherwise the checkbox will be hidden but still available for checking its state. This property only affects the checkbox visibility and has no affect when the checkBoxes property is set to false. See also: Hidden Checkboxes and leafReadOnly

DEFAULT: true

leafIcons:

> **_TYPE_**: Boolean

Determines if the Leaf icon, or its custom equivalent, is displayed. If false, the node or leaf icon is hidden.

DEFAULT: true

leafReadOnly:

> **_TYPE_**: Boolean

Determines if leaf checkboxes are read only. If true, the user can only check/uncheck branch checkboxes. This property overrides the per store item 'enabled' features for any store item associated with a tree leaf.

DEFAULT: false

model:

> **_TYPE_**: Object

Interface to read tree data, get notifications of changes to tree data, and for handling drop operations (i.e drag and drop onto the tree)

DEFAULT: null

openOnChecked:

> **_TYPE_**: Boolean

If true, checking a branch checkbox will open/expand the branch.

DEFAULT: false

This property is especially helpful when the tree is part of a form that you want to submit. Expanding checked branches will guarantee that all checked nodes will be included in the form submission.

openOnClick:

> **_TYPE_**: Boolean

If true, clicking a folder node's label will open it, rather than calling tree's callback method onClick().

DEFAULT: false

openOnDblClick:

> **_TYPE_**: Boolean

If true, double-clicking a folder node's label will open it, rather than calling tree's callback method onDblClick().

DEFAULT: false

persist:

> **_TYPE_**: Boolean

Enables or disables the use of cookies for saving the tree state.

DEFAULT: (dojo < 1.9) true, (dojo >= 1.9) false

showRoot:

> **_TYPE_**: Boolean

Determines if the tree root is displayed or not. This property is specifically helpful when using a Forest Store Model and you don't want to display the fabricate root.

DEFAULT: true

widget:

> **_TYPE_**: [WidgetObject](#widget-object)

Specifies the checkbox widget to be instantiated for the tree node. The default is the CheckBox Tree multi-state checkbox.

DEFAULT: null

Tree Node Properties

All tree nodes are template driven widgets which only have non-configurable properties. User applications should therefore treat all properties as **read-only**

focused:

> If `true` indicates the tree node currently has focus, false otherwise.

TYPE: Boolean

id:

> The unique identifier generated for this tree node.

TYPE: String

indent:

> Zero based indent level of the tree node. The tree root node is at level 0.

TYPE: Number

isExpandable:

> Indicates if the tree node is expandable. If `true` the tree node is a so-called _tree branch_ > and may have child tree nodes, otherwise the tree node is a _tree leaf_. This property is > also exposed as the **_expandable_** attribute of the generated HTML elements whose class > attribute equals to **dijitTreeRow**, for example `
`

TYPE: Boolean

The isExpandable property only indicates if a node has children in the DOM, it is no indication if the store item associated with the tree node has any children in the store.

isExpanded:

> Indicates if the tree node is currently expanded. Only applicable to tree branches.

TYPE: Boolean

item:

> The store item or record this tree node is representing.

TYPE: Object

label:

> The label text for the tree node.

TYPE: String

tree:

> The tree instance this tree node belongs to.

TYPE: Object

Tree Functions

### Accessors

As of dojo 1.6 all dijit widgets come with the so called auto-magic accessors get() and set(). All CheckBox Tree API's, that is, the CheckBox Tree, Tree Styling and Store Model API, use these accessors as their primary interface. For example, to get the checked state of a tree node one could simply call: get("checked") or to change the checked state call: set("checked",true).

Note:

The property names "checked" and "enabled" are automatically mapped to the appropriate store item properties based on the store models checkedAttr and enabledAttr values. Therefore, at the application level you can simple use the keywords "checked" and "enabled" regardless of the actual store item properties.

collapseUnchecked( node )

> Collapse a branch node conditional. If the checkbox of the item associated with the > node is unchecked, the node is closed/collapsed. See also the tree properties > [closeOnUnchecked](#closeonunchecked) and [openOnChecked](#openonchecked) which enable > automatic branch expanding and collapsing.

node: TreeNode

The tree node to close/collapse. If the node argument is omitted the tree root node is used. Calling collapseUnchecked() without the node argument will collapse all unchecked branches in the tree.

get( propertyName )

> Returns the value of the tree or tree node property identified by *propertyName*.

propertyName: String

Name of the tree or tree node property.

returns: any

Returns the property value

expandChecked( node )

> Expand a branch node conditional. If the checkbox of the item associated with the node > is checked, the node is opened/expanded. Checked child branches of the newly expanded > branch will automatically expand as well. See also the tree properties > [closeOnUnchecked](#closeonunchecked) and [openOnChecked](#openonchecked) which enable > automatic branch expanding and collapsing.

node: TreeNode

The tree node to open/expand. If the node argument is omitted the tree root node is used. Calling expandChecked() without the node argument will expand all checked branches in the tree.

mapEventToAttr( oldPropName, property, nodeProp, value? )

> Map an object property name to a tree node property. If the optional *value* > argument is specified, its value is assigned to the tree node property. If > *value* is a function, the result returned by the function is assigned to the > tree node property.

oldPropName: String

Property name that is currently mapped to an tree node attribute. If present its entry in the mapping table is removed.

property: String

Object property name to be mapped to a tree node property.

nodeProp: String

Property name of a tree node to which argument property is mapped.

value: AnyType

Optional, a fixed value to be assigned to nodeProp or a function. If value is a function, the function is called as value(item, nodeProp, modelValue) and the result returned is assigned to nodeProp instead. If the value argument is omitted, the event value passed from the model is used.

set( propertyName, newValue )

> Set the value of the tree or tree node property identified by *propertyName*.

propertyName: String

Name of the tree or tree node property.

value: AnyType

New value to be assigned.

Tree Callbacks

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
click onClick (item, node, event) A tree node is clicked.
checkBoxClick onCheckBoxClick (item, node, event) A checkbox is clicked.
close onClose (item, node) Node closed, a tree node collapsed.
dblClick onDblClick (item, node, event) Double click
event onEvent (item, event, value) User event successful.
load onLoad (void) Tree finished loading.
open onOpen (item, node) Node opened. a tree node is expanded.
submit 1 onSubmit (formNode, treeWidget, event) Submit button on a form is clicked.

See Working with Events for a detailed description.

Widget Object

The optional CheckBox Tree property widget is an object with the following properties:

type:

TYPE: Widget | String

The widget must support the accessors get() and set() and must have a checked property. In addition, the widgets should not stop any 'click' events calling event.stop() nor should it change any related widget instances without generating an 'click' event for those widgets. If type is a string, the string value must be a module ID. For example dojox/form/TriStateCheckbox

DEFAULT: null

args:

TYPE: Object?

An optional JavaScript 'key:value' pairs object to be passed to the constructor of the widget.

DEFAULT: null

target:

TYPE: String

Optional name of the target DOM node of a click event, The default is 'INPUT'.

DEFAULT: "INPUT"

mixin:

TYPE: Function

Optional function called prior to instantiation of the widget. If specified, called as: mixin( args ) were args is the list of arguments to be passed to the widget constructor. Argument args is the widget property args with the default arguments required by the CheckBox Tree mixed in. In the function body the "this" object equates to the enclosing node widget.

DEFAULT: null

postCreate:

TYPE: Function

Optional function called immediately after the creation of the widget. If specified, called as: postCreate(). In the function body the "this" object equates to the newly created widget.

DEFAULT: null

In the following example the ToggleButton widget is used instead of the default CheckBox Tree multi-state checkbox. Note: this example also relies on the Tree Styling extension being loaded to hide the tree node labels and icons.

<script type="text/javascript">
  require([
    "dojo/ready",
    "dijit/form/ToggleButton",
    "cbtree/Tree",                      // CheckBox Tree
    "cbtree/store/ObjectStore",         // Eventable Object Store
    "cbtree/model/ForestStoreModel",    // Tree Forest Store Model
    "cbtree/extensions/TreeStyling"     // Tree Styling extension
    ], function( ready, ToggleButton, Tree, ObjectStore, ForestStoreModel ) {

      var store = new ObjectStore( { url: "../../datastore/Simpsons.json" });
      var model = new ForestStoreModel({ store: store,
                                         query: {type: 'parent'},
                                         rootLabel: 'The Simpsons',
                                         checkedRoot: true
                                       });
      ready( function() {
        var tree = new Tree( { model: model,
                               id: "MyTree",
                               widget: { type: ToggleButton,
                                         args:{iconClass:'dijitCheckBoxIcon'},
                                         mixin: function(args) {
                                            args['label'] = this.label;
                                         }
                                       }
                               }, "CheckBoxTree" );
        // Hide Labels and Icons for the entire tree.
        tree.set("labelStyle", {display:'none'});
        tree.set("iconStyle", {display:'none'});

        tree.startup();
      });
    }
  );
</script>
Clone this wiki locally