NAME

HTML::PopupTreeSelect::Dynamic - dynamic version of HTML::PopupTreeSelect

SYNOPSIS

This module is used just like HTML::PopupTreeSelect, with the addition of 3 new parameters - dynamic_url, dynamic_params and include_prototype. 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 hpts_demo.cgi.

DESCRIPTION

This module provides a dynamic version of HTML::PopupTreeSelect. By dynamic I mean that the tree is sent to the client in chunks as the user clicks around the tree. In HTML::PopupTreeSelect the entire tree is sent to the client when the page is loaded, introducing a long delay for large trees. With HTML::PopupTreeSelect::Dynamic trees of virtually any size can be navigated without noticable delays.

CAVEATS

Be aware of the following issues, some or all of which may be fixed in a future version:

• 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 data 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.

• This module uses HTML::Prototype 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.

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

INTERFACE

This module has the same interface as HTML::PopupTreeSelect, with a few additions:

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.

additional new() param : dynamic_params (optional)

This option provides additional parameters to be added to the request to dynamic_url. These should be in URL format. For example, to set "rm" to "get_node":

$select = HTML::PopupTreeSelect::Dynamic->new(
            dynamic_params => 'rm=get_node',
            ...);

additional new() param : include_prototype (optional)

This options surpress the output of the Prototype.js that comes from HTML::Prototype. By default it is true.

It is useful to set this option to false when you are already using prototype.js in your templates via a <script> tag.

handle_get_node()

This method must be called when your application recieves a request using dynamic_url and dynamic_params. A CGI.pm object containing the data from this query must be passed as a named parameter:

$output = $select->handle_get_node(query => $query);

The return value is the output to be returned to browser.

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

cpanm HTML::PopupTreeSelect::Dynamic

perl -MCPAN -e shell
install HTML::PopupTreeSelect::Dynamic