.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "PopupTreeSelect 3pm" .TH PopupTreeSelect 3pm "2018-05-01" "perl v5.26.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" HTML::PopupTreeSelect \- HTML popup tree widget .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& 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 \*(Aqselect_category(value)\*(Aq when the user selects \& # a category. \& my $select = HTML::PopupTreeSelect\->new(name => \*(Aqcategory\*(Aq, \& data => $data, \& title => \*(AqSelect a Category\*(Aq, \& button_label => \*(AqChoose\*(Aq, \& onselect => \*(Aqselect_category\*(Aq); \& \& # include it in your HTML page, for example using HTML::Template: \& $template\->param(category_select => $select\->output); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module creates an \s-1HTML\s0 popup tree selector. The \s-1HTML\s0 and Javascript produced will work in Mozilla 1+ (Netscape 6+) on all operating systems, Microsoft \s-1IE 5+\s0 and Safari 1.0. For an example, visit this page: .PP .Vb 1 \& http://sam.tregar.com/html\-popuptreeselect/example.html .Ve .PP I based the design for this widget on the xTree widget from WebFX. You can find it here: .PP .Vb 1 \& http://webfx.eae.net/dhtml/xtree/ .Ve .PP 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: .PP .Vb 1 \& http://krang.sf.net .Ve .SH "INSTALLATION" .IX Header "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 \s-1CGI\s0 will run from then you need to set the image_path parameter when you call \fInew()\fR. See below for details. .SH "INTERFACE" .IX Header "INTERFACE" .SS "\fInew()\fP" .IX Subsection "new()" \&\fInew()\fR, is used to build a new \s-1HTML\s0 selector. You call it with a description of the tree to display and get back an object. Call it with following parameters: .IP "name" 4 .IX Item "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. .IP "data" 4 .IX Item "data" This must be a hash reference (or an array reference of these hash references, if there are multiple \*(L"root\*(R" categories) containing the following keys: .RS 4 .IP "label (required)" 4 .IX Item "label (required)" The textual label for this node. .IP "value (required)" 4 .IX Item "value (required)" The value passed to the onselect handler or set in the form_field when the user selects this node. .IP "open (optional)" 4 .IX Item "open (optional)" If set to 1 this node will start open (showing its children). By default all nodes start closed. .IP "inactive (optional)" 4 .IX Item "inactive (optional)" If set to 1 this node will not be selectable. It will not appear as a link in the widget and clicking on the label will have no effect. However, if it has children they will still be accessible. .IP "children (optional)" 4 .IX Item "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. .RE .RS 4 .Sp See \s-1SYNOPSIS\s0 above for an example of a valid data structure. .RE .IP "title" 4 .IX Item "title" The title of the window which pops up. .IP "button_label (optional)" 4 .IX Item "button_label (optional)" The widget pops up when the user presses a button. This field gives the label for the button. Defaults to \*(L"Choose\*(R". .IP "onselect (optional)" 4 .IX Item "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. .IP "form_field (optional)" 4 .IX Item "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). .IP "form_field_form (optional)" 4 .IX Item "form_field_form (optional)" Specifies the form in which to find the \f(CW\*(C`form_field\*(C'\fR specified. If not included the first form on the page will be used. .IP "include_css (optional)" 4 .IX Item "include_css (optional)" Set this to 0 and the default \s-1CSS\s0 will not be included in the widget output. This allows you to include your own \s-1CSS\s0 which will be used by your widget. Modifying the \s-1CSS\s0 will allow you to control the fonts, colors and spacing in the output widget. .Sp 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. .IP "resizable (optional)" 4 .IX Item "resizable (optional)" Set this to 1 and the default widget output will not be resizable. If you run the widget with resizable set to 1 then default output will have a bar at the bottom which allows it to be resized by dragging. Defaults to 0. .IP "image_path (optional)" 4 .IX Item "image_path (optional)" Set this to the \s-1URL\s0 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. .IP "width (optional)" 4 .IX Item "width (optional)" Set this to the width of the popup window. Defaults to 200. .IP "height (optional)" 4 .IX Item "height (optional)" Set this to the height of the tree box inside the window. This defaults to 0 which allows the chooser to grow as the tree expands. If you set this option you'll probably want to set the \&\f(CW\*(C`use_scrollbars\*(C'\fR option as well. .IP "scrollbars (optional)" 4 .IX Item "scrollbars (optional)" If set to 1 the chooser will have a fixed size (specified by width and height) and show scrollbars inside the tree area. .IP "hide_selects (optional)" 4 .IX Item "hide_selects (optional)" 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 \s-1IE\s0 and Mozilla (to a lesser extent). This defaults to 1. For a detailed explanation of the problem, see this page: .Sp .Vb 1 \& http://www.webreference.com/dhtml/diner/seethru/ .Ve .IP "hide_textareas (optional)" 4 .IX Item "hide_textareas (optional)" This option will cause the chooser to dynamically hide textareas on the page when the chooser opens. This is necessary to workaround a bug in Netscape 6.0 through 7.0 in which buttons hovering over textareas are not clickable. This defect is fixed in version 7.1 and later. This option defaults to 0, since this problem only affects older browsers. .IP "parent_var (optional)" 4 .IX Item "parent_var (optional)" This option includes a 'parent' loop in the template data used to construct the widget's \s-1HTML.\s0 It's not used by the default template, so it defaults to 0. Set to 1 to use this variable in your own template via sub-classing. .SH "\fIoutput()\fP" .IX Header "output()" Call \fIoutput()\fR to get \s-1HTML\s0 from the widget object to include in your page. .SH "SUBCLASSING" .IX Header "SUBCLASSING" HTML::PopupTreeSelect can be subclassed, for the purposes of \*(-- for example \*(-- using a different template engine to generate the \s-1HTML.\s0 Here's one brief example, using the Template engine: .PP .Vb 3 \& package My::PopupTreeSelect; \& use Template; \& use base \*(AqHTML::PopupTreeSelect\*(Aq; \& \& sub output { \& my($self) = @_; \& return $self\->SUPER::output(Template\->new); \& } \& \& sub _output_generate { \& my($self, $template, $param) = @_; \& my $output; \& $template\->process(\e$MY_TEMPLATE_SRC, $param, \e$output); \& return $output; \& } .Ve .PP Of course, \f(CW$MY_TEMPLATE_SRC\fR will need to be provided, too. \&\f(CW$HTML::PopupTreeSelect::TEMPLATE_SRC\fR 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. .SH "CAVEATS" .IX Header "CAVEATS" .IP "\(bu" 4 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 \s-1DHTML\s0 on the same page. .SH "TODO" .IX Header "TODO" Here are some possible directions for future development. Send me a patch for one of these and you're guaranteed a place in \fIChanges\fR. .IP "\(bu" 4 Allow each node to specify its own icon. Right now every node uses \&\f(CW\*(C`closed_node.png\*(C'\fR and \f(CW\*(C`open_node.png\*(C'\fR. .SH "BUGS" .IX Header "BUGS" I know of no bugs in this module. If you find one, please file a bug report at: .PP .Vb 1 \& http://rt.cpan.org .Ve .PP Alternately you can email me directly at \f(CW\*(C`sam@tregar.com\*(C'\fR. Please include the version of the module and a complete test case that demonstrates the bug. .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (C) 2003, 2004 Sam Tregar .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself. .SH "AUTHOR" .IX Header "AUTHOR" Sam Tregar