View source for Template:Search link/doc

{{redirect|Template:Sl|the template for linking to sections|Template:Section link}}
{{Documentation subpage}}

{{Warning|This template should not be used in [[WP:WIAA|articles]] as links to search result pages are among the [[WP:LINKSTOAVOID|links normally to be avoided]].}}

{{tsh|sl}}
This template creates a link that can be used to store a Wikipedia search
box query.  A search link is useful for [[collaborative search]] on [[Help:Talk|Talk pages]] and most other pages, but it is not to be used in articles.  If used in [[Wikipedia|article]]s, it outputs the above warning.

=== Basics ===

{{tlc|Search link|first|second|third}}
* The first parameter is for ''the search'', or query.
* The second parameter is a ''label for the link''.
* The third parameter is the ''search domain''.
The name of the template is ''Search link'', or ''sl'' for short.<br/>
The second and third parameters are optional and have defaults, so the short form is {{tlx|sl|''query''}}.

Both a search link and a search box go to the same search engine.  The same query produces the same result.

The basic search covers articles. It finds words and phrases composed of letters and numbers very quickly, but a basic search can also query for all articles that contain a string that includes punctuation, math, and other symbols as seen in the page [[wp:content|content]] or as seen in the page wikitext.

{| class=wikitable
|+ Basic search principles when using a search link
|valign=top|1
||{{tlc|Search link<br />|"search engine query"}}<br />
{{Search link|"search engine query"}}   
|There is one search term, a phrase that produces '''18''' results, including a [[wp|redirect]]. For one term, the page ranking rule is simple: title matches, on top. Two pages hit on "Search Engine Query" and one on "<nowiki>[[Search engine (computing)|search engine]]</nowiki> query".
|-
|valign = top |2
|dummy|{{tlc|Search link<br />|"search engine query"<br />insource:/"search engine query"/}}<br />
{{Search link|"search engine query" insource:/"search engine query"/ }}
|width=52%| Added a term: insource:/"''slash delimited regex''"/. Now there are '''15'''.  Three were filtered out because regex match ''only exact strings''. All other searches always ''ignore capitalization, punctuation, math, and other symbols'', like the ]] above. Proves a basic difference with search 1: only ''insource:'' searches wikitext. All other terms search what is rendered.
|-
|valign="top"|3
||{{tlc|Search link<br />|search engine query}}<br />
{{Search link|search engine query}}
||There are three search terms.  They produce '''1169''' results.  Many page ranking rules apply to make the top most likely and the bottom least likely, ''probably''.
|-
|valign=top|4
|dummy to enable the pipe character to pass|{{tlc|Search link<br />|search engine query<br />insource:/"search engine query"/}}<br />
{{Search link|search engine query insource:/"search engine query"/}}  
| Similar to search 3, the regex crawled character-by-character through the same '''1169'''-page filter to produce its same 15 results.  As much as that seems, 1169 is nothing compared to running an unfiltered (unaccompanied) regex exposed to the {{NUMBEROFPAGES}} pages on the wiki to produce some 15 results.<ref>Some users' default search domain is all namespaces. In cases like the bare regex search, the search engine protects itself by limiting ''all'' regex searches.  A bare regex that crawls through millions of pages can take over twenty seconds, and may even cost you an HTML timeout.  During that time very few other regex searches are allowed. Always use a filter with regex.</ref>
|-
|valign = top | 5
||{{tlc|Search link<br />|insource:/"2 + 2"/<br />prefix:Arithmetic<br />|"Arithmetic" titles & "2 + 2"}}<br />{{search link|insource:/2 \+ 2/ prefix:Arithmetic|"Arithmetic" titles & "2 + 2"}}
|The regexp is the first term, but the ''prefix:'' term first filters out all but a few [[wp:pagename|titles]] that start with the characters A-r-i-t-h-m-e-t-i-c, then the regexp crawls character-wise. Perhaps such a label conveys this to your team.
|}

This template differs from the search box superficially when searching for an equals sign. In the search  box you just say <kbd>=</kbd>, but here you must use the five-letter string <nowiki>{{=}}</nowiki>.<ref>Searching for an equals sign requires using a regexp. As with any template, use {{tl|1==}} or {{para|1}} to pass in an equals sign to any parameter, even the link label.</ref> 

In search 5 notice the need for the double quotes around the search pattern: <code>insource:/"''slash&nbsp;delimited&nbsp;regexp''"/</code>.  These protect any characters from being interpreted as regex metacharacters, and insures they are interpreted literally.  In basic searches quotes are always used, to enable exact-string searches in the wikitext. In advanced searches the double quotes are not used, so that the metacharacters can act as conditional and branching operators to create generalized patterns. 

Search 2 exemplifies the easiest filter to apply to accompany any regexp search.  It just takes the same phrase and make it a separate term. Given any regexp <kbd>insource'''/'''"''exact string search''"'''/'''</kbd>, just accompany it by an <kbd>insource:"''exact string search''"</kbd>.  The later term will always act like a perfect filter, matching every alphanumeric, and ignoring every non-alphanumeric, speeding through an indexed search to filter out pages the regexp couldn't possibly match.  As for other filters, a namespace is weak, but every additional term increases  ''regex'' power.

The next section covers ''Search link'' arguments more in depth.

=== Advanced ===
{{details|topic=Search engine queries|Help:Searching}}

Here are the [[help:Template#Parameters|template parameters]] for Search link.

{| class="wikitable"
|-
|'''1'''
|or {{para|query}} || The search query.  It becomes the text of the search link (how the link will look) so it accepts {{para|text}}.
|-
|'''2'''
|or {{para|label}} || A label to replace the default text.  A new look to the link, so it also accepts {{para|link}}. Defaults to show the search query. 
|-
|'''3'''<br />⋮<br/>'''20'''
|style="white-space: nowrap;"|

<!--{{Big|{{!}}}}{{small|{{param|3}}}}{{Big|{{!}}}}{{small|{{param|4}}}}{{Big|{{!}}}}{{small|{{param|5}}}}{{Big|{{!}}}}…{{big|{{!}}}}{{small|{{param|20}}}}-->
{{Big|{{!}}}}'''3'''{{Big|{{!}}}}'''4'''{{Big|{{!}}}}'''5'''{{Big|{{!}}}}…{{big|{{!}}}}'''20'''<br />
or {{para|ns}} 
|
The search domain: one or more namespaces abbreviated "ns''x''", where ''x'' is
any namespace number.<br /><code>|'''ns'''''x''|'''ns'''''x''|'''ns'''''x''|…|'''ns'''''x''</code>, or 
<code>'''ns='''ns''x''&ns''x''&ns''x''…&ns''x''</code>, or <code>'''ns='''all</code>. Defaults to ns0.
|-
|
|{{para|limit}} || Number of search results on the first page.  Named parameter only, not positional. 
|}
{{namespaces}}

You only ever need to use parameters 3–20 if you want a profile of two or more namespaces for a search domain.
Otherwise you can just say the namespace name (or ''all'') at the beginning of the query,
or a ''prefix'' parameter at the end of the query.

When the query goes through this template, the default search domain is article space, just as it is for basic users. The default search domain of a user, logged-in or not, is article space ''unless the user set their preference''.<ref>Advancing editors who begin to search for Wikipedia's other pages may at times set their default search domain (at [[Special:Search]] ''Advanced'') to ''[[Special:statistics|all]]''. Setting search to ''all'' is the most likely scenario to "set and forget".  Since that includes article space, the usual results are comparable.</ref>  But no matter who uses a search link the results will always be the same. "Cut and paste" can never guarantee the same results for a search, but a search link can because the search domain is just article space for everyone, or search domain is the set of namespaces you set for everyone.

If you know the numbers of your search domain profile, you just type them in <code>{{nowrap|1=ns=ns0&ns1&ns2600}}</code>. (You can get them from the [[wp:namespace|namespace]] table to the right.) Otherwise you refine your query ''and'' search domain on the search results page, whose ''Advanced'' interface is designed to select and adjust namespaces with no knowledge of the namespace numbers. Once that produces satisfactory results, you copy the namespaces string from the URL (in your browser's address bar), and paste it into {{para|ns}}, and you can get the query from the search results page search box, and paste it as the query, and that's your search link.

If you have just one namespace in your search link, and it's not article space, 
you can specify it by saying, say, <kbd>ns=ns10</kbd>, or  <kbd>|ns10"</kbd> at parameter position 3 or greater:
:{{#invoke:DemoTemplate|sl|"search link" namespace||ns10}}
For ''one'' namespace the explicit name is preferred:
:{{#invoke:DemoTemplate|sl|Template:"search link" namespace}} 
The explicit name is preferred if you will be publishing or saving your search link. That way when it is run later the search domain shows up explicitly at the beginning of the search box of the search results page to inform the user.  Otherwise ''only the URL'' and ''only the namespace-profile dialog frame'' pops up on the search results page to inform the user. When it is two or more namespaces, these things always happen, because the query only accepts one namespace (as the first term only).  But '''''all''''' is also an informative query, a pseudo-namespace for Search only.  If you see a query begin with <kbd>all:</kbd>, the URL will be loaded with all the namespace parameters.

You can use "all" in {{tlf|Search link}} to specify all namespaces: 
:<code>{<nowiki/>{sl|''query''|'''ns=all'''}}</nowiki></code>
:<code>{<nowiki/>{sl|''query''|''label''|'''all'''}}</nowiki></code>
but again, it is far more preferable to say
:{{#invoke:DemoTemplate|sl|all:"search link" namespace}}
than it is to use:
:{{#invoke:DemoTemplate|sl|"search link" namespace||all}} 
for the reasons given just above.
''But'' when specifying "all", the query time is about seven times greater because there are [[special:statistics|that many more pages on the wiki]] than there are articles. If a more targeted search is possible, it runs much more quickly than the "all" search.

For example, if you have a query for which know the search domain is 10 and 11, and you want ''no label'', then you need a parameter 3, ''but you need no parameter 2'', so per the [[Help:Template#Parameters|template parameter rules]] the search link can be made in four general ways:
*<code>{<nowiki/>{sl|''query'''''||'''ns10|ns11}}</code>  When parameter 1 unnamed, and parameter 2 is unnamed '''{{big|{{!}}&thinsp;{{!}}}}''' (defined as the "empty string"), then parameter 3 can be defined unnamed <kbd>ns10</kbd>, and parameter 4 can be defined unnamed <code>ns11</code>, and so on.  Nothing is named because everything is defined.
*<code>{<nowiki/>{sl|''query''|3=ns10|4=ns11}}</code> Parameter 2 is undefined, but that's fine because parameters 3 and above are all named... 
*<code>{<nowiki/>{sl|''query''|ns=ns10&ns11}}</code>  or the empty positional parameter '''{{big|{{!}}&thinsp;{{!}}}}''' is not needed when {{para|ns}} defines itself named.
*<code>{<nowiki/>{sl|query=''query''|label=|ns=ns10&ns11}}</code> Everything is explicitly named.

For another example, if you select the "Wikipedia" and "Help" namespaces, then run a query, the URL will show <code>ns4=1&ns12=1</code>. Copy that and paste it to {{para|ns|ns4{{=}}1&ns12{{=}}1}}.  (Note: you can ignore the "=1" part from the URL.)

Note how the URL contains ns0, ns1, ns2, and ns3, and how it got them:
:<code><nowiki>{{sl|systems operations|3=ns2|4=ns1|ns=ns3|20=ns0}}</nowiki></code>  &rarr; {{sl|systems operations prefix:{{FULLPAGENAME}}|systems operations|ns2|4=ns1|ns=ns3|20=ns0}}
:<code><nowiki>{{sl|query = systems operations|||ns2|ns1|ns3|ns0}}</nowiki></code> &rarr; {{sl|query = systems operations prefix:{{FULLPAGENAME}}||systems operations|ns2|ns1|ns3|ns0}}
:<code><nowiki>{{sl|systems operations|3=ns2&ns1&ns3&ns0}}</nowiki></code> &rarr; {{sl|systems operations prefix:{{FULLPAGENAME}}|systems operations|3=ns2&ns1&ns3&ns0}}

If you need to develop a highly specific search domain, a very elaborate one carved out of a set of the thirty namespaces, then you will have developed this at the search results page using the ''Advanced'' search domain picker there.  Then you just cut and paste the entire string ''from the URL'' of your found ''search domain'' namespaces, and paste it into one named parameter {{para|ns}}. 

To type in namespaces 0, 2, 4, 5, 7 and 9, with no label, the two easiest ways are:
* <code>{<nowiki/>{sl|''query''||'''ns0|ns2|ns4|ns5|ns7|ns9'''}}</code>
* <code>{<nowiki/>{sl|''query''|ns='''ns0&ns2&ns4&ns5&ns7&ns9'''}}</code>
The order is irrelevant.

== Advanced examples ==
{{for|examples| Help:Searching/Regex/Sandboxing}}

All these involve <code>insource:/''slash delimited regex''/</code> '''with filters'''. Any search link with an <code>insource:/''regex''/</code> search should always provide the additional query terms that would filter (reduce) the search domain as much as possible.  This template defaults to article space if no namespace is given, which is a filter.

;Quoting
The need to match an equals in an article is not surprising, and is basic. You have to use {{tl|1==}} or {{para|query}} or {{para|1}} just to get the equals sign in your query to the search engine, or {{tl|!}} to get the pipe character to the search engine. Both pipe characters and the equals signs are template ''sensitive'' for all templates, so you can always quote them with curly brackets like that inside templates.  Although the search ''box'' can take = and | directly, quoting is necessary in the search ''link'' because otherwise they have their parameters meaning.

Regex are ''sensitive'' to punctuation, brackets, math and other symbolic characters, collectively known as "[[regex#Character classes|punctuation]]" so you quote them, because otherwise they have their regex ''metacharacter'' meaning. The "metacharacters" of CirrusSearch have claimed most punctuation characters as functions in their regex, but you don't have to know all the metacharacter functions just to search for them as targets literally.  You can simply quote all punctuation to search for them as literal targets in wikitext.  The way to easily quote every character in an entire regexp is to put the whole term in quotes: <kbd>insource:/"''regexp with literal characters''"/</kbd>

To get a pipe character through both the template and the search engine to target it as a character in wikitext, you have to quote it twice, hence the frequent need for the six characters <kbd>\{{tl|!}}</kbd> in an advanced search link.  The equals sign is not a metacharacter, so it does not have to be quoted twice, as the pipe character does.  The pipe character is a metacharacter that means OR.

To generate advanced regex searches, see about doing so at {{tl|regex}}.
{{Help:Searching/Features}}<!--
-->{{Help:Searching/Regex}}{{Help:Searching/Regex/Sandboxing}}

== See also ==
{{Internal search templates common doc|seealso=}}

<includeonly>{{Sandbox other||
<!-- Categories below this line, please; interwikis at Wikidata -->
[[Category:Search templates]]

[[be:Шаблон:Пошук]]
[[ja:Template:Search]]
}}</includeonly>