Module:Experimental/Infobox/doc: Difference between revisions

Latest revision as of 08:58, 1 April 2022

Creating a template step-by-step

Import Module:Infobox

local infobox = require('Module:Infobox')

Unpack the frame arguments

function p.main(frame)
	local args = frame:getParent().args
	...

Define an Infobox object

Main article: Module:Infobox §

	local ret = infobox.new(args)

Map your arguments to functions

Main article: Module:Infobox §

	ret:defineParams {
			...
	}

Parse your arguments

Main article: Module:Infobox §

	ret:cleanParams()

Initialise your HTML

Main article: Module:Infobox §

	ret:create()

Name your infobox

Main article: Module:Infobox §

	-- note: we don't use the "Template:" namespace prefix
	ret:defineName('Infobox FooBar')

Give your infobox custom behaviour

Main articles: Module:Infobox §, Module:Infobox §, and Module:Infobox §

	ret:addClass(...)
	ret:useSMW({ ... })
	ret:defineLinks({ ... })

Give your infobox a caption

Main article: Module:Infobox §

	ret:caption()

Format your table

Main article: Module:Infobox §

	ret:addRow{ ... }
		:addRow{ ... }

Finalise your template

Main article: Module:Infobox §

	ret:finish()

Functions

Public functions

For the example snippets below, ret is an arbitrary infobox initiated as:

	local ret = Infobox.new(args)

Priority

Certain functions rely on information created by other functions, and thus must be run in a particular order:

0	new
1	defineParams
2	create maxVersion
3	cleanParams setMaxButtons noSwitch
4	other functions
5	finish

nilParam

	Infobox.nilParam()

Returns the value of the placeholder value Infobox.nil_param. This value is generally not seen, but it is used to fill switchbox data as nil causes unwanted behaviour.

isDefined

	Infobox.isDefined(arg)

Checks whether the value arg can be considered as defined.

new

	Infobox.new(args)

Creates a new infobox object with args as a table of values passed from the template invocation.

This function also creates the top-level wrapper and sets a metatable for the infobox.

create

	ret:create()

Creates the HTML tags used for the infobox itself. Will run maxVersion() if it has not been run already.

defineName

	ret:defineName(arg)

Defines the name of the infobox. This should be the base pagename; i.e. no "Template:" namespace prefix.

defineLinks

	ret:defineLinks(tbl)

Defines any number of infobox bottom links in a table whose elements are table variables formatted as such:

	{
		{ link, label },
		...
	}

link and label should be string variables that will, in a basic sense, define [[Link|label]].

In a more technical sense, link and label help form a string for string.format(), with the module using the equivalent of (but not exactly):

	string.format('&amp;#91;[['..link..'|'..label..']]&amp;#93;',...)

The template name itself can be called up to 5 times by using "%s", in either link or label.

setMaxButtons

	ret:setMaxButtons(n)

Changes the behaviour of buttons by defining the maximum number of buttons that are allowed to appear. If the version count exceeds the button count, their buttons will be replaced with a drop down menu. If not run, the maximum button count will be 5.

cleanParams

	ret:cleanParams()

Parses the parameters with their mapped functions.

defineParams

	ret:defineParams{
		...
	}

Maps parameters to functions as defined by a table formatted as such:

	{ name = <param>, func = <func>, dupes = true },

param should be a string that names the parameter as it will be in references for use in other functions.

func should be a function or instructions on how to find a function.

dupes is a meta configuration that allows the parameter to be duplicated in switch data. Normally, these duplicate values are not needed, and they will be deleted if they are the same as the default values after all parameters have been parsed. Some parameters require duplication to function properly, such as display altering parameters defined with linkParams().

If duplicates are not needed, this parameter should be deleted.

Predefined functions

If func is a string, then the module will attempt to use a predefined function.

Function	Use
`name`	Uses the parameter named "name". If "name" is blank or undefined, it will use the page name.
`release`	Uses the parameters named "release" and "update" and formats it as such: If both are defined: `<release> ([[Update:<update>\|Update]])` If only release is defined: `<release> (Update unknown)` If release is not defined: `? (edit)`
`removal`	Uses the parameters named "removal" and "removalupdate" and formats it the same as `release`
`hasContent`	If the parameter is defined and not blank, it will be used. Otherwise, `? (edit)` will be used.
`image`	Currently functions the same as `hasContent`
`numbers`	Removes commas from the parameter and attempts to cast it to a `number`. If it works, the number is used, otherwise `? (edit)`
`yesNo`	If the parameter is defined and yes or no, it will be used.

User-defined functions

If func is a function, then that function will be used to parse the parameter. User-defined functions allow for more robust formatting and guidelines.

As a general practice, user-defined functions should be located under the main functions in the module. It is best to document these functions so that they may be changed by other editors if necessary.

In user-defined functions, circumstances where the edit button should be shown should return nil, which is automatically handled by the module.

Simple and complex definitions

Parameters may be mapped to functions in a straightforward manner by simply definining a name of or reference to a function, such as:

	ret:defineParams{
		{ name = 'foo', func = 'hasContent' },
		{ name = 'bar', func = barFunc }
	}

Simple definitions only pass the parameter from the master list named <name>. Some parameters need more interaction with other parameters. To do this, we require a complex definition. Complex definitions point to a user-defined function and map what parameters to pass. Complex definitions can also pass literal values or the uncleaned value with the use of flags.

Complex functions are defined as table values formatted as such:

	func = { name = <funcname>, params = { <paramname>, ... }, flag = <flags> }

A basic example for complex functions is:

	ret:defineParams{
		{ name = 'foo', func = { name = fooFunc, params = { 'bar', 'baz' } },
	}
	-- ...
	-- ...
	function fooFunc(arg1,arg2)
		return arg1..arg2
	end

In this example, we have a parameter named "foo", but we use the parameters passed to the template named "bar" and "baz". Parameters are passed in the order listed, so in the above, the parameter bar is used for arg1, and baz is used for arg2.

Flags define the behaviour of the parameters named. The following flag behaviours exist:

d - Looks for the cleaned and parsed version of the parameter. If not cleaned, it will use the value passed to the template. If neither exist, it will use nil. This is the default behaviour if no flag is defined.
p - Looks only at the value passed to the template. If it does not exist, it will use nil.
r or l - Uses the literal (or raw) value.

If flag is a string, then the behaviour defined by it will apply to every parameter passed. If flag is a table, then each flag will only define the behaviour of the respective parameter.

For example:

	ret:defineParams{
		{ name = 'foo', func = {
					name = fooFunc,
					params = { 'foo', 'bar', 'baz' },
					flag = { 'd', 'p', 'l' },
				},
		}

In the above snippet, foo will use the default behaviour and bar will only look for the value passed to the template. The third parameter will use the string literal 'baz'.

Definition order

Parameters are defined in the order that they are coded. If a parameter relies on the cleaned value of another parameter, then the parameter dependent on the other will need to be defined after in the definition table.

addRow

	ret:addRow(tbl)

Adds a new row to the template with columns and behaviour defined by tbl, which should be a table that holds cells defined as table variables, formatted as such:

	{
		{ celltype, label, <attr1> = <value1>, <attr2> = <value2> ... },
		...
	}

celltype and label are string values that define the fundamental display of the cell.

`celltype`	Output
`th`	Creates a `<th>` tag where the content is the value of `label`
`td`	Creates a `<td>` tag where the content is the value of `label`
`argh`	Creates a `<th>` tag where the content is the value of the parameter named `label`
`argd`	Creates a `<td>` tag where the content is the value of the parameter named `label`

The attributes are any of the available attributes defined inside the function. All functions that are ultimately run are documented in the Lua reference manual and are run on the tag for the specific table cell they are called on.

`attr`	Type	Use
`attr`	`table`	Passes the value to `mw.html.attr()`
`css`	`table`	Passes the value to `mw.html.css()`
`colspan`	`number`	Uses the value to run `mw.html.attr('colspan',#)`
`rowspan`	`number`	Uses the value to run `mw.html.attr('rowspan',#)`
`title`	`string`	Uses the value to run `mw.html.attr('title',text)`
`class`	`string`	Passes the value to `mw.html.addClass()`
`class`	`table`	Passes every value in the table to `mw.html.addClass()`

If the template is a switch infobox, then data-attr-param="<paramname>" will be added to the table cell.