AxKit-XSP-PerForm
view release on metacpan or search on metacpan
AxAddXSPTaglib AxKit::XSP::PerForm
=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*//;
$value =~ s/\s*$//;
die "No value" unless $value;
die "Invalid firstname - non word character not allowed"
if $value =~ /\W/;
}
sub validate_lastname {
return validate_firstname(@_);
}
sub submit_save {
my ($ctxt) = @_;
# save values to a database
warn("User: ", $ctxt->{Form}{firstname}, " ", $ctxt->{Form}{lastname}, "\n");
}
Now these methods need to be global to your XSP page, rather than "closures"
within the XSP page's main handler routine. How do you do that? Well it's
simple. Just put them within a <xsp:logic> section before any user defined
tags. For example, if your XSP page happens to use XHTML as it's basic
format (something I do a lot), your page might be constructed as follows
(namespace declarations omitted for brevity):
<xsp:page>
<xsp:logic>
... form logic here ...
</xsp:logic>
<html>
<head><title>An Example Form</title></head>
<body>
<h1>An Example Form</h1>
<f:form>
... form definition here ...
</f:form>
</body>
</html>
</xsp:page>
[Note that the page-global methods is a useful technique in other
situations, because unlike Apache::Registry scripts, this won't create a
closure from methods defined there].
=head1 SUBMISSION PROCEDURE
In PerForm, all forms submit back to themselves. This allows us to implement
the callback system. Of course with most forms, you want to go somewhere
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
parameters passed in the querystring. For multi-value parameters, they can
be accessed via Apache::Table's get, add and set methods. See
L<Apache::Table>.
=item Apache
The Apache entry is the apache request object for the current request. You
can use this, for example, to get the current URI, or to get something out
of dir_config, or perhaps to send a header. See L<Apache>.
=back
( run in 1.500 second using v1.01-cache-2.11-cpan-62a16548d74 )