cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From t...@apache.org
Subject cvs commit: cocoon-2.1/src/documentation/xdocs/userdocs/concepts modules-ref.xml
Date Mon, 13 Oct 2003 21:18:34 GMT
tony        2003/10/13 14:18:34

  Added:       src/documentation/xdocs/userdocs/concepts modules-ref.xml
  Log:
  new modules reference material
  
  Revision  Changes    Path
  1.1                  cocoon-2.1/src/documentation/xdocs/userdocs/concepts/modules-ref.xml
  
  Index: modules-ref.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://apache.org/forrest/dtd/document-v12.dtd">
  <document> 
  
      <header> 
          <title>Input Modules Reference</title> 
          <authors>
              <person name="Tony Collen" email="tony@apache.org"/> 
          </authors>
          <abstract>A concise reference to Cocoon's InputModules.</abstract> 
      </header> 
  
      <body> 
  
      <section>
          <title>Introduction</title>
          <p>This is meant to be a concise reference to Cocoon's InputModules, 
          what they do, and how to use them.  InputModules are available in 
          Cocoon 2.0.4 and above.  Many descriptions are taken directly from 
          the respective modules' source code, or from trial and error 
          experimentation.</p>
          
          <note>See also: the 
          <link href="http://wiki.cocoondev.org/Wiki.jsp?page=InputModules">InputModules

          Wiki Page</link>.</note>
      </section>
  
  
      <section>
          <title>Modules Reference</title>
  
          <section>
              <title>AbstractInputModule</title>
  
              <p>AbstractInputModule gives you the infrastructure for easily 
              deploying more InputModules.</p>
          </section>
  
          <section>
              <title>AbstractJXPathModule</title>
  
              <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. JXPathMetaModule is based on this 
              class and duplicates the code since multiple inheritance is not possible. 
              Please keep both classes in sync.</p>
  
              <p><strong>Configuration Example:</strong></p>
  
              <p>The following 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>
  
              <source><![CDATA[<function name="java.lang.String" prefix="str"/>]]></source>
  
              <p>The following 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>
  
              <source><![CDATA[<package name="java.util" prefix="util"/>]]></source>
          </section>
  
  
          <section>
              <title>AbstractMetaModule</title>
  
              <p>AbstractMetaModule gives you the infrastructure for easily deploying

              more "meta" InputModules i.e. InputModules that are composed of other 
              InputModules. In order to get at the Logger, use getLogger().</p>
          </section>
  
          <section>
              <title>CollectionMetaModule</title>
  
              <p>Constructs an array of values suitable for a JDBC collection type from

              parameters obtained from another input module. Application is not limited 
              to JDBC collections but can be used wherever similar named attributes 
              shall be collected to an array of a given type. Currently, long, int, and 
              string are known, more to come.</p>
  
              <p><strong>Global and Local Configuration:</strong></p>
  
              <fixme author="TC">Finish the reference for this Module.</fixme>
          </section>
  
          <section>
              <title>DateInputModule</title>
  
              <p>This module returns the current date, optionally formated 
              as string. Format given through attribute "format" of 
              configuration root node or nested &lt;format/&gt; tag on module 
              declaration.</p>
  
              <note>The 'format' attribute doesn't seem to work. Nested 
              <code>&lt;format/&gt;</code> tags work fine.</note>
  
              <note>See also: 
              <link href="http://java.sun.com/j2se/1.4.1/docs/api/java/text/SimpleDateFormat.html">Java

              Date Format</link>.</note>
          </section>
  
          <section>
              <title>GlobalInputModule</title>
              <p>This module allows you to access "global" variables which are defined
in 
              a sitemap's pipelines definition.</p>
  
  
              <p><strong>cocoon.xconf usage:</strong></p>
              <source><![CDATA[
  <input-modules>
    ...
    <component-instance 
       class="org.apache.cocoon.components.modules.input.GlobalInputModule" 
       logger="core.modules.input" 
       name="global"/>
    ...
  </input-modules> 
  ]]></source>
  
              <p><strong>Sitemap Usage:</strong></p>
  
              <source><![CDATA[
  <map:component-configurations>
    <global-variables>
        <doc>doc.xml</doc>
    </global-variables>
  </map:component-configurations>
  ]]></source>
  
              <p><strong>Example Pipeline Fragment:</strong></p>
  
              <source><![CDATA[
  <map:match pattern="foo">
    <map:generate type="file" src="documents/{global:doc}"/>
    <map:transform src="stylesheets/foo2html.xsl"/>
    <map:serialize/>
  </map:match>
  ]]></source>
          </section>
  
  
          <anchor id="raw-request-parameter-module"/>
  
          <section>
              <title>RawRequestParameterModule</title>
  
              <p>This module allows access to "raw" request parameters and their 
              values.</p>
              <p>Values returned are "URL Encoded", meaning if a parameter is 
              submitted as "foo+bar", you will get the string "foo+bar".</p>
  
              <note>For access to URL-Decoded request parameters, see the <link href=
              "#request-parameter-module">RequestParameterModule</link>.</note>
  
              <p><strong>cocoon.xconf usage:</strong></p>
  
              <source><![CDATA[
  <input-modules>
    ...
    <component-instance 
       class="org.apache.cocoon.components.modules.input.RawRequestParameterModule" 
       logger="core.modules.input" 
       name="raw-request-param"/>
    ...
  </input-modules> 
  ]]></source>
  
              <p><strong>Example Pipeline Fragment:</strong></p>
  
              <source><![CDATA[
  <map:match pattern="amazonProxy">
    <map:generate type="file" 
        src="http://localhost:8888/search?qry={raw-request-param:actor}"/>
    <map:serialize type="xml"/>
  </map:match>
  ]]></source>
  
              <p>
                  This input module is useful when you are querying a remote service, 
                  and you need to be able to send a search string with spaces or other 
                  special characters intact. If you were to simply use 
                  <code>{request-param:actor}</code>, you would end up sending
a space 
                  character to the remote service, which would be an error, since 
                  <link href="http://www.faqs.org/rfcs/rfc1738.html">RFC 1738</link>

                  requires spaces and other special characters to be correctly encoded.
              </p>
          </section>
  
          <anchor id="request-parameter-module"/>
  
          <section>
              <title>RequestParameterModule</title>
  
              <p>This module allows access to request parameters. Values returned are

              "URL Decoded". That is, if a request parameter is submitted as 
              <code>foo+bar</code>, you will get the string "foo bar".</p>
  
              <note>For URL-Encoded request parameters, see the 
              <link href="#raw-request-parameter-module">RawRequestParameterModule</link>.</note>
  
              <p><strong>cocoon.xconf usage:</strong></p>
  
              <source><![CDATA[
  <input-modules>
    ...
    <component-instance 
       class="org.apache.cocoon.components.modules.input.RequestParameterModule" 
       logger="core.modules.input" 
       name="request-param"/>
    ...
  </input-modules>
  ]]></source>
  
              <p><strong>Example Pipeline Fragment:</strong></p>
  
              <source><![CDATA[
  <map:match pattern="bar">
     <map:generate type="file" src="documents/{request-param:file}"/>
     <map:transform src="stylesheets/{request-param:stylesheet}"/>
     <map:serialize/>
  </map:match>
  ]]></source>
  
              <p>This pipeline will match a request for "bar" and pass the request 
              parameters "file" and "stylesheet" to the generator and transformer, 
              respectively. (e.g. 
              http://localhost:8080/cocoon/bar?file=doc.xml&amp;stylesheet=main.xsl).</p>
  
              <warning>
                  Directly passing request parameters for file access can be 
                  dangerous. Remember to follow basic webapp safety rules when 
                  designing your pipelines, and when passing around request 
                  parameters.
              </warning>
          </section>
  
          <section>
              <title>RequestURIModule</title>
  
              <p>Returns the URI of the request.</p>
  
              <p>If you are familliar with Avalon and Cocoon's component architecture,

              the following will explain what is specifically returned:</p>
  
              <source>String uri = ObjectModelHelper.getRequest(objectModel).getSitemapURI();</source>
  
              <p><strong>cocoon.xconf usage:</strong></p>
  
              <source><![CDATA[
  <input-modules>
    ...
    <component-instance 
       class="org.apache.cocoon.components.modules.input.RequestURIModule" 
       logger="core.modules.input" 
       name="request-uri"/>
    ...
  </input-modules>
  ]]></source>
  
              <p><strong>Example Sitemap Usage:</strong></p>
  
              <source>{request-uri:requestURI}</source>
  
              <p>This is how you would use the module most of the time, since the 
              module only returns one item, the Request URI.</p>
  
              <note>
                  The same effect can be achieved by passing the parameter name 
                  "sitemapURI" to the request module. Therefore this component is not 
                  declared in cocoon.xconf by default. You must manually add it.
              </note>
  
          </section>
          
      </section>
  
      </body> 
      
      <footer> 
          <legal>© 2002 Apache Forrest</legal> 
      </footer>
  
  </document>
  
  
  

Mime
View raw message