cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From je...@apache.org
Subject cvs commit: cocoon-2.1/src/java/org/apache/cocoon/components/modules/input package.html
Date Sat, 03 May 2003 16:01:45 GMT
jefft       2003/05/03 09:01:44

  Modified:    src/java/org/apache/cocoon/components/modules/input
                        package.html
  Log:
  Improve package.html description of input modules.
  
  Revision  Changes    Path
  1.2       +141 -6    cocoon-2.1/src/java/org/apache/cocoon/components/modules/input/package.html
  
  Index: package.html
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/java/org/apache/cocoon/components/modules/input/package.html,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- package.html	9 Mar 2003 00:09:04 -0000	1.1
  +++ package.html	3 May 2003 16:01:44 -0000	1.2
  @@ -8,12 +8,147 @@
   </head>
   <body>
      
  -<h1>input<br>
  -</h1>
  -   
  -<p>Input modules provide a simple interface to obtain values largely based
  -on the methods provided by request and session to get values and names of
  -attributes.</p>
  +<h1>InputModules</h1>
  +
  +<h2>Introduction</h2>
  +<p>
  +Input modules are generic components that let one map a key to one or more
  +values.  In concept and API, input modules are closest to the <a
  +    href="http://java.sun.com/j2se/1.4/docs/api/java/util/Properties.html">java.util.Properties</a>
  +class. An input module has a number of named attributes, each of which has an
  +associated value or values, which will be computed or looked up when requested.
  +</p>
  +<pre>
  +    |       InputModule          |
  +    |----------------------------|
  +    | PropName   | PropValue(s)  |
  +    |----------------------------|
  +    | prop1      | value1        |
  +    | prop2      | value2        |
  +    | ...        | ...           |
  +    | propn      | valuen        |
  +    +----------------------------+
  +</pre>
  +<p>Three operations are defined by the <a
  +    href="InputModule.html">InputModule</a> interface:</p>
  +<dl>
  +    <dt>getAttributeNames</dt>
  +    <dd>Retrieve a list of all available attributes (the set <i>prop1, prop2,
..., propn</i>).</dd>
  +    <dt>getAttribute</dt>
  +    <dd>
  +    Retrieve the value of an attribute.  For instance,
  +    <code>getAttribute(<i>prop1</i>)</code> would return <i>value1</i>
  +    </dd>
  +    <dt>GetAttributeValues</dt>
  +    <dd>Retrieve an Iterator for a list of values for an attribute.</dd>
  +</dl>
  +
  +<h2>Usage</h2>
  +<p>
  +Input modules are used in various places in Cocoon, notably from within the
  +sitemap, XSPs, and matchers.</p>
  +<p>
  +In the sitemap, input modules are made available
  +through a {modulename:attributename} syntax.  For instance, if a <a
  +    href="RequestParameterModule.html">RequestParameterModule</a> named
  +<code>request-param</code> is defined in cocoon.xconf, then
  +<code>{request-param:user}</code> will in effect be replaced by the value of
  +the <code>user</code> request parameter (e.g. index.html?user=joe).  Similarly,
  +a <a href="SystemPropertyModule.html">SystemPropertyModule</a> named
  +<code>system-property</code> would allow
  +<code>{system-property:user.home}</code> to represent user's home directory
  +path.
  +</p>
  +
  +<h2>Configuration</h2>
  +<p>
  +Input modules are declared in cocoon.xconf.  There is a section dedicated to
  +input modules:</p>
  +<pre>
  +  &lt;input-modules>
  +    &lt;component-instance name="global"
  +             class="org.apache.cocoon.components.modules.input.GlobalInputModule"
  +             logger="core.modules.input"/>
  +    &lt;component-instance name="request"
  +             class="org.apache.cocoon.components.modules.input.RequestModule"
  +             logger="core.modules.input"/>
  +    &lt;component-instance name="session"
  +             class="org.apache.cocoon.components.modules.input.SessionModule"
  +             logger="core.modules.input"/>
  +    &lt;component-instance name="request-param"
  +             class="org.apache.cocoon.components.modules.input.RequestParameterModule"
  +             logger="core.modules.input"/>
  +    ...
  +    &lt;component-instance name="defaults"
  +             class="org.apache.cocoon.components.modules.input.DefaultsModule"
  +             logger="core.modules.input">
  +      &lt;values>
  +        &lt;skin>defaultSkin&lt;/skin>
  +        &lt;base-url>http://localhost:8080/cocoon&lt;/base-url>
  +      &lt;/values>
  +    &lt;/component-instance>
  +  &lt;input-modules>
  +</pre>
  +<h3>Static/dynamic configuration</h3>
  +<p>
  +In cocoon.xconf, each input module can take a <em>static</em> configuration.
  +This is made available to the class via the <code>configure()</code> method,
  +called once on startup.  In the example above, an Avalon
  +<code>Configuration</code> object representing the &lt;values> node
will be
  +passed to the DefaultsModule.
  +</p>
  +<p>
  +In addition, every time an input module is used, a <em>dynamic</em>
  +configuration is passed to it, as well as the current "object model".  You can
  +see these in the <a href="InputModule.html">InputModule</a> interface
  +definition for all three methods.  This dynamic, per-request configuration will
  +usually <strong>override</strong> the static configuration.  This dual
  +static/dynamic configuration makes input modules useful in a wide variety of
  +circumstances.
  +</p>
     
  +
  +<h2>Meta Modules</h2>
  +<p>
  +So-called "meta" modules are modules that act on other modules. The simplest
  +example of a meta module is the <a
  +href="SimpleMappingMetaModule.html">SimpleMappingMetaModule</a>, which will
  +query another module with a modified version of an attribute name.  For
  +instance, if configured with:</p>
  +<pre>
  +&lt;component-instance name="mappingmodule"
  +    class="org.apache.cocoon.components.modules.input.SimpleMappingMetaModule"
  +    logger="core.modules.mapper">
  +  &lt;input-module name="xmlmodule"/>
  +  &lt;prefix>/site/&lt;/prefix>
  +  &lt;suffix>/@href&lt;/suffix>
  +&lt;/component-instance>
  +</pre>
  +<p>
  +Then a key <code>foo</code> will cause <code>xmlmodule</code> to
be queried for
  +attribute <code>/site/foo/@href</code>, and that value will be returned.</p>
  +<p>
  +Another useful example is <a href="ChainMetaModule.html">ChainMetaModule</a>,
  +which will query a set of input modules until one returns a non-null value for
  +an attribute, providing "fall-back" behaviour.
  +</p>
  +<p>
  +The machinery for meta modules is provided in <a
  +href="AbstractMetaModule.html">AbstractMetaModule</a>.
  +
  +<h2>JXPath use in Input Modules</h2>
  +<p>Many input modules make use of the <a
  +href="http://jakarta.apache.org/commons/jxpath/">JXPath</a> library, which lets
  +one traverse Java object structures with an XPath-like syntax.  Support for
  +this is mostly located in the <a
  +href="JXPathMetaModule.html">JXPathMetaModule</a> and <a
  +href="AbstractJXPathModule.html">AbstractJXPathModule</a> superclasses, which
  +should be kept synchronised.
  +</p>
  +
  +<h2>Further Information</h2>
  +<p>The best way to learn what can be done with input modules is by examining
  +the samples that come with the Cocoon application.  The main Cocoon
  +documentation and Cocoon Wiki should have further information.
   </body>
   </html>
  
  
  

Mime
View raw message