Take me over?

The maintainer of this distribution is looking for someone to take over! If you're interested then please contact them via email.

NAME

AxKit::XSP::PerForm - XSP Taglib for making complex forms easy

SYNOPSIS

AxAddXSPTaglib AxKit::XSP::PerForm

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.

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 $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: Form and 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 $ctxt-{Form}{firstname}>. "Apache" is the $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].

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 goto attribute on the submit or cancel button, or implement a callback and return a URI to redirect to.

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:

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 Apache::Table.
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 Apache.

To add an entry to the context object, simply use it as a hashref:

$ctxt->{my_key} = $my_value;

And you can later get at that in another callback via $ctxt-{my_key}>.

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>
      </f:submit>
  </p>
}
</xsp:logic>

The submit callback might be:

sub submit_SubmitBuy {
  my ($ctxt, $index) = @_;
  return "purchase.xsp?item=$index";
}

This example produces a list of items with a 'Buy me' button next to each one. Each button has an index that corresponds an array index of an item in the shopping list. When one of the submit buttons is pressed, the submit_SubmitBuy callback will be triggered (as part of the submission procedure) and the browser will redirect to a page that handles the purchase of the associated item.

NOTE: arrays not supported for file-upload elements.

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.

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 onvalidate and onload attributes which specify perl function names to validate and load respectively. Submit buttons support onsubmit attributes. Cancel buttons support oncancel attributes. Forms themselves support both oncancel and onsubmit attributes.

If a form is submitted without pressing a button (such as via JavaScript, or by hitting <Enter>, then the form tag's 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 disabled attribute. Set this to a true value (i.e. disabled="1") to set the control to disabled. This will be interpreted as a HTML 4.0 feature in the default perform stylesheet.

TAG DOCUMENTATION

The following documentation uses the prefix f: for all PerForm tags. This assumes you have a namespace declaration xmlns:f="http://axkit.org/NS/xsp/perform/v1" in your XSP file.

Please note that for all of the widget tags, PerForm uses TaglibHelper. This has the advantage that you can define attributes either as XML attributes in the tag, or as child tags in the PerForm namespace. So:

<f:textfield name="foo" default="bar"/>

Is exactly equivalent to:

<f:textfield name="foo">
  <f:default>bar</f:default>
</f:textfield>

The advantage of this is that child tags can get their content from other XSP tags.

<f:form>

This tag has to be around the main form components. It does not have to have any ACTION or METHOD attributes, as that is all sorted out internally. Note that you can have as many f:form tags on a page as you want, but it probably doesn't make sense to nest them.

Attributes:

name: The name of the form. This name is used to call start_form_<name>, and end_form_<name>.

Callbacks:

start_form_<name>: Passed a single parameter: $ctxt, the context object. This callback is called before processing the form contents.
end_form_<name>: Passed a single parameter: $ctxt, the context object. This callback is called after processing the form contents, but before processing any submit or cancel buttons.

Note that <f:form> is the only tag (besides <f:single-select/> and <f:multi-select/>) in PerForm that has content. All other tags are empty, unless you define the attributes in child tags, as documented above.

<f:submit/>

A submit button. Every form should have one, otherwise there is little point in having a form!

Attributes:

name (mandatory): The name of the submit button. Used for the submit callbacks.
value: The text on the button, if you are using a browser generated button.
image: A URI to the image, if you instead wish to use an image for the button.
alt: Alternate text for an image button.
border: The width of the border around an image button. Default is zero.
align: The alignment of the button
goto: If you do not wish to implement the callback below, you can set the goto attribute to a URI to redirect to when the user hits the button. Normally you won't use this unless you happen to not want to save the form values in any way.
index: If your button is a member of an array, then set the index attribute to the corresponding array index.
onclick: This attribute is intended to be passed through to the generated output for client-side onClick routines (usually written in javascript). Simply specify a string as you would if writing dynamic html forms in plain HTML.

Callbacks:

submit_<name> ( $ctxt , $index )

This callback is used to "do something" with the submitted form values. You might write them to a database or a file, or change something in your application.

The $index parameter identifies which button was pressed in an array of buttons.

The return value from submit_<name> is used to redirect the user to the "next" page, whatever that might be.

<f:cancel/>

A cancel button. This is similar to the submit button, but instead of being used to save the form values (or "do something" with them), should be used to cancel the use of this particular form and go somewhere else. The most common use of this is to simply set the goto attribute to redirect to another page.

Attributes:

All attributes are the same as for <f:submit/>.

Callbacks:

cancel_<name> ( $ctxt, $index ): Implement this method to override the goto attribute. Return the URI you want to redirect to. This can be used to dynamically generate the URI to redirect to.

<f:textfield/>

A text entry field.

Attributes:

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 $ctxt->{Form}{<name>} to retrieve the value.
default: A default value for the textfield.
width: The width of the textfield on the screen. Units are dependant on the final rendering method - for HTML this would be em characters.
maxlength: The maximum number of characters you can enter into this text field.
index: If your text field is a member of an array, then set the index attribute to the corresponding array index.
onchange: This is a javascript callback implemented on the client side in HTML 4.0 capable browsers. It simply passes the value through to the generated HTML.

Callbacks:

load_<name> ( $ctxt, $default, $current, $index )

Used to load a value into the edit box. The default is from the attributes above. The current value is only set if this form has been submitted once already, and contains the value submitted.

Simply return the value you want to appear in the textfield.

If the text field is a memeber of an array, then $index will be the array index.

If you do not implement this method, the value in the textfield defaults to $current || $default.

validate_<name> ( $ctxt, $value, $index )

Implement this method to validate the contents of the textfield. If the value is valid, you don't need to do anything. However if it invalid, throw an exception with the reason why it is invalid. Example:

sub validate_username {
    my ($ctxt, $value) = @_;
    # strip leading/trailing whitespace
    $value =~ s/^\s*//;
    $value =~ s/\s*$//;
    die "No value" unless length $value;
    die "Invalid characters" if $value =~ /\W/;
}

If the text field is a memeber of an array, then $index will be the array index.

<f:password/>

A password entry field. This works exactly the same way as a textfield, so we don't duplicate the documentation here

<f:checkbox/>

A checkbox.

Attributes:

name (mandatory): The name of the checkbox, used to name the callback methods.
value: The value that gets sent to the server when this checkbox is checked.
checked: Set to 1 or yes to have this checkbox checked by default. Set to 0, no, or leave off altogether to have it unchecked.
label: Used in HTML 4.0, the label for the checkbox. Use this with care as most browsers don't support it.
index: Use this to identify the array index when using arrayed form elements.
onclick: This attribute is intended to be passed through to the generated output for client-side onClick routines (usually written in javascript). Simply specify a string as you would if writing dynamic html forms in plain HTML.

Callbacks:

load_<name> ( $ctxt, $current, $index )

If you implement this method, you can change the default checked state of the checkbox, and the value returned by the checkbox if you need to.

Return one or two values. The first value is whether the box is checked or not, and the second optional value is what value is sent to the server when the checkbox is checked and submitted.

validate_<name> ( $ctxt, $value, $index )

Validate the value in the checkbox. Throw an exception to indicate validation failure.

<f:file-upload/>

A file upload field (normally in HTML, a text entry box, and a "Browse..." button).

Attributes:

name (mandatory): The name of the file upload field.
value: A default filename to put in the box. Use with care because putting something in here is not very user friendly!
accept: A list of MIME types to accept in this dialog box. Some browsers might use this in the Browse dialog to restrict the list of files to show.
onclick: This attribute is intended to be passed through to the generated output for client-side onClick routines (usually written in javascript). Simply specify a string as you would if writing dynamic html forms in plain HTML.

Callbacks:

load_<name> ( $ctxt, $default, $current )

Load a new value into the file upload field. Return the value to go in the field.

validate_<name> ( $ctxt, $filename, $fh, $size, $type, $info )

Validate the uploaded file. This is also actually the place where you would save the file to disk somewhere, by reading from $fh and writing to somewhere else, or using File::Copy to do that for you. It is much harder to access the file from the submit callback.

If the file is somehow invalid, throw an exception with the text of why it is invalid.

<f:hidden/>

A hidden form field, for storing persistent information across submits.

PerForm hidden fields are quite useful because they are self validating against modification between submits, so if a malicious user tries to change the value by editing the querystring or changing the form value somehow, the execution of your script will die with an exception.

Attributes:

name (mandatory): The name of the hidden field
value: The value stored in the hidden field
index: Use this to identify the array index when using arrayed form elements.

Callbacks:

load_<name> ( $ctxt, $default, $index ): If you wish the value to be dynamic somehow, implement this callback and return a new value for the hidden field.

There is no validate callback for hidden fields.

<f:textarea/>

A large box of editable text.

Attributes:

name (mandatory): A name for the textarea
cols: The number of columns (width) of the box.
rows: The number of rows of text to display.
wrap: Set this to "yes" or "1" to have the textarea wrap the text automatically. Set to "no" or leave blank to not wrap. Default is to not wrap.
default: The default text to put in the textarea.
index: Use this to identify the array index when using arrayed form elements.
onchange: This is a javascript callback implemented on the client side in HTML 4.0 capable browsers. It simply passes the value through to the generated HTML.

Callbacks:

load_<name> ( $ctxt, $default, $current, $index )

Load a new value into the widget. Return the string you want to appear in the box.

validate_<name> ( $ctxt, $value, $index )

Validate the contents of the textarea. If the contents are somehow invalid, throw an exception in your code with the string of the error. One use for this might be validating a forums posting edit box against a small DTD of HTML-like elements. You can use XML::LibXML to do this, like this:

sub validate_body {
  my ($ctxt, $value) = @_;
  $value =~ s/\A\s*//;
  $value =~ s/\s*\Z//;
  die "No content" unless length($value);
  my $dtdstr = <<EOT;
<!ELEMENT root (#PCDATA|p|b|i|a)*>
<!ELEMENT p (#PCDATA|b|i|a)*>
<!ELEMENT b (#PCDATA|i|a)*>
<!ELEMENT i (#PCDATA|b|a)*>
<!ELEMENT a (#PCDATA|b|i)*>
<!ATTLIST a
      href CDATA #REQUIRED
      >
EOT
  my $dtd = XML::LibXML::Dtd->parse_string($dtdstr);
  my $xml = XML::LibXML->new->parse_string(
              "<root>$value</root>"
              );
  eval {
      $xml->validate($dtd);
  };
  if ($@) {
      die "Invalid markup in body text: $@";
  }
  
}

<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.

Attributes:

name (mandatory): The name of the single select widget.
default: The default value that is to be selected.
index: Use this to identify the array index when using arrayed form elements.
onchange: This is a javascript callback implemented on the client side in HTML 4.0 capable browsers. It simply passes the value through to the generated HTML.

Elements:

<f:options>: Child to a <f:single-select> element, this wraps around a listing of populated options
<option>: Child to <f:options>, this is an individual option
<name>: This is the name for a given option, to which it is a child
<value>: Similar to <name>, this indicates the value for an option

Callbacks:

load_<name> ( $ctxt, $currently_selected )

The return values for this callback both populate the list, and define which value is selected.

The return set is a simple list: selected, text, value, text, value, ...

Where selected matches a value from that list. So, for example, it might be:

sub load_list {
    my ($ctxt, $current) = @_;
    return $current || "#FF0000", 
      "Blue" => "#0000FF", 
      "Red" => "#FF0000",
      "Green" => "#00FF00",
      ;
}

validate_<name> ( $ctxt, $value )

Validate the value. Throw an exception with the text of the error if something is wrong.

<f:multi-select/>

A multiple select box, with a scrollable list of values.

Attributes:

name (mandatory): The name of the multiple select widget.
default: The default value that is to be selected. This can be specified as a child element (e.g. <f:default>) in order to indicate multiple default values.
index: Use this to identify the array index when using arrayed form elements.
onclick: This attribute is intended to be passed through to the generated output for client-side onClick routines (usually written in javascript). Simply specify a string as you would if writing dynamic html forms in plain HTML.

Elements:

The available child elements are identical to <f:single-select> so they will not be repeated here.

Callbacks:

load_<name> ( $ctxt, $currently_selected ): This works very similarly to the load callback for single selects (above), except that both the $currently_selected, and the returned selected value are array refs.
validate_<name> ( $ctxt, $values ): Here $values is an array ref of the selected values. As usual, if one is in error somehow, throw an exception containing the text of the error.

AUTHOR

Matt Sergeant, matt@sergeant.org

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

Take me over?

NAME

SYNOPSIS

DESCRIPTION

EXAMPLE FORM

SUBMISSION PROCEDURE

THE CONTEXT OBJECT

ARRAYED FORM ELEMENTS

XSP INHERITANCE

SPECIFYING CALLBACKS

TAG DOCUMENTATION

<f:form>

<f:submit/>

<f:cancel/>

<f:textfield/>

<f:password/>

<f:checkbox/>

<f:file-upload/>

<f:hidden/>

<f:textarea/>

<f:single-select/>

<f:multi-select/>

AUTHOR

SEE ALSO

Module Install Instructions