RockTree jQuery Extension

RockTree is a jQuery TreeView plugin written specifically for RockChMS. We couldn't find a good TreeView solution that supported multi-select, that looked good, and that implemented Bootstrap 3, so we wrote our own.

Basic Usage

Getting started with RockTree looks a lot like any other jQuery plugin you may have worked with before.

$('#some-element').rockTree();

Additionally, you can get to the underlying object instance by getting the element's data. This allows developers to access RockTree's methods and properties, such as selectedIds.

$('#some-button').click(function () {
    var rockTree = $('#some-element').data('rockTree'),
        idString = rockTree.selectedIds.join(',');
    $('#some-hidden-field').val(idString);
    return true;
});

Options

Setting Name	Data Type	Default Value	Description
id	string	0	Represents the numeric Id or Guid of a node. This option will be used in combination with the restUrl option to pre-fetch data.
selectedIds	array	null	Represents the set of Ids or Guids that should be pre-selected after the tree's data is loaded.
expandedIds	array	null	Represents the set of Ids or Guids of tree nodes that should be pre-fetched and expanded after the tree's data is loaded.
restUrl	string	null	The REST endpoint that the tree will use to fetch data from.
restParams	string	null	Additional query string parameters to be passed along with each request.
local	array	null	Represents a hierarchical data structure that RockTree will attempt to map into its internal data set.
multiselect	bool	false	Determines whether or not more than one tree node can be selected at a time.
loadingHtml	string	Spinner icon	Represents the HTML that will be rendered when a node's content is being loaded remotely.
iconClasses	object	Folder icons	A hash of class names. Valid properties are branchOpen, branchClosed and leaf.
mapping	object		A hash including an array of properties to include in the tree markup as data-* attributes called include and a function called mapData that can be overridden to provide custom data mapping functionality.
onSelected	array	null	An array of event names that will be triggered by the RockTree instance's $el property when a node is selected.

Local or Remote data

RockTree will attempt to load data from any REST endpoint it is configured to point to. Based on the restUrl, the id and the restParams options, RockTree will construct a URL and fire a GET request.

$('#some-element').rockTree({
    id: 1,
    restUrl: '/api/groups',
    restParams: '?groupType=1'
});

Alternatively, RockTree can be initialized with an array of objects if local data is being supplied.

$('#some-element').rockTree({
    local: [
        {
            id: 1,
            name: 'George',
            hasChildren: false
        },
        {
            id: 2,
            name: 'Samuel',
            hasChildren: true,
            children: [
                {
                    id: 3,
                    name: 'Joey',
                    parentId: 2,
                    hasChildren: false
                }
            ]
        }
    ]
});

Finally, if no remote or local option is configured, RockTree will attempt to derive its data from the inner HTML of the element it's initialized on.

<div id="some-element">
    <ul>
        <li data-id="1">George</li>
        <li data-id="2">
            Samuel
            <ul>
                <li data-id="3" data-parent-id="2">Joey</li>
            </ul>
        </li>
    </ul>
</div>

<script type="text/javascript">
    $(function () {
        $('#some-element').rockTree();
    });
</script>

Custom Icons

The icons used in RockTree can be overridden by defining the iconClasses config option.

$('#some-element').rockTree({
    iconClasses: {
        branchOpen: 'icon-minus-sign',
        branchClosed: 'icon-plus-sign',
        leaf: 'icon-ok'
    } 
});

Custom Mapping

If the mapping.mapData config option is overridden, a custom mapping rules can be supplied. Note that this function will need to be recursive.

var mapTheData = function (array) {
    return $.map(array, function (item) {
        var node = {
            id: item.Guid,
            name: item.Title,
            iconCssClass: item.CssClass,
            parentId: item.ParentId,
            hasChildren: item.HasChildren
            isCategory: item.IsCategory
        };

        if (item.Children && typeof item.Children.length === 'number') {
            node.children = mapTheData(item.Children);
        }

        return node;
    });
};

$('#some-element').rockTree({
    mapping: {
        include: [ 'isCategory' ],
        mapData: mapTheData
    }
});

Events

RockTree emits some helpful DOM events that will allow custom code to respond to what's going on with the tree.

Event Name	Description
rockTree:selected	This event is fired after a node has been selected on the tree. The id of the node is passed along as a parameter. Listeners for this event can be bound at any time.
rockTree:dataBound	This event is fired as soon as data local or remote data is bound to the tree. For best results, bind listeners for this event before initializing RockTree.
rockTree:rendered	This event is fired when the tree has finished rendering to the DOM. For best results, bind listeners for this event before initializing RockTree.
rockTree:expand	This event is fired when a tree node is expanded. Listeners for this event can be bound at any time.
rockTree:collapse	This event is fired when a tree node is collapsed. Listeners for this event can be bound at any time.

$('#some-element')
    .on('rockTree:dataBound', function () {
        console.log('data bound!');
    })
    .on('rockTree:rendered', function () {
        console.log('rendered!');
    })
    .on('rockTree:selected', function (e, id) {
        console.log('the node with the id "' + id + '" has been selected');
    })
    .on('rockTree:expand', function () {
        console.log('expanded!');
    })
    .on('rockTree:collapse', function () {
        console.log('collapsed!');
    })
    .rockTree();