From MegaZine3
Jump to: navigation, search
Search could also mean Wiki Search
Plugin: Search
Name Search
  • 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.


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.

Example file

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



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


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.

Plugin interactions


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


If the Links Plugin is loaded, a special url "protocol" can be used to start a search on a click with the mouse.

This allows to prepare a specific search that will run if the element providing such url is clicked.

This can be an <img> or <area> tag; or whatever element is supporting the url attribute. If e.g. an <area> is defined and an url attribute set with "search:" as protocol, the words added as value will be used as mandatory keys for an immediately triggered search.


On a page a list of topics is provided in kind of a table.

Behind each cell an area element is placed set like this one, which will list all hits for pages, where all 3 word "2014", "special" and "offer" are located.

<area url='search:2014 special offer' top='287' height='25' left='110' width='215' overlay='color(0,0.2,0x7feeee)' />

With a click inside the area a search will be started that uses the search text: "+2014 +special +offer"

This allows to offer "intelligent links" for topics that are spread across the MZ3 Title, and where the position i.e. page namer might change, and that can occur more than once.

Another use case could be an art catalog, whre the key words for a search are artists or technology.



  • Type: Boolean
  • Default: true

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


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


  • Type: Boolean
  • Default: true
  • Version: 2.0.10

Determines whether to clear the search input field after it is being focused for the first time. This saves the user from having to delete the default text ("Search"), which doubles as the text field's title, herself.


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


  • Type: Integer
  • Default: 0xFFEF00

The color to use for highlighting search results.


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


  • Type: Integer
  • Default: 20

The maximum number of search results to display.


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


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


  • Type: String
  • Default: ?q=$1&cat=$2&excerptlen=$3&bookid=$4
  • Version: 2.0.11

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.
  • $4: will be replaced with the book's id, which is an md5-hash generated from either the XML path or a user provided value. It can also be queried via the API.


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

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.

Custom server-side search

When implementing a custom server-side search script, have a look at the default implementation for reference. The input is given via the book@searchquery setting (see that settings documentation for what the variables represent). The output must be XML, and look as described in the following.

If an error occurs while searching (not if there are just no matches):

<search status="error" message="what went wrong"/>


<search status="ok">
  <result page="25"> <!-- page is the number of the page the result was found on -->
    <!-- A short excerpt surrounding the match(es) -->
  <!-- more search results... -->

These are the very basics. Your script may return more meta information for a match by adding more attributes to the result tag. Per default, there is one more attribute expected, result@matches. A list of these additional attributes may be given in the book@searchresults setting. All attributes with the names listed there will be made available to be used in the GUI in the LNG_SEARCH_RESULT_INFO localization string. I.e. for every attribute name listed in book@searchresults, an additional variable is tried to be put into the LNG_SEARCH_RESULT_INFO string (numbering starts at $2 and then goes on $3,$4...).

So for example if searchresults="ranking,matches,chapter" and LNG_SEARCH_RESULT_INFO were set to the following in the search.xml localization files:

<?xml version="1.0" encoding="utf-8"?>
<lang id="en">
  <!-- ... -->
  <langstring name="LNG_SEARCH_RESULT_INFO">Page $1 in chapter '$4' contains $3 match(es). Ranking is $2.</langstring>
  <!-- ... -->

it would evaluate to the following for the example result: Page 12 in chapter 'Concerning Hobbits' contains 12 match(es). Ranking is 3.4.


<book plugins="search" searchmethod="server"
    searchindex="myindex" searchhighlightcolor="0xFF0000">
    <!-- ... -->
MegaZine3 Plugin-related articles
Plugins Anchors · Background Sounds · Batchpages · Bookmarks · Console · ElementIDs · Gallery · Google Analytics · Help · JavaScript · Keyboard Navigation · Links · NavigationBar · Options · Overlays · Password · PDFLinks · Print · PrintPDF · SWFAddress· Search · Sidebar · Slideshow · Titles
Plugin Articles Writing a plugin · Writing a plugin II · Plugin development