SEARCH -- search content

Inline search, shows a search result embedded in a topic


Parameter Description Default:
Search term. Is a keyword search, literal search, regular expression search, or query, depending on the type parameter. SearchHelp has more required
web Comma-separated list of webs to search. e.g.
web="Main, Know"
The special word all means all webs that do not have the NOSEARCHALL preference set to on in their WebPreferences.
You can specifically exclude webs from an all search using a minus sign - for example, web="all,-Secretweb". Caution: The "all,-Secretweb" syntax does not exclude subwebs of the excluded web. It applies to only a single web. See Foswikitask:Item8893 AccessControls are respected when searching webs; it is much better to use them than NOSEARCHALL. Wildcards are not currently supported for web names.
Current web
topic Limit search to topics e.g.
Note this is a list of topic names and must not include web names. Adding a topic restriction to a search can greatly improve the search performance.
All topics in a web
excludetopic Exclude topics from search e.g.
excludetopic="WebHome, WebChanges"
scope Search topic name ("title"); the body ("text") of the topic; or title and body ("all") text
type Control how the search is performed when scope="text" or scope="all"
"keyword" - use Google-like controls as in soap "web service" -shampoo; searches word parts: using the example, topics with "soapsuds" will be found as well, but topics with "shampoos" will be excluded
"word" - identical to keyword but searches whole words: topics with "soapsuds" will not be found, and topics with "shampoos" will not be excluded
"literal" - search for the exact string, like web service
"regex" - use a RegularExpression search like soap;web service;!shampoo; to search on whole words use \bsoap\b
"query" - query search of form fields and other meta-data, like (Firstname='Emma' OR Firstname='John') AND Lastname='Peel'
%SEARCHVARDEFAULTTYPE% preferences setting (currently literal)
order Sort the results of search by the topic names ("topic"), topic creation time ("created"), last modified time ("modified"), last editor's WikiName ("editby"), or named field of DataForms ("formfield(name)"). The sorting is done web by web; if you want to sort across webs, create a formatted table and sort it with TablePlugin's initsort. Note that dates are sorted most recent date last (i.e at the bottom of the table).
The web order is always alphabetical. When ordered by topic the result is first ordered by web and then by topic.
limit A number will limit the number of topics from which results will be returned. This is done after sorting if order is specified. Note that this does not limit the number of hits from the same topic when you have multiple="on". all
date limits the results to those pages with latest edit time in the given time interval.  
reverse If "on" will reverse the direction of the search. Does only apply to key specified by order. off
casesensitive If "on" perform a case sensitive search. (For type=query searches, casesensitive is always on. See QuerySearch for more flexible case comparison options) off
decode Reverse any encoding done to protect search terms by %URLPARAM{}% macro. Comma separated list of encodings, entered in reverse order of the URLPARAM macro arguments. Supported decoding types are entity|entities, safe and url.  
bookview If ="on", perform a BookView search, e.g. show complete topic text. Very resource demanding. Use only with small result sets off
nonoise If "on", shorthand for nosummary="on" nosearch="on" nototal="on" zeroresults="off" noheader="on" noempty="on" off
nosummary Show topic title only, no content summary off
nosearch Suppress search string off
noheader Suppress default search header
Topics: Changed: By: , unless a header is explicitly specified
Show default search header, unless search is inline and a format is specified
nototal Do not show number of topics found off
zeroresults If off, false or 0, suppress/replace all output if there are no hits. Can also be set to a FormattedSearch string to customise the output on - displays the summary, and number of topics found. "Number of topics: 0"
noempty If "on", suppress results for webs that have no hits. off
header Custom format results: see FormattedSearch for usage & examples  
format Custom format results: see FormattedSearch for usage & examples  
footer Custom format results: see FormattedSearch for usage & examples  
expandvariables If "on", expand embedded macros before applying a FormattedSearch on a search hit. Useful to show the expanded text, e.g. to show the result of a SpreadSheetPlugin %CALC{}% instead of the formula off
multiple If ="on", find multiple hits per topic. Each hit can be formatted. The last token is used in case of a regular expression ";" and search off (only one hit found per topic
nofinalnewline If "on", the search variable does not end in a line by itself. Any text continuing immediately after the SEARCH macro on the same line will be rendered as part of the table generated by the search, if appropriate. This feature is only active when format is defined. on
recurse If "on", recurse into subwebs, if subwebs are enabled. Note: recurse will currently search subwebs of explicitly excluded webs. (web="all, -Sandbox" recurse="on") will still search subwebs of Sandbox. This behavior is likely to change in a future release. off
separator Separator between search hits (only used when format is set) uses FormatTokens.
If separator is not defined, the default is "$n" (newline). Not defining the separator will additionally cause a newline to be added after a header and before a footer.
$n (Newline)
headingoffset Adds the given offset to any HTML headings generated in the search result. Works on headings defined by HTML tags as well as headings defined using foswiki markup. 0
newline Line separator within a search hit. Useful if you want to put multi-line content into a table cell, for example if the format parameter contains a $pattern() or a $formfield() the result of which may contain newlines, in which case you could use newline="%BR%" $n (Newline)
pagesize number of items to show per page 25
showpage Page of items to show (starts at 1) (overridden by the value specified by the URL parameter hash from $previousurl and $nexturl) "1"
pager If "on" adds paging to your SEARCHes
Note: the default pager (when pagerformat is not defined) requires the parameters to the SEARCH to not change while paging, as it uses $previousurl and $nexturl. If you use time variable parameters, you will have to define your own pagerformat.
pagerformat Custom format results: see FormattedSearch for usage & examples filled from skin template
groupby Warning: this option is liable to change dramatically (and potentially incompatibly) in the next major release of foswiki. Setting to "none" applies only to multi-web SEARCHs, and means the header and footer are only output once - at the beginning and end of the list of results, and the order parameter is applied over the entire set of results (this setting removes the legacy that results are always partitioned by web) see SiteChanges for an example. web


  • %SEARCH{"wiki" web="%USERSWEB%" scope="topic"}%
  • %SEARCH{
        format="| $topic    | $summary    |"
    (displays results in a table with header - details)

Results are sorted alphanumerically on the web name (major key) and topic name (minor key). Only the minor key is affected by the order parameter.

TIP The appearance of the table emitted by the SEARCH may be controlled with TablePlugin's %TABLE{}% macro placed just before the %SEARCH{}%. Example: %TABLE{ tablewidth="90%" }%

FormattedSearch, QuerySearch, SearchHelp, SearchPatternCookbook, RegularExpression, TOPICLIST, WEBLIST
Topic revision: r1 - 16 Nov 2015, UnknownUser
Ideas, requests, problems regarding Foswiki? Send feedback