AxKit-XSP-PerForm
view release on metacpan or search on metacpan
=head1 DESCRIPTIONPerForm is a large and complex taglib for AxKit XSP that facilitatescreating 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 fromdifferent data sources, such as DBI, or even XML.PerForm works as an XSP taglib, meaning you simply add some custom XML tagsto your XSP page, and PerForm does the rest. Well, almost... PerForm worksmainly by callbacks, as you will see below.=head1 EXAMPLE FORMIgnoring 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 itis fairly useless. You also need to add callbacks. You'll notice with eachof these callbacks you recieve a C<$ctxt> object. This is simply an emptyhash-ref that you can use in the callbacks to maintain state. Actually"empty" is an exhageration - it contains two entries always: C<Form> andC<Apache>. "Form" is a simply a hashref of the entries in the form (actuallyit is an Apache::Table object, which allows for supporting multi-valuedparameters). So for example, the firstname below is inC<$ctxt->{Form}{firstname}>. "Apache" is the C<$r> apache request object forthe current request, which is useful for access to the URI or headers.sub validate_firstname {my ($ctxt, $value) = @_;$value =~ s/^\s*//;
elseonce you've processed the form. Soforthis, we issue redirects oncethe formhasbeen processed. Thishasthe advantage that you can't hitreload by accident and have the form re-submitted.To define where you go on hitting submit, you can eitherreturnset theI<goto> attribute on the submit or cancel button, or implement a callbackandreturna URI to redirect to.=head1 THE CONTEXT OBJECTEach of the form callbacks is passed a context object. This is a hashref youare allowed to use to maintain state between your callbacks. There is a newcontext object created for every form on your XSP page. There are twoentries filled in automatically into the hashref for you:=over 4=item FormThis is actually an Apache::Table object, so it looks and works just like anordinary hashref, and contains the values submitted from the form, or isperhaps 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 ELEMENTSSometimes you need to display a list of items in your form where the numberof items is not known until runtime. Use arrayed form elements to triggerthe 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 bepassed 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 INHERITANCEStarting with AxKit 1.6.1 it is possible to specify a class which your XSPpage inherits from. All the validate, load, submit and cancel functions canbe in the class you inherit from, reducing code duplication, memory usage,and complexity.=head1 SPECIFYING CALLBACKSAll of the documentation here uses the default callbacks which are impliedby the name of the form element you give. Unfortunately this makes itdifficult to have multiple elements with the same validation logic withoutduplicating code. In order to get around this you can manually specify thecallbacks to use.Every main tag supports both C<onvalidate> and C<onload> attributes whichspecify perl function names to validate and load respectively. Submitbuttons 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 beused. It is always sensible to define this to be one of your button'ssubmit 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 interpretedas a HTML 4.0 feature in the default perform stylesheet.=head1 TAG DOCUMENTATIONThe following documentation uses the prefix I<f:> for all PerForm tags. Thisassumes you have a namespace declarationC<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 pointin having a form!B<Attributes:>=over 4=item name (mandatory)The name of the submit button. Used for the submit callbacks.=item valueThe text on the button, if you are using a browser generated button.=item imageA 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, ascallbacks only use the widget name. Can also be used inC<$ctxt-E<gt>{Form}{E<lt>nameE<gt>}> to retrieve the value.=item defaultA default value for the textfield.=item widthThe width of the textfield on the screen. Units are dependant on the finalrendering 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 eitherby 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 libraryforbuilding complex webapplications. Forms aredefinedusing the tags provided by thismodule, and thenforeachelement on the form, callbacks are usedforloadingvalues, validatingvalues, and submitting the form.
( run in 0.242 second using v1.01-cache-2.11-cpan-0d8aa00de5b )