Stevan Little

NAME

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

SYNOPSIS

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

  ## more complex examples
                                        
  # use the CSS properties                                    
  my $tree_view = Tree::Simple::View::HTML->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",                               
                                ));  
                                
  # use the CSS classes                                  
  my $tree_view = Tree::Simple::View::HTML->new($tree => (
                                list_css_class => "myListClass",
                                list_item_css_class => "myListItemClass",
                                expanded_item_css_class => "myExpandedListItemClass",                                
                                ));                                                                                                                                                                                                                                                                                                                                                                                                                                                                                
                                   
  # mix the CSS properties and CSS classes
  my $tree_view = Tree::Simple::View::HTML->new($tree => (
                                list_css => "list-style: circle;",
                                list_item_css => "font-family: courier;",
                                expanded_item_css_class => "myExpandedListItemClass",                                                         
                                node_formatter => sub {
                                    my ($tree) = @_;
                                    return "<B>" . $tree->getNodeValue()->description() . "</B>";
                                    }
                                ));  
                              
  
  # 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 HTML. 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 in its simpliest configuration, suitable for both legacy browsers and text-based browsers. Through the use of various configuration options, CSS can be applied to support more advanced browsers but still degrade gracefully to legacy browsers.

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:

tag_style

This can be either 'html' or 'xhtml', which will produce output with tags in capitals or lowercase respectively, for xhtml compliance. The default is 'html' for backwards compatibility.

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.

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 list item tags (LI). This option can be used to implement; custom formatting of the node, handling of complex node objects or implementing any type of handler code to drive your interface (using link tags or form submissions, etc).

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 (nor is the HTML of the un-expanded nodes to be found in the output).

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.

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.

TO DO

depth-based css

I would like to be able to set any of my css properties as an array, which would essentially allow for depth-based css values. For instance, something like this:

  list_css => [
      "font-size: 14pt;",
      "font-size: 12pt;",
      "font-size: 10pt;"      
      ];

This would result in the first level of the tree having a font-size of 14 points, the second level would have a font-size of 12 points, then all other levels past the second level (third and beyond) would have a font-size of 10 points. Of course if a fourth element were added to this array (ex: "font-size: 8pt;"), then the third level would have a font-size of 10 points, and all others past that level would have the font-size of 8 points.

Ideally this option would be available for all *_css and *_css_class options. I have not yet figured out the best way to do this though, so ideas/suggestions are welcome, of course, patches are even better.

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.

SEE ALSO

If a DHTML based tree is what you are after, then look at the Tree::Simple::View::DHTML class.

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.




Hosting generously
sponsored by Bytemark