/ 
HTML-PopupTreeSelect-1.1
River stage one • 2 direct dependents • 2 total dependents
/ HTML::PopupTreeSelect

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 and Microsoft IE 5+ on Windows and Mac. 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/

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

new()

new(), is used to build a new HTML selector. You call it with a description of the tree to display and get back an object. Call it with following parameters:

name

A unique name for the tree selector. You can have multiple tree selectors on a page, but they must have unique names. Must be alpha-numeric and begin with a letter.

data

This must be a hash reference containing the following keys:

label (required)

The textual label for this node.

value (required)

The value passed to the onselect handler or set in the form_field when the user selects this node.

open (optional)

If set to 1 this node will start open (showing its children). By default all nodes start closed.

children (optional)

The 'children' key may point to an array of hashes with the same keys. This is the tree structure which will be displayed in the tree selector.

See SYNOPSIS above for an example of a valid data structure.

title

The title of the window which pops up.

button_label (optional)

The widget pops up when the user presses a button. This field gives the label for the button. Defaults to "Choose".

onselect (optional)

Specifies a Javascript function that will be called when an item in the tree is selected. Recieves the value of the item as a single argument. The default is for nothing to happen.

form_field (optional)

Specifies a form field to recieve the value of the selected item. This provides a no-javascript means to use this widget (although the widget itself, of course, uses great gobs of javascript).

form_field_form (optional)

Specifies the form in which to find the form_field specified. If not included the first form on the page will be used.

include_css (optional)

Set this to 0 and the default CSS will not be included in the widget output. This allows you to include your own CSS which will be used by your widget. Modifying the CSS will allow you to control the fonts, colors and spacing in the output widget.

If you run the widget with include_css set to 1 then you can use that output as a base on which to make changes.

image_path (optional)

Set this to the URL to the images for the widget. These files should be copied from the images directory in the module distribution into a place where your webserver can reach them. By default this is empty and the widget expects to find images in the current directory.

output()

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

CAVEATS

  • Under IE you'll find that select boxes show through the select window. This is a well known bug in IE's CSS positioning support and as far as I know there's nothing I can do about it. Careful form design is the only solution. Please contact me if you know different!

  • Performance on huge trees isn't great, but should improve in future versions. This version should be usable up to around 10,000 nodes.

  • The javascript used to implement the widget needs control over the global document.onmousedown handler. This means that

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.

  • Allow the select window to be dragged around by clicking and dragging the title.

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 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>