Module:Unsubst/sandbox

Module documentation[view] [edit] [history] [purge]

Maintenance templates, such as {{Citation needed}} or {{Refimprove}}, should never be substituted. A trick to avoid that is to make a template substitute to its transcluded form. This module implements that trick.

Infoboxes should use Module:Unsubst-infobox, as should any other templates with parameters listed in block format by default.

Usage

To turn a template into a self-substituting template, wrap the existing template code with:

{{SAFESUBST:<noinclude />#invoke:Unsubst||$B=

 [ ... existing template code ... ]

}}

The wikitext to display when not substed must be given as "$B". All other parameters passed to the #invoke will be copied to the generated template invocation as default values. If the value of any of these default parameters is __DATE__, that value in the generated template invocation will be the current month and year.

Some templates have a <noinclude> but no matching </noinclude> at the end of the template. In such cases the missing </noinclude> must be added before the ending }}.

Advanced

{{SAFESUBST:<noinclude />#invoke:Unsubst||$params=[ parameters ]|$aliases=[ aliases ]|$flags=[ flags ]|$B=

 [ ... existing template code ... ]

}}

Due to Lua limitations, parameters are normally ordered randomly when the template is substituted. |$params= can be used in #invoke:Unsubst to list template parameters in order, comma-separated (e.g. egg,bacon,sausage,cheese,spam). Numbered parameters should be before others in the list. Any remaining parameters are tacked onto the end of the generated invocation.

Parameter aliases can be listed in |$aliases= (and shouldn't be listed in |$params=), and will be replaced automatically. Each alias and its replacement should be formatted as alias>replacement, and each of those pairs should be comma-separated (e.g. œuf>egg,melt>cheese). Note that this parameter can function with or without |$params=.

Parameter |$flags= can be used to modify other facets of the module's behaviour; entries are comma-separated. Valid flags are override (allows parameters in the #invoke: to take precedence over parameters in the original template invocation); keep-whitespace (prevents whitespace from being trimmed from unnamed parameters); and remove-empty (removes empty parameters).

These parameters can be manipulated using parser functions to provide more complicated options (note that in the parameters any parser function, or template or module invocation, should also have SAFESUBST:<noinclude />).

Parameter |$template-name= will override the subst'd template's name with the template name assigned to this parameter.

Example

Consider a template Template:Example containing the following code:

{{SAFESUBST:<noinclude />#invoke:Unsubst||foo=bar |date=__DATE__ |$B=

 [ ... Template code goes here ... ]

}}

Original	Result
{{subst:example}}	{{Example|date=May 2025|foo=bar}}
{{subst:example|foo=X}}	{{Example|date=May 2025|foo=X}}
{{subst:example|baz=X}}	{{Example|baz=X|date=May 2025|foo=bar}}
{{subst:example|date=January 2001}}	{{Example|date=January 2001|foo=bar}}

The above documentation is transcluded from Module:Unsubst/doc. (edit | history)
Editors can experiment in this module's sandbox (edit | diff) and testcases (edit) pages.
Add categories to the /doc subpage. Subpages of this module.

local checkType = require('libraryUtil').checkType

local p = {}

local BODY_PARAM = '$B'

function p.invocation(name, args)
	-- This function makes a template invocation from the name and the arguments
	-- given. The arguments are not altered.
	checkType('p.invocation', 1, name, 'string')
	checkType('p.invocation', 2, args, 'table')
	
	-- Copy the invocation args and convert magic words.
	-- We need to make a copy of the table rather than just using the original,
	-- as some of the values may be erased when building the invocation.
	local invArgs = {}
	for k, v in pairs(args) do
		invArgs[k] = v
	end

	-- Build the invocation body with numbered args first, then named.
	local ret = {}
	ret[#ret + 1] = '{{'
	ret[#ret + 1] = name
	for k, v in ipairs(invArgs) do
		if string.find(v, '=', 1, true) then
			-- Likely something like 1=foo=bar, we need to do it as a named arg
			break
		end
		ret[#ret + 1] = '|'
		ret[#ret + 1] = v
		invArgs[k] = nil -- Erase the key so that we don't add the value twice
	end
	for k, v in pairs(invArgs) do
		ret[#ret + 1] = '|'
		ret[#ret + 1] = k
		ret[#ret + 1] = '='
		ret[#ret + 1] = v
	end
	ret[#ret + 1] = '}}'

	return table.concat(ret)
end

function p._main(frame, body)
	-- If we are substing, this function returns a template invocation. The
	-- invocation substitutes the magic word "__DATE__" for the current month
	-- and year in "Month YYYY" format. If we are not substing, the function
	-- returns the body parameter, without any type checking. This function
	-- is intended to be called from Lua modules.
	--
	-- Params:
	-- @frame - the current frame object. Requires a parent frame to be available.
	-- @body - the template body, returned as-is if not substing.

	if not mw.isSubsting() then
		return body
	end

	-- Sanity check for the frame object.
	if type(frame) ~= 'table'
		or type(frame.getParent) ~= 'function'
		or not frame:getParent()
	then
		error(
			"argument #1 to '_main' must be a frame object with a parent " ..
			"frame available", 2
		)
	end

	-- Find the invocation name.
	local titleobj = mw.title.new(frame:getParent():getTitle())
	local name
	if titleobj.namespace == 10 then -- NS_TEMPLATE
		name = titleobj.text
	elseif titleobj.namespace == 0 then -- NS_MAIN
		name = ':' .. titleobj.text
	else
		name = titleobj.prefixedText
	end

	-- Combine passed args with passed defaults, and substitute magic words.
	local args = {}
	for k, v in pairs(frame.args) do
		if v == '__DATE__' then
			v = mw.getContentLanguage():formatDate('F Y')
		end
		args[k] = v
	end
	for k, v in pairs(frame:getParent().args) do
		args[k] = v
	end

	return p.invocation(name, args)
end

function p.main(frame)
	-- This function is called from #invoke. It uses the parameter defined in
	-- BODY_PARAM for the template content.
	local body = frame.args[BODY_PARAM]
	if not body then
		error(string.format(
			"no template content provided (use parameter '%s')",
			BODY_PARAM
		), 2)
	end
	frame.args[BODY_PARAM] = nil
	return p._main(frame, body)
end

p[''] = p.main -- Alias for p.main, for backwards compatibility.

return p