Sam Tregar > HTML-PopupTreeSelect-Dynamic > HTML::PopupTreeSelect::Dynamic

Download:
HTML-PopupTreeSelect-Dynamic-1.2.tar.gz

Dependencies

Annotate this POD

Related Modules

HTML::Template
XML::Writer
more...
By perlmonks.org

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 1.2   Source  

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:

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>

syntax highlighting: