HTML::AutoWidget
The Idea
The aim of this perl subsystem is to simplify 'simple' user entry
form for CGI scripting.
It make the generation of dialog box relatively straight forward
and allow easily abstraction of data
HTML::Autowidget
This is no longer has any work done on it as I now use Autowidget::HTML
which I present futher down this page. However you might find this early
version might be easier to user.
Client interface
The main module HTML::AutoWdiget exports two functions:-
- sub getBodyAttr - returns a hash of attributes to
pass to CGI::start_html.
This is used primarily to initialise a
javascript environment. In case any of
the widgets use javascript.
- sub get_params - takes a CGI.pm object and a
list of descriptions and HTML::AutoWidget::xxx
compliant widgets. (see below)
returns list of values of the passed
widgets returned from the form or undef.
{ In the undef case output s appropriate HTML to
ask the user for the values - using the passed
widgets }
Any unknown params in the query object are
preserved as hidden fields.
Essentially thats it.
This means you can do a
my @data = get_params($query ,
['Begin Date' , new HTML::AutoWidget::Date('begin') ],
['End Date' , new HTML::AutoWidget::Date('end') ] );
if ($#data > 0 ) {
# Process with params...
} else {
# tidy up html and wait for next invocation...
}
Inside your CGI scripts to simplify step-by step querying of the user.
Widget interface
Compliant widgets need to support:-
- sub new - takes widget specific arguments...
- sub verify - takes $query as a param returns undef or
value from form.
- sub render - Creates HTML for widget.
- sub getfieldnames - returns list of html NAME='x' attributes generated.
- sub scriptname - get's unique tag for any javascript required.
{ allows javascript from similiar widgets
only to be included once! }
- sub get_script - returns javascript block.
How to get HTML::AutoWidget
I currently consider HTML::AutoWidget to be beta but for those of you
brave enough to try it you can download a simple tar-gz file from
here
AutoWidget::*
This recode is design to make the interface more generic, the big change
the early version is no output is generated during or before the verify
phase. HTML::AutoWidget assumed that a valid HTML container up to
and including the <BODY> tag had been output before get params.
The new Autowidget doesn't require this, and his design to be
indepent of UI and and encapsulation api. Eg. we have
AutoWidget::CGI::Controller which handles the processing of output
wether it be the existing AutoWidget::HTML or a possible AutoWidget::XML
Additionally I currently plan an AutoWidget::Curses::{Controller,Widgets}
Stop Press!!(09 April 2002) This may not happen, I might just suggest use of Curses::UI instead
Download It!
Client Interface
The client interface is simpler in concept than the previous on although
more verbose to implement.
my $query = new AutoWidget::CGI::Controller;
replaces your existing usage of CGI.pm.
Then AutoWidget::CGI::Controller provides a do_modal call
which will display a HTML page (of AutoWidget::HTML style objects
and exit if they fail to verify . If verify is succesful the
nothing is output and do_modal returns the output of
get_data() on the first item in the list.
Widget Interface
This is much bigger than the previous HTML::Autowidget interface although
made easier to build quick widgets, via base class of
AutoWidget:HTML::Base and AutoWidget:HTML::Tag, which I urge
you to use.
To create a new widget you probably only need to override
new(), render() and verify(). - If you use AutoWidget:HTML::Tag,
you may not need to override render.
Package functions
This functions are part of the package and
don't operate on a specific instance (execpt arguably new).
sub new()
This function creates a new object of the called class.
sub _splitargs
This is a helper function for new to split objects, into and
attribute hash and a list of passed objects or other data.
sub _attribh2s
This function builds up HTML compliant attrib code for placing
inside tags.
Instance Methods...
These functions relate to a specific instance of a widget
since widgets for a conatinership DAG, with no unique parent
or query context these are limited. And need relate to global
changes to the widget in all contexts.
sub set_attrib
This and the other attrib are a special case instance methods which knows about the query
methods calling conventions and automatically switchs between the
two depending on how it is called.
If the Controller is passed as the first arguement then
it sets the attribute in the dynamic attrib set,which
are specific to each query.
else a a static attrib which affect in the instance
in all queries it is involved in.
sub delete_attrib
Removes an attribute declareation from the approriate
set. Note currently you can't whiteout a static attrib
with a dynamic attrib. Deleting a dynamic attrib returns
it to it's 'default' value.
But it should be necessary to do this a you can
always make sure you only handle that attribute as a dynamic
attribute. By setting at the beginning of verify() it
the worst case.
sub get_attrib
This fetches an attribute so that you can examine or modify
it. If you are interested in generating a valid HTML
attirbute string havea look at _attribh2s which does this for
all the attributes.
sub get_basename
Return the basename of the object, this is the same as the name
attribute.
sub callchild
This can be used to generate the correct parameter for calling
a child object - see the code for examples.
sub callparent
This can be used to generate the correct parameter for calling
a parent object - see the code for examples.
We need the last to functions because the HTML containership
hieracharchy is a strict tree where ever object has a unique
parent, where as AutoWidget does not try to enforce this to
simplifiy object sharing.
Also by dropping the parent link we have a garbage collectable
data structure. This means that specific querys can contain
global objects, and if the golobal object change the can be dropped
from global symbol table but will be correct garbage collected
after any query using them completes.
Query Methods.
These methods provide the context specific stuff, and are intended
to be queried by controllers accesses the class and other context
specific methods.
It is good rule of thumb that these methods _should_not_ access instance
methods. Also they _must_not_ be accessed by instance methods.
Almost all of these methods take the same arguments.
-
$_[0] -self
-
$_[1] -query
-
$_[2] -ref to array of parent instances in the context.
sub get_parent
Return the most immediate parent.
eg., the last element in @{$[2]}
sub verify
Each widget must provide it's own verify routine which
checks to see if the user has entered valid data into
the widget's param.
The verify method is guaranteed to be called before
render() and it's secondary function is to do any query
specific setup which the widget may require.
verify is also use to set the widgets own hash in
the query, this hash as a number of predefined keys
for which there are functions below which extract the
data. You should alwasy use the finctions to get the
data from another widget as the fucntions are the public
interface. You aren't required to store data in the
hash is there is a better way of doing it.
| key | Meaning |
value => value to return to caller
displayvalue => value to report to user
value => value to return to caller
value => value to return to caller
|
sub get_value
Returns the value associated with the widget.
The default action in base is to return the value
element of the widgets private has in the current
query if it exists or the list of values
of it's contained widgets
sub get_displayvalue
Returns the displayvalue associated with the widget.
A Display value, is a value that can be shown the the user,
as verification (or whatever) of there selection).
The default action in base is to return the displayvalue
element of the widgets private has in the current
query if it exists or the list of values
of it's contained widgets
sub get_error
Returns theerror message associated with the widget.
The default action in base is to return the an array contianing
the (errno errmsg ) elements of the widgets private hash held
by the query.
Errmsg is supposed to a human readable string, describing the error.
Errno is also a string, but is designed to be terse and
the idea is not to change this, unless the semantics of the error
has changed. Hence you can change the message without changed the behaviour
of the container elements which may handle different Errno's differently.
Currently I have only defined ETOOMANY, ENOTENOUGH,
EINVAL, and OK,
sub get_containername
Get the Dom object pathname.
sub get_objectnames
This returns the contianed object names and the
name on of the contianing HTML object.
sub render()
Returns the html required for the widget.
sub get_fieldnames
Returns a list of names of paramaters includeing by the
widget.
sub get_script
Returns script portions named by @_.
I advise using the same names internally here as a
identifer used in the script to prevent conflicts.
sub scriptname
Returns the list of script names required by the
widget to function correctly.
Note: All that messing with scripts means that a widget
can appear multiple times in a page but it's support
script only needs appear once for the common code.
Note the existing AutoWidget::HTML::Page add some javascript
in which you can register your own functions to be called
at onload().