END
1;
__END__
=head1 NAME
HTML::PopupTreeSelect::Dynamic - dynamic version of HTML::PopupTreeSelect
=head1 SYNOPSIS
This module is used just like HTML::PopupTreeSelect, with the addition
of 3 new parameters - C, C and C. Here's
a full example:
use HTML::PopupTreeSelect::Dynamic;
# 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::Dynamic->new(
name => 'category',
data => $data,
title => 'Select a Category',
button_label => 'Choose',
onselect => 'select_category',
dynamic_params => 'rm=get_node');
# include it in your HTML page, for example using HTML::Template:
$template->param(category_select => $select->output);
A complete, and terribly coded, example of how to use this modules is
included in the module distribution. Look for the file called
C.
=head1 DESCRIPTION
This module provides a dynamic version of
L. By dynamic I mean
that the tree is sent to the client in chunks as the user clicks
around the tree. In L
the entire tree is sent to the client when the page is loaded,
introducing a long delay for large trees. With
L trees of virtually any size can be
navigated without noticable delays.
=head1 CAVEATS
Be aware of the following issues, some or all of which may be fixed in
a future version:
=over
=item *
As you can see from the SYNOPSIS and INTERFACE sections no provision
for dynamically generating the tree data is present. This means that
while the client gets data in chunks, the server code still needs to
compile the complete tree in memory to pass as the C parameter
to new(). In general this is considerably less problematic than
sending the entire tree to the client, but it would be nice to remove
this potential bottleneck as well.
=item *
This module uses L to provide AJAX
functionality. This limits support to only those browsers supported
by the Prototype Javascript library. Details concerning Prototype may
be found here:
http://prototype.conio.net/
I have personally tested Firefox v1.0.2 on Linux and IE 6 on Windows
XP.
=item *
Although this module uses Prototype for the AJAX calls, it's still
using all the painfully hand-wrought dragging and tree-generation
code. It would be nice to move this stuff over to Prototype, although
it seems like it would have little practical benefits.
=head1 INTERFACE
This module has the same interface as
L, with a few additions:
=head2 additional new() param : dynamic_url (optional)
This option provides the URL which will be used for callbacks from the
widget to get node data. For example:
$select = HTML::PopupTreeSelect::Dynamic->new(
dynamic_url => 'http://example.com/tree_select.cgi',
...);
This will cause the widget to make dynamic (AJAX) requests to
http://example.com/tree_select.cgi to request node data. The code
running behind this URL should call handle_get_node(), shown below.
Defaults to the current URL of the running application, as determined
via Javascript's window.location method.
=head2 additional new() param : dynamic_params (optional)
This option provides additional parameters to be added to the request
to C. These should be in URL format. For example, to
set "rm" to "get_node":
$select = HTML::PopupTreeSelect::Dynamic->new(
dynamic_params => 'rm=get_node',
...);
=head2 additional new() param : include_prototype (optional)
This options surpress the output of the C that comes
from L. By default it is C.
It is useful to set this option to C when you are already using
F in your templates via a C<<
