From MegaZine3

Search could also mean Wiki Search

Plugin: Search

Name	Search
Files	search.swf search.asul plugins/scripts/search.php

This plugin adds search functionality to the engine. It provides search based on an index and highlights results in the book if possible. There are two basic ways the plugin can produce search results:

• one is using the internal search functionality. For this purpose, the path to an index file must be given in book@searchindex. For more information on the index format, see below. The index will be loaded once in the beginning and then used to process search queries.
• the other is using a server based search script. A PHP example one will be provided, which implements the exact same functionality as the engine internal search routine. To use this mode, change book@searchmethod to "server" and define the category to search in using book@searchindex.

[edit] Index

The search index used by the default implementations is a simple text file where pages are separated by a \f control character (form feed, see Wikipedia for more information). Such an index can either be generated manually, or when generating it from a PDF, click "File > Save as Text..." ("Text (verfügbar)" in German). In most cases, though, it will be necessary to perform further clean up, e.g. removing special characters.

[edit] Example file

This example index was generated from the Wald PhD. Some cleanup was done regarding special characters and stop words.

Download

[edit] Highlighting

Search matches can be highlighted on the book's pages if they are accordingly formatted. For this feature to work, the text displayed on the pages must be embedded in a SWF file which embeds the font information. This can be achieved by creating a SWF from a FLA using static text fields, or when converting a PDF to SWF files (using PDF2SWF) using the parameter "-f", and if necessary "-F" (also see the corresponding info on the SWFTools Wiki).

[edit] Searching

When searching it is possible to define required and forbidden words, using the + and - characters as prefixes, respectively. For example, the query world -war +peace would find all pages containing at least peace, optionally also world, but not pages containing war.

[edit] Plugin interactions

If the JavaScript plugin is loaded, it will be possible to trigger a search using the JavaScript API.

[edit] Settings

searchclear

• Type: Boolean
• Default: true

Determines whether to clear the search input field after sending the query (pressing enter) or not.

searchexcerptlength

• Type: Integer
• Default: 200

The length of the excerpt to show for a search result, i.e. the text surrounding the first match on a page that gets displayed for a search match, to give the user a better idea of the context of the hit.

searchhighlight

• Type: Boolean
• Default: true

Determines whether to highlight matches on the pages. Note that all required and optional words will be highlighted, regardless of the page was part of the search result or not (i.e. excluded due to forbidden words).

searchhighlightcolor

• Type: Integer
• Default: 0xFFEF00

The color to use for highlighting search results.

searchindex

• Type: String or Definition

This setting is required, regardless of the book@searchmethod used. It has a different use, depending on the used mode, though:

• client: in client mode, this defines the path to the index file to load and use for searching.
• server: in server mode, this defines the name of the category to search in.

As of version 2.0.8 it is also possible to localize the search index by using the definition format. In that case, you can map language ids to the search index to use for that language. For example to use the index index_english for the English localization, and index_german for the German one, the attribute value would look like this: en(index_english); de(index_german).

• See also: book@searchquery

searchlimit

• Type: Integer
• Default: 20

The maximum number of search results to display.

searchmethod

• Type: {client, server}
• Default: client

The search method to use:

• client: the engine internal search will be used. This requires book@searchindex to be a path to the index file to use.
• server: an external server-side search will be used. The URL of the search script can be set using book@searchprovider.

searchprovider

• Type: String
• Default: plugins/scripts/search.php

The server-side search script to use for generating search results. The default search script expects only a few parameters such as the category to search in and the actual search query. The length of the excerpts can be set to. When using a custom search script, use book@searchquery to adjust the structure of the actual query.

The default script expects the index files to be located in a subdirectory named index, i.e. at plugins/scripts/index, and be named after the categories that are searched in, with the extension .txt. For example, when using searchindex="myindex" the file plugins/scripts/index/myindex.txt would be used as the index file.

searchquery

• Type: String
• Default: ?q=$1&cat=$2&excerptlen=$3

This variable can be used to adjust the actual query sent to the server when using searchmethod="server", which might be necessary when using a custom search script. This string will be appended to the path defined in book@searchprovider, and provides three variables:

• $1: will be replaced with the actual search query entered by the user.
• $2: will be replaced with the category to search in, which is the value of book@searchindex.
• $3: will be replaced with the wanted length of excerpts, which is the value of book@searchexcerptlength.

searchresults

• Type: String
• Default: matches

This in an advanced setting which can be used to define names of additional return values to use in the GUI. It can only be used when using book@searchmethod="server".

The setting must be a comma separated list (e.g. for more items, matches,ranking,...), where each word stands for an attribute in the returned result XML. E.g. if your serverside search script returns an XML like this:

<search status="ok">
    <result matches="12" ranking="3.4" page="12" chapter="Concerning Hobbits">
        <![CDATA[...some text excerpt...]]>
    </result>
</search>

You would probably also want to use the "ranking" and "chapter" attributes when displaying your results. To do that, adjust the LNG_SEARCH_RESULT_INFO string in the language files by adding additional variables ($X, where X is a number. $1 is always reserved for the page number, the following numbers stand for the attributes defined in this setting, in the same order. E.g. if this setting were set to matches,ranking, then $2 would be evaluated to the content of the matches attribute of a result, and $3 to the content of the ranking attribute.

[edit] Example

<book plugins="search" searchmethod="server"
    searchindex="myindex" searchhighlightcolor="0xFF0000">
    <!-- ... -->
</book>