HTML::PopupTreeSelect - HTML popup tree widget
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);
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
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.
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:
This must be a hash reference (or an array reference of these hash references, if there are multiple "root" categories) containing the following keys:
See SYNOPSIS above for an example of a valid data structure.
form_field specified. If
not included the first form on the page will be used.
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.
use_scrollbars option as well.
This option will cause the chooser to dynamically hide select boxes on the page when the chooser opens. This is necessary in order to avoid the select boxes showing through the chooser under Windows in both IE and Mozilla (to a lesser extent). This defaults to 1. For a detailed explanation of the problem, see this page:
http://www.webreference.com/dhtml/diner/seethru/
Call output() to get HTML from the widget object to include in your page.
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.
Here are some possible directions for future development. Send me a patch for one of these and you're guaranteed a place in Changes.
closed_node.png and open_node.png.
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 (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.
Sam Tregar <sam@tregar.com>