aciTree using the API demo - A treeview control with jQuery

A demo to show how you can use the aciTree API (read below).

back to index

see the JSON behind this tree
Sample tree
Tree Log... clear log

Init the aciTree by using a relative path to the `ajax.url` option (see the docs for all available aciTree options):

Note: the `ajax` option will be used whenever a tree node needs to be loaded, it is used on the initial AJAX request to init (load) the tree ROOT (what you first see as the tree when you visit this page) and it it used again when a not-yet-loaded inner node (a node that can have children) is opened for the first time. In this demo the entire tree is loaded in one step but the tree can be loaded node by node on request if needed (i.e. when the user clicks on the [+] button to open a node). aciTree will create as many tree levels as returned in the JSON, practically (with server-side coding) the tree can not only be loaded node-by-node but in an optimised way - many levels at once - depending on the tree weight.

You can init as many trees as you want on a single page:

And you can init many at once. Because the tree will be init by default - you need to specify the `autoInit` option (set to FALSE), set the `ajax.url` option and - just after that - init the tree:

Note: when aciTree will make a AJAX request to the `ajax.url` option (to load the tree nodes and init them based on the JSON response from the server), the node ID will be appended to the [string] value of the `ajax.url`, for example - when the tree node with the ID 'node-547' needs to be loaded, the request made to the server will be String(ajax.url + 'node-547'), that's why in my examples there is a ?branch= or ?node_id= at the end of the URL. Server-side you need to read the GET value and return only the data for whatever node ID was requested (insted of returning the entire tree).

Get the aciTree API to use it later (see the docs for all available aciTree API methods):

Note: you need to keep in mind that loading the tree/nodes with AJAX is made in asynchronous way, that means - on tree init - the called function will exit before the tree is actually loaded so we may end up executing some code before the tree itself is ready. That's why I have added a little delay in the previous example, to let time to the tree to finish loading with AJAX and init his structure. The example here is just to let you know how aciTree behaves and not the correct way to implement things. Do not use in real applications, you will need to use events for that! (see examples a bit lower)

Use the 'itemHook' option to set each item in a custom way (just before it is actually added to the DOM):

see the JSON behind this tree
Sample tree

Where the 'parent' is the parent LI element (if any; as a jQuery object), the 'item' is the LI element for the item (as a jQuery object), 'itemData' is the item data (as read from the JSON) and the 'level' is the tree branch level (where the item is located - starting from 0). Inside the itemHook function, this keyword points to the aciTree API (for the current tree).

The way to respond to the aciTree changes is using the events, also if you want to do some stuff just after init or when a specific event is fired:

see the JSON behind this tree
Sample tree

The event handler receives a few extra parameters: the aciTree 'api', the 'item' is the LI element for the item (as a jQuery object; can be NULL - for ROOT for example), 'eventName' the aciTree event name (like 'selected' when a tree item is selected), 'options' is an object you can pass to some of the aciTree API methods and it is sent back to the event handler function (more about this a bit later).

Note: most of the aciTree API methods trigger one or more events. When you call the API methods from inside the event handler function you need to make sure you will not end in a loop, consult the docs to see what events are triggered for each API method you want to call.

Now that we know how to listen for the aciTree events, the way to go with the example where we used the setTimeout to add a delay and set the selection to the first tree item:

see the JSON behind this tree
Sample tree

Bad way to do things and end up in a loop:

Note: because the API method .open itself is triggering the 'beforeopen' event, you will end in a never endin loop with the above code. There is no easy explanation what you can and can't do inside the event handler function, you need to check the docs and see what events are triggered. Please note that some API methods also internally call other API methods so more events (than expected) can be triggered at a time. In practice any of the API methods can be used by checking the 'eventName' and item states before trying to call the API to do something.

Important: a few words about the 'options' object for the API methods that support this parameter:

see the JSON behind this tree
Sample tree

As you can see it's the same example as before but now we use the 'success' and 'fail' callbacks to do some processing on success/fail (depending on the current opperation, in this example - on item selection).

Note: the 'success' and 'fail' callbacks need to be used whenever you want to do any processing related to the success (or not) of an operation. These callbacks are available for most of the API methods that change the aciTree structure (read the docs to find what other options are available with the 'options' parameter for each API method). Their use is needed because there can be async operations involved, then the API method will exit before the job is finished. Also note that the this keyword inside these callback functions points to the aciTree API, 'item' is the LI for the item (if any, as a jQuery object, can be NULL for the ROOT - for example) and the 'options' is the object initially passed to the API method. Note that the 'options' object inside the callbacks can also contain other new properties, some of the API methods are returning values as properties of the 'options' object (check the docs for each API method you want to use).

The 'options' parameter (for the API methods that support this parameter) is passed to all inner API methods and ends up as a parameter to both the event handler and the 'success' and 'fail' callbacks. There can be new properties set and you can pass your own properties (but make sure you do not override the defaults, I suggest using a [_] infront of custom property names). You can also check the uid property (set by default to 'ui'). By setting this value you can respond in different ways for different actions:

see the JSON behind this tree
Sample tree
(select a closed tree inode item and press open - vs. - open with the [+] button)