You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by hu...@apache.org on 2002/12/28 23:29:24 UTC
cvs commit: xml-cocoon2/src/documentation/xdocs/userdocs/selectors browser-selector.xml host-selector.xml template-selector.xml book.xml
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><map:when></code> test expressions, and a
optional <code><map:otherwise></code> clause.
</p>
<p>
The test attribute of the <code><map:when></code> clause must match
a browser attribute name value. The value of the test attribute in a
<code><map:when></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><map:when></code> test expressions, and a
optional <code><map:otherwise></code> clause.
</p>
<p>
The test attribute of the <code><map:when></code> clause must match
a host attribute name value. The value of the test attribute in a
<code><map:when></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