apache > cocoon

- Home

# Browser-Selector in Cocoon

## BrowserSelector

NAME | browser
WHAT | The `BrowserSelector` component is used to select appropriate sitemap processing depending on the `User-Agent` header value.
TYPE | Selector, Sitemap Component
BLOCK | Core
CLASS | org.apache.cocoon.selection.BrowserSelector
SINCE | Cocoon 2.0
CACHEABLE | not applicable

## Description

The `BrowserSelector` tests the user agent header field against the test attribute of the selectors when clause.

## Usage

The `BrowserSelector` allows to define brower specific sitemap processing.

### Sitemap pipeline examples

    <map:select type="browser">
      <map:when test="netscape">
      ....
      </map:when>
      <map:when test="explorer">
      ...
      </map:when>
      ...
      <map:otherwise>
      ...
      </map:otherwise>
    </map:select>

### Sitemap component configuration example

    <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>
    ...

### Configuration

The configuration section of `BrowserSelector` specifies a mapping from user-agent strings to symbolic browser names.

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.

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 `test="wap-handset"` if the user-agent header contains `Nokia`, `UP`, or `Wapalizer`.

    ...
      <browser name="wap-handset" useragent="Nokia"/>
      <browser name="wap-handset" useragent="UP"/>
      <browser name="wap-handset" useragent="Wapalizer"/>
    ...

### Setup

Setting up a `BrowserSelector` includes choosing the `<map:when>` test expressions, and a optional `<map:otherwise>` clause.

The test attribute of the `<map:when>` clause must match a browser attribute name value. The value of the test attribute in a `<map:when>` clause must be declared in a `browser` name attribute.

### Effect on Object Model and Sitemap Parameters

The `BrowserSelector` has no side effects on the object model, or any sitemap parameters.

## Bugs/Caveats

The `BrowserSelector` adds the response header attribute `Vary` having value `User-Agent` indicating that the response differ for different user agents. This information especially meaningfull for an http-proxy server.

## History

28-12-02: initial creation

## See also

A general documentation about selectors is available at Matchers and Selectors.

Errors and Improvements? If you see any errors or potential improvements in this document please help us: View, Edit or comment on the latest development version (registration required).