shannon 2002/07/15 07:01:31 Added: targets/cocoon/userdocs/concepts xmlform.html targets/cocoon/userdocs/generators linkstatus-generator.html targets/cocoon/userdocs/selectors parameter-selector.html targets/cocoon/userdocs/transformers encodeurl-transformer.html sourcewriting-transformer.html Log: release 2.0.3 update Revision Changes Path 1.1 xml-site/targets/cocoon/userdocs/concepts/xmlform.html Index: xmlform.html =================================================================== XMLForm Handling
XMLForm Handling
http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Main
User Documentation

Concepts
Overview
Sitemap
Views
Caching
Actions
Matchers and Selectors
Entity Catalogs
MRUMemoryStore
Persistence
StoreJanitor
XMLSearching
XMLForm
Databases
Modules

Notice

This document is based on components included in the current Cocoon 2.1 distribution. If you do not have this version, you can obtain it from the Apache Cocoon web site. Be sure to look at the WARNING document that accompanies such pre-release versions.

Introduction

The XMLForm framework is inspired by Apache Jakarta Struts and W3C XForms.

Its goal is to:

  • Ease the development of sophisticated web applications utilizing complex data types and multi-page transactions
  • Provide an automated 2 way mapping between HTML Forms <-> XML <-> JavaBeans
  • Use standard XML schema languages like XML Schema, Relax-NG, Schematron for data validation
  • Promote complete reuse of Cocoon Actions for:
    • UI centric web applications - HTML, WML, UXL, VoiceML, etc.
    • Web Services (based on the REST paradigm)
    • Remote Portal Forms. (An interactive extension of static content formats like Netscape RSS)
  • Utilize XPath tools like Apache Jakarta Commons JXPath for read/write access to JavaBeans, DOM nodes and mixed objects.
  • Utilize the existing Cocoon XML functional testing framework - AntEater.

The current implementation offers the following features:

  1. Automated 2 way binding of HTML Forms to JavaBeans (and DOM nodes) through XPath
  2. Automatic validation of JavaBeans(and DOM nodes) through Schematron schemas
  3. Intermediate XForms like XML markup for form views
Background

The aim of XMLForm, is to build and edit an xml document (called the instance), subject to constraints from some schema (XMLSchema, Schematron, ...), through a sequence of form pages. The instance is either a dom-document or a Java bean-structure or a mix. XMLForm consist, of three main components:

  • Form - is responsible for the instance and validation of it. Form objects are stored in request attributes for one page forms and session attributes for wizards (multi page forms). A Form can be populated from the request parameters. This is the "model in MVC terms.
  • XMLFormTransformer - takes a form descriptor, (similar to XForms) as input and fill it with data and error messages from a Form object that is referred in an attribute. This is the "view" in MVC terms.
  • AbstractXMLFormAction, (WizardAction) - creates the Form object if necessary and populates it with data based on the request parameters. It can also take care of flow handling and checkbox state. This is the "controller" in MVC terms.
Demonstration

In version 2.1, see XMLForm in action with the by selecting: http://localhost:8080/cocoon/samples/xmlform/".

Further information

See the Cocoon XMLForm How-To

Please discuss Cocoon XMLForm on the mailing lists

Copyright © 1999-2002 The Apache Software Foundation. All Rights Reserved.
1.1 xml-site/targets/cocoon/userdocs/generators/linkstatus-generator.html Index: linkstatus-generator.html =================================================================== LinkStatus Generator
LinkStatus Generator
http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Main
User Documentation

Generators
Overview

Default
File Generator

Core
HTML Generator
Directory Generator
Image Directory Generator
Fragment Extractor Generator
JSP Generator
Script Generator
Server Pages Generator
Velocity Generator
Request Generator
Status Generator
Stream Generator
Profile Generator
Error Generator
Search Generator
LinkStatus Generator

Optional
Php Generator
XML:DB Generator
XML:DB Collection Generator

LinkStatus Generator

The LinkStatus Generator emits a list of links that are reachable. Please note that it is available only in Cocoon 2.1.

The LinkStatusGenerator has serveral configuration options.

include-name -
RE pattern for including links
By default include-name is empty.
exclude-name -
RE pattern for excluding links.
By default exclude-name is defined as .*\.gif(\?.*)?$, .*\.png(\?.*)?$, .*\.jpe?g(\?.*)?$, .*\.js(\?.*)?$, .*\.css(\?.*)?$ .
link-content-type -
expected MIME type of xml document requested on view link-query-view
By default link-content-type is set to application/x-cocoon-links.
link-view-query -
A query-string appended to the crawling URL
By default link-view-query is set to cocoon-view=links.
user-agent -
HTTP user-agent for requesting links, By default user-agent is set to value of org.apache.cocoon.Constants.COMPLETE_NAME, ie. Apache Cocoon 2.1-dev
accept -
Not currently used
  • Name : linkStatus
  • Class: org.apache.cocoon.generation.LinkStatusGenerator
  • Cacheable: no.

A simple example might help to use the LinkStatusGenerator effectivly:

Add the LinkStatusGenerator to the components in your sitemap.xmap

  ...
  <map:components>
  ...
    <map:generators default="file">
    ...
      <map:generator name="linkStatus"
        src="org.apache.cocoon.generation.LinkStatusGenerator"/>
    </map:generators>
    <map:serialize default="html">
      <map:serializer name="links"
        src="org.apache.cocoon.serialization.LinkSerializer"/>
    </map:serialize>
  </map:components>
  <map:views>
    <map:view>
      <map:view from-position="last" name="links">
        <map:serialize type="links"/>
      </map:view>
      ...
  </map:view>
  

Next define in your pipeline to use the LinkStatusGenerator

  <map:match pattern="/linkStatus">
    <map:generate type="linkStatus" name="my-root"/>
    ...
    <map:serialize/>
  </map:match>
  
Copyright © 1999-2002 The Apache Software Foundation. All Rights Reserved.
1.1 xml-site/targets/cocoon/userdocs/selectors/parameter-selector.html Index: parameter-selector.html =================================================================== Parameter Selector
Parameter Selector
http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Main
User Documentation

Selectors
Overview

Default

Core
Parameter

Optional

Parameter Selector
  • Name : ParameterSelector
  • Class: org.apache.cocoon.selection.ParameterSelector
  • Cacheable: not applicable

This Selector matches a string, in the Parameters object passed to the selector, against a specified Cocoon internal parameter. It performs a case-sensitive string comparison between the value of the 'parameter-selector-test' parameter and the value of the 'test' attribute of the <map:when ...> element.

This internal parameter could be:

  • A sitemap parameter from the <map:match ...> portion of the pipeline
  • A sitemap parameter set by an action
Reasons to use ParameterSelector

One purpose of this selector is to choose between different components of a pipeline based on sitemap parameters set by an action. This would allow the action to control the logic required to set one or more parameters, which can then be used by this selector to control pipeline processing. Thus, complex decision-making logic can be contained in actions, while the sitemap simply uses the results of the actions (the parameters) to determine pipeline processing.

Parameter Selector can also be used to select on the value of 'keys' (such as {1} or {../2} ) from the wildcard matcher. Information in the URI, such as part of a filename, can then be used to determine pipeline processing.

Examples

Add the component to your sitemap.xmap:

     <map:components>
      ...
      <map:selectors>
       ...
       <map:selector
  	    name="parameter"
        	logger="sitemap.selector.parameter"
        	src="org.apache.cocoon.selection.ParameterSelector"/>
       ...

Use a parameter set by an action:

Assume there is an action (named MyAction) that sets a parameter (named MyRegion) to several possible values. For more information on actions, including a simple example of an action that creates a sitemap parameter, see Creating and Using Actions.

     <map:match pattern="*.xml">
      <map:act type="MyAction">
        <map:generate src="{../1}.xml"/>
  
        <map:select type="parameter">
          <map:parameter name="parameter-selector-test" value="{MyRegion}"/>
        
          <!-- executes iff the value of MyRegion equals 
               "United States" (without quotes) -->
          <map:when test="United States">
            <map:transform src="stylesheets/us.xsl"/>
          </map:when>
        
          <map:when test="South_America">
            <map:transform src="stylesheets/southamerica.xsl"/>
          </map:when>
  
          <map:when test="Europe">
            <map:transform src="stylesheets/europe.xsl"/>
          </map:when>
  
          <map:otherwise>
            <map:transform src="all_others.xsl"
          </map:otherwise>
  
        </map:select>
      </map:act>
      <map:serialize/>
    </map:match>

Use values from the URI:

     <map:pipeline>
       <!-- {1}/{2}/myfile.xml -->
       <map:match pattern="**/*/myfile.xml"> 
     
         <!-- Use ParameterSelector -->
         <map:select type="parameter">
          <map:parameter name="parameter-selector-test" value="{2}"/>
  
          <!-- executes iff the value of {2} equals 
               "basic" (without quotes); the requested URI
                could be **/basic/myfile.xml -->
          <map:when test="basic">
              <map:generate src="{1}/myfile.xml"/>
              <map:transform src="stylesheets/basic.xsl">
                  <map:parameter name="use-request-parameters" value="true"/>
                  <map:parameter name="resource" value="{2}.html"/>
              </map:transform>
              <map:serialize/>
          </map:when>
  
          <map:when test="aggregate">
              <map:aggregate element="site">
          	<map:part src="cocoon:/{1}/sidebar-{1}/{2}.xml"/>
          	<map:part src="cocoon:/body-{1}/{2}.xsp"/>
              </map:aggregate>
              <map:transform src="stylesheets/aggregate2xhtml.xsl"/>
              <map:serialize/>
          </map:when>
  
          <map:otherwise>
              <map:redirect-to uri="other_URI"/>
          </map:otherwise>
  
        </map:select>
      </map:match> 
      ...
Copyright © 1999-2002 The Apache Software Foundation. All Rights Reserved.
1.1 xml-site/targets/cocoon/userdocs/transformers/encodeurl-transformer.html Index: encodeurl-transformer.html =================================================================== EncodeURL Transformer
EncodeURL Transformer
http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Main
User Documentation

Transformers
Overview

Default
XSLT Transformer

Core
Fragment Extractor Transformer
I18n Transformer
Log Transformer
SQL Transformer
Filter Transformer
Read DOM Session Transformer
Write DOM Session Transformer
XInclude Transformer
CInclude Transformer
EncodeURL Transformer
SourceWriting Transformer

Optional
XT Transformer
LDAP Transformer

EncodeURL Transformer

The encodeURL transformer emits encoded URLs. This transformer applies encodeURL method to URLs. You may want to use this transform to avoid doing the manually encodeURL() call.

Usually this transformer is appended as last transformer before the serialization process. In this case it is possible to encode URLs introduced in the generator, and xslt transformer phase.

You can specify which attributes hold URL values in order to restrict URL rewriting to specific attributes only. In the current implementation you specify include, and exclude patterns as regular expressions, concatting element-name + "/@" + attribute-name.

The EncodeURLTransformer has serveral configuration options. These options may be specified in the sitemap, or by each request.

include-name -
RE pattern for including attributes from encode URL rewriting, The attribute values are encoded, if an expressions of the form element-name/@attribute-name matches.
By default include-name is defined as .*/@href|.*/@action|frame/@src.
exclude-name -
RE pattern for excluding attributes from encode URL rewriting, The attribute values are not encoded, if an expressions of the form element-name/@attribute-name matches.
By default exclude-name is defined as img/@src.
  • Name : encodeURL
  • Class: org.apache.cocoon.transformation.EncodeURLTransformer
  • Cacheable: yes.

A simple example might help to use the EncodeURLTransformer effectivly:

Add the EncodeURLTransformer to the components in your sitemap.xmap

  ...
  <map:components>
  ...
    <map:transformers default="xslt">
    ...
      <map:transformer name="encodeURL"
        src="org.apache.cocoon.transformation.EncodeURLTransformer">
        <!-- default configuration, explicitly defined -->
        <include-name>.*/@href|.*/@action|frame/@src</include-name>
        <exclude-name>img/@src</exclude-name>
      </map:transformer>
    ...
  

Next define in your pipeline to use the EncodeURLTransformer

  <map:match pattern="*.xsp">
    <map:generate type="serverpages" name="docs/samples/xsp/{1}.xsp"/>
    <map:transform src="stylesheets/page/simple-page2html.xsl"/>
    
    <map:transform type="encodeURL"/>
    <map:serialize/>
  </map:match>
  

In this example pipeline it is assumed that the attribute href of element a contains an URL which should get encoded. Moreover the attribute action of any element contains an URL which should get encoded, too. Finally the attribute src of element frame should get encoded, too.

The attribute src of element img is excluded from encoding.

In other words, images are served regardless of the current session, in contrast anchor links, form actions, and frame src are served depending on the current session.

The encoding itself applies the servlet method response.encodeURL() upon the URL.

Copyright © 1999-2002 The Apache Software Foundation. All Rights Reserved.
1.1 xml-site/targets/cocoon/userdocs/transformers/sourcewriting-transformer.html Index: sourcewriting-transformer.html =================================================================== Source Writing Transformer
Source Writing Transformer
http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Main
User Documentation

Transformers
Overview

Default
XSLT Transformer

Core
Fragment Extractor Transformer
I18n Transformer
Log Transformer
SQL Transformer
Filter Transformer
Read DOM Session Transformer
Write DOM Session Transformer
XInclude Transformer
CInclude Transformer
EncodeURL Transformer
SourceWriting Transformer

Optional
XT Transformer
LDAP Transformer

Source Writing Transformer

Diverts xml from a pipeline, writing it to a Source.

Thankfully, FileSource is no longer the only Source that currently implements WritableSource; there are implementations of WebDAV and Apache Slide WritableSources in the scratchpad. Hopefully further WriteableSource implementations (XMLDB, CVS, Email, SQL, etc.) will be appear in the future.

  • Name : write-source
  • Class: org.apache.cocoon.transformation.SourceWritingTransformer
  • Cacheable: no.

If you have built Cocoon with the ScratchPad included (using: ./build.sh -Dinclude.webapp.libs=yes -Dinclude.scratchpad.libs=yes webapp), there is a set of samples set up, including tests at http://localhost:8080/cocoon/mount/editor/tests and a demonstration editor at http://localhost:8080/cocoon/mount/editor/edit/

NotePlease beware of putting these samples on a public-facing server.

The Tags

  					
  		<source:write>
  			[<source:path/>]
  			<source:source/>
  			<source:fragment/>
  		</source:write>
  		
  		<source:insert/>
  			<source:path/>
  			<source:source/>
  			<source:fragment/>
  			[<source:replace/>]
  			[<source:reinsert/>]
  		</source:insert>
  					
  				

In the namespace xmlns:source="http://apache.org/cocoon/source/1.0".

The contents of the <source:fragment/> tag are written to the specified WriteableSource when the document containing it is transformed by SourceWritingTransformer.

Definition

  					
   <map:transformer name="write-source" 
      src="org.apache.cocoon.transformation.SourceWritingTransformer">
  		<map:parameter name="serializer" value="xml"/>  
   </map:transformer/>
  					
  				

The SourceWritingTransformer is predefined for you in the main SiteMap.

Invocation

This invokes the SourceWritingTransformer on your pipeline.

  					
   <map:transform type="write-source"/>
  					
  				

Or you can over-ride the default serializer here.

  					
   <map:transform type="write-source">
     <map:parameter name="serializer" value="my-special-serializer"/>   
   </map:transform>
  					
  				

The Tags in detail
source:write

The source:write tag can take optional attributes, create (defaults to 'true') and serializer (defaults to the serializer set up in the definition or invocation of the transformer).

Replaces the entire content of a Source (specified by the <source:source/> tag) with the contents of the <source:fragment/> tag, if @create is 'true', a new asset will be created if one does not already exist.

The <source:source/> and <source:fragment/> tags are required, a <source:path/> tag is optional, if specified, the value is an used as an XPath to generate xml in your Source, inwhich to wrap your content.

source:source

The System ID of the Source to be written to.

eg: <source:source>docs/blah.xml</source:source> or <source:source>context:/blah.xml</source:source> etc.

source:fragment

The XML Fragment to be written.

eg:

  							
  	<source:fragment><foo>
  			<bar id="dogcow"/>
  		</foo></source:fragment>
  							
  						
or
  							
  	<source:fragment>
  		<foo/>
  		<bar>
  			<dogcow/>
  		<bar/>
  	</source:fragment>
  							
  						
etc.

NoteThe second example type, can only be used when the <source:path/> tag has been specified.

source:path

[Optional] XPath to specify how your content is wrapped

eg: <source:path>doc</source:path> - your content is placed inside a <doc/> root tag.

NoteIf this parameter is omitted, your content MUST have only ONE top-level node.

source:insert

The source:insert tag can take optional attributes, create (defaults to 'true') and serializer (defaults to the serializer set up in the definition or invocation of the transformer).

Inserts into a Source (specified by the <source:source/> tag) the contents of the tag <source:fragment/> at the XPath location specified in the <source:path/> tag, if @create is 'true', a new Source will be created if one does not already exist.

The <source:source/>, <source:path/> and <source:fragment/> tags are all required, the <source:replace/> and <source:reinsert/> tags are optional.

source:source

The System ID of the Source to be inserted into.

eg: <source:source>docs/blah.xml</source:source> or <source:source>context:/blah.xml</source:source> etc.

source:fragment

The XML Fragment to be written.

eg:

  							
  	<source:fragment>
  		<foo>
  			<bar id="dogcow"/>
  		</foo>
  	</source:fragment>
  							
  						
or
  							
  	<source:fragment>
  		<foo/>
  		<bar>
  			<dogcow/>
  		<bar/>
  	</source:fragment>
  							
  						
etc.

source:path

source:replace

[Optional] XPath (from <source:path/>) to select the node that is replaced by your new content

eg: <source:replace>foo/bar/dogcow/@status='cut'</source:replace> (is equivalent to this in XSLT: select="foo[bar/dogcow/@status='cut']"), what gets replaced is the <foo/> which has a <bar/> with a <dogcow status="cut"/> in it.

The overwrite attribute of the parent <source:insert/> is used to check if replacing is allowed. If overwrite is 'true' (the default) the node is replaced. If overwrite is 'false' the node is only inserted if the replace node is found.

source:reinsert

[Optional] The XPath (relative to <source:replace/>) to backup the contents of the overwritten node to.

eg: <source:reinsert>foo/versions</source:reinsert> or <source:reinsert>/doc/versions/foo</source:reinsert>.

If specified and a node is replaced, all children of this replaced node will be reinserted at the given path.

Notes

  • if 'replace' is not specified, your 'fragment' is appended as a child of 'path'.
  • if 'replace' is specified and it exists and 'overwrite' is true, your 'fragment' is inserted in 'path', before 'replace' and then 'replace' is deleted.
  • if 'replace' is specified and it exists and 'overwrite' is false, no action occurs.
  • if 'replace' is specified and it does not exist and 'overwrite' is true, your 'fragment' is appended as a child of 'path'.
  • if 'replace' is specified and it does not exist and 'overwrite' is false, your 'fragment' is appended as a child of 'path'.
  • if 'reinsert' is specified and it does not exist, no action occurs.

Examples
Simple Write

  						
   <page>
     ...
     <source:write xmlns:source="http://apache.org/cocoon/source/1.0">
       <source:source>context://doc/editable/my.xml</source:source>      
       <source:fragment><page>
         <title>Hello World</title>
         <content>
           <p>This is my first paragraph.</p>
         </content>
       </page></source:fragment>
     </source:write>
     ...
   </page>
  						
  					

Insert at end

  						
   <page>
     ...
     <source:insert xmlns:source="http://apache.org/cocoon/source/1.0">
       <source:source>context://doc/editable/my.xml</source:source>      
       <source:path>page/content</source:path>      
       <source:fragment>
         <p>This paragraph gets <emp>inserted</emp>.</p>
         <p>With this one, at the end of the content.</p>
       </source:fragment>
     </source:insert>
     ...
   </page>
  						
  					

Replace

  						
   <page>
     ...
     <source:insert xmlns:source="http://apache.org/cocoon/source/1.0">
       <source:source>context://doc/editable/my.xml"</source:source>      
       <source:path>page/content</source:path>      
       <source:replace>p[1]</source:replace>      
       <source:fragment>
         <p>This paragraph <emp>replaces</emp> the first paragraph.</p>
       </source:fragment>
     </source:insert>
     ...
   </page>
  						
  					

Insert at the beginning

  						
   <page>
     ...
     <source:insert>
       <source:source>context://doc/editable/my.xml</source:source>
       <source:path>page</source:path>
       <source:replace>content</source:replace>
       <source:reinsert>content</source:reinsert>
       <source:fragment>
         <content>
           <p>This new paragraph gets inserted <emp>before</emp> the other ones.</p>
         </content>
       </source:fragment>
      <source:insert>
     ...
   </page>
  						
  					

This sample does not currently work, see the tests in the scratchpad at http://localhost:8080/cocoon/mount/editor/tests.

NoteYou must have built Cocoon with the scratchpad included for this link to work.

Sample of the output of these tags

This is the kind of information that the SourceWritingTransformer outputs to the pipeline, replacing the original source:write and source:insert tags

  						
   <page>
     ...
     <sourceResult>
       <action>new|overwritten|none</action>
       <behaviour>write|insert<behaviour>
       <execution>success|failure</execution>
       <serializer>xml</serializer>
       <source>source:specific/path/to/context/doc/editable/my.xml</source>
       <message>a message about what happened</message>
     </sourceResult>
     ...
   </page>
  						
  					

Known Problems

Namespace handling: namespace declarations are not copied to the Source, resulting in invalid XML.

I cannot get the 'insert before' example working, which uses the <source:reinsert/> tag.

Warning

It is not known how robust this transformer is under even moderate load, especially when it comes to more than one person modifying the same file at the same time.

Copyright © 1999-2002 The Apache Software Foundation. All Rights Reserved.
--------------------------------------------------------------------- To unsubscribe, e-mail: general-cvs-unsubscribe@xml.apache.org For additional commands, e-mail: general-cvs-help@xml.apache.org