Stevan Little > Tree-Simple-View-0.17 > Tree::Simple::View::DHTML

Download:
Tree-Simple-View-0.17.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.13   Source  

NAME ^

Tree::Simple::View::DHTML - A class for viewing Tree::Simple hierarchies in DHTML

SYNOPSIS ^

  use Tree::Simple::View::DHTML;
  
  ## a simple example
  
  # use the defaults (an unordered list with no CSS)
  my $tree_view = Tree::Simple::View::DHTML->new($tree);

  ## more complex examples
  
  # using the CSS properties
  my $tree_view = Tree::Simple::View::DHTML->new($tree => (
                                list_type  => "ordered",
                                list_css => "list-style: circle;",
                                list_item_css => "font-family: courier;",
                                expanded_item_css => "font-family: courier; font-weight: bold",
                                link_css => "text-decoration: none;"                                
                                ));  

  # using the CSS classes                                                                  
  my $tree_view = Tree::Simple::View::DHTML->new($tree => (
                                list_css_class => "myListClass",
                                list_item_css_class => "myListItemClass",
                                expanded_item_css_class => "myExpandedListItemClass",                                
                                link_css_class => "myListItemLinkClass"
                                ));                                                                                                                                                                                                                                                                                                                                                                                                                                                                                

  # mixing the CSS properties and CSS classes                                   
  my $tree_view = Tree::Simple::View::DHTML->new($tree => (
                                list_css => "list-style: circle;",
                                list_item_css => "font-family: courier;",
                                expanded_item_css_class => "myExpandedListItemClass",                                
                                link_css_class => "myListItemLinkClass"                                  
                                # format complex nodes with a function
                                node_formatter => sub {
                                    my ($tree) = @_;
                                    return "<B>" . $tree->getNodeValue()->description() . "</B>";
                                    },
                                # add a radio button element to the tree
                                # with the name of 'tree_id'
                                radio_button => 'tree_id'    
                                ));  

  # print out the javascript nessecary for the DHTML 
  # functionality of this tree                                 
  print $tree_view->javascript();                   
  
  # print out the tree fully expanded
  print $tree_view->expandAll();
  
  # print out the tree expanded along a given path (see below for details)
  print $tree_view->expandPath("Root", "Child", "GrandChild");                                                                          

DESCRIPTION ^

This is a class for use with Tree::Simple object hierarchies to serve as a means of displaying them in DHTML. It is the "View", while the Tree::Simple object hierarchy would be the "Model" in your standard Model-View-Controller paradigm.

This class outputs fairly vanilla HTML, which is augmented with CSS and javascript to produce an expanding and collapsing tree widget. The javascript code used is intentionally very simple, and makes no attempt to do anything but expand and collapse the tree. The javascript code is output seperately from the actual tree, and so it can be overridden to implement more complex behaviors if you like. see the documentation for the javascript method for more details.

It should be noted that each expandable/collapsable level is tagged with a unique ID which is constructed from the object instances hex-address and a counter. This means if you call expandAll and/or expandPath on the same object in the same output, you will have generated two totally different trees, which just happend to look exactly alike, but will behave independently of one another. However, abuse of this "feature" is not recommended, as I am cannot guarentee it will always be this way.

METHODS ^

new ($tree, %configuration)

Accepts a $tree argument of a Tree::Simple object (or one derived from Tree::Simple), if $tree is not a Tree::Simple object, and exception is thrown. This $tree object does not need to be a ROOT, you can start at any level of the tree you desire. The options in the %config argument are as follows:

list_type

This can be either 'ordered' or 'unordered', which will produce ordered and unordered lists respectively. The default is 'unordered'.

list_css

This can be a string of CSS to be applied to the list tag (UL or OL depending upon the list_type option). This option and the list_css_class are mutually exclusive, and this option will override in a conflict.

list_css_class

This can be a CSS class name which is applied to the list tag (UL or OL depending upon the list_type option). This option and the list_css are mutually exclusive, and the list_css option will override in a conflict.

list_item_css

This can be a string of CSS to be applied to the list item tag (LI). This option and the list_item_css_class are mutually exclusive, and this option will override in a conflict.

list_item_css_class

This can be a CSS class name which is applied to the list item tag (LI). This option and the list_item_css are mutually exclusive, and the list_item_css option will override in a conflict.

expanded_item_css

This can be a string of CSS to be applied to the list item tag (LI) if it has an expanded set of children. This option and the expanded_item_css_class are mutually exclusive, and this option will override in a conflict.

expanded_item_css_class

This can be a CSS class name which is applied to the list item tag (LI) if it has an expanded set of children. This option and the expanded_item_css are mutually exclusive, and the expanded_item_css option will override in a conflict.

link_css_class

This can be a string of CSS to be applied to the link (A tag) which serves as the handler to drive the expansion and collapsing of the tree. This option and the link_css_class_class are mutually exclusive, and this option will override in a conflict.

link_css_class_class

This can be a CSS class name which is applied to the link (A tag) which serves as the handler to drive the expansion and collapsing of the tree. This option and the link_css_class are mutually exclusive, and the link_css_class option will override in a conflict.

node_formatter

This can be a CODE reference which will be given the current tree object as its only argument. The output of this subroutine will be placed within the link tags (A) which themselves are within the list item tags (LI). This option can be used to implement; custom formatting of the node, handling of complex node objects.

radio_button

This will create a radio button for each node of the tree with the INPUT NAME attribute being the value of this attribute. This is basically a 'macro' for the form_element_formatter.

checkbox

This will create a checkbox for each node of the tree with the INPUT NAME attribute being the value of this attribute. This is basically a 'macro' for the form_element_formatter.

form_element_formatter

This can be a CODE reference which will be given the current tree object as its only argument. The output of this subroutine will be placed after the list item (LI) tags, and if applicable, before the the link tag (A). This option can be used to add a form element such a radio button or checkbox to each element of the tree, which is useful when creating selection widgets.

use_tree_uids

This item allows you to bypass the built in unique ID generation feature of this module and instead use the unique ID from the Tree::Simple object itself (gotten by calling the method getUID).

getTree

A basic accessor to reach the underlying tree object.

getConfig

A basic accessor to reach the underlying configuration hash.

includeTrunk ($boolean)

This controls the getting and setting (through the optional $boolean argument) of the option to include the tree's trunk in the output. Many times, the trunk is not actually part of the tree, but simply a root from which all the branches spring. However, on occasion, it might be nessecary to view a sub-tree, in which case, the trunk is likely intended to be part of the output. This option defaults to off.

setPathComparisonFunction ($CODE)

This takes a $CODE reference, which can be used to add custom path comparison features to Tree::Simple::View. The function will get two arguments, the first is the $current_path, the second is the $current_tree. When using expandPath, it may sometimes be nessecary to be able to control the comparison of the path values. For instance, your node may be an object and need a specific method called to match the path against.

expandPath (@path)

This method will return a string of HTML which will represent your tree expanded along the given @path. This is best shown visually. Given this tree:

  Tree-Simple-View
      lib
          Tree
              Simple
                  View.pm
                  View
                      HTML.pm
                      DHTML.pm
      Makefile.PL
      MANIFEST
      README 
      Changes
      t
          10_Tree_Simple_View_test.t
          20_Tree_Simple_View_HTML_test.t
          30_Tree_Simple_View_DHTML_test.t

And given this path:

  Tree-Simple-View, lib, Tree, Simple

Your display would like something like this:

  Tree-Simple-View
      lib
          Tree
              Simple
                  View.pm
                  View
      Makefile.PL
      MANIFEST
      README 
      Changes
      t

As you can see, the given path has been expanded, but no other sub-trees are shown. However, the other sub-trees are actually there, and can be expanded or collapsed by clicking on them. It is worth noting that this method will actually output the entire tree, but with only the expanded path shown.

It should be noted that this method actually calls either the expandPathSimple or expandPathComplex method depending upon the %config argument in the constructor. See their documenation for details.

expandPathSimple ($tree, @path)

If no %config argument is given in the constructor, then this method is called by expandPath. This method is optimized since it does not need to process any configuration, but just as the name implies, it's output is simple.

This method can also be used for another purpose, which is to bypass a previously specified configuration and use the base "simple" configuration instead.

expandPathComplex ($tree, $config, @path)

If a %config argument is given in the constructor, then this method is called by expandPath. This method has been optimized to be used with configurations, and will actually custom compile code (using eval) to speed up the generation of the output.

This method can also be used for another purpose, which is to bypass a previously specified configuration and use the configuration specified (as a HASH reference) in the $config parameter.

expandAll

This method will return a string of HTML which will represent your tree completely expanded. You can then collapse and re-expand any items at will though the DHTML functionality.

It should be noted that this method actually calls either the expandAllSimple or expandAllComplex method depending upon the %config argument in the constructor.

expandAllSimple

If no %config argument is given in the constructor, then this method is called by expandAll. This method too is optimized since it does not need to process any configuration.

This method as well can also be used to bypass a previously specified configuration and use the base "simple" configuration instead.

expandAllComplex ($config)

If a %config argument is given in the constructor, then this method is called by expandAll. This method too has been optimized to be used with configurations, and will also custom compile code (using eval) to speed up the generation of the output.

Just as with expandPathComplex, this method can be to bypass a previously specified configuration and use the configuration specified (as a HASH reference) in the $config parameter.

javascript

This method is used to output an HTML SCRIPT tag which contains the javascript used to drive the DHTML in this widget. This is not done automatically, so that one can optionally override my javascript and implement a more complex handler to serve their purposes. The javascript function returned is documented here:

toggleTree (tree_id)

The DOM element whose ID attribute corresponds to the given tree_id is found. If its CSS display property is set to 'none', it is then set to 'block'. If its CSS display property is not set to 'none', it is then set to 'none'. This controls the basic expansion and collapsing of the tree widget.

TO DO ^

depth-based css

See this item in the Tree::Simple::View::HTML documentation, since Tree::Simple::View::DHTML actually is a subclass of Tree::Simple::View::HTML, this functionality would be inherited.

optional javascript handler override

This class implements the javascript handler for the DHTML functionally as an anchor tag (A) whose CSS properties can be set, but nothing more. I would like to allow this to be overridden, but I want to do it in the correct way which will eliminate issues with the DHTML. I am still giving this some thought.

expand/collapse all javascript function

An available javascript function which would expand or collapse the entire tree. This is would be pretty reasonable to implement since I know all the tree_ids I have created. However, on large trees, this would inadvisable as it would probably bring the browser to a screaching halt.

BROWSER SUPPORT ^

While DHTML in the early days (1998-2001) was a bug ridden cross-platform/cross-browser nightmare (believe me I know, I made my living doing it back then). Recent browsers (5.0 and above) tend to be able to handle a decent sub-set of CSS1 and the javascript DOM objects to drive it. This module output DHTML which should work on any browser that supports CSS1, in particular the 'display' property, and DOM1, in particular the 'getElementById' method and the ability to manipulate the CSS 'display' property of the object that DOM method would return.

But in case you don't care that much about CSS1 and the DOM, and just want to know what browsers/platforms this supports, here is the list (of ones I have tested so far):

Mac OS X
Safari 1.2 and above
OmniWeb 4.5
Internet Explorer 5.2 and above
Netscape 7.1
Windows XP Pro
Mozilla 1.7
Firefox
Internet Explorer 6.0
Netscape 7.1

This is also known to gracefully degrade in Netscape 4.7.2, in which it just shows the entire expanded tree.

BUGS ^

None that I am aware of. Of course, if you find a bug, let me know, and I will be sure to fix it.

CODE COVERAGE ^

See the CODE COVERAGE section of Tree::Simple::View for details.

ACKNOWLEDGEMENTS ^

Thanks to Brett Nuske for the idea of the use_tree_uid configuration parameter.

SEE ALSO ^

A great CSS reference can be found at:

    http://www.htmlhelp.com/reference/css/

Information specifically about CSS for HTML lists is at:

    http://www.htmlhelp.com/reference/css/classification/list-style.html

AUTHOR ^

stevan little, <stevan@iinteractive.com>

COPYRIGHT AND LICENSE ^

Copyright 2004-2008 by Infinity Interactive, Inc.

http://www.iinteractive.com

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: