README

Path: README
Last Update: Wed Jul 13 01:19:01 Pacific Standard Time 2005

LiveTree - Tree widget that loads data asynchronously as-needed

Home page: www.epiphyte.ca/code/live_tree.html

LiveTree implements a JavaScript/DHTML tree widget that loads data asynchronously as-needed (using AJAX). This makes it ideal for cases where the dataset is too large to load to the browser all at once. Data can be provided in the HTML page as well, in which case no asynchronous loading is needed, making this widget suitable for standalone client-side use.

LiveTree consists of two components: client-side JavaScript code that runs in the user’s browser which displays and allows the user to navigate the tree, and a server component that provides data to the client. The client-server protocol is very simple, which means server components can be easily created for just about any web server configuration with minimal effort. Presently, the only existing server component is for Ruby On Rails. The rest of this document specifically addresses using LiveTree with Ruby On Rails.

The client-side JavaScript component is documented here.

See STATUS for LiveTree’s current development status.

Setup

  1. Untar/zip the distribution into your rails application directory. It will create the following:
    • README.live_tree - small note that points to this file
    • vendor/live_tree/* - ruby on rails code
    • vendor/live_tree/doc/* - this documentation
    • public/images/live_tree*.gif - images
    • public/stylesheets/live_tree.css - stylesheet
    • public/javascripts/live_tree.js - JavaScript
  2. Add to app/controllers/application.rb:
         require "live_tree/live_tree.rb"
         class ApplicationController < ActionController::Base
                 include LiveTree
                 helper LiveTreeHelper
         end
    

    This will make LiveTree available to your whole application. If you only want it to be available to a particular controller, add it to that controller instead.

Getting Started

This section will walk you through setting up a tree.

Model

LiveTree gets your data from an ActiveRecord model object which acts as a tree. For the sake of efficiency, you should also have your model use a counter cache.

For example (in app/models/person.rb):

        class Person < ActiveRecord::Base
                acts_as_tree :order => "name", :counter_cache => true
        end

and the table definition:

        CREATE TABLE people (
                id INT(11) NOT NULL AUTO_INCREMENT,
                parent_id INT(11) DEFAULT NULL,
                name VARCHAR(100) NOT NULL DEFAULT '',
                children_count INT(11) NOT NULL DEFAULT 0,
                PRIMARY KEY (id)
        );

If you wish to serve data that does not come from an ActiveRecord model, simply use an object that has a children and a parent method.

Controller

A controller is used to serve data to the client. The simplest way to set up your controller is as follows (in app/controllers/family_tree_controller.rb):

        class FamilyController < ApplicationController
                live_tree :family_tree, :model => :person
                def show_tree
                        @root = Person.find(params[:id]);
                end
        end

The LiveTree::ClassMethods.live_tree class method sets up your controller to serve data to the client.

By default, it gets a data item’s name using the model object’s name property. You can change that using the :get_item_name_proc option. Also note that the LiveTree does not escape HTML special characters in item names, so your names can contain HTML formatting and special characters (and if this is not desirable, you must use the :get_item_name_proc option to escape the name).

The show_tree action defined in the example reads the specified person from the database, which will be the root (top) of the displayed family tree, for use by the view.

View

Finally, the view displays the tree (in app/views/family/show_tree.rhtml):

        <div style="width:300px;height:415px">
                <%= live_tree(:family_tree, {
                        :initial_data_root => @root,
                        :on_click_item => "alert('You clicked on ' + item.name)",
                }) %>
        </div>

The LiveTree::LiveTreeHelper.live_tree helper method displays the tree. The :initial_data_root option specifies the top item of the tree. Since the tree by default expands in size to fill the element it is in, we wrap it in a div that has a specified width and height.

You will also need to include the LiveTree JavaScript and stylesheet in your page’s HEAD section, as well as the Prototype JavaScript (which is bundled with rails):

        <html>
                <head>
                        ...
                        <%= stylesheet_link_tag('live_tree') %>
                        <%= javascript_include_tag "prototype" %>
                        <%= javascript_include_tag "live_tree" %>
                        ...
                </head>
                ...
        </html>

Now if you start rails and browse to localhost:3000/family/show_tree/1, it will display the family tree, with the person whose database ID is 1 at the top.

Author and Copyright

Author:Emanuel Borsboom (www.epiphyte.ca/)
Copyright:Copyright © 2005 Emanuel Borsboom
License:MIT (see LICENSE)

[Validate]