AxKit-XSP-PerForm
view release on metacpan or search on metacpan
=head1 DESCRIPTION
PerForm is a large and complex taglib for AxKit XSP that facilitates
creating large and complex HTML, WML, or other types of data-entry forms.
PerForm tends to make life easier for you if your form data is coming from
different data sources, such as DBI, or even XML.
PerForm works as an XSP taglib, meaning you simply add some custom XML tags
to your XSP page, and PerForm does the rest. Well, almost... PerForm works
mainly by callbacks, as you will see below.
=head1 EXAMPLE FORM
Ignoring the outside XSP and namespace declarations, assuming the prefix "f"
is bound to the PerForm namespace:
<f:form name="add_user">
First name: <f:textfield name="firstname" width="30" maxlength="50"/>
<br />
Last name: <f:textfield name="lastname" width="30" maxlength="50"/>
<br />
<f:submit name="save" value="Save" goto="users.xsp" />
<f:cancel name="cancel" value="Cancel" goto="home.html" />
</f:form>
Now it is important to bear in mind that this is just the form, and alone it
is fairly useless. You also need to add callbacks. You'll notice with each
of these callbacks you recieve a C<$ctxt> object. This is simply an empty
hash-ref that you can use in the callbacks to maintain state. Actually
"empty" is an exhageration - it contains two entries always: C<Form> and
C<Apache>. "Form" is a simply a hashref of the entries in the form (actually
it is an Apache::Table object, which allows for supporting multi-valued
parameters). So for example, the firstname below is in
C<$ctxt->{Form}{firstname}>. "Apache" is the C<$r> apache request object for
the current request, which is useful for access to the URI or headers.
sub validate_firstname {
my ($ctxt, $value) = @_;
$value =~ s/^\s*//;
else once you've processed the form. So for this, we issue redirects once
the form has been processed. This has the advantage that you can't hit
reload by accident and have the form re-submitted.
To define where you go on hitting submit, you can either return set the
I<goto> attribute on the submit or cancel button, or implement a callback
and return a URI to redirect to.
=head1 THE CONTEXT OBJECT
Each of the form callbacks is passed a context object. This is a hashref you
are allowed to use to maintain state between your callbacks. There is a new
context object created for every form on your XSP page. There are two
entries filled in automatically into the hashref for you:
=over 4
=item Form
This is actually an Apache::Table object, so it looks and works just like an
ordinary hashref, and contains the values submitted from the form, or is
perhaps empty if the form hasn't been submitted yet. It may also contain any
$ctxt->{my_key} = $my_value;
And you can later get at that in another callback via C<$ctxt->{my_key}>.
=head1 ARRAYED FORM ELEMENTS
Sometimes you need to display a list of items in your form where the number
of items is not known until runtime. Use arrayed form elements to trigger
the same callback for each item in the list. When setting up each element,
use an index to identify each member of the list. The callbacks will be
passed the index as a parameter. e.g.
Your form may have a section like this:
<xsp:logic>
for $index (0..$#shoppinglist) {
<p>
<xsp:expr>$shoppinglist[$index]</xsp:expr>
<f:submit name="SubmitBuy" value="Buy me">
<f:index><xsp:expr>$index</xsp:expr></f:index>
=head1 XSP INHERITANCE
Starting with AxKit 1.6.1 it is possible to specify a class which your XSP
page inherits from. All the validate, load, submit and cancel functions can
be in the class you inherit from, reducing code duplication, memory usage,
and complexity.
=head1 SPECIFYING CALLBACKS
All of the documentation here uses the default callbacks which are implied
by the name of the form element you give. Unfortunately this makes it
difficult to have multiple elements with the same validation logic without
duplicating code. In order to get around this you can manually specify the
callbacks to use.
Every main tag supports both C<onvalidate> and C<onload> attributes which
specify perl function names to validate and load respectively. Submit
buttons support C<onsubmit> attributes. Cancel buttons support C<oncancel>
attributes. Forms themselves support both C<oncancel> and C<onsubmit>
attributes.
If a form is submitted without pressing a button (such as via JavaScript,
or by hitting <Enter>, then the form tag's C<onsubmit> callback will be
used. It is always sensible to define this to be one of your button's
submit callbacks.
All tags allow a C<disabled> attribute. Set this to a true value (i.e.
C<disabled="1">) to set the control to disabled. This will be interpreted
as a HTML 4.0 feature in the default perform stylesheet.
=head1 TAG DOCUMENTATION
The following documentation uses the prefix I<f:> for all PerForm tags. This
assumes you have a namespace declaration
C<xmlns:f="http://axkit.org/NS/xsp/perform/v1"> in your XSP file.
A submit button. Every form should have one, otherwise there is little point
in having a form!
B<Attributes:>
=over 4
=item name (mandatory)
The name of the submit button. Used for the submit callbacks.
=item value
The text on the button, if you are using a browser generated button.
=item image
A URI to the image, if you instead wish to use an image for the button.
=item alt
A text entry field.
B<Attributes:>
=over 4
=item name (mandatory)
The name of the textfield. Should be unique to the entire XSP page, as
callbacks only use the widget name. Can also be used in
C<$ctxt-E<gt>{Form}{E<lt>nameE<gt>}> to retrieve the value.
=item default
A default value for the textfield.
=item width
The width of the textfield on the screen. Units are dependant on the final
rendering method - for HTML this would be em characters.
}
=back
=head2 <f:single-select/>
A drop-down select list of items.
The single-select and multi-select (below) elements can be populated either
by callbacks or through embedded elements.
B<Attributes:>
=over 4
=item name (mandatory)
The name of the single select widget.
=item default
AxKit::XSP::PerForm
===================
This module is a "magic" forms library for building complex web
applications. Forms are defined using the tags provided by this
module, and then for each element on the form, callbacks are used
for loading values, validating values, and submitting the form.
( run in 0.345 second using v1.01-cache-2.11-cpan-9b1e4054eb1 )