You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by da...@cocoon.zones.apache.org on 2005/10/05 15:11:34 UTC
[DAISY] Updated: Input Modules Reference
A document has been updated:
http://cocoon.zones.apache.org/daisy/legacydocs/727.html
Document ID: 727
Branch: main
Language: default
Name: Input Modules Reference (unchanged)
Document Type: Document (unchanged)
Updated on: 10/5/05 1:11:31 PM
Updated by: Patrick Ahles
A new version has been created, state: draft
Parts
=====
Content
-------
This part has been updated.
Mime type: text/xml (unchanged)
File name: (unchanged)
Size: 27012 bytes (previous version: 7971 bytes)
Content diff:
(49 equal lines skipped)
"meta" InputModules i.e. InputModules that are composed of other InputModules.
In order to get at the Logger, use getLogger().</p>
+++ <h2>BaseLinkModule</h2>
+++
+++ <p>BaseLinkModule returns a relative link (../, ../../ etc) to the base of the
+++ current request or sitemap URI. For instance, if called within a <map:match
+++ pattern="a/b/c.xsp"> pipeline, {baselink:SitemapBaseLink} would evaluate to
+++ ../../.</p>
+++
+++ <h2>ChainMetaModule</h2>
+++
+++ <p>This modules allows to "chain" several other modules. If a module returns
+++ "null" as attribute value, the next module in the chain is queried until either
+++ a value can be obtained or the end of the chain is reached.</p>
+++
+++ <p>A typical example would be to "chain" request parameters, session attributes,
+++ and constants in this order. This way, an application could have a default skin
+++ that could be overridden by a user in her/his profile stored in the session. In
+++ addition, the user could request a different skin through passing a request
+++ parameter.</p>
+++
+++ <p><strong><strong>Usage</strong>:</strong></p>
+++
+++ <p>Any number of <input-module/> blocks may appear in the component
+++ configuration. The @name attribute is used as the name of the requested input
+++ module. The complete <input-module/> block is passed at run-time to the
+++ module and thus can contain any configuration data for that particular module.
+++ </p>
+++
+++ <p><strong>Configuration:</strong></p>
+++
+++ <p>It can be controlled whether it returns a flat or a deep view, i.e. whether
+++ only values from the first module are returned if non-null or they are merged
+++ with values from other modules <all-values>true</all-values>. The
+++ same is possible for the attribute names (<all-names/>). In addition,
+++ empty strings could be treated the same as null values (<empty-as-null/>).
+++ </p>
+++
+++ <h2>ContextPathModule</h2>
+++
+++ <p>ContextRealPathModule provides a real filesystem path for a virtual
+++ context-relative path. If this mapping cannot be performed (e.g. Cocoon is
+++ running in a .war file), null will be returned. Compared to the
+++ <a href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/components/modules/input/RealPathModule.html">RealPathModule</a>
+++ this module is able to provide the "real" absolute path even if the application
+++ is mounted outside the webapp tree of Cocoon.</p>
+++
+++ <p>Note: the primary use for this is to support external code that wants a
+++ filesystem path. For example, The FOP 0.20.x serializer doesn't like relative
+++ image paths, and doesn't understand Cocoon URLs (context:, cocoon: etc). So we
+++ pass the *2fo.xsl stylesheet a real filesystem path to where we keep our images:
+++ </p>
+++
+++ <p>A absolute path argument like {contextrealpath:/resources} will be resolved
+++ from the root context path (ie. COCOON_HOME/build/webapp) whereas a relative
+++ path attribute like {contextrealpath:./resources} will be resolved from the
+++ location of the sitemap that uses it. If that sitemap is mounted outside the
+++ usual COCOON_HOME/build/webapp the path resolved with this modules points to the
+++ correct location.</p>
+++
+++ <pre><map:transform src="skins/%7Bforrest:skin%7D/xslt/fo/document2fo.xsl">
+++ <map:parameter name="basedir" value="{contextrealpath:resources}/">
+++ </map:parameter>
+++
+++ And then prepend this to all image paths:
+++ ...
+++ <xsl:param name="basedir" select="''">
+++ ...
+++ <xsl:template match="img">
+++ <xsl:variable name="imgpath" select="concat($basedir, @src)">
+++ <fo:external-graphic src="%7B$imgpath%7D" .=""></fo:external-graphic>
+++ </xsl:variable></xsl:template></xsl:param></map:transform>
+++ </pre>
+++
<h2>CollectionMetaModule</h2>
<p>Constructs an array of values suitable for a JDBC collection type from
(32 equal lines skipped)
<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html">Java
Date Format</a>.</p>
+++ <h2>DateMetaInputModule</h2>
+++
+++ <p>Parses a date string according to a given format and returns a date object.
+++ Configuration options: element "format" to hold a
+++ <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html">SimpleDateFormat</a>
+++ format string, child element "input-module" holds InputModule to obtain the
+++ string from.</p>
+++
+++ <h2>DefaultsModule</h2>
+++
+++ <p>Set a number of constants. To override the values with input from another
+++ module, combine this one with the ChainMetaModule and an arbitrary number of
+++ other modules. <values> <skin>myskin</skin>
+++ <base>baseurl</base> ... </values></p>
+++
+++ <h2>DigestMetaModule</h2>
+++
+++ <p>Meta module that obtains values from other module and returns message digest
+++ of value. Very useful for storing and checking passwords. Input module
+++ configured through nested element "input-module", message digest algorithm,
+++ security provider, salt, and URL encoded output configurable through elements
+++ "algorithm", "provider", "salt", "encode". Defaults are "sha", null, "salt", and
+++ "false". Available value for encode are "none" (returns byte[]), "string"
+++ (return hash as string), "url" (returns url encoded string), "hex" (returns
+++ string of hex values).</p>
+++
+++ <h2>FlowAttributeModule</h2>
+++
+++ <p>FlowAttributeModule provides access to the flow business object properties.
+++ To get access to the properties use XPath syntax. If requested object is not
+++ found then an exception will be thrown.</p>
+++
+++ <h2>FlowContinuationModule</h2>
+++
+++ <p>FlowContinuationModule provides access to the flow web continuation object.
+++ To get access to the properties use XPath syntax. If requested object is not
+++ found then an exception will be thrown.</p>
+++
<h2>GlobalInputModule</h2>
<p>This module allows you to access "global" variables which are defined in a
(29 equal lines skipped)
</map:match>
</pre>
+++ <h2>HeaderAttributeModule</h2>
+++
+++ <p>HeaderAttributeModule accesses request header attributes. If the attribute
+++ name contains an asterisk "*" this is considered a wildcard and all attributes
+++ that would match this wildcard are considered to be part of an array of that
+++ name for getAttributeValues. Only one "*" is allowed.</p>
+++
+++ <h2>JXPathMetaModule</h2>
+++
+++ <p>JXPathModule allows to access properties of any object in generic way. JXPath
+++ provides APIs for the traversal of graphs of JavaBeans, DOM and other types of
+++ objects using the XPath syntax. This is based on the AbstractJXPathModule and
+++ duplicates the code since multiple inheritance is not possible. Please keep both
+++ classes in sync.</p>
+++
+++ <p>Configuration example:</p>
+++
+++ <table>
+++ <tbody>
+++ <tr>
+++ <td>
+++ <p><tt><lenient>false</lenient></tt></p>
+++ </td>
+++ <td>
+++ <p>When set to true, non-existing attributes return null, when set to false, an
+++ exception is thrown. Default is true.</p>
+++ </td>
+++ </tr>
+++ <tr>
+++ <td>
+++ <p><tt><parameter>false</parameter></tt></p>
+++ </td>
+++ <td>
+++ <p>Attribute name to be used instead of passed attribute name.</p>
+++ </td>
+++ </tr>
+++ <tr>
+++ <td>
+++ <p><tt><from-parameter>false</from-parameter></tt></p>
+++ </td>
+++ <td>
+++ <p>Attribute name to pass to configured input module</p>
+++ </td>
+++ </tr>
+++ <tr>
+++ <td><tt><input-module name="request-attr"/></tt></td>
+++ <td>
+++ <p>Uses the "request-attr" input module to obtain a value and applies the given
+++ JXPath expression to it.</p>
+++ </td>
+++ </tr>
+++ <tr>
+++ <td><tt><function name="java.lang.String" prefix="str"/></tt></td>
+++ <td>
+++ <p>Imports the class "String" as extension class to the JXPathContext using the
+++ prefix "str". Thus "str:length(xpath)" would apply the method "length" to the
+++ string object obtained from the xpath expression. Please note that the class
+++ needs to be fully qualified.</p>
+++ </td>
+++ </tr>
+++ <tr>
+++ <td><tt><package name="java.util" prefix="util"/></tt></td>
+++ <td>
+++ <p>Imports all classes in the package "java.util" as extension classes to the
+++ JXPathContext using the prefix "util". Thus "util:Date.new()" would create a new
+++ java.util.Date object.</p>
+++ </td>
+++ </tr>
+++ </tbody>
+++ </table>
+++
+++ <h2>LocateResource</h2>
+++
+++ <p>Locate a resource in a resource tree. Any attribute name is interpreted as a
+++ URI with the last part being the resource name unless it ends with a slash. The
+++ URI is checked if the resource exists and the URI is returned. If the resource
+++ does not exist, the URI is shortened until the resource name is found and the
+++ new URI is returned. If no resource with the given name exists, null is
+++ returned.</p>
+++
+++ <p>A use case is to locate the closest menu file or when moving a site from a
+++ filesystem path == URL system from a httpd to Cocoon and provide similar
+++ functions to .htaccess files.</p>
+++
+++ <p>Example: for context:/some/path/to/a/file.xml the following URIs are tested:
+++ context:/some/path/to/a/file.xml, context:/some/path/to/file.xml,
+++ context:/some/path/file.xml, context:/some/file.xml, and context:/file.xml. For
+++ the attribute name context:/some/path/foo/ tests context:/some/path/foo/,
+++ context:/some/path/, context:/some/, and context:/ are tested.</p>
+++
+++ <p>The getAttribute() method will return the URI for the first match while
+++ getAttributeValues() will return an array of all existing paths.
+++ getAttributeNames() will return an Iterator to an empty collection.</p>
+++
+++ <h2>MapMetaModule</h2>
+++
+++ <p>Meta module that obtains an Object from another module, assumes that this
+++ Object implements the java.util.Map interface, and gives access to the map
+++ contents. Possible use is to propagate data from flow through request attributes
+++ to database actions. The same can be achieved by using the
+++ <a href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/components/modules/input/JXPathMetaModule.html">JXPathMetaModule</a>.
+++ </p>
+++
+++ <p>Configuration: "input-module", "object", "parameter"</p>
+++
+++ <h2>NamingInputModule</h2>
+++
+++ <p>NamingInputModule accesses values stored in the JNDI context.</p>
+++
+++ <p>This module accept any configuration parameters and passes them as properties
+++ to the InitialContext. When connecting to the Naming context of the server
+++ Cocoon is running in, no parameters are required.</p>
+++
+++ <p>Example module configuration when connecting to external WebLogic server:
+++ </p>
+++
+++ <pre> <java.naming.factory.initial>weblogic.jndi.WLInitialContextFactory</java.naming.factory.initial>
+++ <java.naming.provider.url>t3://localhost:7001</java.naming.provider.url>
+++ </pre>
+++
+++ <p>Example usage:</p>
+++
+++ <pre> <map:generate src="{naming:java:comp/env/greeting}"/>
+++ </pre>
+++
+++ <p>This lookups greeting entry from the environment of the webapp. Webapp's
+++ web.xml should define this entry:</p>
+++
+++ <pre> <env-entry>
+++ <env-entry-name>greeting</env-entry-name>
+++ <env-entry-value>Hello, World</env-entry-value>
+++ <env-entry-type>java.lang.String</env-entry-type>
+++ </env-entry>
+++ </pre>
+++
+++ <h2>NullInputModule</h2>
+++
+++ <p>NullInputModule returns a null object. Use this if you want to explicitly
+++ forbid a parameter to be filled. E.g. a database column shall be filled with a
+++ default value, your forms never contain that parameter but you don't want anyone
+++ to provide this parameter manually.</p>
+++
+++ <h2>PortletURLModule</h2>
+++
+++ <p>Input module to be used in together with
+++ <a href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/transformation/LinkRewriterTransformer.html">LinkRewriterTransformer</a>
+++ in JSR-168 (Portlet) environment. Allows creation of render, action, and
+++ resource URLs using syntax:</p>
+++
+++ <ul>
+++ <li>portlet:action:<path> for action URL;</li>
+++ <li>portlet:render:<path> for render URL;</li>
+++ <li>portlet:resource:<path> for resource URL;</li>
+++ </ul>
+++
+++ <p>Outside of portlet environment, prefixes (portlet:action:, portlet:render:,
+++ portlet:resource:) are omitted.</p>
+++
+++ <h2>PropertiesFileModule</h2>
+++
+++ <p>Input module for accessing properties in a properties file.</p>
+++
+++ <p>The properties file can only be configured statically and is resolved via the
+++ SourceResolver system.</p>
+++
+++ <h2>RandomNumberModule</h2>
+++
+++ <p>RandomNumberModule returns a random number as a string. Configuration through
+++ child elements: "min", "max" setting range of random number. Defaults to "0" and
+++ "9999999999" respectively.</p>
+++
<h2 id="raw-request-parameter-module">RawRequestParameterModule</h2>
<p>This module allows access to "raw" request parameters and their values.</p>
(32 equal lines skipped)
since <a href="http://www.faqs.org/rfcs/rfc1738.html">RFC 1738</a> requires
spaces and other special characters to be correctly encoded.</p>
+++ <h2>RealPathModule</h2>
+++
+++ <p>RealPathModule provides a real filesystem path for a virtual context-relative
+++ path. If this mapping cannot be performed (e.g. Cocoon is running in a .war
+++ file), null will be returned.</p>
+++
+++ <h2>RequestAttributeModule</h2>
+++
+++ <p>RequestAttributeModule accesses request attributes. If the attribute name
+++ contains an asterisk "*" this is considered a wildcard and all attributes that
+++ would match this wildcard are considered to be part of an array of that name for
+++ getAttributeValues. Only one "*" is allowed.</p>
+++
+++ <h2>RequestModule</h2>
+++
+++ <p>RequestModule provides access to Request object properties. To get access to
+++ request properties use XPath syntax, e.g. to get the request context path use
+++ 'contextPath' as the attribute name.</p>
+++
+++ <p>More complex expressions are also supported, e.g.:</p>
+++
+++ <pre> 'userPrincipal/name' </pre>
+++
+++ <p>will return the name property of the Principal object returned by the
+++ request.getUserPrincipal() method. If requested object is not found then an
+++ exception will be thrown.</p>
+++
<h2 id="request-parameter-module">RequestParameterModule</h2>
<p>This module allows access to request parameters. Values returned are "URL
(64 equal lines skipped)
"sitemapURI" to the request module. Therefore this component is not declared in
cocoon.xconf by default. You must manually add it.</p>
+++ <h2>SelectMetaInputModule</h2>
+++
+++ <p><strong>Configuration</strong></p>
+++
+++ <table>
+++ <tbody>
+++ <tr>
+++ <td>
+++ <p>input-module</p>
+++ </td>
+++ <td>
+++ <p>Configuration and name of input module used for the selection.</p>
+++ </td>
+++ <td>
+++ <p><tt>req</tt></p>
+++ </td>
+++ <td>
+++ <p>String</p>
+++ </td>
+++ <td>
+++ <p><tt>null</tt></p>
+++ </td>
+++ </tr>
+++ <tr>
+++ <td>
+++ <p>when</p>
+++ </td>
+++ <td>
+++ <p>Selection case, condition in test attribute, input module name in name
+++ attribute. Optional configuration as nested content.</p>
+++ </td>
+++ <td>
+++ <p><tt>req</tt></p>
+++ </td>
+++ <td>
+++ <p>String</p>
+++ </td>
+++ <td>
+++ <p><tt>null</tt></p>
+++ </td>
+++ </tr>
+++ <tr>
+++ <td>
+++ <p>otherwise</p>
+++ </td>
+++ <td>
+++ <p>Default selection case. If not present and no case matches, null is returned.
+++ </p>
+++ </td>
+++ <td/>
+++ <td>
+++ <p>String</p>
+++ </td>
+++ <td>
+++ <p><tt>null</tt></p>
+++ </td>
+++ </tr>
+++ </tbody>
+++ </table>
+++
+++ <h2>SessionAttributeModule</h2>
+++
+++ <p>essionAttributeModule accesses session attributes. If the attribute name
+++ contains an asterisk "*" this is considered a wildcard and all attributes that
+++ would match this wildcard are considered to be part of an array of that name for
+++ getAttributeValues. Only one "*" is allowed.</p>
+++
+++ <h2>SessionModule</h2>
+++
+++ <p>SessionModule provides access to Session object properties. To get access to
+++ session properties use XPath syntax, e.g. to get the session id use 'id' as the
+++ attribute name.<br/>
+++ More complex expressions with functions are also supported, e.g.:</p>
+++
+++ <pre> 'substring(id, 8)' </pre>
+++
+++ <p>will return the substring of id property of the session object.
+++ <strong>NOTE:</strong> The module does not create a new session.</p>
+++
+++ <h2>SimpleMappingMetaModule</h2>
+++
+++ <p>Meta module that obtains values from an other module and by replacing the
+++ requested attribute name with another name. This is done first through a
+++ replacement table and may additionally prepend or append a string. Replacement
+++ works in both ways, it is applied to the returned attribute names as well.</p>
+++
+++ <p>Example configuration:</p>
+++
+++ <pre> <prefix>cocoon.</prefix>
+++ <suffix>.attr</suffix>
+++ <mapping in="foo" out="bar"/>
+++ <mapping in="yuk" out="yeeha"/>
+++ </pre>
+++
+++ <p>Will map a parameter "foo" to the real one named "cocoon.bar.attr". If
+++ parameters "cocoon.yeeha.attr" and "shopping.cart" exist, the iterator will
+++ return "yeeha". "shopping.cart" does not contain the pre-/ suffix and thus is
+++ dropped.</p>
+++
+++ <p>Similarily, rm-prefix and rm-suffix will be removed from the attribute name.
+++ </p>
+++
+++ <h2>SitemapVariableHolder</h2>
+++
+++ <p>This "component" is a trick to get global variables on a per sitemap base.
+++ </p>
+++
+++ <h2>StringConstantModule</h2>
+++
+++ <p>StringConstantModule returns a constant string. Constant must be the only
+++ content of the configuration object.</p>
+++
+++ <h2>SystemPropertyModule</h2>
+++
+++ <p>SystemPropertyModule is an JXPath based InputModule implementation that
+++ provides access to system properties. Available system properties are defined by
+++ Java's
+++ <a href="http://java.sun.com/j2se/1.4.1/docs/api/java/lang/System.html#getProperties%28%29">System.getProperties()</a>.
+++ JXPath allows to apply XPath functions to system properties. If there is a
+++ security manager, its checkPropertiesAccess method is called with no arguments.
+++ This may result in a security exception which is wrapped into a configuration
+++ exception and re-thrown.</p>
+++
+++ <h2>URLDecodeModule</h2>
+++
+++ <p>This module provides functionality for converting a String from the
+++ application/x-www-form-urlencoded MIME format. It is useful for example for
+++ calling remote services:</p>
+++
+++ <pre><map:generate src="http://remote/page?param1={url-decode:{request-param:param1}}"/></pre>
+++
+++ <p>Module configuration takes only one configuration parameter: "encoding" which
+++ is a target string encoding. This is utf-8 by default.</p>
+++
+++ <h2>URLEncodeModule</h2>
+++
+++ <p>This module provides functionality for converting a String to the
+++ application/x-www-form-urlencoded MIME format. It is useful for example for
+++ calling remote services:</p>
+++
+++ <pre><map:generate src="http://remote/page?param1={url-encode:{request-param:param1}}"/></pre>
+++
+++ <p>Module configuration takes only one configuration parameter: "encoding" which
+++ is a target string encoding. This is utf-8 by default.</p>
+++
+++ <h2>XMLFileModule</h2>
+++
+++ <p>This module provides an Input Module interface to any XML document, by using
+++ XPath expressions as attribute keys. The XML can be obtained from any Cocoon
+++ Source (e.g., cocoon:/..., context://.., and regular URLs). Sources can be held
+++ in memory for better performance and reloaded if changed.</p>
+++
+++ <p>Caching and reloading can be turned on / off (default: on) through
+++ <reloadable>false</reloadable> and
+++ <cacheable>false</cacheable>. The file (source) to use is specified
+++ through <file src="protocol:path/to/file.xml" reloadable="true"
+++ cacheable="true"/> optionally overriding defaults for caching and or
+++ reloading.</p>
+++
+++ <p>In addition, xpath expressions are cached for higher performance. Thus, if an
+++ expression has been evaluated for a file, the result is cached and will be
+++ reused, the expression is not evaluated a second time. This can be turned off
+++ using the cache-xpaths configuration option.</p>
+++
+++ <h2>XMLMetaModule</h2>
+++
+++ <p>Meta module that obtains values from other module and returns all parameters
+++ as XML.</p>
+++
+++ <p>Config:</p>
+++
+++ <pre> <!-- in cocoon.xconf -->
+++ <ignore>do-</ignore>
+++ <strip>user.</strip>
+++ <input-module name="request-param"/>
+++
+++ <!-- e.g. in database.xml -->
+++ <mode type="all" name="xmlmeta"/>
+++ <ignore>foo.</ignore>
+++ <strip>f</strip>
+++ <use>foo</use>
+++ <root>my-root</root>
+++ <input-module name="request-param"/>
+++ </mode>
+++ </pre>
+++
+++ <p>If present, "ignore" gives a prefix of parameters to ignore, ignore has
+++ precedence over the "use" attribute, "strip" a prefix that will be removed from
+++ the final parameter names in the produced XML, "use" is a prefix for parameters
+++ to include in the XML, and "root" is the name of the root element in the created
+++ XML.</p>
+++
+++ <p>Input:</p>
+++
+++ <pre> foo.one = ['abc']
+++ foo.two = ['def']
+++ foo1 = ['bar']
+++ foo2 = ['one','two','three']
+++ bar = ['rubber duck']
+++ </pre>
+++
+++ <p>Output:</p>
+++
+++ <pre> <my-root>
+++ <item name="oo1">bar</item>
+++ <item name="oo2">
+++ <value>one</value>
+++ <value>two</value>
+++ <value>three</value>
+++ </item>
+++ </my-root>
+++ </pre>
+++
+++ <p>Produces Objects of type
+++ <a href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/xml/dom/DocumentWrapper.html">DocumentWrapper</a>
+++ </p>
+++
</body>
</html>
Fields
======
no changes
Links
=====
no changes
Custom Fields
=============
no changes
Collections
===========
no changes