Editing Module:Find sources/doc (section)

== Making new templates ==

There are two basic ingredients to making a new source-finding template. The first is the template configuration module, and the second is the template invocation on the template page.

=== Template configuration page ===

To find the name of the template configuration page, take the page name of your proposed template without the namespace prefix, and add it to the base page of "Module:Find sources/templates/". For example, for [[Template:Find sources]], the configuration page is located at [[Module:Find sources/templates/Find sources]]. Note that the template must be capitalised exactly as the page name is, otherwise the arguments will not be passed through from the template page to the module.

The template configuration page should look something like this:

<syntaxhighlight lang="lua">
return {
	blurb = "Find sources for $1 – $2",
	introLink = {code = 'google'},
	links = {
		{code = 'google news', display = 'news'},
		{code = 'google newspapers', display = 'newspapers', tooltip = 'Search newspapers with Google Books'}
	},
	separator = ', ',
	isUsedInMainspace = true,
	class = 'custom-class',
	style = 'color: green; font-size: 110%;'
}
</syntaxhighlight>

* '''blurb''' - the text presented to users. There are two parameters available in the blurb, $1 and $2. $1 is the intro link, if specified, and $2 represents the other links. This field is required.
* '''introLink''' - an optional introductory link. If specified, this must be a [[#Link tables|link table]]. If the display value in the link table is not set, the search terms that the user entered will be used instead.
* '''links''' - an array of [[#Link tables|link tables]] defining the main links to be used by the template. This field is required.
* '''separator''' - the text separating the search engine links. This field is optional; the default value is taken from [[MediaWiki:Dot-separator]].
* '''isUsedInMainspace''' - set this to true if the template will be used in the main namespace. If this is not set, when the template is used in the main namespace it will produce an error and be put in [[:Category:Pages with templates in the wrong namespace]].
* '''class''' - a custom HTML class to apply to the template text. The "plainlinks" class is added by default. This field is optional.
* '''style''' - custom CSS to apply to the template text. This field is optional.

Once you have created your template configuration page, you need to add the template to [[Module:Find sources/templates]] in order for it to show up in the table of templates on this documentation page.

==== Link tables ====

[[Module:Find sources/links|Link tables]] are used in the "introLink" and "links" fields of the template configuration. They can contain three fields, "code", "display", and "tooltip". The "code" field is required, and must be one of the link codes listed in the table below. The "display" field is optional, and specifies a custom display value for that link to be used by the template. If the display field is not set, a default value is set by the module. The "tooltip" field is also optional, and specifies a custom tooltip for the link. HTML reserved characters are escaped by the module. If the field is absent, no tooltip is displayed. For the "introLink" field, the default value is the search text entered by the user; for the "links" field, the default value is defined in the link configuration modules.

The following table contains all the available link codes, with descriptions and examples.

{{#invoke:Find sources/autodoc|linkTable}}

=== Template invocation ===

The template invocation on the template page itself should look like this:

 &#123;{#invoke:Find sources|''template''}&#125;&lt;noinclude&gt;
 &#123;{#invoke:Find sources/autodoc|''template''}&#125;
 &lt;/noinclude&gt;

This activates the template code and also provides automatic documentation. <var>template</var> is the name of the template without the namespace prefix, and must be correctly capitalised.

If you want to use custom documentation from a /doc subpage instead of the automatic documentation, use this invocation instead:

 &#123;{#invoke:Find sources|''template''}&#125;&lt;noinclude&gt;
 &#123;{documentation}&#125;
 &lt;!-- Categories go on the /doc subpage, and interwikis go on Wikidata. --&gt;
 &lt;/noinclude&gt;