Module:Find sources
This Lua module is used on many pages, so changes to it will be widely noticed. Please test any changes in the module's /sandbox or /testcases subpages. Please consider discussing changes on the talk page before implementing them. |
This module is subject to page protection. It is a highly visible module in use by a very large number of pages, or is substituted very frequently. Because vandalism or mistakes would affect many pages, and even trivial editing might cause substantial load on the servers, it is protected from editing. |
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.
Alternatively the following can be used, which will convert any title to a search query, with the main portion of the title in quotation marks, and any parenthetical disambiguator outside quotation marks.
{{#invoke:Find sources|template|title=title}}
- template as above, 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.
- title the title to be converted to a search query. This is processed in the same way as the subpage name of the page if no parameters are used.
From Lua
Load the module with the following code:
<syntaxhighlight lang="lua"> local mFindSources = require('Module:Find sources') </syntaxhighlight>
You can then produce the list of search links like this:
<syntaxhighlight lang="lua"> mFindSources._main(template, searchTerms) </syntaxhighlight>
- 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. Alternatively, an empty table with the
title
key set will automatically generate a query as described above. This parameter is optional.
Example syntax:
<syntaxhighlight lang="lua"> mFindSources._main('Find sources', {'Albert Einstein', '-"Marilyn Monroe"', 'relativity', 'science'}) </syntaxhighlight>
Available templates
The following templates are available for use:
Lua error in package.lua at line 80: module 'Module:Find sources/autodoc/config' not found.
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 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.
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
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.
Lua error in package.lua at line 80: module 'Module:Find sources/autodoc/config' not found.
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>
Adding new links
New links are added to Module:Find sources/links. Link codes should be short but descriptive, and should be in lower case. For example, the link code for Google search is "google".
The link configuration page should look something like this:
<syntaxhighlight lang="lua"> return { url = '//www.google.com/search?as_eq=wikipedia&q=$1', display = 'Google',
description = 'Google, the flagship search engine from Google Inc.',
} </syntaxhighlight>
Parameter | Description |
---|---|
url | The url to perform the search. This field takes a parameter $1, which is the URL-encoded search text entered by the user. This field is required. |
display | If a display value is not specified in the template configuration, this value is used instead. This field is required. |
separator | This is used to separate the search terms entered by the user. This is optional, and defaults to "+" (a URL-encoded space). |
description | a brief description of what the search engine link does. This is used in the template documentation to generate the list of link descriptions, and also to make the descriptions in the table of link codes above. This is optional, but recommended. |
notes | notes about the search engine link. These are put in the table of link codes above, but they are not put in the template documentation for individual source-finding templates. This field is optional.
tooltip |
tooltip |
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.
Template documentation configuration page
This page is located at the "/autodoc" subpage of the template configuration page. It is only used to generate the documentation, not to generate any of the actual template output, so it does not need to be protected. It should look something like this:
<syntaxhighlight lang="lua"> return { shortcuts = {'shortcut1', 'shortcut2'}, description = 'This template is used to provide source links on AfD pages', docIntro = 'This template produces a series of search-engine links to be used on AfD pages.' } </syntaxhighlight>
- shortcuts - an array of shortcuts that redirect to the template page. These are displayed on the template documentation page using the {{template shortcut}} template.
- description - a brief description of what the template does. This is displayed on this documentation page in the table of available templates.
- docIntro - text to be used instead of the first sentence of the template documentation for individual source-finding templates. This is optional, and the default value is "This template produces a series of links to various search interfaces to help find additional reference material for articles."
Configuration
The messages used in this module can be found at Module:Find sources/config and Module:Find sources/autodoc/config. This can be helpful for translating this module for use in other languages. Note that any template and link configuration used must also be translated.
-- This module implements {{find sources}} and other similar templates, and -- also provides a mechanism to easily create new source-finding templates. -- Define constants local ROOT_PAGE = 'Module:Find sources' local TEMPLATE_ROOT = ROOT_PAGE .. '/templates/' -- for template config modules local LINK_CONFIG = ROOT_PAGE .. '/links' -- for link config modules local CONFIG_PAGE = ROOT_PAGE .. '/config' -- for global config -- Load required modules local checkType = require('libraryUtil').checkType local cfg = mw.loadData(CONFIG_PAGE) local p = {} local function maybeLoadData(page) local success, data = pcall(mw.loadData, page) return success and data end local function substituteParams(msg, ...) return mw.message.newRawMessage(msg, ...):plain() end local function renderSearchString(searchTerms, separator, transformFunc) -- This takes a table of search terms and turns it into a search string -- that can be used in a URL or in a display value. The transformFunc -- parameter can be used to transform each search term in some way (for -- example, URL-encoding them). local searchStrings = {} for i, s in ipairs(searchTerms) do searchStrings[i] = s end if transformFunc then for i, s in ipairs(searchStrings) do searchStrings[i] = transformFunc(s) end end return table.concat(searchStrings, separator) end function p._renderLink(code, searchTerms, display, tooltip) -- Renders the external link wikicode for one link, given the link code, -- a table of search terms, and an optional display value and tooltip. -- Get link config. local links = maybeLoadData(LINK_CONFIG) local linkCfg = links[code] if not linkCfg then error(string.format( "invalid link code '%s'; no link config found at [[%s]]", code, LINK_CONFIG )) end -- Make URL. local url do local separator = linkCfg.separator or "+" local searchString = renderSearchString( searchTerms, separator, mw.uri.encode ) url = substituteParams(linkCfg.url, searchString) end if tooltip then return string.format('<span title="%s" style="border-bottom: 1px dotted;">[%s %s]</span>', mw.text.encode(tooltip), url, display or linkCfg.display) else return string.format('[%s %s]', url, display or linkCfg.display) end end function p._main(template, args) -- The main access point from Lua. checkType('_main', 1, template, 'string') checkType('_main', 2, args, 'table', true) args = args or {} local title = mw.title.getCurrentTitle() -- Get the template config. local templateCfgPage = TEMPLATE_ROOT .. template local templateCfg = maybeLoadData(templateCfgPage) if not templateCfg then error(string.format( "invalid template name '%s'; no template config found at [[%s]]", template, templateCfgPage )) end -- Namespace check. if not templateCfg.isUsedInMainspace and title.namespace == 0 then local formatString = '<strong class="error">%s</strong>' if cfg['namespace-error-category'] then formatString = formatString .. '[[%s:%s]]' end return string.format( formatString, cfg['namespace-error'], mw.site.namespaces[14].name, cfg['namespace-error-category'] ) end -- Get the search terms from the arguments. local searchTerms = {} for i, s in ipairs(args) do searchTerms[i] = s end if not searchTerms[1] then -- Use the current subpage name as the default search term, unless -- another title is provided. If the page uses a disambiguator like -- "Foo (bar)", make "Foo" the first term and "bar" the second. local searchTitle = args.title or title.subpageText local term, dab = searchTitle:match('^(.*) (%b())$') if dab then dab = dab:sub(2, -2) -- Remove parens end if term and dab then searchTerms[1] = term searchTerms[2] = dab else searchTerms[1] = searchTitle end end searchTerms[1] = '"' .. searchTerms[1] .. '"' -- Make the intro link local introLink if templateCfg.introLink then local code = templateCfg.introLink.code local display = templateCfg.introLink.display or renderSearchString( searchTerms, ' ' ) local tooltip = templateCfg.introLink.tooltip introLink = p._renderLink(code, searchTerms, display, tooltip) else introLink = '' end -- Make the other links local links = {} local separator = templateCfg.separator or cfg['default-separator'] local sep = '' for i, t in ipairs(templateCfg.links) do links[i] = sep .. p._renderLink(t.code, searchTerms, t.display, t.tooltip) .. (t.afterDisplay or '') sep = t.separator or separator end links = table.concat(links) -- Make the blurb. local blurb = substituteParams(templateCfg.blurb, introLink, links) local span = mw.html.create('span') span :addClass('plainlinks') :addClass(templateCfg.class) :cssText(templateCfg.style) :wikitext(blurb) return tostring(span) end setmetatable(p, { __index = function(t, template) -- The main access point from #invoke. -- Invocations will look like {{#invoke:Find sources|template name}}, -- where "template name" is a subpage of [[Module:Find sources/templates]]. local tname = template if tname:sub(-8) == '/sandbox' then -- This makes {{Find sources/sandbox|Albert Einstein}} work. tname = tname:sub(1, -9) end return function(frame) local args = require('Module:Arguments').getArgs(frame, { wrappers = mw.site.namespaces[10].name .. ':' .. tname }) return t._main(template, args) end end}) return p