NatSearch

Search facility for the NatSkin.

Description

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.

NatSearch is heavily inspired by the 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

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 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
TWikiUsers	if the current web is the Main go to the TWikiUsers
	if the current web is the TWiki go to the TWikiUsersGuide
g:twikiusers	list all topics in all webs whose name match "twikiusers"
/TWikiUsers	list all topics that contain the word "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

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
NATSEARCHINCLUDETOPIC	a regular expression that must match a topic in the hit set
NATSEARCHIGNORECASE	'on' or 'off', the default case match mode
NATSEARCHGLOBAL	'on' searches in all public webs, 'off' restricts search to the current web (default)
NATSEARCHEXCLUDEWEB	a regular expression that must not match a web
NATSEARCHEXCLUDETOPIC	a regular expression that excludes a topic from the hit set
NATSEARCHCONTENT	'on' searches content first, 'off' tries to find a matching topic name first (default), it will still GO to the named topic if it exists

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 TWikiApplications to define a customized look of search results.