org.apache.cocoon.transformation
Class SimpleFormTransformer

java.lang.Object
  org.apache.cocoon.util.AbstractLogEnabled
      org.apache.cocoon.xml.AbstractXMLProducer
          org.apache.cocoon.xml.AbstractXMLPipe
              org.apache.cocoon.transformation.AbstractTransformer
                  org.apache.cocoon.transformation.AbstractSAXTransformer
                      org.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