apache > cocoon

- Home

# Simple Forms

## Introduction

This chapter describes the (simple) form handling approach of the session framework.

Note
Cocoon provides several approaches for form handling. This chapter explains one of them.

## Form Handling

To get feedback or information from a user, forms are commonly used to present input field in the browser. The usual approach for form handling in web application consists of two steps. The first request presents the form to the user. This form initiates a second request that processes the form values.

Cocoon supports this two step process, in addition Cocoon offers a single step approach.

### The common approach

The common approach consists of two steps or of creating two resources. The first resource defines the form: All input fields are declared, each gets a unique name. This form invokes the second resource.

This resource uses the session transformer to get the values provided by the user. The values are added by the browser to the parameters of the request. So using the request context and getxml, the values can be fetched.

If you want to create a form with two values - forename and surname of the user, you could generate a base xml file with the information about this form:

    <page>
      <form>
        <action>form-handling-page</action>
        <input name="forename" type="text"/>
        <input name="surname" type="text"/>
      </form>
    </page>

A stylesheet can transform this into valid html. The action tag indicates that the "form-handling-page" should be invoked by submitting the values.

The "form-handling-page" is a pipeline which is declared in the sitemap and uses the session transformer. It could also read the following xml:

    <page xmlns:session="http://apache.org/cocoon/session/1.0">
      <forename>
        <session:getxml context="request" path="/parameter/forename"/>
      </forename>
      <surname>
        <session:getxml context="request" path="/parameter/surname"/>
      </surname>
    </page>

As the form values are appended to the request, getxml with specifying the path (which is the parameter name used for the input field) inserts the value submitted by the user into the xml stream.

If you want to write the information in a session context, you must wrap the whole xml inside a setxml:

    <page xmlns:session="http://apache.org/cocoon/session/1.0">
      <session:setxml context="userdata" path="/user">
        <forename>
          <session:getxml context="request" path="/parameter/forename"/>
        </forename>
        <surname>
          <session:getxml context="request" path="/parameter/surname"/>
        </surname>
      </session:setxml>
    </page>

The user data is now stored inside the session context "userdata", so the context has the following content:

    <user>
      <forename>Walter</forename>
      <surname>Walterson</surname>
    </user>

### The Session Framework approach

The previous chapter showed the common approach for handling form values. It forces the user to create two resources for a single form handling.

Cocoon offers an advanced approach. Only one single resource is created. This resources contains the information about the input fields used and in addition the information about where the submitted values should be stored inside the session.

The example from the previous chapter could look like this:

    <page xmlns:session="http://apache.org/cocoon/session/1.0">
      <session:form name="myform">
        <session:action>the-next-page</session:action>
        <session:content>
          <session:inputxml name="forename" type="text" context="userdata" path="/user/forename"/>
          <session:inputxml name="surname" type="text" context="userdata" path="/user/surname"/>
        </session:content>
      </session:form>
    </page>

The form tag starts the form definition. The name attribute is required to distinct between different forms on the same page. The action tag defines the url invoked by the form and the content tag describes the content of the form: its input fields.

The inputxml tag tells Cocoon that the following request contains form values which should be stored in the specified context under the given path. The session transformer transforms by removing the namespace and the context attribute:

    <page xmlns:session="http://apache.org/cocoon/session/1.0">
      <form action="the-next-page">
        <inputxml name="forename" type="text"/>
        <inputxml name="surname" type="text"/>
      </form>
    </page>

A stylesheet can now generate the appropriate html (or any other format). The main difference is, that the resource invoked by submitting the values has not to care about the form as Cocoon maintains the form handling. The only prerequisit is that a session for the current user and a session context to store the information exists.

The Cocoon approach allows a very easy way of form handling where the resource which creates the form also handles the form.

For editing values - if the context already contains information about the user - inputxml inserts the current value inside the tag. So the xml streamed would after a second run would look like this:

    <page xmlns:session="http://apache.org/cocoon/session/1.0">
      <form action="the-next-page">
        <inputxml name="forename" type="text">Walter</inputxml>
        <inputxml name="surname" type="text">Walterson</inputxml>
      </form>
    </page>

Like getxml it is also possible to provide default values for the input field, if the context does not contain any information:

    <session:inputxml name="forename" context="userdata" path="/user/forename">
         Defaultname
    </session:inputxml>

But as always there is one drawback with this approach as well, you have to put the session-form-manager action somewhere so that it is called when the form values are submitted. As this action does no harm, it can simply be put as the first action in your main sitemap:

            <map:act type="session-form-manager"/>

Errors and Improvements? If you see any errors or potential improvements in this document please help us: View, Edit or comment on the latest development version (registration required).