org.apache.cocoon.transformation
Class SimpleFormTransformer

java.lang.Object
  extended byorg.apache.cocoon.util.AbstractLogEnabled
      extended byorg.apache.cocoon.xml.AbstractXMLProducer
          extended byorg.apache.cocoon.xml.AbstractXMLPipe
              extended byorg.apache.cocoon.transformation.AbstractTransformer
                  extended byorg.apache.cocoon.transformation.AbstractSAXTransformer
                      extended byorg.apache.cocoon.transformation.SimpleFormTransformer
All Implemented Interfaces:
Configurable, ContentHandler, Disposable, LexicalHandler, Poolable, Recyclable, Serviceable, org.apache.cocoon.sitemap.SitemapModelComponent, org.apache.cocoon.transformation.Transformer, XMLConsumer, org.apache.cocoon.xml.XMLConsumer, org.apache.cocoon.xml.XMLPipe, org.apache.cocoon.xml.XMLProducer

public class SimpleFormTransformer
extends org.apache.cocoon.transformation.AbstractSAXTransformer

Eliminates the need for XSP to use FormValidatorAction or HTML forms. Caveat: Select options need a value attribute to work correctly.

This transformer fills all HTML form elements with values from an InputModule, e.g. request, with the same name. It handles select boxes, textareas, checkboxes, radio buttons, password and text fields, and buttons. Form elements and complete forms can be protected from substitution by adding an attribute fixed="true" to them.

In addition, it handles FormValidatorAction results by selectively omitting <error/> elements. These elements need a "name" attribute corresponding to the name of the form element, and either a "when" or a "when-ge" attribute.

An error element is send down the pipeline if validation results are available and either the results equals the "when" attribute or the result is greater or equal to the "when-ge" attribute.

Names for validation results are "ok", "not-present", "error", "is-null", "too-small", "too-large", and "no-match" for the similar named values from ValidatorActionResult.

There need not to be an "error" element for every form element, multiple error elements for the same form element may be present.

Names of error elements are never augmented by prefix, suffix or form name.

Page parts with multiple occurrences depending on the number of actual parameters can be enclosed in <repeat on="expr" using="var"/> elements. expr is used to determine the number of occurrences and var will be expanded with the ordinary number. Repeat elements can be nested.

Example:

  
 

Will include as many input elements as mult parameters are present. Adding the repeater variable to the elements name is necessary only with structured parameters or when they should be numbered. See also the strip-number configuration parameter.

To use this transformer, add the following to your transformation pipeline:

   <map:transform type="simple-form"/>
 

Configuration elements:

input-module(String) InputModule configuration, defaults to an empty configuration and the "request-param" module
fixed-attribute(String) Name of the attribute used to indicate that this element should not be changed. ("fixed")
use-form-name(boolean) Add the name of the form to the name of form elements. Uses default Separator , if default separator is null or empty, separator is set to "/". ("false")
use-form-name-twice(boolean) Add the name of the form twice to the name of form elements. This is useful when the form instance has no all enclosing root tag and the form name is used instead and the form name needs to be used to find the form data. Uses default Separator , if default separator is null or empty, separator is set to "/".("false")
separator(String) Separator between form name and element name ("/")
prefix(String) Prefix to add to element name for value lookup. No separator will be added between prefix and rest of the name. Default is "", when use-form-name is set, defaults to separator.
suffix(String) Added to the input element's name. No separator will be added between rest of the name and suffix. ("")
ignore-validation(boolean) If set to true, all error tags are copied as is regardless of the validation results.("false")
decoration(int) Length of decorations around repeat variable. Example: when using JXPath based module, decoration would be "[" and "]", hence 1. (1)
strip-number(boolean) If set to false, element names of repeated elements will contain the expanded repeater variable. ("true")

Sitemap parameters:

fixed(boolean) Do not change values
prefix(String) Added to the input element's name
suffix(String) Added to the input element's name
input(String) InputModule name
decoration(int) Length of decorations around repeat variable.
strip-number(boolean) Expanded repeater variable.

Example:

     <input name="user.name" size="50" maxlength="60"/>
     <error name="user.name" when-ge="error">required</error>
 

Version:
$Id: SimpleFormTransformer.html 1304280 2012-03-23 11:18:01Z ilgrosso $

Nested Class Summary
protected  class SimpleFormTransformer.RepeaterStatus
          Keep track of repeater status.
protected static class SimpleFormTransformer.ValueList
          Keep track of multiple values.
 
Field Summary
protected  Map formValues
          Map of SimpleFormTransformer.ValueList to track multiple parameters.
protected static String INPUT_MODULE_ROLE
           
protected static String INPUT_MODULE_SELECTOR
           
protected  int recordingCount
          Count nested repeat elements.
protected  List repeater
          List of SimpleFormTransformer.RepeaterStatus elements keeping track of nested repeat blocks.
protected  boolean skipChildrenOnly
          Skip element's content only.
protected  Map validationResults
          current request's validation results (all validated elements)
protected  Object[] values
          current element's request parameter values
 
Fields inherited from class org.apache.cocoon.transformation.AbstractSAXTransformer
context, defaultNamespaceURI, EMPTY_ATTRIBUTES, ignoreEmptyCharacters, ignoreEventsCount, ignoreHooksCount, ignoreWhitespaces, manager, namespaceURI, objectModel, parameters, recorderStack, removeOurNamespacePrefixes, request, resolver, response, source, stack
 
Fields inherited from class org.apache.cocoon.xml.AbstractXMLProducer
contentHandler, EMPTY_CONTENT_HANDLER, lexicalHandler, xmlConsumer
 
Fields inherited from interface org.apache.cocoon.transformation.Transformer
ROLE
 
Constructor Summary
SimpleFormTransformer()
          Constructor.
 
Method Summary
 void configure(Configuration config)
          Avalon Configurable Interface
protected  void endRepeatElement(String uri, String name, String raw)
          Stop recording repeat contents and replay required number of times.
 void endTransformingElement(String uri, String name, String raw)
          Start processing elements of our namespace.
protected  String printAttributes(Attributes attr)
          Generate string representation of attributes.
 void recycle()
          Recycle this component.
protected  void relayEndElement(String uri, String name, String raw)
          Calls the super's method endTransformingElement and decrements the ignoreEventsCount if larger than zero.
protected  void relayStartElement(boolean skip, boolean skipChildrenOnly, String uri, String name, String raw, Attributes attr)
          Calls the super's method startTransformingElement and increments the ignoreEventsCount if skip is true.
protected  void relayStartElement(String uri, String name, String raw, Attributes attr)
          Calls the super's method startTransformingElement.
 void setup(org.apache.cocoon.environment.SourceResolver resolver, Map objectModel, String src, Parameters par)
          Setup the next round.
protected  void startCheckableElement(String aName, String uri, String name, String raw, AttributesImpl attributes)
          Handle input elements that may have a "checked" attributes, i.e.
protected  void startErrorElement(String uri, String name, String raw, Attributes attr)
          Handle error elements.
protected  void startFormElement(String uri, String name, String raw, Attributes attr)
          Start processing a form element.
protected  void startInputElement(String uri, String name, String raw, Attributes attr)
          Handle input elements.
protected  void startNonCheckableElement(String aName, String uri, String name, String raw, AttributesImpl attributes)
          Handle input elements that may don't have a "checked" attributes, e.g.
protected  void startOptionElement(String uri, String name, String raw, Attributes attr)
          Handle option elements.
protected  void startRepeatElement(String uri, String name, String raw, Attributes attr)
          Start recording repeat element contents and push repeat expression and variable to repeater stack.
protected  void startSelectElement(String uri, String name, String raw, Attributes attr)
          Handle select elements.
protected  void startTextareaElement(String uri, String name, String raw, Attributes attributes)
          Handles textarea elements.
 void startTransformingElement(String uri, String name, String raw, Attributes attr)
          Start processing elements of our namespace.
 
Methods inherited from class org.apache.cocoon.transformation.AbstractSAXTransformer
addRecorder, characters, comment, dispose, endCDATA, endDocument, endDTD, endElement, endEntity, endParametersRecording, endParametersRecording, endPrefixMapping, endRecording, endSAXRecording, endSerializedXMLRecording, endTextRecording, findPrefixMapping, getMutableAttributes, ignorableWhitespace, processingInstruction, removeRecorder, sendEndElementEvent, sendEndElementEventNS, sendEndPrefixMapping, sendEvents, sendParametersEvents, sendStartElementEvent, sendStartElementEvent, sendStartElementEventNS, sendStartElementEventNS, sendStartPrefixMapping, sendTextEvent, service, setDocumentLocator, setupTransforming, skippedEntity, startCDATA, startDocument, startDTD, startElement, startEntity, startParametersRecording, startPrefixMapping, startRecording, startSAXRecording, startSerializedXMLRecording, startTextRecording
 
Methods inherited from class org.apache.cocoon.xml.AbstractXMLProducer
setConsumer, setContentHandler, setLexicalHandler
 
Methods inherited from class org.apache.cocoon.util.AbstractLogEnabled
getLogger, setLogger
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.apache.cocoon.xml.XMLProducer
setConsumer
 

Field Detail

INPUT_MODULE_ROLE

protected static final String INPUT_MODULE_ROLE

INPUT_MODULE_SELECTOR

protected static final String INPUT_MODULE_SELECTOR

values

protected Object[] values
current element's request parameter values


validationResults

protected Map validationResults
current request's validation results (all validated elements)


skipChildrenOnly

protected boolean skipChildrenOnly
Skip element's content only. Otherwise skip also surrounding element.


recordingCount

protected int recordingCount
Count nested repeat elements.


repeater

protected List repeater
List of SimpleFormTransformer.RepeaterStatus elements keeping track of nested repeat blocks.


formValues

protected Map formValues
Map of SimpleFormTransformer.ValueList to track multiple parameters.

Constructor Detail

SimpleFormTransformer

public SimpleFormTransformer()
Constructor. Set the namespace.

Method Detail

configure

public void configure(Configuration config)
               throws ConfigurationException
Avalon Configurable Interface

Throws:
ConfigurationException

setup

public void setup(org.apache.cocoon.environment.SourceResolver resolver,
                  Map objectModel,
                  String src,
                  Parameters par)
           throws org.apache.cocoon.ProcessingException,
                  SAXException,
                  IOException
Setup the next round. The instance variables are initialised.

Parameters:
resolver - The current SourceResolver
objectModel - The objectModel of the environment.
src - The value of the src attribute in the sitemap.
par - The parameters from the sitemap.
Throws:
org.apache.cocoon.ProcessingException
SAXException
IOException

recycle

public void recycle()
Recycle this component.


printAttributes

protected String printAttributes(Attributes attr)
Generate string representation of attributes. For debug only.


startCheckableElement

protected void startCheckableElement(String aName,
                                     String uri,
                                     String name,
                                     String raw,
                                     AttributesImpl attributes)
                              throws SAXException
Handle input elements that may have a "checked" attributes, i.e. checkbox and radio.

Throws:
SAXException

startNonCheckableElement

protected void startNonCheckableElement(String aName,
                                        String uri,
                                        String name,
                                        String raw,
                                        AttributesImpl attributes)
                                 throws SAXException
Handle input elements that may don't have a "checked" attributes, e.g. text, password, button.

Throws:
SAXException

startInputElement

protected void startInputElement(String uri,
                                 String name,
                                 String raw,
                                 Attributes attr)
                          throws SAXException
Handle input elements. Calls startCheckableElement or startNonCheckableElement.

Throws:
SAXException

startSelectElement

protected void startSelectElement(String uri,
                                  String name,
                                  String raw,
                                  Attributes attr)
                           throws SAXException
Handle select elements. Sets up some instance variables for following option elements.

Throws:
SAXException

startOptionElement

protected void startOptionElement(String uri,
                                  String name,
                                  String raw,
                                  Attributes attr)
                           throws SAXException
Handle option elements. Uses instance variables set up by startSelectElement. Relies on option having a "value" attribute, i.e. does not check following characters if "value" is not present.

Throws:
SAXException

startTextareaElement

protected void startTextareaElement(String uri,
                                    String name,
                                    String raw,
                                    Attributes attributes)
                             throws SAXException
Handles textarea elements. Skips nested events if request parameter with same name exists.

Throws:
SAXException

startErrorElement

protected void startErrorElement(String uri,
                                 String name,
                                 String raw,
                                 Attributes attr)
                          throws SAXException
Handle error elements. If validation results are available, compares validation result for parameter with the same name as the "name" attribute with the result names is "when" and "when-ge". Drops element and all nested events when error condition is not met.

Throws:
SAXException

startFormElement

protected void startFormElement(String uri,
                                String name,
                                String raw,
                                Attributes attr)
                         throws SAXException
Start processing a form element. Sets protection indicator if attribute "fixed" is present and either "true" or "yes". Removes attribute "fixed" if present.

Parameters:
uri - The namespace of the element.
name - The local name of the element.
raw - The qualified name of the element.
attr - The attributes of the element.
Throws:
SAXException

startRepeatElement

protected void startRepeatElement(String uri,
                                  String name,
                                  String raw,
                                  Attributes attr)
                           throws SAXException
Start recording repeat element contents and push repeat expression and variable to repeater stack. Only start recording, if no other recorder is currently running.

Parameters:
uri -
name -
raw -
attr -
Throws:
SAXException

endRepeatElement

protected void endRepeatElement(String uri,
                                String name,
                                String raw)
                         throws SAXException
Stop recording repeat contents and replay required number of times. Stop only if outmost repeat element is ending.

Parameters:
uri -
name -
raw -
Throws:
SAXException

startTransformingElement

public void startTransformingElement(String uri,
                                     String name,
                                     String raw,
                                     Attributes attr)
                              throws SAXException
Start processing elements of our namespace. This hook is invoked for each sax event with our namespace.

Parameters:
uri - The namespace of the element.
name - The local name of the element.
raw - The qualified name of the element.
attr - The attributes of the element.
Throws:
SAXException

endTransformingElement

public void endTransformingElement(String uri,
                                   String name,
                                   String raw)
                            throws SAXException
Start processing elements of our namespace. This hook is invoked for each sax event with our namespace.

Parameters:
uri - The namespace of the element.
name - The local name of the element.
raw - The qualified name of the element.
Throws:
SAXException

relayStartElement

protected void relayStartElement(String uri,
                                 String name,
                                 String raw,
                                 Attributes attr)
                          throws SAXException
Calls the super's method startTransformingElement.

Parameters:
uri -
name -
raw -
attr -
Throws:
SAXException

relayStartElement

protected void relayStartElement(boolean skip,
                                 boolean skipChildrenOnly,
                                 String uri,
                                 String name,
                                 String raw,
                                 Attributes attr)
                          throws SAXException
Calls the super's method startTransformingElement and increments the ignoreEventsCount if skip is true. Increment can be done either before invoking super's method, so that the element itself is skipped, or afterwards, so that only the children are skipped.

Parameters:
skip -
skipChildrenOnly -
uri -
name -
raw -
attr -
Throws:
SAXException

relayEndElement

protected void relayEndElement(String uri,
                               String name,
                               String raw)
                        throws SAXException
Calls the super's method endTransformingElement and decrements the ignoreEventsCount if larger than zero.

Parameters:
uri -
name -
raw -
Throws:
SAXException


Copyright 1999-2008 The Apache Software Foundation. All Rights Reserved.