HTML::FormWidgets - Create HTML user interface components
Describes version v0.25.$Rev: 1 $ of HTML::FormWidgets
use HTML::FormWidgets;
my $widget = HTML::FormWidgets->new( id => 'test' );
print $widget->render;
# <div class="container">
# <input value="" name="test" type="text" id="test" class="ifield" size="40">
# </div>
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
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
-
content_type
Either
application/xhtml+xml
which generates XHTML 1.1 ortext/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 tohtml_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
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
$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
$widet->add_literal_js( $js_class_name, $id, $config );
The config hash will be serialised and added to the literal Javascript on the page
$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
$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
$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
$bool = $widget->is_xml;
Returns true if the content type matches xml
$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 localise the key to
the required language. The @args
list contains parameters to substituted
in place of the placeholders which have the form [_n]
$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<br>
element -
stepno
If true it's value is wrapped in a
<span class="lineNumber">
element and appended to the return value -
prompt
If true it's value is wrapped in a
<label class="prompt_class">
element and appended to the return value. The prompt class is set by thepclass
attribute. Theid
attribute is used to set thefor
attribute of the<label>
element. Thepwidth
attribute sets the width style attribute in the<label>
element -
sep
If true it's value is wrapped in a
<span class="separator">
element and appended to the return value -
container
If true the value return by the "_render" method is wrapped in
<span class="container">
element -
tip
The text of the field help. If
tiptype
is set todagger
(which is the default) then a dagger symbol is wrapped in a<span class="help tips">
and this is appended to the returned input field. The tip text is used as thetitle
attribute. If thetiptype
is not set todagger
then the help text is wrapped around the input field itself -
check_field
Boolean which if true causes the field to generate server side check field requests
Adds markup for the Ajax field validation
Wraps the rendered field in a containing div
Should be overridden in the factory subclass. It should return the markup for the specified field type
Adds a label element to the generated markup
Insert a spacing element between the prompt and the field
Markup containing the step number on the form if required
Flyover tooltip field help text
Makes absolute URI from relative paths by calling the supplied function
$widget->$_bootstrap( $args );
Determine the id
, name
and type
attributes of the widget from
the supplied arguments
$widget->$_ensure_class_loaded( $class );
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
$widget->$_set_error( $error_text );
Stores the passed error message in the text
attribute so that it
gets rendered in place of the widget
$args = $_arg_list->( @args );
Accepts either a single argument of a hash ref or a list of key/value pairs. Returns a hash ref in either case.
$item = $_form_wrapper->( $options, $item, $stack );
Wraps the top nitems
number of widgets on the build stack in a <form>
element
$item = $_group_fields->( $options, $item, $stack );
Wraps the top nitems
number of widgets on the build stack in a <fieldset>
element with a legend
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:
Returns an <anchor>
element with a class set from the class
argument (which defaults to linkFade
). It's href
attribute
set to the href
argument. The anchor body is set to the text
argument
Returns a <div>
element with a class set from the class
argument (which defaults to server
). The div body is set to the
text
argument. When the JavaScript onload
event handler fires it
will asynchronously load the content of the div if it is visible
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
. If the image file does not
exist a regular input button is rendered instead
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
argument determines the checkbox's initial
setting
Creates a popup window which allows one item to be selected from a long list of items
Creates list of links from the data set supplied in the data
argument
Return another <textfield>
, this time with a calendar icon
which when clicked pops up a Javascript date picker. Requires the
appropriate JavaScript 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 read only
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 ifselect
>= 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>
element whosesrc
attribute is set topath
. Paths that do not begin withhttp:
will passed to "uri_for" -
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
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
.
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
Hidden
Generates a hidden input field. Uses the default
attribute as the value
Generates an image tag. The text
attribute contains the source URI. The
fhelp
attribute contains the alt text and the tiptype
attribute is
defaulted to normal
(wraps the image in a span with a JavaScript tooltip)
Calls "loc" with the text
attribute if set otherwise returns nothing.
If dropcap
is true the first character of the text is wrapped
in a <span class="dropcap">
. Wraps the text in a span of class
class
which defaults to label_text
Generates an ordered and unordered lists of items. Set the ordered
attribute to true for an ordered list. Defaults to false
Generates an unordered list of links. Used with some applied CSS to implement a navigation menu
Calls "localize" with the name
attribute as the message key. If
the message does not exist the value if the text
attribute is
used. The text is wrapped in a c<< >> with
width
setting the style width
Uses Pod::Html to render the POD in the given module as HTML
Newspaper like paragraphs rendered in a given number of columns, each approximately the same length. Defines these attributes;
-
column_class
CSS class name of the
<span>
wrapped around each column. Defaults to null -
columns
Number of columns to render the paragraphs in. Defaults to 1
-
data
Paragraphs of text. A hash ref whose
values
attribute is an array ref. The values of that array are the hash refs that define each paragraph. The keys of the paragraph hash ref areclass
,heading
, andtext
. -
hclass
Each paragraph can have a heading. This is the class of the
<div>
that wraps the heading text. Defaults to null -
max_width
Maximum width of all paragraphs expressed as a percentage. Defaults to 90
-
para_lead
Paragraph leading. This value is in characters. It is added to the size of each paragraph to account for the leading applied by the CSS to each paragraph. If a paragraph is split, then the first part must by greater than twice this value or the widows and orphans trap will reap it
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
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 the onchange
attribute value
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
Generates a horizontal rule with optional clickable action
Implements clickable navigation markers that scroll the page to given
location. Returns an unordered list of class class
which defaults
to pintray
. This is the default selector class for the JavaScript
ScrollPins
object
The height
attribute controls the number of options the scrolling
list displays. The list of options is passed in values
with the
display labels in labels
. The onchange
event handler will
be set to onchange
Generates the markup for a sidebar accordion panel (a "header" div
and a "body" div
). The panel contents are requested asynchronously
by the browser. The "SidebarPanel" widget defines these attributes:
-
config
A hash ref whose keys and values are written out as literal JavaScript by "add_literal_js"
-
header
A hash that provides the
id
,class
, andtext
for headerdiv
-
panel
A hash that provides the
id
andclass
for bodydiv
Implements a dragable slider which returns an integer value. The "Slider" widget defines these attributes:
-
display
Boolean which if true causes the widget to display a read only text field containing the sliders current value. If false a
<hidden
>> element is generated instead. Defaults to1
-
element
Name of the Javascript instance variable. This will need setting to a unique value for each slider on the same form. Defaults to
behaviour.sliderElement
-
hide
If the
display
attribute is false the current value is pushed onto this array. Defaults to[]
-
mode
Which orientation to render in. Defaults to
horizontal
-
offset
Sets the minimum value for the slider. Defaults to
0
-
range
The range is either the offset plus the number of steps or the two values of this array if it is set. Defaults to
false
-
snap
Snap to the nearest step value? Defaults to
1
-
steps
Sets the number of steps. Defaults to
100
-
wheel
Use the mouse wheel? Defaults to
1
A list of div
s is constructed that can be styled to display only one at
a time. Clicking the tab header displays the corresponding div
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.
Returns markup for a table row. Used to generate responses for the LiveGrid
JavaScript class
This provides for a "user defined" widget type.
Looks 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. Alternatively take the template data
from the text
attribute
A text area. It defaults to five lines high (height
) and
sixty characters wide (width
)
This is the default widget type. Your basic text field which defaults
to sixty characters wide (width
)
Implements an expanding tree of selectable objects. The tree information is
contained in the data
attribute which is a hash reference. If the data
hash reference has an attribute _keys
then this array reference will contain
the list of keys for this level of the tree in the correct display order. If
this attribute is missing the keys in the data
hash reference are displayed
in their natural sort order
None
- Class::Accessor::Fast
- Class::Load
- HTML::Accessors
- Syntax::Highlight::Perl
- Text::ParseWords
- Text::Tabs
- Try::Tiny
Included in the distribution are the Javascript files whose methods are called by the event handlers associated with these widgets
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
Mootools - My Object Oriented javascript.
License: MIT-style license.
WWW: http://mootools.net/
This is the main JavaScript library used with this package
Replaces Mootools' setHTML
method with one that uses the HTML
parser. The included copy has a few hacks that improve the Accordion
widget
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
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.
There are no known incompatibilities in this module.
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 http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTML-FormWidgets. Patches are welcome
Peter Flanigan, <pjfl@cpan.org>
Copyright (c) 2015 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