Ajax.Tree
The most kick-ass tree class you can’t surpass so don’t blow your gas lest development reach an impasse, not to be crass...
Ajax.Tree
Index

Ajax Tree

Created by Colin Mollenhour

Description

This tree class can be used with or without Ajax.  You simply define node types and supply options, hooks, handlers, etc. for each type and start creating nodes.  All node types can be created using the same constructor by passing it the type as a string.  The way it handles data and reacts to user input is completely customizable for each individual node type.

LIVE DEMO

http://colin.mollenhour.com- /ajaxtree- /ajaxtreetest.html

Summary
Ajax Tree
Created by Colin Mollenhour
Usage
Usage specifications and examples.
Using the Javascript
Handling Server Requests
Server Response
The server response is expected to be in JSON format.
Specifications
Example
Ajax.Tree
Ajax.Tree is the utility class for Ajax.Tree.Base.
Usage
Use Ajax.Tree.create to create a customized tree class.
Functions
create
Returns a constructor for a new class that is specific to the structure passed.
Options
All options are unique per type, and can be accessed inside class functions by “this.options.<option>”.
className
The className for the newly created element div and span elements, defaults to the node type
draggable
Not yet implimented.
leafNode
If true, the <mark> will get the className ‘leaf’ and clicks will not fire a <toggleChildren>.
page
If specified, <getContents> will be called on clicking the <mark>.
prependParentId
If true, the new element id will be prepended with it’s parent’s id.
insertion
The insertion function used to handle the node “data”.
Ajax. Tree.Base
Ajax.Tree.Base is designed to be extended using Ajax.Tree.create.
Usage
Use this class as the base for your own customized Ajax.Tree class.
constructor
DOM Elements
The DOM elements created on instantiation of a new node.
Hooks
Hooks are provided for fine control over interactivity.
callback
Called to build query parameters for the Ajax.Request.
onClearContents
Called after a node’s children have been cleared.
onClick
Called on user clicking the mark.
onContentLoaded
Called after all new nodes have been constructed.
onDispose
Called after a node has been disposed.
onGetContents
Called immediately after the Ajax.Request is sent.
onGetContentsComplete
Called after the Ajax.Request onComplete
insertion
Called by the constructor after the basic node element has been built.
Flags
All flags listed here are accessed by this.<flag> and initialized to the values on the left.
Functions
Options
See Ajax.Tree.Options
Properties
All properties are accessed by this.<property>.

Usage

Usage specifications and examples.

Requirements

Prototype 1.5.0 rc1 http://prototype.conio.net/

LIVE DEMO

http://colin.mollenhour.com- /ajaxtree- /ajaxtreetest.html

Source Code

http://colin.mollenhour.com/ajaxtree/ajaxtree.js

Summary
Using the Javascript
Handling Server Requests
Server Response
The server response is expected to be in JSON format.
Specifications
Example

Using the Javascript

Ajax.Tree is designed to be used in two steps:

Handling Server Requests

The default format for server requests, which can be customized via the <callback> hook

getContents’tree=getContents&id=’this.element.id

Now just handle those post variables however you like and use correct format in your Server Response.

Server Response

The server response is expected to be in JSON format.  It can be sent either in the responseText, or an X-JSON header.  The X-JSON header evaluated result is check for the presence of a nodes key, which is expected to be an Array.  If the X-JSON header does not contain a nodes key, the responseText is evaluated.  If the evaluated responseText does not have a nodes key, no nodes are built and this is not an error.  Any related hooks will still be called and passed the server response variables as usual.

Specifications

  • Must contain a “nodes” array of nodes.
  • If the “nodes” array does not exist, no nodes will be created.  However, the <onContentLoaded> and <onGetContentsComplete> hooks will still be called.
  • Each element of “nodes” must contain:
idThe new node’s element id.  See <prependParentId>.
typeThe new node’s <type> keyword, as defined in the structure passed to Ajax.Tree.create.
dataEither a string (for default <insertion>) or some other object to be passed to <insertion>.
  • Each node can contain nested nodes by adding a “nodes” array to a node.
  • Other attributes can be scattered throughout the response data.  It can be accessed by the <onContentLoaded> and <getContentsComplete> hooks or for each individual node through the <insertion> option.

Example

This response example coincides with the Ajax.Tree.Usage example

{
    nodes: [
        {
            id: 'dir-1',
            type: 'directory',
            data: 'Work',
            nodes: [
                {
                    id: 'dir-1_subdir-1',
                    type: 'directory',
                    data: 'Accounting'
                }
            ]
        },
        {
            id: 'file-1',
            type: 'file',
            data: {
                name: 'Presentation.ppt',
                size: '30.2KB',
                fileid: 53255596
            },
        }
    ]
}

Ajax.Tree

Ajax.Tree is the utility class for Ajax.Tree.Base.  Using create, you can create a new class that is an extension of Ajax.Tree.Base.  Using this new constructor, you can build a tree dynamically using multiple node types without the need for separate constructors.  The node types are defined in a hash passed to create which also defines settings and handlers for each type.

Summary
Usage
Use Ajax.Tree.create to create a customized tree class.
Functions
create
Returns a constructor for a new class that is specific to the structure passed.
Options
All options are unique per type, and can be accessed inside class functions by “this.options.<option>”.
className
The className for the newly created element div and span elements, defaults to the node type
draggable
Not yet implimented.
leafNode
If true, the <mark> will get the className ‘leaf’ and clicks will not fire a <toggleChildren>.
page
If specified, <getContents> will be called on clicking the <mark>.
prependParentId
If true, the new element id will be prepended with it’s parent’s id.
insertion
The insertion function used to handle the node “data”.

Usage

Use Ajax.Tree.create to create a customized tree class.

This example creates a simple file browser tree.  It also demonstrates the use of an overridden insertion, and the <onClick> hook.

See Ajax.Tree.Base.Usage for information on using the constructor produced by this example.

For more detail on defining your own types and handling server responses, see Options and Ajax.Tree.Base.

Ajax.FileBrowser = Ajax.Tree.create({
    types: {
        directory: {
            page: 'filebrowser.php'
        },
        file: {
            leafNode: true,
            insertion: function(element,data){
                Element.update(element, data.name+' Size: '+data.size);
                this.dlLink = Builder.node('span',{
                    id: data.fileid,
                    className: 'download'
                },['download']);
                this.dlLinkObserver = this.options.download.bindAsEventListener(this);
                Event.observe(this.dlLink,'click',this.dlLinkObserver);
                element.appendChild(this.dlLink);
            },
            dispose: function(){
                Event.stopObserving(this.dlLink,'click',this.dlLinkObserver);
            },
            onClick: function(event){
                showThumbnail(this.element.id);
            },
            download: function(event){
                window.location.href = 'getfile.php?fileid='+Event.element(event).id;
            }
        }
    }
});

Functions

create

create: function(structure)

Returns a constructor for a new class that is specific to the structure passed.  This new class is an extension of Ajax.Tree.Base

structureThe structure that defines node types and their options and hooks.

Options

All options are unique per type, and can be accessed inside class functions by “this.options.<option>”.

className

className: type

The className for the newly created element div and span elements, defaults to the node type

draggable

draggable: false

Not yet implimented.

leafNode

leafNode: false

If true, the <mark> will get the className ‘leaf’ and clicks will not fire a <toggleChildren>.

page

page: null

If specified, <getContents> will be called on clicking the <mark>.

prependParentId

prependParentId: false

If true, the new element id will be prepended with it’s parent’s id.

insertion

insertion: Element.update

The insertion function used to handle the node “data”.

See Ajax.Tree.Base.insertion

Ajax. Tree.Base

Ajax.Tree.Base is designed to be extended using Ajax.Tree.create.  The extension of this base class lets you add nodes to a tree in any way you like.

Summary
Usage
Use this class as the base for your own customized Ajax.Tree class.
constructor
DOM Elements
The DOM elements created on instantiation of a new node.
Hooks
Hooks are provided for fine control over interactivity.
callback
Called to build query parameters for the Ajax.Request.
onClearContents
Called after a node’s children have been cleared.
onClick
Called on user clicking the mark.
onContentLoaded
Called after all new nodes have been constructed.
onDispose
Called after a node has been disposed.
onGetContents
Called immediately after the Ajax.Request is sent.
onGetContentsComplete
Called after the Ajax.Request onComplete
insertion
Called by the constructor after the basic node element has been built.
Flags
All flags listed here are accessed by this.<flag> and initialized to the values on the left.
Functions
Options
See Ajax.Tree.Options
Properties
All properties are accessed by this.<property>.

Usage

Use this class as the base for your own customized Ajax.Tree class.  The Ajax.Tree.Base class is not intended to be used directly.  Instead, create your own extension of this class with Ajax.Tree.create.  With the extended class, you may now start creating nodes using a typical javascript constructor.

constructor

The class returned from Ajax.Tree.create can be instantied with the following arguments

Arguments

parentThe id or element of the new node’s parent
idThe new node’s id
typeThe new node’s type, corresponding to one of the keys of the types hash passed to Ajax.Tree.create
dataA string or other object containing data to be processed by the type’s insertion function

Example code

See Ajax.Tree.Usage for the corresponding, more detailed usage example of Ajax.Tree.create

<div id="file_browser"></div>
<script type="text/javascript">
    Ajax.FileBrowser = Ajax.Tree.create({...});
    new Ajax.FileBrowser('file_browser','root','directory','My Files');
</script>

DOM Elements

The DOM elements created on instantiation of a new node.  All DOM elements are accessible using this.<element>.

parent(div) - the node’s parent element
element(div) - the primary div, contains mark, span and children. has className: ‘treenode’ and this.options.className || this.type
mark(span) - the expanded/collapsed mark. has className: ‘mark’ and one of ‘expanded’, ‘collapsed’, ‘leaf’
span(span) - the primary container for node data. has className: ‘treedata’ and this.options.className || this.type

Hooks

Hooks are provided for fine control over interactivity.  Implement hooks separately for each node type.

NOTE

For all hooks, this is a reference to the node’s class instance.

Example

Alerts the user as to how many child nodes are loaded.

TreeOfNodes = Ajax.Tree.create({
    types: {
        node:  {
            page: 'nodes.php',
            onContentLoaded: function(xhr,json){
                alert('Got '+$H(json.nodes).keys().length+' new nodes');
            }
        }
    }
});

callback

Called to build query parameters for the Ajax.Request.  Should return a query string.

idThe id of the node’s element.

onClearContents

Called after a node’s children have been cleared.

onClick

Called on user clicking the mark.

eventThe click event object

onContentLoaded

Called after all new nodes have been constructed.

xhrThe XMLHttpRequest transport
jsonThe evaluated X-JOSN header object

onDispose

Called after a node has been disposed.

onGetContents

Called immediately after the Ajax.Request is sent.

requestThe Ajax.Request object

onGetContentsComplete

Called after the Ajax.Request onComplete

xhrThe XMLHttpRequest transport
jsonThe evaluated X-JOSN header object

insertion

Called by the constructor after the basic node element has been built.

elementThe tree node’s span DOM element
dataThe data value from the <getContents> response

Default

Element.update(element,data)

Flags

All flags listed here are accessed by this.<flag> and initialized to the values on the left.

loadedfalse - The data below this node has been loaded (<loadContents> sets to true, <getContents> sets to false)
openingfalse - Ajax.Request is in progress (<getContents> sets to true, <getContentsComplete> sets to false)

Functions

clearContentsclears the node’s children and sets loaded to false
disposecalls clearContents and cleans up the node’s events, references, etc..
getContentstriggers the Ajax.Request if loaded is true, otherwise, calls clearContents
hidehides the node’s element
hideChildrenhides all of the node’s children’s elements and sets the mark’s class to ‘collapsed’
showshows the node’s element
showChildrenshows all of the node’s children’s elements and sets the mark’s class to ‘expanded’
togglecalls show/hide as appropriate
toggleChildrencalls showChildren/hideChildren as appropriate

Options

See Ajax.Tree.Options

Properties

All properties are accessed by this.<property>.

childrenAn Array (with Prototype extensions) of all children of the current node
element.treeNodeReference to the tree node (this)
parent.treeNodeThe node’s parent’s tree node (if exists, else undefined)
typeThe tree node’s type (string)
Copyright © 2006 Colin Mollenhour.  Generated by Natural Docs.
Ajax.Tree.Base is designed to be extended using Ajax.Tree.create.
create: function(structure)
Returns a constructor for a new class that is specific to the structure passed.
className: type
The className for the newly created element div and span elements, defaults to the node type
draggable: false
Not yet implimented.
leafNode: false
If true, the mark will get the className ‘leaf’ and clicks will not fire a toggleChildren.
page: null
If specified, getContents will be called on clicking the mark.
prependParentId: false
If true, the new element id will be prepended with it’s parent’s id.
insertion: Element.update
The insertion function used to handle the node “data”.
All options are unique per type, and can be accessed inside class functions by “this.options.<option>”.
Use Ajax.Tree.create to create a customized tree class.
Use this class as the base for your own customized Ajax.Tree class.
The server response is expected to be in JSON format.
Called by the constructor after the basic node element has been built.