| <?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.3 2003/10/12 13:04:51 cziegeler 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-2003 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> |
| |
