Name
HTML::FormWidgets - Create HTML form markup
Version
0.1.$Rev: 28 $
Synopsis
package MyApp::View::HTML;
use base qw(CatalystX::Usul::View::HTML);
use HTML::FormWidgets;
sub build_form {
my ($me, $c) = @_;
my $s = $c->stash;
my $form = [ $s->{iFrame} ];
my $config = {};
$config->{root } = $c->config->{root};
$config->{base } = $c->req->base;
$config->{url } = $c->req->path;
$config->{assets } = $s->{assets};
$config->{fields } = $s->{fields} || {};
$config->{form } = $s->{form};
$config->{hide } = $s->{iFrame}->{hidden};
$config->{messages } = $s->{messages};
$config->{swidth } = $s->{width} if ($s->{width});
$config->{templatedir} = $c->config->{dynamic_templates};
HTML::FormWidgets->build( $config, $form );
return;
}
Description
Transforms a Perl data structure which defines one or more "widgets"
into 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 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::HTML and as such its main
use is a form generator within a Catalyst application
Subroutines/Methods
build
The "build" method iterates over a data structure that represents the
form. One or more lists of widgets are processed in turn. New widgets
are created and their rendered output replaces their definitions in the
data structure
new
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
msg
Use the supplied key to return a value from the "$me->messages" hash.
This hash was passed to the constructor and should contain any literal
text used by any of the widgets
render
Assemble the components of the generated widget. Each component is
concatenated onto a scalar which is the returned value. This method
calls "_render" which should be defined in the factory subclass for this
widget type.
This method uses these attributes:
"$me->clear"
If set to left the widget begins with an
element
"$me->stepno"
If true it's value is wrapped in a span element of class lineNumber
and appended to the return value
"$me->prompt"
If true it's value is wrapped in a label element of class prompt and
appended to the return value. The "$me->id" attribute is used to set
the for attribute of the label element. The "$me->palign" attribute
sets the text align style for the label element. The "$me->nowrap"
attribute sets whitespace style to nowrap in the label element. The
"$me->pwidth" attribute sets the width style attribute in the label
element
"$me->sep"
If true it's value is wrapped in a div element of class separator and
appended to the return value
"$me->container"
If true the value return by the "_render" method is wrapped in div
element of classes container and "$me->align"
"$me->tip"
The text of the field help. If "$me->tiptype" is set to dagger (which
is the default) then a dagger symbol "$me->nb_symbol" is wrapped in a
span of class help tips and this is appended to the returned input
field. The tip text is used as the title attribute. If the tiptype is
not set to dagger then the help text is wrapped around the input
field itself
"$me->ajaxid"
The text of the message which is displayed if the field's value fails
server side validation
_arg_list
Accepts either a single argument of a hash ref or a list of key/value
pairs. Returns a hash ref in either case.
_group_fields
Wraps the top nitems widgets on the build stack in a fieldset element
with a legend
_merge_config
Does a simple merging of the two hash refs that are passed as arguments.
The second argument takes precedence over the first
_render
This should have been overridden in the factory subclass. If it gets
called its probably an error so return the value of our "text" attribute
if set or an error message otherwise
Configuration and Environment
The following are passed to "build" in the config hash (they reflect
this modules primary use within a Catalyst application):
"$c->config->{root}"
The path to the document root for this application ("$config->root")
"$c->config->{dynamic_templates}"
The path to template files used by the "::Template" subclass
("$config->templatedir")
"$c->req->base"
This is the prefix for our URI ("$config->base")
"$c->req->path"
Only used by the "::Tree" subclass to create self referential URIs
("$config->url")
"$c->stash->{assets}"
Some of the widgets require image files. This attribute is used to
create the URI for those images ("$config->assets")
"$c->stash->{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
"$c->stash->{form}"
Used by the "::Chooser" subclass ("$config->form")
"$c->stash->{iFrame}->{hidden}"
So that the "::File" and "::Table" subclasses can store the number of
rows added as the hidden form variable nRows ("$config->hide")
"$c->stash->{messages}"
Many of the subclasses use this hash to supply literal text in a
language of the users choosing
"$c->stash->{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
("$config->swidth")
Sensible defaults are provided by "new" if any of the above are
undefined
Factory Subclasses
These are the possible values for the "type" attribute which defaults to
textfield. Each subclass implements the "_render" method, it receives a
hash ref of options an returns a scalar containing some XHTML.
The distribution ships with the following factory subclasses:
Anchor
Returns an anchor element of class "$me->class" or linkFade with it's
href attribute set to "$me->href". The anchor body is set to "$me->text"
Checkbox
Return a checkbox element of value "$me->value". Use the element's value
as key to the "$me->labels" hash. The hash value (which defaults null)
is used as the displayed label. The "$me->checked" attribute determines
the checkbox's initial setting
Chooser
Creates a popup window which allows one item to be selected from a long
list of items
Date
Return another text field, this time with a calendar icon which when
clicked pops up a Javascript date picker. Requires the appropriate JS
library to have been loaded by the page. Attribute "$me->width" controls
the size of the textfield (default 10 characters) and "$me->format"
defaults to *dd/mm/yyyy*
File
Display the contents of a file pointed to by "$me->path". Supports the
following subtypes:
csv
Return a table containing the CSV formatted file. This and the *file*
subtype are selectable if "$me->select" >= 0 and represents the
column number of the key field
file
Default subtype. Like the logfile subtype but without the pre tags
html
The "_render" method returns an iframe tag whose src attribute is set
to "$me->path". Paths that begin with "$me->root" will have that
replaced with "$me->base". Paths that do not begin with "http:" will
have "$me->base" prepended to them
logfile
The "_render" method returns a table where each line of the logfile
appears as a separate row containing one cell. The logfile lines are
each wrapped in pre tags
source
The module "Syntax::Highlight::Perl" is used to provide colour
highlights for the Perl source code. Tabs are expanded to
"$me->tabstop" spaces and the result is returned wrapped in pre tags
Freelist
New values entered into a text field can be added to the list. Existing
list values (passed in "$me->values") can be removed. The height of the
list is set by "$me->height".
GroupMembership
Displays two lists which allow for membership of a group. The first
scrolling list contains "all" values ("$me->all"), the second contains
those values currently selected ("$me->current"). The height of the
scrolling lists is set by "$me->height"
ImageButton
Generates an image button where "$me->name" identifies the image file in
"$me->assets" and is also used as the return value. The button name is
set to *_verb*
Label
Calls "$me->msg" with "$me->name" as the message key. If the text does
not exist "$me->text" is used. If "$me->dropcap" is true the first
character of the text is wrapped in a span of class *dropcap*
Note
Calls "$me->msg" with "$me->name" as the message key. If the text does
not exist "$me->text" is used. The text is wrapped in a div of class
*note* with "$me->align" setting the style text alignment and
"$me->width" setting the style width
Password
Returns a password field of width "$me->width" which defaults to twenty
characters. If "$me->subtype" equals *verify* then the message
*vPasswordPrompt* and another password field are appended. The fields
"$me->id" and "$me->name" are expected to contain the digit 1 which will
be substituted for the digit 2 in the attributes of the second field
PopupMenu
Returns a list of option elements wrapped in a select element. The list
of options is passed in "$me->values" with the display labels in
"$me->labels". The onchange event handler will be set to "$me->onchange"
RadioGroup
The attribute "$me->columns" sets the number of columns for the returned
table of radio buttons. The list of button values is passed in
"$me->values" with the display labels in "$me->labels". The onchange
event handler will be set to "$me->onchange"
ScrollingList
The "$me->height" attribute controls the height of the scrolling list.
The list of options is passed in "$me->values" with the display labels
in "$me->labels". The onchange event handler will be set to
"$me->onchange"
Table
The input data is in "$me->data->{values}" which is an array ref for
which each element is an array ref containing the list of field values.
Template
Look in "$me->templatedir" for a Template::Toolkit template called
"$me->id" with a *.tt* extension. Slurp it in and return it as the
content for this widget. This provides for a "user defined" widget type
Textarea
A text area. It defaults to five lines high ("$me->height") and sixty
characters wide ("$me->width")
Textfield
This is the default widget type. Your basic text field which defaults to
sixty characters wide ("$me->width")
Tree
Implements an expanding tree of selectable objects. See "Bugs and
Limitations"
Diagnostics
None
Dependencies
Class::Data::Accessor
HTML::Accessors
Readonly
Syntax::Highlight::Perl
Text::ParseWords
Text::Tabs
Included in the distribution are the Javascript files whose functions
are called by the event handlers associated with these widgets
mootools.js
Mootools - My Object Oriented javascript.
License: MIT-style license.
WWW: http://mootools.net/
Implements the Ajax methods used to perform server side field
validation. The included copy has a few hacks that improve the Accordion
widget
calendar.js
Author: Matt Kruse
WWW: http://www.mattkruse.com/
which has a license restriction that prevents inclusion in other
distributions so I'll drop this at the next release. Only used by
"::Date" subclass
behaviour.js
Is included from the App::Munchies default skin. It uses the MooTools
library to implement the server side field validation
Also included in the "images" subdirectory of the distribution are
example PNG files used by some of the widgets.
Incompatibilities
There are no known incompatibilities in this module.
Bugs and Limitations
The Javascript for the tree widget is not included due to copyright
issues, so that widget doesn't work. Same for the date widget except
that there is a link in Dependencies to a web site where the Javascript
might be available
The installation script does nothing with the Javascript or PNG files
which are included in the distribution for completeness
There are no known bugs in this module. Please report problems to the
address below. Patches are welcome.
Author
Peter Flanigan, ""
License and Copyright
Copyright (c) 2008 Peter Flanigan. All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. See perlartistic.
This program is distributed in the hope that it will be useful, but
WITHOUT WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.