Difference between revisions of "Module:Find sources/doc"

From blackwiki
Jump to navigation Jump to search
blackwiki>Mr. Stradivarius
(add template invocation info)
blackwiki>Mr. Stradivarius
(Add some info on autodocs and module config)
Line 91: Line 91:
 
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.
 
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 the following invocation instead:
+
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;{#invoke:Find sources|''template''}&#125;&lt;noinclude&gt;
Line 98: Line 98:
 
  &lt;/noinclude&gt;
 
  &lt;/noinclude&gt;
  
== Documentation ==
+
== Automatic documentation ==
  
The documentation for individual templates is generated by [[Module:Find sources/autodoc]].
+
Automatic documentation is provided for templates based on this module; the documentation is generated by [[Module:Find sources/autodoc]]. The autodoc module uses the following pages:
 +
* [[Template:Find sources documentation]] - the template used for most of the documentation content.
 +
* The template configuration page. Used to find the list of link codes, and to see if the template is used in articles.
 +
* The template documentation configuration page. Used to find template shortcuts.
 +
* The link documentation configuration page. Used to find descriptions of each of the search links.
 +
 
 +
== Configuration ==
 +
 
 +
Module-wide settings can be configured at [[Module:Find sources/config]] and [[Module:Find sources/autodoc/config]]
  
 
<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox||
 
<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox||

Revision as of 05:51, 29 September 2014

This module produces a list of links to search engines to help editors find sources about a given subject. It implements {{find sources}} and other similar templates. It is highly extensible; new templates and new link types can be added easily and by any user.

Usage

From wikitext

Usually, from wikitext this module should be used via a template, e.g. {{find sources}}. However, it is also possible to use it directly from #invoke, like this:

{{#invoke:Find sources|template|search term 1|search term 2|...}}
  • template is the name of the template that should be called. It must be the full page name of the template, without the namespace, and with the correct capitalisation. So, for Template:Find sources, the template name should be "Find sources"; "find sources" with a lower-case "f" would cause an error. This parameter is required.
  • search term 1, search term 2, etc., are the terms to be searched for in each of the search engine links. The first search term will appear in quotation marks, and subsequent search terms will be added without quotation marks. Each term will be separated by spaces. These parameters are all optional. If no parameters are given, the current page name will be used as a search term.

From Lua

Load the module with the following code:

local mFindSources = require('Module:Find sources')

You can then produce the list of search links like this:

mFindSources._main(template, searchTerms)
  • template is the template name, as outlined in the #From wikitext section above. This parameter is required.
  • searchTerms is an array of search terms. Each item in the array corresponds to a numbered search term as outlined in the #From wikitext section above. This parameter is optional.

Example syntax:

mFindSources._main('Find sources', {'Albert Einstein', '-"Marilyn Monroe"', 'relativity', 'science'})

Available templates

The following templates are available for use:

Template Description Example Configuration
Find sources The most widely used source-finding template. Until September 2014 it was transcluded on all AfD discussion pages. Find sources: Google (books⧼Dot-separator⧽news⧼Dot-separator⧽newspapers⧼Dot-separator⧽scholar⧼Dot-separator⧽free images⧼Dot-separator⧽WP refs)⧼Dot-separator⧽FENS⧼Dot-separator⧽JSTOR⧼Dot-separator⧽NYT⧼Dot-separator⧽TWL main, documentation
Find sources mainspace A source-finding template for use in mainspace. Used in Template:Notability. Find sources: "Example" – news⧼Dot-separator⧽newspapers⧼Dot-separator⧽books⧼Dot-separator⧽scholar⧼Dot-separator⧽JSTOR main, documentation
Find sources video games The source-finding template transcluded on AfD pages for video games and related topics. Find video game sources: "Example" – news⧼Dot-separator⧽newspapers⧼Dot-separator⧽books⧼Dot-separator⧽scholar⧼Dot-separator⧽JSTOR⧼Dot-separator⧽free images⧼Dot-separator⧽free news sources⧼Dot-separator⧽The Wikipedia Library⧼Dot-separator⧽NYT⧼Dot-separator⧽WP reference⧼Dot-separator⧽VG/RS⧼Dot-separator⧽VG/RL⧼Dot-separator⧽WPVG/Talk main, documentation

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:

return {
	blurb = "Find sources for $1 – $2",
	introLink = {code = 'google'},
	links = {
		{code = 'google news', display = 'news'},
		{code = 'google newspapers', display = 'newspapers'}
	},
	separator = ', ',
	isUsedInMainspace = true,
	class = 'custom-class',
	style = 'color: green; font-size: 110%;'
}
  • 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 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 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.

Link tables

Link tables are used in the "introLink" and "links" fields of the template configuration. They can contain two fields, "code" and "display". The "code" field is compulsory, 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. 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.

Code Description Example Configuration Notes
archive.org The Internet Archive, a digital library of public websites. Archive.org main, documentation
bing Bing, Microsoft's flagship search engine. Bing main, documentation
ccsearch the official search engine of Creative Commons CC search main, documentation
duckduckgo DuckDuckGo, a search engine that emphasizes protecting searchers' privacy and avoiding the "filter bubble" of personalized search results. DuckDuckGo main, documentation
google Google, the flagship search engine from Google Inc. Google main, documentation
google books Google Books, Google's search engine for books. Google Books main, documentation
google free images Google Images, Google's search engine for images. Only images compatible with Wikipedia's licensing are included. Free Google Images main, documentation
google news Google News, Google's search engine for news sites. Google News main, documentation In the past this link searched news archives, but this functionality has been removed by Google. Currently, only recent news articles are searched.
google newspapers Google Newspapers, a search of Google's digital archive of print newspapers. Google Newspapers main, documentation
google scholar Google Scholar, Google's search engine for academic papers and other scholarly research. Google Scholar main, documentation
jstor JSTOR, an online library containing digitised versions of academic journals. Requires a subscription. JSTOR main, documentation
new york times The website of The New York Times, a highly respected newspaper. New York Times main, documentation
vgrl Wikipedia:WikiProject Video games/Reference library internal archive search. VGRL main, documentation
vgrs Thibbs' Google RS, a custom Google search engine that limits the search to sites listed in Wikipedia:WikiProject Video games/Sources. VGRS main, documentation
vgtalk A search in the WikiProject Video games talk page and its archives under Wikipedia talk:WikiProject Video games. WPVG Talk main, documentation
wikipedia library A link to Wikipedia:The Wikipedia Library. This isn't actually a search link, but a portal page for various resources available only to Wikipedians. Wikipedia Library main, documentation
wikipedia reference search Wikipedia Reference Search, a Google search that only searches sites vetted by Wikipedians. Wikipedia Reference Search main, documentation
yahoo No description available Yahoo! main, documentation

Template invocation

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

{{#invoke:Find sources|template}}<noinclude>
{{#invoke:Find sources/autodoc|template}}
</noinclude>

This activates the template code and also provides automatic documentation. template 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:

{{#invoke:Find sources|template}}<noinclude>
{{documentation}}
<!-- Categories go on the /doc subpage, and interwikis go on Wikidata. -->
</noinclude>

Automatic documentation

Automatic documentation is provided for templates based on this module; the documentation is generated by Module:Find sources/autodoc. The autodoc module uses the following pages:

  • Template:Find sources documentation - the template used for most of the documentation content.
  • The template configuration page. Used to find the list of link codes, and to see if the template is used in articles.
  • The template documentation configuration page. Used to find template shortcuts.
  • The link documentation configuration page. Used to find descriptions of each of the search links.

Configuration

Module-wide settings can be configured at Module:Find sources/config and Module:Find sources/autodoc/config