haul 2002/12/04 01:51:09
Modified: src/documentation/xdocs/userdocs/concepts Tag:
cocoon_2_0_3_branch modules.xml
Log:
remove obsolete note
Revision Changes Path
No revision
No revision
1.1.2.5 +159 -131
xml-cocoon2/src/documentation/xdocs/userdocs/concepts/modules.xml
Index: modules.xml
===================================================================
RCS file:
/home/cvs/xml-cocoon2/src/documentation/xdocs/userdocs/concepts/modules.xml,v
retrieving revision 1.1.2.4
retrieving revision 1.1.2.5
diff -u -r1.1.2.4 -r1.1.2.5
--- modules.xml 18 Sep 2002 16:28:10 -0000 1.1.2.4
+++ modules.xml 4 Dec 2002 09:51:09 -0000 1.1.2.5
@@ -12,73 +12,73 @@
<body>
- <s1 title="Introduction">
- <p>
- Many sitemap components serve a purpose regardless how the input is
- obtained. Still, to provide a wide range of components to quickly get
- you up to speed, variants for different inputs exist. Modules allow to
- create generic components and plug-in input or output later.
- </p>
- <p>
- This document will explain how modules work and how to make use of
- them. If you plan on writing your own modules, it is highly recommended
- to read <fork
- href="http://jakarta.apache.org/avalon/developing/index.html";>
- Developing With Apache Avalon</fork>. It is a very good description
- of the underlying rationale and principles.
- </p>
- </s1>
- <s1 title="Types of Modules">
- <p>
- Currently, three different types of modules exist: Input modules
- provide means to enumerate parameters and to retrieve them, output
- modules allow storing of data and exhibit transaction like semantics,
- database modules encapsulate different mechanisms for auto increment
- columns of various database management systems. Please refer to the
- javadoc documentation of these interfaces.
- </p>
- <p>
- Input modules are modelled after request parameters. The main
- difference is, that every method takes two additional arguments, the
- request object and a configuration object. The configuration object is
- used to allow arbitrarily complex instructions for the input module.
- Apart from that, input modules are more or less a drop-in replacement.
- </p>
- <p>
- Output modules are again very similar to using request
- attributes. Basically, they provide a method to set an attribute to a
- value. Again, a request and a configuration object is the only change
- to request attributes. A fundamental difference is, however, that
- output modules should exhibit transactional behaviour. Thus setting an
- attributes implicitly starts a transaction that must be ended by
- calling rollback or commit. Only if the transaction is completed by
- calling commit, the values set should be visible. This is needed
- e.g. by the database actions.
- </p>
- <p>
- Database modules, actually named AutoIncrementModule, contains
- configuration information how to retrieve a value for an auto increment
- column. It is possible to obtain the value before inserting a row,
- while inserting as part of the SQL or after successful insert. If the
- value is obtained before inserting, it can be generated
- externally. Currently, supported database management systems include
- HSQL, Informix, MySQL, and querying the database for the current max
- value.
- </p>
- </s1>
- <s1 title="Using modules">
- <p>
- Using any of these modules requires a two step setup process. Step one
- has already been done for your for all modules that come with Apache
- Cocoon. Exception to this rule are the auto increment modules: only the
- HSQL module is already setup.
- </p>
- <s2 title="Step 1: Making a new module know to Apache Cocoon">
- <p>
- Like other core components of Apache Cocoon, modules are declared in
- <code>cocoon.xconf</code>. There are already too many to list here.
- </p>
- <source>
+ <s1 title="Introduction">
+ <p>
+ Many sitemap components serve a purpose regardless how the input is
+ obtained. Still, to provide a wide range of components to quickly get
+ you up to speed, variants for different inputs exist. Modules allow to
+ create generic components and plug-in input or output later.
+ </p>
+ <p>
+ This document will explain how modules work and how to make use of
+ them. If you plan on writing your own modules, it is highly recommended
+ to read <fork
+ href="http://jakarta.apache.org/avalon/developing/index.html";>
+ Developing With Apache Avalon</fork>. It is a very good description
+ of the underlying rationale and principles.
+ </p>
+ </s1>
+ <s1 title="Types of Modules">
+ <p>
+ Currently, three different types of modules exist: Input modules
+ provide means to enumerate parameters and to retrieve them, output
+ modules allow storing of data and exhibit transaction like semantics,
+ database modules encapsulate different mechanisms for auto increment
+ columns of various database management systems. Please refer to the
+ javadoc documentation of these interfaces.
+ </p>
+ <p>
+ Input modules are modelled after request parameters. The main
+ difference is, that every method takes two additional arguments, the
+ request object and a configuration object. The configuration object is
+ used to allow arbitrarily complex instructions for the input module.
+ Apart from that, input modules are more or less a drop-in replacement.
+ </p>
+ <p>
+ Output modules are again very similar to using request
+ attributes. Basically, they provide a method to set an attribute to a
+ value. Again, a request and a configuration object is the only change
+ to request attributes. A fundamental difference is, however, that
+ output modules should exhibit transactional behaviour. Thus setting an
+ attributes implicitly starts a transaction that must be ended by
+ calling rollback or commit. Only if the transaction is completed by
+ calling commit, the values set should be visible. This is needed
+ e.g. by the database actions.
+ </p>
+ <p>
+ Database modules, actually named AutoIncrementModule, contains
+ configuration information how to retrieve a value for an auto increment
+ column. It is possible to obtain the value before inserting a row,
+ while inserting as part of the SQL or after successful insert. If the
+ value is obtained before inserting, it can be generated
+ externally. Currently, supported database management systems include
+ HSQL, Informix, MySQL, and querying the database for the current max
+ value.
+ </p>
+ </s1>
+ <s1 title="Using modules">
+ <p>
+ Using any of these modules requires a two step setup process. Step one
+ has already been done for your for all modules that come with Apache
+ Cocoon. Exception to this rule are the auto increment modules: only the
+ HSQL module is already setup.
+ </p>
+ <s2 title="Step 1: Making a new module know to Apache Cocoon">
+ <p>
+ Like other core components of Apache Cocoon, modules are declared in
+ <code>cocoon.xconf</code>. There are already too many to list here.
+ </p>
+ <source>
<![CDATA[
<input-modules>
<component-instance name="request"
@@ -97,11 +97,11 @@
class="org.apache.cocoon.components.modules.input.DateInputModule"/>
<component-instance name="defaults"
class="org.apache.cocoon.components.modules.input.DefaultsMetaModule">
- <input-module name="request"/>
- <values>
- <skin>defaultSkin</skin>
- <base-url>http://localhost:8080/cocoon</base-url>
- </values>
+ <input-module name="request"/>
+ <values>
+ <skin>defaultSkin</skin>
+ <base-url>http://localhost:8080/cocoon</base-url>
+ </values>
</component-instance>
</input-modules>
@@ -125,62 +125,90 @@
-->
</autoincrement-modules>
]]>
- </source>
- <p>
- The above snippet declares a number of modules. After this, the
- modules are accessible through the given name. Thus, when an
- <code>input-module</code> is expected, it is sufficient to give the
- name of a module, like <code>header</code>.
- </p>
- <p>
- For the auto increment modules only one is declared as the name
- <code>"auto"</code> has special meaning to the modular database
- actions. If more than one is needed at the same time, the
- configuration of the database actions needs to explicitly specify
- which one to use.
- </p>
- </s2>
- <s2 title="Step 2: Use it">
- <p>
- Two alternatives for using modules exist:
- </p>
- <s3 title="Step 2a: Use it as sitemap variable">
- <p>
- Input modules can be used in a sitemap almost like a sitemap
- variable. If the variable name contains a colon (":"), the
- preceeding string is used as the name of the module to use and
the
- trailing string is passed to the module. The expression is
replaced
- with the string value returned from the module.
- </p>
- <source>
+ </source>
+ <p>
+ The above snippet declares a number of modules. After this, the
+ modules are accessible through the given name. Thus, when an
+ <code>input-module</code> is expected, it is sufficient to give the
+ name of a module, like <code>header</code>.
+ </p>
+ <p>
+ For the auto increment modules only one is declared as the name
+ <code>"auto"</code> has special meaning to the modular database
+ actions. If more than one is needed at the same time, the
+ configuration of the database actions needs to explicitly specify
+ which one to use.
+ </p>
+ </s2>
+ <s2 title="Step 2: Use it">
+ <p>
+ The following alternatives for using modules exist:
+ </p>
+ <s3 title="Step 2a: Use it as sitemap variable">
+ <p>
+ Input modules can be used in a sitemap almost like a sitemap
+ variable. If the variable name contains a colon (":"), the
+ preceeding string is used as the name of the module to use and the
+ trailing string is passed to the module. The expression is replaced
+ with the string value returned from the module.
+ </p>
+ <source>
<![CDATA[
<map:transform src="resources/stylesheets/{../skin}.xsl"/>
]]>
- </source>
- <p>
- The above example uses the variable <code>skin</code> declared
- e.g. by an action for the stylesheet to apply to the page. The
- example below uses an input module instead. The way this
module was
- declared above allows to override the skin with a request
parameter
- named "skin".
- </p>
- <note>
- The above sitemap syntax is only available with the 2.1-dev
version
- of Apache Cocoon.
- </note>
- <source>
+ </source>
+ <p>
+ The above example uses the variable <code>skin</code> declared
+ e.g. by an action for the stylesheet to apply to the page. The
+ example below uses an input module instead. The way this module was
+ declared above allows to override the skin with a request parameter
+ named "skin".
+ </p>
+ <source>
<![CDATA[
<map:transform src="resources/stylesheets/{default:skin}.xsl"/>
]]>
- </source>
- </s3>
- <s3 title="Step 2b: Have sitemap components use a module">
- <p>
- This depends on the component that is to be used. As an
example the
- <code>CachingWildcardMatcher</code> requires to set the
- <code>input-module</code> on declaration.
- </p>
- <source>
+ </source>
+ </s3>
+ <s3 title="Step 2b: Use it on an XSP">
+ <p>
+ The input logicsheet allows easy use of InputModules from an
+ XSP. Currently, it provides tags for getting one value, an
+ array of values, and an Iterator for a Collection of
+ parameter names.
+ </p>
+ <source>
+<![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<xsp:page language="java"
+ xmlns:xsp="http://apache.org/xsp";
+ xmlns:input="http://apache.org/cocoon/xsp/input/1.0";>
+
+<page>
+
+ <title>Testing InputModules</title>
+
+ <p>
+ Parameter name=<input:get-parameter module="request-param"
+ as="string" name="module" default="John Doe"/>;
+ </p>
+ <p>
+ Parameter cars=<input:get-parameter-values module="request-param"
+ as="xml" name="car"/>;
+ </p>
+ </page>
+</xsp:page>
+]]>
+ </source>
+ </s3>
+ <s3 title="Step 2c: Have sitemap components use a module">
+ <p>
+ This depends on the component that is to be used. As an example the
+ <code>CachingWildcardMatcher</code> requires to set the
+ <code>input-module</code> on declaration.
+ </p>
+ <source>
<![CDATA[
<map:matchers default="wildcard">
<map:matcher name="cached-uri"
@@ -189,15 +217,15 @@
</map:matcher>
</map:matchers>
]]>
- </source>
- <p>
- By replacing the input module name with any of the other
declared
- input modules, this matcher can be used to match e.g. on
session
- attributes, request headers or even dates!
- </p>
- </s3>
- </s2>
- </s1>
+ </source>
+ <p>
+ By replacing the input module name with any of the other declared
+ input modules, this matcher can be used to match e.g. on session
+ attributes, request headers or even dates!
+ </p>
+ </s3>
+ </s2>
+ </s1>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
