/ 
HTML-Controls-0.1
/ HTML::Controls

NAME

HTML::Controls - framework for complex controls/widgets in HTML

Version

Version 0.1

SYNOPSIS

use HTML::Controls;

# in your request-handling sub
my $w=HTML::Controls::Date('date_field');
if ($request->method eq 'POST') { # or something to that effect
 $w->setDataFromPost($request);
 if ($w->isDataValid()) {
  my $date=$w->getData();
  # do what you need with the data
 } else {
  # data not complete or invalid: cope with it
 }
}
print some_html_up_to_head();
print $w->head();
print a_lot_of_html_closing_head_and_apening_a_form();
print $w->form();
print a_lot_of_html_closing_the_form();

This module is the front-end to the HTML::Controls framework.

The aim of this framework is to facilitate the development of modular controls to ease the handling of complex HTML forms. For example, the HTML::Controls::Date in the example could be rendered as a single input field, or three separate fields, or a pop-up calendar written in JavaScript, and you should have to change nothing in your code.

DESCRIPTION

This module exists mostly to load the other HTML::Controls::*, via Module::Pluggable::Fast. In this section we'll look at the underlying ideas of the framework, and only later we'll look at the methods defined here.

As you can see from the example in the synopsis, the life-cycle of a control is more or less the following:

construction

you create the controls you need with the new method, passing (at least) their name, and possibly some other data (see the specific control's module for details)

setting data

using the setData method, you can give the control some initial values. These values are passed in internal representation (again, see each module for details). On the other hand, if you received a data from the user (via a POST or GET request), you should pass the request to the control using the setDataFromPost, so that it can update itself. The request should implement at least param method like the one in CGI. Some controls might require a parameters method, that returns a reference to a hash containig all passed parameters

validating data

if you set the data, especially from a user request, you should test if it is valid with the isDataValid method

getting the data back

if the data is valid, you can get it (in internal representation) with the getData method

outputting the form

to obtain the HTML output, you have to use the head and form methods, to get a string to emit inside the HTML element of the same name. Note that you should not assume much about this output, save that:

  • it is valid (X)HTML

  • it presents the user with a way to input the data you need

  • when submitted, said data will be read correctly by the setDataFromPost method

In other words, these methods produce an external representation of the data, and the whole point is to allow you not to worry about it.

Relation to other modules

This framework uses the Template Toolkit to create the HTML fragments, but does not require that you use it. If you do use it, there will be some glue to avoid creating a different Template object for each control (as it happens right now).

I do integration testing using Catalyst, but everything should work as well using CGI, or anything that can parse a request into an object and send strings to the browser.

METHODS

controls

returns the list of the names of all the modules found in the HTML::Controls:: namespace

templateProvider

returns a Template::Provider object that looks for template files in all the directories specified by the various controls. See HTML::Controls::Base::templateDir

AUTHOR

Gianni Ceccarelli <dakkar@thenautilus.net>

TODO

  • better integration with TT2

  • more AJAX controls

  • more and better tests

  • better-looking templates

  • factor the templates to allow easy CSS styling

BUGS

No bugs in the functionality are known.

Please report any bugs or feature requests to bug-html-controls@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT

Copyright 2005 Gianni Ceccarelli, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.