cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hu...@apache.org
Subject cvs commit: xml-cocoon2/src/documentation/xdocs/userdocs/selectors browser-selector.xml host-selector.xml template-selector.xml book.xml
Date Sat, 28 Dec 2002 22:29:24 GMT
huber       2002/12/28 14:29:24

  Modified:    src/documentation/xdocs/userdocs/selectors book.xml
  Added:       src/documentation/xdocs/userdocs/selectors
                        browser-selector.xml host-selector.xml
                        template-selector.xml
  Log:
  added docs about browser, and host selector
  added template-selector intended for using when writing new selector docs
  
  Revision  Changes    Path
  1.3       +2 -0      xml-cocoon2/src/documentation/xdocs/userdocs/selectors/book.xml
  
  Index: book.xml
  ===================================================================
  RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/userdocs/selectors/book.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- book.xml	10 Jul 2002 18:54:33 -0000	1.2
  +++ book.xml	28 Dec 2002 22:29:24 -0000	1.3
  @@ -14,8 +14,10 @@
       <menu-item label="Overview" href="selectors.html"/>
     </menu>
     <menu label="Default">
  +    <menu-item label="Browser Selector" href="browser-selector.html"/>
     </menu>
     <menu label="Core">
  +    <menu-item label="Host Selector" href="host-selector.html"/>
       <menu-item label="Parameter" href="parameter-selector.html"/>
     </menu>
     <menu label="Optional">
  
  
  
  1.1                  xml-cocoon2/src/documentation/xdocs/userdocs/selectors/browser-selector.xml
  
  Index: browser-selector.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
  
  <!--
    <![CDATA[ CVS Version: $Id: browser-selector.xml,v 1.1 2002/12/28 22:29:24 huber Exp
$ 
    ]]>
  -->
  
  <document>
    <header>
      <title>Browser-Selector in Cocoon</title>
      <version>0.9</version>
      <type>Technical document</type>
      <authors>
        <person name="Bernhard Huber" email="huber@apache.org"/>
      </authors>
      <abstract>This document describes the BrowserSelector of Cocoon.</abstract>
    </header>
    <body>
      <s1 title="BrowserSelector">
        <table>
          <tr>
            <td>NAME</td><td>browser</td>
          </tr>
          <tr>
            <td>WHAT</td><td>The <code>BrowserSelector</code>
component is used to
              select appropriate sitemap processing depending on the <code>User-Agent</code>
              header value.
            </td>
          </tr>
          <tr>
            <td>TYPE</td><td>Selector, Sitemap Component</td>
          </tr>
          <tr>
            <!-- choose Core, the block name, or Scratchpad 
              depending on where BrowserSelector sources live
            -->
            <td>BLOCK</td><td>Core</td>
          </tr>
          <tr>
            <td>CLASS</td><td>org.apache.cocoon.selection.BrowserSelector</td>
          </tr>
          <!-- uncomment folling tr iff BrowserSelector is deprecated -->
          <!--tr>
            <td>DEPRECATED</td><td>Cocoon 2.0, 2.1</td>
          </tr-->
          <tr>
            <td>SINCE</td><td>Cocoon 2.0</td>
          </tr>
          <tr>
            <td>CACHEABLE</td><td>not applicable</td>
          </tr>
        </table>
      </s1>
      <s1 title="Description">
        <p>
          The <code>BrowserSelector</code> tests the user agent header field against
          the test attribute of the selectors when clause.
        </p>
      </s1>
      <s1 title="Usage">
        <p>
          The <code>BrowserSelector</code> allows to define brower specific sitemap
          processing.
        </p>
        <s2 title="Sitemap pipeline examples">
          <p></p>
          <source><![CDATA[
  <map:select type="browser">
    <map:when test="netscape">
    ....
    </map:when>
    <map:when test="explorer">
    ...
    </map:when>
    ...
    <map:otherwise>
    ...
    </map:otherwise>
  </map:select>
          ]]></source>
        </s2>
        
        <s2 title="Sitemap component configuration example">
          <p>
          </p>
          <source><![CDATA[
  <map:selectors...
    <map:selector name="browser" 
      src="org.apache.cocoon.selection.BrowserSelector"
      logger="sitemap.selector.browser" 
      
      <browser name="explorer" useragent="MSIE"/>
      ...
      <browser name="mozilla5" useragent="Moziall/5"/>
      <browser name="netscape" useragent="Mozilla"/>
      
    </map:selectors>
  ...
  ]]></source>
        </s2>
        <s2 title="Configuration">
          <p>
            <!-- Explain the sitemap selector configuration, options when declaring browser
selector -->
            The configuration section of <code>BrowserSelector</code> specifies
            a mapping from user-agent strings to symbolic browser names.
          </p>
          <p>
            Each browser element specifies a name attribute holding the symbolic browser name
            used in the test attribute expression. The attribute useragent contains 
            a matchable substring of some real user-agent values.
          </p>
          <p>
            It is allowed to specify for a browser name more than one entry. This way
            a symbolic browser name is matched by different user-agent substrings.
            The snippet belows will yield true for <code>test="wap-handset"</code>
if 
            the user-agent header contains <code>Nokia</code>, <code>UP</code>,
or 
            <code>Wapalizer</code>.
          </p>
          <source><![CDATA[
  ...
    <browser name="wap-handset" useragent="Nokia"/>
    <browser name="wap-handset" useragent="UP"/>
    <browser name="wap-handset" useragent="Wapalizer"/>
  ...
          ]]></source>
        </s2>
        <s2 title="Setup">
          <p>
            <!-- Explain the sitemap selector setup, ie options when using browser selector
-->
            Setting up a <code>BrowserSelector</code> includes choosing the 
            <code>&lt;map:when&gt;</code> test expressions, and a 
           optional <code>&lt;map:otherwise&gt;</code> clause.
          </p>
          <p>
            The test attribute of the <code>&lt;map:when&gt;</code> clause
must match
            a browser attribute name value. The value of the test attribute in a 
            <code>&lt;map:when&gt;</code> clause must be declared in a

            <code>browser</code> name attribute.
          </p>
        </s2>
        <s2 title="Effect on Object Model and Sitemap Parameters">
          <p>
            The <code>BrowserSelector</code> has no side effects on the object
model, or 
            any sitemap parameters. 
          </p>
        </s2>
      </s1>
      <s1 title="Bugs/Caveats">
        <p>
          The <code>BrowserSelector</code> adds the response header attribute
          <code>Vary</code> having value <code>User-Agent</code> indicating
          that the response differ for different user agents. This information
          especially meaningfull for an http-proxy server.
        </p>
      </s1>
      <s1 title="History">
        <p>
          28-12-02: initial creation
        </p>
      </s1>
      <s1 title="Copyright">
        <p>
          Copyright (C) 1999-2002 The Apache Software Foundation. All rights reserved.
        </p>
      </s1>
      <s1 title="See also">
        <p>
          <!-- Links to related components pages. -->
          A general documentation about selectors is available at
          <link href="../concepts/matchers_selectors.html">Matchers and Selectors</link>.
        </p>
      </s1>
    </body>
  </document>
  
  
  
  
  1.1                  xml-cocoon2/src/documentation/xdocs/userdocs/selectors/host-selector.xml
  
  Index: host-selector.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
  
  <!--
    <![CDATA[ CVS Version: $Id: host-selector.xml,v 1.1 2002/12/28 22:29:24 huber Exp $

    ]]>
  -->
  
  <document>
    <header>
      <title>Host-Selector in Cocoon</title>
      <version>0.9</version>
      <type>Technical document</type>
      <authors>
        <person name="Bernhard Huber" email="huber@apache.org"/>
      </authors>
      <abstract>This document describes the HostSelector of Cocoon.</abstract>
    </header>
    <body>
      <s1 title="HostSelector">
        <table>
          <tr>
            <td>NAME</td><td>host</td>
          </tr>
          <tr>
            <td>WHAT</td><td>The <code>HostSelector</code> component
is used to
              select appropriate sitemap processing depending on <code>Host</code>
header
              value.
            </td>
          </tr>
          <tr>
            <td>TYPE</td><td>Selector, Sitemap Component</td>
          </tr>
          <tr>
            <!-- choose Core, the block name, or Scratchpad 
              depending on where HostSelector sources live
            -->
            <td>BLOCK</td><td>Core</td>
          </tr>
          <tr>
            <td>CLASS</td><td>org.apache.cocoon.selection.HostSelector</td>
          </tr>
          <!-- uncomment folling tr iff HostSelector is deprecated -->
          <!--tr>
            <td>DEPRECATED</td><td>Cocoon 2.0, 2.1</td>
          </tr-->
          <tr>
            <td>SINCE</td><td>Cocoon 2.0</td>
          </tr>
          <tr>
            <td>CACHEABLE</td><td>not applicable</td>
          </tr>
        </table>
      </s1>
      <s1 title="Description">
        <p>
          The <code>HostSelector</code> tests the <code>Host</code>
header field from the 
          request against the test attribute of the selectors when clause.
        </p>
      </s1>
      <s1 title="Usage">
        <p>
          The <code>HostSelector</code> allows to define host specific sitemap
          processing. This way Cocoon can do multi-homed sitemap processing.
        </p>
        <s2 title="Sitemap pipeline examples">
          <p>
            The snippet below uses a <code>HostSelector</code> named <code>host</code>,
            and testing against symbolic host-sites which are configured in the <code>host</code>
            selector section.
          </p>
          <source><![CDATA[
  <map:select type="host">
    <map:when test="uk-site">
    ....
    </map:when>
    <map:when test="de-site">
    ...
    </map:when>
    ...
    <map:otherwise>
    ...
    </map:otherwise>
  </map:select>
          ]]></source>
        </s2>
        
        <s2 title="Sitemap component configuration example">
          <p>
            The snippet below declares a <code>HostSelector</code>
            defining symbolic host-site names for some host domains.
          </p>
          <source><![CDATA[
  <map:selectors...
    <map:selector name="host" 
      src="org.apache.cocoon.selection.HostSelector"
      logger="sitemap.selector.host" 
      
      <host name="uk-site" value="foo.bar.uk"/>
      ...
      <host name="de-site" useragent="foo.bar.de"/>
      <host name="us-site" useragent="foo.bar.com"/>
      
    </map:selectors>
  ...
  ]]></source>
        </s2>
        <s2 title="Configuration">
          <p>
            <!-- Explain the sitemap selector configuration, options when declaring host
selector -->
            The configuration section of <code>HostSelector</code> specifies
            a mapping from host strings to symbolic host-site names.
          </p>
          <p>
            Each host element specifies a name attribute holding the symbolic host-site name
            used in the test attribute expression. The attribute name contains 
            a matchable substring of some real host header values.
          </p>
          <p>
            It is allowed to specify for a host name more than one entry. This way
            a symbolic host-site name is matched by different host header substrings.
            The snippet belows will yield true for <code>test="central-europe"</code>
if 
            the user-agent header contains <code>foo.bar.cz</code>, <code>foo.bar.at</code>,
or 
            <code>foo.bar.hu</code>.
          </p>
          <source><![CDATA[
  ...
    <host name="central-europe" useragent="foo.bar.cz"/>
    <host name="central-europe" useragent="foo.bar.at"/>
    <host name="central-europe" useragent="foo.bar.uk"/>
  ...
          ]]></source>
        </s2>
        <s2 title="Setup">
          <p>
            <!-- Explain the sitemap selector setup, ie options when using host selector
-->
            Setting up a <code>HostSelector</code> includes choosing the 
            <code>&lt;map:when&gt;</code> test expressions, and a 
           optional <code>&lt;map:otherwise&gt;</code> clause.
          </p>
          <p>
            The test attribute of the <code>&lt;map:when&gt;</code> clause
must match
            a host attribute name value. The value of the test attribute in a 
            <code>&lt;map:when&gt;</code> clause must be declared in a

            <code>host</code> name attribute.
          </p>
        </s2>
        <s2 title="Effect on Object Model and Sitemap Parameters">
          <p>
            The <code>HostSelector</code> has no side effects on the object model,
or 
            any sitemap parameters. 
          </p>
        </s2>
      </s1>
      <s1 title="Bugs/Caveats">
        <p>
          The <code>HostSelector</code> adds the response header attribute
          <code>Vary</code> having value <code>Host</code> indicating
          that the response differ for different user agents. This information
          especially meaningfull for an http-proxy server.
        </p>
      </s1>
      <s1 title="History">
        <p>
          28-12-02: initial creation
        </p>
      </s1>
      <s1 title="Copyright">
        <p>
          Copyright (C) 1999-2002 The Apache Software Foundation. All rights reserved.
        </p>
      </s1>
      <s1 title="See also">
        <p>
          <!-- Links to related components pages. -->
          A general documentation about selectors is available at
          <link href="../concepts/matchers_selectors.html">Matchers and Selectors</link>.
        </p>
        <p>
          For a detailed <code>Host</code> header documentation 
          see <link href="http://www.ietf.org/rfc/rfc2068.txt">RFC 2068</link>,
especially
          if Cocoon's run time environment is an http servlet environment. 
        </p>
      </s1>
    </body>
  </document>
  
  
  
  
  1.1                  xml-cocoon2/src/documentation/xdocs/userdocs/selectors/template-selector.xml
  
  Index: template-selector.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
  
  <!--
    <![CDATA[ CVS Version: $Id: template-selector.xml,v 1.1 2002/12/28 22:29:24 huber Exp
$ 
    ]]>
  
    Using this TemplateMatcher:
    
    *  replace TemplateMatcher by the name of the matcher you are describing
    * write concrete description
    
  -->
  <document>
    <header>
      <title>Template-Selector in Cocoon</title>
      <version>0.9</version>
      <type>Technical document</type>
      <authors>
        <person name="Your Name" email="your-email"/>
      </authors>
      <abstract>This document describes the TemplateSelector of Cocoon.</abstract>
    </header>
    <body>
      <s1 title="TemplateSelector">
        <table>
          <tr>
            <td>NAME</td><td>template</td>
          </tr>
          <tr>
            <td>WHAT</td><td>The <code>TemplateSelector</code>
component is used to 
              select...
            </td>
          </tr>
          <tr>
            <td>TYPE</td><td>Selector, Sitemap Component</td>
          </tr>
          <tr>
            <!-- choose Core, the block name, or Scratchpad 
              depending on where TemplateSelector sources live
            -->
            <td>BLOCK</td><td>Core/Block-Name/Scratchpad</td>
          </tr>
          <tr>
            <td>CLASS</td><td>org.apache.cocoon.reading.TemplateSelector</td>
          </tr>
          <!-- uncomment folling tr iff TemplateSelector is deprecated -->
          <!--tr>
            <td>DEPRECATED</td><td>Cocoon 2.0, 2.1</td>
          </tr-->
          <tr>
            <td>SINCE</td><td>Cocoon X.Y</td>
          </tr>
          <tr>
            <td>CACHEABLE</td><td>not applicable</td>
          </tr>
        </table>
      </s1>
      <s1 title="Description">
        <p>
          A general description of TemplateSelector
        </p>
      </s1>
      <s1 title="Usage">
        <p>
          A usage scenario of TemplateSelector
        </p>
        <s2 title="Sitemap pipeline examples">
          <p></p>
          <source><![CDATA[
  <map:match pattern="*.xyz">
    <map:read type="template" 
      src="{1}" 
      mime-type="type/sub-type">
      <!-- option sitemap parameters -->
    </map:read>
  </map:match>
          ]]></source>
        </s2>
        
        <s2 title="Sitemap component configuration example">
          <p></p>
          <source><![CDATA[
  <map:selectors...
    <map:selector name="template" 
      src="org.apache.cocoon.reading.TemplateSelector"
      logger="sitemap.selector.template" 
    />
      <!-- optional selector configuration -->
      ...
    </map:selectors>
  ...
  ]]></source>
        </s2>
        <s2 title="Configuration">
          <p>
            Explain the sitemap selector configuration, options when declaring template selector
          </p>
        </s2>
        <s2 title="Setup">
          <p>
            Explain the sitemap selector setup, ie options when using template selector
          </p>
        </s2>
        <s2 title="Effect on Object Model and Sitemap Parameters">
          <p>
          
          </p>
        </s2>
      </s1>
      <s1 title="Bugs/Caveats">
        <p>
          Describe limitation, bugs of TemplateSelector 
        </p>
      </s1>
      <s1 title="History">
        <p>
          MM-DD-YY: initial creation
        </p>
      </s1>
      <s1 title="Copyright">
        <p>
          Copyright (C) 1999-2002 The Apache Software Foundation. All rights reserved.
        </p>
      </s1>
      <s1 title="See also">
        <p>
          <!-- Links to related components pages. -->
          A general documentation about selectors is available at
          <link href="../concepts/matchers_selectors.html">Matchers and Selectors</link>.
        </p>
      </s1>
    </body>
  </document>
  
  
  
  

----------------------------------------------------------------------
In case of troubles, e-mail:     webmaster@xml.apache.org
To unsubscribe, e-mail:          cocoon-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: cocoon-cvs-help@xml.apache.org


Mime
View raw message