View source for Template:Find substed templates notice/doc

{{Documentation subpage}}
{{tsh|fstn}}
{{no subst}}
{{template rating|beta}}
Emits a notice intended for Template doc pages with an embedded [[WP:Advanced search|Cirrus link]] to help prospective template users search for [[Wikipedia:Substitution|substed]] examples of the template. Text emitted is configurable.

== Usage ==
{{tlc|find substed templates notice}}{{br}}
{{tlc|fstn|''Template name''|sns{{=}}''search namespace''|msg{{=}}''Message''|lt{{=}}''anchor''|after{{=}}''more text''|noyears{{=}}yes}}

== Parameters ==

This template has one positional parameter and six named parameters, all optional:

* {{para|1}} – name of the template, excluding namespace (default: name of the current page; uses [[Help:Magic words#Variables|basepagename]] on /doc pages)
* {{para|sns}} – search namespace: what namespace to search for the template (default = {{pval|User talk}}; see [[Wikipedia:Namespace|list]])
*:::the special value {{pval|all}} (i.e., {{para|sns|all}}{{thinspace}}) may be used to search all namespaces simultaneously
* {{para|ns}} – namespace of the template being searched for; e.g., use {{para|ns|User}} for a userspace template; (default: {{pval|Template}}{{hairspace}})
* {{para|msg}} – message to display before the [[WP:Advanced search|Cirrus link]] (default = 'Find subst count and examples of this template on User talk pages using')
* {{para|lt}} – link text to display; (default: 'this advanced search link')
* {{para|after}} – text to append after the Cirrus link (default = ''<small>'(Patience; this may take a while.)'</small>'')
*:::the special value {{pval|no}} (i.e., {{para|after|no}}{{thinspace}}) may be used to suppress the text after the link.)
* {{para|noyears}} – set to {{pval|yes}} to disable search-by-year links. See {{slink||Search by year issues}}.
* {{para|sort}} – [[mw:Help:CirrusSearch#Explicit sort orders|Cirrus sort order]]; (optional; default: {{pval|relevance}})

== Examples ==
{{hatnote|Note: example 1 should return no results, as this template is not substed.}}
* {{tlg|find substed templates notice|code=y|_show_result=y}}
* {{tlg|Find substed templates notice|uw-vandalism4|code=y|_show_result=y}}
* {{tlg|Find substed templates notice|Notified|sns{{=}}Talk|code=y|_show_result=y}}
* {{tlg|Find substed templates notice|Notified|sns{{=}}Wikipedia|noyears{{=}}yes|code=y|_show_result=y}}
* {{tlg|find substed templates notice|uw-spam4im|msg{{=}}Find examples at|code=y|_show_result=y}}
* {{tlg|fstn|welcome mentee|sort{{=}}last_edit_desc|code=y|_show_result=y}}
* {{tlg|fstn|polltop|msg{{=}}Find examples at|after{{=}}no|code=y|_show_result=y}}
* {{tlg|fstn|RFDNote|msg{{=}}See examples|lt{{=}}here|after{{=}}no|sns{{=}}Help talk|noyears{{=}}y|code=y|_show_result=y}}
* {{tlg|fstn|welcome-retro|code=y|_show_result=y}}

== Notes ==

In most cases, this template should be used with no parameters, unless you are altering the message or link text. The {{slink||Examples}} above use parameter 1 so they can run on this doc page, but normally you would not need it. Param 1, explained [[#Parameters|§&nbsp;above]] as the "name of the template", is in reality the value of the hidden tag at the end of the template. Since the two are invariably the same, you don't need to include it, except in very rare cases; see {{slink||False positives and negatives}}.

=== Method ===
This template cannot find all substed templates. It depends upon a convention used in some templates of having the template name substed onto the page embedded in an [[HTML comment]]. The last example above, for example, depends upon finding the string <code><nowiki><!-- Template:Welcome-retro --></nowiki></code> substed onto the page. There can be any number of blanks–including none–between the template name and the [[HTML comment]] delimiters at each end, and there can be two, or three hyphens in each delimiter. Templates which are substed but which do not follow this convention cannot be found by this template.

=== Sorting ===
You can use the optional {{para|sort}} param to alter the [[mw:Help:CirrusSearch#Explicit sort orders|Cirrus sort order]]. For example, using {{para|sort|last_edit_esc}} is an option, but note that it applies to the whole page, not the date of the warning message. Another useful one may be {{pval|title_natural_asc}}, which will order the results in alphabetical order of username; this means all the [[WP:TA|temporary accounts]] will be shown first.
This sort value may be more useful for templates that are not usually placed on TAs, like [[Wikipedia:Welcoming committee/Welcome templates|Welcome templates]]. The default Cirrus order if you don't specify a value is {{pval|relevance}}.

=== Performance and timeout ===
The search link in {{str rep|{{Excerpt|Template:Find substed/doc|Performance and timeout|hat=no|inline=yes}}|This template|this template}}

=== False positives and negatives ===
{{Excerpt|Template:Find substed/doc|False positives and negatives|hat=no|inline=yes}}

=== Search by year issues ===

Successful display of accurate results using the search-by-year links depends on the appearance of the year as part of the date timestamp included in a [[WP:SIG|signature]] which appears after the hidden template id. This template cannot find substed templates in a given year that contain no signature, or which contain a signature without a timestamp, or which contain extraneous information between the hidden template id and the dated signature. Because pages in [[WP:subject namespace|subject namespaces]] generally contain no signature, it usually does not make sense to display the by-year links when parameter {{para|sns}} is present and specifies any subject namespace, with the exception of noticeboards and other boards like [[WP:Xfd]] in [[Wikipedia:Project namespace|project space]] which typically do contain dated signatures. The search-by-year links are on by default, but may be disabled using {{para|noyears|yes}}.

The search string used to find templates substed in a given year depends on the hidden template name string at the end of the template, and on a signature containing the date following it, in that order, with no intervening newline. A very few templates include both elements but in the reverse order, with the timestamped signature first and the hidden template id afterward. Such templates, such as [[WP:Teahouse/Invitation2]], {{tl|Notified}}, and some auto-sig templates cannot be found for a given year by this template, but they are few. They can still be searched without a year specified, so using {{para|noyears|yes}} is best in these cases.

----
{{notelist}}

==TemplateData==

{{TemplateData header}}
<templatedata>
{
	"description": "Emits a notice with an embedded Cirrus link to help find substed templates; intended for Template doc pages.",
	"params": {
		"1": {
			"label": "Template",
			"description": "Name of the template to search for (without the namespace)",
			"type": "wiki-page-name",
			"default": "Current pagename"
		},
		"sns": {
			"label": "Search namespace",
			"description": "what namespace to search for the template in ('all' searches all namespaces)",
			"type": "string",
			"default": "User talk"
		},
		"msg": {
			"label": "Message",
			"description": "Message to display before the Cirrus link",
			"type": "string",
			"default": "Find examples of this template substed onto User talk pages using"
		},
		"lt": {
			"label": "Link text",
			"description": "Link text to display underlying the Cirrus link",
			"type": "string",
			"default": "this advanced search link"
		},
		"after": {
			"label": "After",
			"description": "text to append after the Cirrus link ('no' suppresses the text)",
			"type": "string",
			"default": "(Patience; this may take a while.)"
		},
		"noyears": {
			"label": "No years",
			"description": "suppress display of by-year search links",
			"type": "boolean",
			"default": "no"
		}

	}
}
</templatedata>

== See also ==
* {{tl|Find substed}}
* {{tl|Single notice}}
* {{tl|Templates notice}}
* [[Wikipedia:Template index/User talk namespace]]
* [[Wikipedia:Welcoming committee/Welcome templates]]
<includeonly>{{Sandbox other||
<!-- Categories below this line -->
[[Category:Documentation shared content templates]]
}}</includeonly>