Google Git
Sign in
apache / cocoon / 19fa7c660808d288d1d6231525a957b07558e5b6 / . / non-releases / trunk_before_flattening / src / documentation / src / content / xdocs / c21-block-lucene-search-generator / content_en.html
blob: 4824e64f9fa3d14ccf67fe8302708489a34a5f69 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Search Generator</title>
<link href="http://purl.org/DC/elements/1.0/" rel="schema.DC">
<meta content="Bernhard Huber" name="DC.Creator">
<meta content="This document describes the search generator of Cocoon." name="DC.Description">
</head>
<body>
<h1>Search Generator</h1>
<p>
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.
</p>
<p>
The xml content generated by SearchGenerator is described later.
</p>
<ul>
<li>Name : search</li>
<li>Class: org.apache.cocoon.generation.SearchGenerator</li>
<li>Cacheable: no.</li>
</ul>
<pre class="code">
&lt;map:generate type="search"/&gt;
</pre>
<p>or</p>
<pre class="code">
&lt;map:generate type="search"&gt;
&lt;query&gt;your query string&lt;/query&gt;
&lt;/map:generate&gt;
</pre>
<h1>Configuration</h1>
<p>
Configuring of the SearchGenerator involves mainly setting up
configuration needed by avalon component used for searching.
As today SearchGenerator uses the Avalon component
<span class="codefrag">org.apache.cocoon.components.search.LuceneCocoonSearcher</span>
for searching, the configuration is tailored for this component.
</p>
<table>
<tr>
<th colspan="1" rowspan="1">Parameter Name</th><th colspan="1" rowspan="1">Default</th><th colspan="1" rowspan="1">Description</th>
</tr>
<tr>
<td colspan="1" rowspan="1">analyzer</td><td colspan="1" rowspan="1">org.apache.lucene.analysis.standard.StandardAnalyzer</td>
<td colspan="1" rowspan="1">
This parameter defines the analyzer to use for searching. Take care to use a
compatible analyzer as used when generating the index.
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">index</td><td colspan="1" rowspan="1">index</td>
<td colspan="1" rowspan="1">
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.
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">query-string</td><td colspan="1" rowspan="1">queryString</td>
<td colspan="1" rowspan="1">
This parameter specifies the name of the query parameter name used
for passing the query-string, eg.
<span class="codefrag">http://foo/bar?queryString=cocoon</span>, for generating
xml content for query "cocoon".
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">page-length</td><td colspan="1" rowspan="1">PageLength</td>
<td colspan="1" rowspan="1">
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.
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">start-index</td><td colspan="1" rowspan="1">StartIndex</td>
<td colspan="1" rowspan="1">
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.
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">start-next-index</td><td colspan="1" rowspan="1">StartNextIndex</td>
<td colspan="1" rowspan="1">
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.
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">start-previous-index</td><td colspan="1" rowspan="1">StartPreviousIndex</td>
<td colspan="1" rowspan="1">
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.
</td>
</tr>
</table>
<h1>Query Parameters</h1>
<p>
This generator accepts following query parameters, the table below assumes
the default settings of the setup parameters.
</p>
<table>
<tr>
<th colspan="1" rowspan="1">Query Parameter Name</th><th colspan="1" rowspan="1">Default</th><th colspan="1" rowspan="1">Description</th>
</tr>
<tr>
<td colspan="1" rowspan="1">queryString</td><td colspan="1" rowspan="1">No default</td>
<td colspan="1" rowspan="1">
Specifies the query string, parsable by the search engine.
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">pageLength</td><td colspan="1" rowspan="1">10</td>
<td colspan="1" rowspan="1">
This value specifies the number of hits displayed per page.
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">startIndex</td><td colspan="1" rowspan="1">0</td>
<td colspan="1" rowspan="1">
Start displaying hits starting from this index (counting starts
at 0).
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">startNextIndex</td><td colspan="1" rowspan="1">0</td>
<td colspan="1" rowspan="1">
Start displaying hits starting from this index (counting start at 0).
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">startPreviousIndex</td><td colspan="1" rowspan="1">0</td>
<td colspan="1" rowspan="1">
Start displaying hits starting from this index (counting starts
at 0).
</td>
</tr>
</table>
<h1>Using SearchGenerator</h1>
<p>
Using the SearchGenerator needs some configuration steps regarding
<span class="codefrag">cocoon.xconf</span>, 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.
</p>
<p>
As SearchGenerator uses some avalon components be sure to configure
your <span class="codefrag">cocoon.xconf</span> properly. The avalon
component <span class="codefrag">org.apache.cocoon.components.search.LuceneCocoonSearcher</span>
is used by the SearchGenerator.
Usually this component is specified in
<span class="codefrag">cocoon.roles</span> and the <span class="codefrag">cocoon.xconf</span> file
for the default cocoon webapp.
</p>
<p>
Inside of a sitemap you have to define the SearchGenerator in the
generator componenets section.
</p>
<p>
Moreover you have to match a URI to the SearchGenerator processing, the
following example matches the URI <span class="codefrag">findIt</span> to the
SearchGenerator processing. The stylesheet <span class="codefrag">search2html.xsl</span>
transforms the xml content of SearchGenerator to html:
</p>
<pre class="code">
&lt;map:match pattern="findIt"&gt;
&lt;map:generate type="search"/&gt;
&lt;map:transform type="log"/&gt;
&lt;map:transform src="stylesheets/search2html.xsl"/&gt;
&lt;map:serialize/&gt;
&lt;/map:match&gt;
</pre>
<h1>DTD</h1>
<p>XML generated by SearchGenerator uses namespace
<span class="codefrag">http://apache.org/cocoon/search/1.0</span>.
The DTD of XML generated by SearchGenerator:
</p>
<pre class="code">
&lt;!ELEMENT results (hits,navigation)?&gt;
&lt;!ATTLIST results
date CDATA #IMPLIED
query-string CDATA #IMPLIED
start-index CDATA #IMPLIED
page-length CDATA #IMPLIED
&gt;
&lt;!ELEMENT hits (hit)*&gt;
&lt;!ATTLIST hits
total-count CDATA #IMPLIED
count-of-pages CDATA #IMPLIED
&gt;
&lt;!ELEMENT hit (#PCDATA)&gt;
&lt;!ATTLIST hit
rank CDATA #REQUIRED
score CDATA #IMPLIED
uri CDATA #IMPLIED
&gt;
&lt;!ELEMENT field (#PCDATA)&gt;
&lt;!ATTLIST field
name CDATA #REQUIRED
&gt;
&lt;!ELEMENT navigation (navigation-page)*&gt;
&lt;!ATTLIST navigation
total-count CDATA #IMPLIED
count-of-pages CDATA #IMPLIED
&gt;
&lt;!ELEMENT navigation-page EMPTY&gt;
&lt;!ATTLIST navigation
start-index CDATA #IMPLIED
&gt;
</pre>
<h1>Example</h1>
<p>The search generator generates following xml content, for the query
<span class="codefrag">query-string=cocoon&amp;start-index=0&amp;page-length=10</span>.
</p>
<pre class="code">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;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"&gt;
&lt;search:hits total-count="125" count-of-pages="13"&gt;
&lt;search:hit rank="0" score="1.0"
uri="http://localhost:8080/cocoon/documents/hosting.html"/&gt;
&lt;search:hit rank="1" score="1.0"
uri="http://localhost:8080/cocoon/documents/hosting.html"/&gt;
&lt;search:hit rank="2" score="1.0"
uri="http://localhost:8080/cocoon/documents/hosting.html"/&gt;
&lt;search:hit rank="3" score="0.93121004"
uri="http://localhost:8080/cocoon/documents/userdocs/actions/actions.html"/&gt;
&lt;search:hit rank="4" score="0.93121004"
uri="http://localhost:8080/cocoon/documents/userdocs/actions/actions.html"/&gt;
&lt;search:hit rank="5" score="0.7112235"
uri="http://localhost:8080/cocoon/documents/mail-archives.html"/&gt;
&lt;search:hit rank="6" score="0.70967746"
uri="http://localhost:8080/cocoon/documents/userdocs/
serializers/link-serializer.html"/&gt;
&lt;search:hit rank="7" score="0.6881721"
uri="http://localhost:8080/cocoon/documents/userdocs/
serializers/text-serializer.html"/&gt;
&lt;search:hit rank="8" score="0.6881721"
uri="http://localhost:8080/cocoon/documents/userdocs/
serializers/vrml-serializer.html"/&gt;
&lt;search:hit rank="9" score="0.6666666"
uri="http://localhost:8080/cocoon/documents/userdocs/
serializers/svgpng-serializer.html"/&gt;
&lt;/search:hits&gt;
&lt;search:navigation total-count="125" count-of-pages="13"
has-next="true" has-previous="false" next-index="10" previous-index="0"&gt;
&lt;search:navigation-page start-index="0"/&gt;
&lt;search:navigation-page start-index="10"/&gt;
&lt;search:navigation-page start-index="20"/&gt;
&lt;search:navigation-page start-index="30"/&gt;
&lt;search:navigation-page start-index="40"/&gt;
&lt;search:navigation-page start-index="50"/&gt;
&lt;search:navigation-page start-index="60"/&gt;
&lt;search:navigation-page start-index="70"/&gt;
&lt;search:navigation-page start-index="80"/&gt;
&lt;search:navigation-page start-index="90"/&gt;
&lt;search:navigation-page start-index="100"/&gt;
&lt;search:navigation-page start-index="110"/&gt;
&lt;search:navigation-page start-index="120"/&gt;
&lt;/search:navigation&gt;
&lt;/search:results&gt;
</pre>
</body>
</html>