Name HTML::FormWidgets - Create HTML form markup Version 0.2.$Rev: 102 $ 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