apache > cocoon

- Home

# Search Generator

The search generator creates xml content resulting from an indexing search. Speaking simply, SearchGenerator takes a query-string passes it to search engine. The hits delivered by the search engine are wrapped into xml output and fed into the pipeline.

The xml content generated by SearchGenerator is described later.

- Name : search
- Class: org.apache.cocoon.generation.SearchGenerator
- Cacheable: no.

    <map:generate type="search"/>

or

    <map:generate type="search">
      <query>your query string</query>
    </map:generate>

## Configuration

Configuring of the SearchGenerator involves mainly setting up configuration needed by avalon component used for searching. As today SearchGenerator uses the Avalon component `org.apache.cocoon.components.search.LuceneCocoonSearcher` for searching, the configuration is tailored for this component.

Parameter Name | Default | Description
--- | --- | ---
analyzer | org.apache.lucene.analysis.standard.StandardAnalyzer | This parameter defines the analyzer to use for searching. Take care to use a compatible analyzer as used when generating the index.
index | index | This parameter defines a filesystem directory, expecting to be the location of the lucene filesystem index directory. Relative directory names are resolved relative to Cocoon's working directory.
query-string | queryString | This parameter specifies the name of the query parameter name used for passing the query-string, eg. `http://foo/bar?queryString=cocoon`, for generating xml content for query "cocoon".
page-length | PageLength | This parameter specifies the name of the query parameter name used for passing the page length. The page length specifies the number of hits generated into the xml content. A negative page length value will generate all hits into the xml content.
start-index | StartIndex | This parameter specifies the name of the query parameter name used for passing the start index of the hits result. This query parameter has higher precedence than query parameter defined by start-next-index, and start-previous-index.
start-next-index | StartNextIndex | This parameter specifies the name of the query parameter name used for passing the start index of the hits result. Use this if you have a form defining both next and previous navigation control.
start-previous-index | StartPreviousIndex | This parameter specifies the name of the query parameter name used for passing the start index of the hits result. Use this if you have a form defining both next and previous navigation control.

## Query Parameters

This generator accepts following query parameters, the table below assumes the default settings of the setup parameters.

Query Parameter Name | Default | Description
--- | --- | ---
queryString | No default | Specifies the query string, parsable by the search engine.
pageLength | 10 | This value specifies the number of hits displayed per page.
startIndex | 0 | Start displaying hits starting from this index (counting starts at 0).
startNextIndex | 0 | Start displaying hits starting from this index (counting start at 0).
startPreviousIndex | 0 | Start displaying hits starting from this index (counting starts at 0).

## Using SearchGenerator

Using the SearchGenerator needs some configuration steps regarding `cocoon.xconf`, and the sitemap mounting a pipeline defining a SearchGenerator generation step. Moreover you will have to define some XSLT processing for reendering the xml content of the SearchGenerator.

As SearchGenerator uses some avalon components be sure to configure your `cocoon.xconf` properly. The avalon component `org.apache.cocoon.components.search.LuceneCocoonSearcher` is used by the SearchGenerator. Usually this component is specified in `cocoon.roles` and the `cocoon.xconf` file for the default cocoon webapp.

Inside of a sitemap you have to define the SearchGenerator in the generator componenets section.

Moreover you have to match a URI to the SearchGenerator processing, the following example matches the URI `findIt` to the SearchGenerator processing. The stylesheet `search2html.xsl` transforms the xml content of SearchGenerator to html:

    <map:match pattern="findIt">
      <map:generate type="search"/>
      <map:transform type="log"/>
      <map:transform src="stylesheets/search2html.xsl"/>
      <map:serialize/>
    </map:match>

## DTD

XML generated by SearchGenerator uses namespace `http://apache.org/cocoon/search/1.0`. The DTD of XML generated by SearchGenerator:

    <!ELEMENT results (hits,navigation)?>

    <!ATTLIST results
       date CDATA #IMPLIED
       query-string CDATA #IMPLIED
       start-index CDATA #IMPLIED
       page-length CDATA #IMPLIED
    >

    <!ELEMENT hits (hit)*>
    <!ATTLIST hits
       total-count CDATA #IMPLIED
       count-of-pages CDATA #IMPLIED
    >

    <!ELEMENT hit (#PCDATA)>
    <!ATTLIST hit
       rank CDATA #REQUIRED
       score CDATA #IMPLIED
       uri CDATA #IMPLIED
    >

    <!ELEMENT field (#PCDATA)>
    <!ATTLIST field
       name CDATA #REQUIRED
    >

    <!ELEMENT navigation (navigation-page)*>
    <!ATTLIST navigation
       total-count CDATA #IMPLIED
       count-of-pages CDATA #IMPLIED
    >

    <!ELEMENT navigation-page EMPTY>
    <!ATTLIST navigation
       start-index CDATA #IMPLIED
    >

## Example

The search generator generates following xml content, for the query `query-string=cocoon&start-index=0&page-length=10`.

    <?xml version="1.0" encoding="UTF-8"?>
    <search:results date="1008437081064"
     query-string="cocoon" start-index="0" page-length="10"
     xmlns:search="http://apache.org/cocoon/search/1.0"
     xmlns:xlink="http://www.w3.org/1999/xlink">
     <search:hits total-count="125" count-of-pages="13">
       <search:hit rank="0" score="1.0"
         uri="http://localhost:8080/cocoon/documents/hosting.html"/>
       <search:hit rank="1" score="1.0"
         uri="http://localhost:8080/cocoon/documents/hosting.html"/>
       <search:hit rank="2" score="1.0"
         uri="http://localhost:8080/cocoon/documents/hosting.html"/>
       <search:hit rank="3" score="0.93121004"
         uri="http://localhost:8080/cocoon/documents/userdocs/actions/actions.html"/>
       <search:hit rank="4" score="0.93121004"
         uri="http://localhost:8080/cocoon/documents/userdocs/actions/actions.html"/>
       <search:hit rank="5" score="0.7112235"
         uri="http://localhost:8080/cocoon/documents/mail-archives.html"/>
       <search:hit rank="6" score="0.70967746"
         uri="http://localhost:8080/cocoon/documents/userdocs/
         serializers/link-serializer.html"/>
       <search:hit rank="7" score="0.6881721"
         uri="http://localhost:8080/cocoon/documents/userdocs/
         serializers/text-serializer.html"/>
       <search:hit rank="8" score="0.6881721"
         uri="http://localhost:8080/cocoon/documents/userdocs/
         serializers/vrml-serializer.html"/>
       <search:hit rank="9" score="0.6666666"
         uri="http://localhost:8080/cocoon/documents/userdocs/
         serializers/svgpng-serializer.html"/>
     </search:hits>
     <search:navigation total-count="125" count-of-pages="13"
       has-next="true" has-previous="false" next-index="10" previous-index="0">
       <search:navigation-page start-index="0"/>
       <search:navigation-page start-index="10"/>
       <search:navigation-page start-index="20"/>
       <search:navigation-page start-index="30"/>
       <search:navigation-page start-index="40"/>
       <search:navigation-page start-index="50"/>
       <search:navigation-page start-index="60"/>
       <search:navigation-page start-index="70"/>
       <search:navigation-page start-index="80"/>
       <search:navigation-page start-index="90"/>
       <search:navigation-page start-index="100"/>
       <search:navigation-page start-index="110"/>
       <search:navigation-page start-index="120"/>
     </search:navigation>
    </search:results>

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