NAME¶

HTML::PopupTreeSelect - HTML popup tree widget

SYNOPSIS¶

  use HTML::PopupTreeSelect;
  # setup your tree as a hash structure.  This one sets up a tree like:
  # 
  # - Root
  #   - Top Category 1
  #      - Sub Category 1
  #      - Sub Category 2
  #   - Top Category 2
  my $data = { label    => "Root",
               value    => 0,              
               children => [
                            { label    => "Top Category 1",
                              value    => 1,
                              children => [
                                           { label => "Sub Category 1",
                                             value => 2
                                           },
                                           { label => "Sub Category 2",
                                             value => 3
                                           },
                                          ],
                            },
                            { label  => "Top Category 2",
                              value  => 4 
                            },
                           ]
              };
  # create your HTML tree select widget.  This one will call a
  # javascript function 'select_category(value)' when the user selects
  # a category.
  my $select = HTML::PopupTreeSelect->new(name         => 'category',
                                          data         => $data,
                                          title        => 'Select a Category',
                                          button_label => 'Choose',
                                          onselect     => 'select_category');
  # include it in your HTML page, for example using HTML::Template:
  $template->param(category_select => $select->output);

DESCRIPTION¶

This module creates an HTML popup tree selector. The HTML and Javascript produced will work in Mozilla 1+ (Netscape 6+) on all operating systems, Microsoft IE 5+ and Safari 1.0. For an example, visit this page:

  http://sam.tregar.com/html-popuptreeselect/example.html

I based the design for this widget on the xTree widget from WebFX. You can find it here:

  http://webfx.eae.net/dhtml/xtree/

This module is used to provide the category chooser in Krang, an open source content management system. You can find out more about Krang here:

  http://krang.sf.net

INSTALLATION¶

To use this module you'll need to copy the contents of the images/ directory in the module distribution into a place where your webserver can serve them. If that's not the same place your CGI will run from then you need to set the image_path parameter when you call new(). See below for details.

INTERFACE¶

output()¶

Call output() to get HTML from the widget object to include in your page.

SUBCLASSING¶

HTML::PopupTreeSelect can be subclassed, for the purposes of -- for example -- using a different template engine to generate the HTML. Here's one brief example, using the Template engine:

   package My::PopupTreeSelect;
   use Template;
   use base 'HTML::PopupTreeSelect';
   sub output {
       my($self) = @_;
       return $self->SUPER::output(Template->new);
   }
   sub _output_generate {
       my($self, $template, $param) = @_;
       my $output;
       $template->process(\$MY_TEMPLATE_SRC, $param, \$output);
       return $output;
   }

Of course, $MY_TEMPLATE_SRC will need to be provided, too. $HTML::PopupTreeSelect::TEMPLATE_SRC is a global variable, so it may be modified to your liking, or your own template data can be provided to your own template generator method.

CAVEATS¶

•

The javascript used to implement the widget needs control over the global document.onmousedown, document.onmousemove and document.onmouseup handlers. This means that it's unlikely to play nice with other DHTML on the same page.

TODO¶

Here are some possible directions for future development. Send me a patch for one of these and you're guaranteed a place in Changes.

•

Allow each node to specify its own icon. Right now every node uses "closed_node.png" and "open_node.png".

BUGS¶

I know of no bugs in this module. If you find one, please file a bug report at:

  http://rt.cpan.org

Alternately you can email me directly at "sam@tregar.com". Please include the version of the module and a complete test case that demonstrates the bug.

COPYRIGHT AND LICENSE¶

Copyright (C) 2003, 2004 Sam Tregar

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

AUTHOR¶

Sam Tregar <sam@tregar.com>