%META:TOPICINFO{author="TWikiContributor" date="1156516487" format="1.1" version="1"}%
%META:TOPICPARENT{name="NatSkin"}%

---+!! %TOPIC%
Search facility for the NatSkin.

<nop>NatSearch unifies the Seach and the Jump box known from the standard TWiki. You can 
use one input field to either jump to a topic or start a content query.

<nop>NatSearch is heavily inspired by the <nop>PhotonSearch of the TWiki:Plugins/PhotonSkin.

---+++ Usage
This basically works in three modes: 
   1 GO: look up the named topic and jump to it immediately if found
   2 topic search: search a topic whose name matches the search string
   3 content search: search a topic whose content matches the search string

<nop>NatSearch proceeds along the following lines:
   1 the search string starts with an uppercase letter: 
      1 try a GO: the topic is looked up the following way:
         1 look it up in ="web"= if the search string is of the form ="web.topic"=
         2 or look it up in the current web 
         3 or look it up in all public webs; in case there are topics of the
           same name in different webs the first topic
           found is used, webs being sorted alphabetically
      2 fallback to a topic search when a direct jump in 1.1 is not possible 
      3 fallback to content search when the topic search in 1.2 fails
   2 the string starts with a /: normal content search
   3 the string does not start with an upper case letter or /
      1 try a topic search
      2 fallback to content search

If only one topic was found in 2. or 3. then <nop>NatSearch jumps to that topic directly.

---+++ Options
The search string may be prepended with a set of options that are separated from the
rest of the search string with a colon(:). Known options are:
| *Option* | *Description* |
| g | global search (default is local) |
| l | local search |
| u | case-sensitive search (default is to ignore case) |

A search string may consist of a list of terms that are retrieved. If a term shall contain
spaces it can be surrounded by double quotes. Each term may be preceded with a minus (-) to
exclude this term from the hit set.

---+++ Examples
| *Search* | *Description* |
| <nop>TWikiUsers | if the current web is the %MAINWEB% go to the <nop>TWikiUsers  |
|                 | if the current web is the %TWIKIWEB% go to the <nop>TWikiUsersGuide |
| g:twikiusers | list all topics in all webs whose name match "twikiusers" |
| /<nop>TWikiUsers | list all topics that contain the word "<nop>TWikiUsers" |
| gu:copyright | list all topics that contain the word "copyright" in lowercase |
| g:copyright -webpref | list all topics that contain the word "copyright" but not "webpref" |
| g:"Good morning" -natskin | list all topics that contain the term "Good morning" but not "natskin" |


---+++ Customization
<nop>NatSearch can be restricted to certain webs and topics by setting WebPreferences.
Besides the NOSEARCHALL feature of every web that excludes a web from search the following variables
 restrict the hit set:

| *Name* | *Description* |
| =NATSEARCHINCLUDEWEB= | a regular expression that must match webs to be considered |
| =NATSEARCHEXCLUDEWEB= | a regular expression that must not match a web |
| =NATSEARCHINCLUDETOPIC= | a regular expression that must match a topic in the hit set |
| =NATSEARCHEXCLUDETOPIC= | a regular expression that excludes a topic from the hit set |

Furthermore, the WebPreferences variable =NATSEARCHTEMPLATE= can be set to a template topic that
is used instead of the skin's =search= template. This can be used in <nop>TWikiApplications to
define a customized look of search results.


-- Main.MichaelDaum - 25 Aug 2006
