Name
HTML::FormWidgets - Create HTML user interface components
Version
0.17.$Rev: 387 $
Synopsis
use HTML::FormWidgets;
my $widget = HTML::FormWidgets->new( id => q(test) );
print $widget->render;
#
#
#
Description
Transforms a Perl data structure which defines one or more "widgets"
into HTML or XHTML. Each widget is comprised of these optional
components: a line or question number, a prompt string, a separator, an
input field, additional field help, and Ajax field error string.
Input fields are selected by the widget "type" attribute. A factory
subclass implements the method that generates the HTML or XHTML for that
input field type. Adding more widget types is straightforward
This module is using the MooTools Javascript
library to modify default browser behaviour
This module is used by CatalystX::Usul::View and as such its main use is
as a form generator within a Catalyst application
Configuration and Environment
The following are passed to "build" in the "config" hash (they reflect
this modules primary use within a Catalyst application):
"assets"
Some of the widgets require image files. This attribute is used to
create the URI for those images
"base"
This is the prefix for our URI
"content_type"
Either "application/xhtml+xml" which generates XHTML 1.1 or
"text/html" which generates HTML 4.01 and is the default
"fields"
This hash ref contains the fields definitions. Static parameters for
each widget can be stored in configuration files. This reduces the
number of attributes that have to be passed in the call to the
constructor
"hidden"
So that the "File" and "Table" subclasses can store the number of
rows added as the hidden form attribute "nRows"
"js_object"
This is the name of the global Javascript variable that holds
"config" object. Defaults to "html_formwidgets"
"root"
The path to the document root for this application
"width"
Width in pixels of the browser window. This is used to calculate the
width of the field prompt. The field prompt needs to be a fixed
length so that the separator colons align vertically
"templatedir"
The path to template files used by the "Template" subclass
Sensible defaults are provided by "new" if any of the above are
undefined
Subroutines/Methods
Public Methods
build
HTML::FormWidgets->build( $config_hash );
The "build" method iterates over a data structure that represents the
form. One or more lists of widget definitions are processed in turn. New
widgets are created and their rendered output replaces their definitions
in the data structure
new
$widget = HTML::FormWidgets->new( [{] key1 => value1, ... [}] );
Construct a widget. Mostly this is called by the "build" method. It
requires the factory subclass for the widget type.
This method takes a large number of options with each widget using only
few of them. Each option is described in the factory subclasses which
use that option
add_hidden
$widget->add_hidden( $key, $value );
The key / value pair are added to list of hidden input elements that
will be included in the page
add_literal_js
$widet->add_literal_js( $js_class_name, $id, $config );
The config hash will be serialised and added to the literal Javascript
on the page
add_optional_js
$widget->add_optional_js( @filenames );
The list of Javascript filenames (with extension, without path) are
added to the list of files which will be included on the page
inflate
$widget->inflate( $args );
Creates new objects and returns their rendered output. Called by the
"_render" methods in the factory subclasses to inflate embeded widget
definitions
init
$widget->init( $args );
Initialises this object with data from the passed arguments. This is
usually overridden in the factory subclass which sets the default for
it's own attributes. In the base class this method does nothing
is_xml
$bool = $widget->is_xml;
Returns true if the content type matches "xml"
loc
$message_text = $widget->loc( $message_id, @args );
Use the supplied key to return a value from the "l10n" object. This
object was passed to the constructor and should localize the key to the
required language. The @args list contains parameters to substituted in
place of the placeholders which have the form "[_n]"
render
$html = $widget->render;
Assemble the components of the generated widget. Each component is
concatenated onto a scalar which is the returned value. This method
calls "render_field" which should be defined in the factory subclass for
this widget type.
This method uses these attributes:
"clear"
If set to "left" the widget begins with an " " element
"stepno"
If true it's value is wrapped in a ""
element and appended to the return value
"prompt"
If true it's value is wrapped in a "