%META:TOPICINFO{author="ProjectContributor" date="1655468868" format="1.1" version="1"}%
%META:TOPICPARENT{name="Macros"}%
---+ SEARCH -- search content
Inline search, shows a search result embedded in a topic
---++ Parameters
     %TABLE{sort="off"}%
     | *Parameter* | *Description* | *Default:* |
     | ="text"= <br> =search="text"= | 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.  <br/> =web="%USERSWEB%, Know"= <br /> =web="all"= <br> \
     The special word =all= means all webs that do *not* have the =NOSEARCHALL= preference set to =on= in their %WEBPREFSTOPIC%.<br />\
     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\
     [[AccessControl][AccessControls]] are respected when searching webs; it is *much* better to use them than =NOSEARCHALL=. Wildcards are not currently supported for web names.<br />\
     | Current web |
     | =topic= | Limit search to topics e.g. <br> \
=topic="%WEBPREFSTOPIC%"= <br /> =topic="*Bug"= <br> =topic="MyTopic,YourTopic"= <br> \
A topic, a topic with asterisk wildcards, or a list of topics separated by comma. <br> *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. <br> \
=excludetopic="Web*"= <br /> =excludetopic="%HOMETOPIC%, <nop>WebChanges"= <br> A topic, a topic with asterisk wildcards, or a list of topics separated by comma.<br> *Note* this is a list of *topic names* and must *not* include web names. |  |
     | =scope= | Search topic name (="topic"=); the body (="text"=) of the topic; or name and body (="all"=) | =text= |
     | =type= | Control how the search is performed when =scope="text"= or =scope="all"= <br /> ="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 <br /> ="word"= - identical to =keyword= but searches whole words: topics with "soapsuds" will not be found, and topics with "shampoos" will not be excluded <br /> ="literal"= - search for the exact string, like =web service= <br /> ="regex"= - use a RegularExpression search like =soap;web service;!shampoo=; to search on whole words use =\bsoap\b= <br /> ="query"= - [[query search]] of form fields and other meta-data, like =(Firstname='Emma' OR Firstname='John') AND Lastname='Peel'= | =%<nop>SEARCHVARDEFAULTTYPE%= [[%WIKIPREFSTOPIC%][preferences]] setting (currently =%SEARCHVARDEFAULTTYPE%=) |
     | =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 [[FormattedSearch][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). <br /> The web order is always alphabetical. When ordered by =topic= the result is first ordered by web and then by topic. | =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 [[TimeSpecifications#TimeIntervals][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 =%<nop>URLPARAM{}%= macro. Comma separated list of encodings, entered in reverse order of the =URLPARAM= macro arguments. Supported decoding types are =entity%VBAR%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 <br /> <span style='background: #FFB0B0;'> *Topics: Changed: By:* </span>, 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 &amp; examples | |
     | =format= | Custom format results: see *[[FormattedSearch]]* for usage &amp; examples | |
     | =footer= | Custom format results: see *[[FormattedSearch]]* for usage &amp; 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 =%<nop>CALC{}%= instead of the formula | =off= |
     | =multiple= | If ="on", find multiple hits per topic. Each hit can be [[FormattedSearch][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, -%SANDBOXWEB%" recurse="on")= will still search subwebs of =%SANDBOXWEB%=. This behavior is likely to change in a future release. | =off= |
     | =separator= | Separator _between_ search hits (only used when =format= is set) uses FormatTokens. <br />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="%<nop>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 <br> \
                      _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=. | =off= |
     | =pagerformat= | Custom format results: see *[[FormattedSearch]]* for usage &amp; 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 %SYSTEMWEB%.SiteChanges for an example. | =web= |
---++ Examples
   * <verbatim class="tml">%SEARCH{"wiki" web="%USERSWEB%" scope="topic"}%</verbatim>
   * <verbatim class="tml">
%SEARCH{
    "FAQ"
    nonoise="on"
    header="| *Topic: * | *Summary: * |"
    format="| $topic    | $summary    |"
}%</verbatim> _(displays results in a table with header - [[FormattedSearch#SearchTable][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.

<div class="foswikiHelp">%T% The appearance of the table emitted by the [[VarSEARCH][SEARCH]] may be controlled with TablePlugin's =%<nop>TABLE{}%= macro placed just before the =%<nop>SEARCH{}%=.  Example: =%<nop>TABLE{ tablewidth="90%" }%= </div>

%STOPINCLUDE%
---++ Related
FormattedSearch, QuerySearch, SearchHelp, SearchPatternCookbook, RegularExpression, [[VarTOPICLIST][TOPICLIST]], [[VarWEBLIST][WEBLIST]]
