Модул:Пронађи изворе

Из Википедије, слободне енциклопедије
Иди на навигацију Иди на претрагу

This module produces a list of links to search engines to help editors find sources about a given subject. It implements {{Пронађи изворе}} 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. {{Пронађи изворе}}. However, it is also possible to use it directly from #invoke, like this:

{{#invoke:Пронађи изворе|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:Пронађи изворе, the template name should be "Пронађи изворе"; "пронађи изворе" with a lower-case "п" 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('Модул:Пронађи изворе')

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:

mПронађи изворе._main('Пронађи изворе', {'Albert Einstein', '-"Marilyn Monroe"', 'relativity', 'science'})

Available templates[уреди]

The following templates are available for use:

Template Description Example Configuration
Find sources No description available Пронађи изворе: „Example” — Гугл вести · Гугл новине · Гугл књиге · Гугл академик · HB · JSTOR · Гугл бесплатне слике · WL main, documentation
Find sources mainspace No description available Пронађи изворе: „Example” — Гугл вести · Гугл новине · Гугл књиге · Гугл академик · JSTOR · Гугл бесплатне слике main, documentation
Find sources video games No description available Модул:Пронађи_изворе:49: invalid link code 'free news sources'; no link config found at Module:Пронађи изворе/links/free news sources 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:Пронађи изворе/templates/". For example, for Template:Пронађи изворе, the configuration page is located at Module:Пронађи изворе/templates/Пронађи изворе. 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 = "Пронађи изворе 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.

Once you have created your template configuration page, you need to add the template to Module:Пронађи изворе/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 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
bing Bing, Microsoft's flagship search engine. Bing main, documentation This is a replacement for MS Books and MS Academic, which unfortunately have been discontinued by Microsoft.
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
highbeam Highbeam, a paid search engine and full text online archive owned by Cengage Learning. Available through The Wikipedia Library. Highbeam 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
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
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

Template invocation[уреди]

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

{{#invoke:Пронађи изворе|template}}<noinclude>
{{#invoke:Пронађи изворе/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:Пронађи изворе|template}}<noinclude>
{{documentation}}
<!-- Categories go on the /doc subpage, and interwikis go on Wikidata. -->
</noinclude>

Adding new links[уреди]

To make a new link code available to use from source-finding templates, you need to make a link configuration module for it. The page name for this module should start with "Module:Пронађи изворе/links/" and end with the link code. Link codes should be short but descriptive, and should be in lower case. For example, the link code for Google search is "google", and the configuration page is at Module:Пронађи изворе/links/google.

The link configuration page should look something like this:

return {
	url = '//www.google.com/search?q=$1',
	display = 'Google',
	separator = ','
}
  • 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).

Once you have created your link configuration page, you need to add the link to Module:Пронађи изворе/links in order for it to show up in the table of links on this documentation page.

Automatic documentation[уреди]

Automatic documentation is provided for templates based on this module; the documentation is generated by Module:Пронађи изворе/autodoc. The autodoc module uses the following pages:

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:

return {
	shortcuts = {'shortcut1', 'shortcut2'},
	description = 'This template is used to provide source links on [[WP:AFD|AfD]] pages',
	docIntro = 'This template produces a series of search-engine links to be used on [[WP:AFD|AfD]] pages.'
}
  • 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."

Link documentation configuration page[уреди]

This page is located at the "/autodoc" subpage of the link 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:

return {
	description = '[[Google]], the flagship search engine from Google Inc.',
	notes = 'This is the most commonly used search link.'
}
  • 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.

Configuration[уреди]

The messages used in this module can be found at Module:Пронађи изворе/config and Module:Пронађи изворе/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:Пронађи изворе'
local TEMPLATE_ROOT = ROOT_PAGE .. '/templates/' -- for template config modules
local LINK_ROOT = 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)
	-- Renders the external link wikicode for one link, given the link code,
	-- a table of search terms, and an optional display value.

	-- Get link config.
	local linkCfg = maybeLoadData(LINK_ROOT .. code)
	if not linkCfg then
		error(string.format(
			"invalid link code '%s'; no link config found at [[%s]]",
			code,
			LINK_ROOT .. code
		))
	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

	return string.format('[%s %s]', url, display or linkCfg.display)
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. If the page
		-- uses a disambiguator like "Foo (bar)", make "Foo" the first term and
		-- "bar" the second.
		local term, dab = title.subpageText: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] = title.subpageText
		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,
			'&nbsp;'
		)
		introLink = p._renderLink(code, searchTerms, display)
	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.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:Пронађи изворе|template name}},
	-- where "template name" is a subpage of [[Module:Пронађи изворе/templates]].
	local tname = template
	if tname:sub(-8) == '/sandbox' then
		-- This makes {{Пронађи изворе/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