Name
HTML::FormWidgets - Create HTML form markup
Version
0.2.$Rev: 108 $
Synopsis
package MyApp::View::HTML;
use base qw(CatalystX::Usul::View::HTML);
use HTML::FormWidgets;
sub build_form {
my ($self, $c) = @_;
my $s = $c->stash;
my $form = [ $s->{iFrame} ];
my $config = {};
$config->{root } = $c->config->{root};
$config->{base } = $c->req->base;
$config->{content_type} = $c->config->{content_type};
$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 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::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
$self = $class->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
init
$self->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 and then calls this method in the base class
msg
$message_text = $self->msg( $message_id );
Use the supplied key to return a value from the 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:
clear
If set to left the widget begins with an
element
stepno
If true it's value is wrapped in a span element of class lineNumber
and appended to the return value
prompt
If true it's value is wrapped in a label element of class prompt and
appended to the return value. The id attribute is used to set the for
attribute of the label element. The palign attribute sets the text
align style for the label element. The nowrap attribute sets
whitespace style to nowrap in the label element. The pwidth attribute
sets the width style attribute in the label element
sep
If true it's value is wrapped in a div element of class separator and
appended to the return value
container
If true the value return by the "_render" method is wrapped in div
element of classes container and align
tip
The text of the field help. If tiptype is set to dagger (which is the
default) then a dagger symbol 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
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.
_ensure_class_loaded
Once the factory subclass is known this method ensures that it is loaded
and then re-blesses the self referential object into the correct class
_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
_set_error
Stores the passed error message in the "text" attribute so that it gets
rendered in place of the widget
_set_id_name_and_type
Determine the "id", "name" and "type" of the widget from the supplied
arguments
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 and is the
default or *text/html* which generates HTML 4.01
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
form
Used by the "::Chooser" subclass
hide
So that the "::File" and "::Table" subclasses can store the number of
rows added as the hidden form variable *nRows*
messages
Many of the subclasses use this hash to supply literal text in a
language of the users choosing
root
The path to the document root for this application
swidth
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
url
Only used by the "::Tree" subclass to create self referential URIs
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 option *class* (which defaults to
*linkFade*) with it's *href* attribute set to the *href* option. The
anchor body is set to the *text* option
Checkbox
Return a *checkbox* element of value *value*. Use the element's value as
key to the *labels* hash. The hash value (which defaults null) is used
as the displayed label. The *checked* option determines the checkbox's
initial setting
Chooser
Creates a popup window which allows one item to be selected from a
*long* list of items
Cloud
Creates list of links from the data set supplied in the *data* option
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 *width* controls the
size of the textfield (default 10 characters) and *format* defaults to
*dd/mm/yyyy*. Setting the *readonly* attribute to true (which is the
default) causes the input textfield to become readonly
File
Display the contents of a file pointed to by *path*. Supports the
following subtypes:
csv
Return a table containing the CSV formatted file. This and the *file*
subtype are selectable if *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 *path*. Paths that begin with *root* will have that replaced
with *base*. Paths that do not begin with "http:" will have *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 *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 *values*) can be removed. The height of the list
is set by *height*.
GroupMembership
Displays two lists which allow for membership of a group. The first
scrolling list contains "all" values (*all*), the second contains those
values currently selected (*current*). The height of the scrolling lists
is set by *height*
ImageButton
Generates an image button where *name* identifies the image file in
*assets* and is also used as the return value. The button name is set to
*_verb*
Label
Calls *msg* with *name* as the message key. If the text does not exist
*text* is used. If *dropcap* is true the first character of the text is
wrapped in a *span* of class *dropcap*
Note
Calls *msg* with *name* as the message key. If the text does not exist
*text* is used. The text is wrapped in a *div* of class *note* with
*align* setting the style text alignment and *width* setting the style
width
Password
Returns a password field of width *width* which defaults to twenty
characters. If *subtype* equals *verify* then the message
*vPasswordPrompt* and another password field are appended. The fields
*id* and *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 *values* with the display labels in
*labels*. The onchange event handler will be set to *onchange*
RadioGroup
The attribute *columns* sets the number of columns for the returned
table of radio buttons. The list of button values is passed in *values*
with the display labels in *labels*. The onchange event handler will be
set to *onchange*
Rule
Generates a horizontal rule with optional clickable action
ScrollingList
The *height* attribute controls the height of the scrolling list. The
list of options is passed in *values* with the display labels in
*labels*. The onchange event handler will be set to *onchange*
Table
The input data is in *$data->{values}* which is an array ref for which
each element is an array ref containing the list of field values.
Template
Look in *templatedir* for a Template::Toolkit template called *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 (*height*) and sixty
characters wide (*width*)
Textfield
This is the default widget type. Your basic text field which defaults to
sixty characters wide (*width*)
Tree
Implements an expanding tree of selectable objects. See "Bugs and
Limitations"
Diagnostics
None
Dependencies
Class::Accessor::Fast
Class::Inspector
HTML::Accessors
Syntax::Highlight::Perl
Text::Markdown
Text::ParseWords
Text::Tabs
Included in the distribution are the Javascript files whose methods are
called by the event handlers associated with these widgets
10htmlparser.js
HTML Parser By John Resig (ejohn.org)
Original code by Erik Arvidsson, Mozilla Public License
http://erik.eae.net/simplehtmlparser/simplehtmlparser.js
Used to reimplement "innerHTML" assignments from XHTML
20mootools.js
Mootools - My Object Oriented javascript.
License: MIT-style license.
WWW: http://mootools.net/
This is the main JS library used with this package
30ourtools.js
Replaces Mootools' "setHTML" method with one that uses the HTML parser.
The included copy has a few hacks that improve the Accordion widget
40calendar.js
Copyright Mihai Bazon, 2002-2005 | www.bazon.net/mishoo
The DHTML Calendar, version 1.0 | www.dynarch.com/projects/calendar
License: GNU Lesser General Public License
Implements the calendar popup used by the *::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
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