(→Building an Infobox: added priority table) |
(→Functions: Added some documentation of functions) |
||
Line 127: | Line 127: | ||
== Functions == |
== Functions == |
||
For the following functions, assume an InfoboxBuilder object called "infobox" already exists. |
|||
<source lang="lua"> |
|||
local infobox = InfoboxBuilder.new() |
|||
</source> |
|||
=== Public functions === |
|||
==== new ==== |
|||
''This function is '''required'''.'' |
|||
<source lang="lua"> |
|||
InfoboxBuilder.new() |
|||
</source> |
|||
Creates a new InfoboxBuilder object. |
|||
==== setName ==== |
|||
''This function is '''required'''.'' |
|||
<br> |
|||
''This function is chainable.'' |
|||
<source lang="lua"> |
|||
infobox:setName(arg) |
|||
</source> |
|||
<code>arg</code> should be a <code>string</code>. Setting the infobox name will link the navbar to the correct template page and template talk page. |
|||
==== setHeaderTextColor ==== |
|||
''This function is optional.'' |
|||
<br> |
|||
''This function is chainable.'' |
|||
<source lang="lua"> |
|||
infobox:setHeaderTextColor(arg) |
|||
</source> |
|||
<code>arg</code> should be a <code>string</code> that contains a valid CSS color (hex code, rgb value, hsl value, etc.). Calling this function will change the color of the text in the infobox's headers and subheaders. The changes will not apply to headers added before this function is called, so it is recommended to call this function early. |
|||
==== setHeaderBackgroundColor ==== |
|||
''This function is optional.'' |
|||
<br> |
|||
''This function is chainable.'' |
|||
<source lang="lua"> |
|||
infobox:setHeaderBackgroundColor(arg) |
|||
</source> |
|||
<code>arg</code> should be a <code>string</code> that contains a valid CSS color (hex code, rgb value, hsl value, etc.). Calling this function will change the background color of the infobox's headers and subheaders. The changes will not apply to headers added before this function is called, so it is recommended to call this function early. |
|||
==== setParams ==== |
|||
''This function is '''required'''.'' |
|||
<br> |
|||
''This function is chainable.'' |
|||
<source lang="lua"> |
|||
infobox:setParams(...) |
|||
</source> |
|||
This function sets the valid parameters, their default values, and their formatting. |
|||
The arguments passed in should be tables of format: |
|||
<source lang="lua"> |
|||
{ |
|||
name = <paramName>, |
|||
pFunc = <processFunc>, |
|||
dFunc = <displayFunc>, |
|||
default = <default> |
|||
} |
|||
</source> |
|||
<code>paramName</code> should be a valid <code>string</code> that is unique. This name serves the key used to grab the raw values from the <code>args</code> table passed in from <code>setArgs()</code>. It also serves as the key for each parameter and will be referenced later. |
|||
<code>processFunc</code> should be a <code>function</code> or a <code>table</code> that transforms the raw value of the argument passed in. The result of this function or table should be something that <code>displayFunc</code> an use as a parameter. This value is optional. |
|||
<code>displayFunc</code> should be a <code>function</code> that transforms the processed value of the argument into something that can be displayed (ex. an HTML list). This value is optional. |
|||
<code>default</code> should be a string that serves as the default value if no raw value is present for the key in the <code>args</code> table. This value is optional. |
|||
;Predefined processing functions and tables |
|||
There are no predefined functions and tables at this time. The following table contains proposed functions. |
|||
{| class="wikitable" |
|||
! Function or table !! Use |
|||
|- |
|||
| split |
|||
| Splits a string into a numerical array with a specific delimiter |
|||
|} |
|||
;Predefined display functions |
|||
There are no predefined display functions at this time. The following table contains proposed functions. |
|||
{| class="wikitable" |
|||
! Function !! Use |
|||
|- |
|||
| link |
|||
| Creates a link when given a numerical array of one or two elements. |
|||
|- |
|||
| blist |
|||
| Creates a bulleted list from a numerical array. |
|||
|- |
|||
| ulist |
|||
| Creates an unbulleted list from a numerical array. |
|||
|- |
|||
| hlist |
|||
| Creates a horizontal list from a numerical array. |
|||
|- |
|||
| olist |
|||
| Creates an ordered list from a numerical array. |
|||
|} |
|||
==== setArgs ==== |
|||
''This function is '''required'''.'' |
|||
<br> |
|||
''This function is chainable.'' |
|||
<source lang="lua"> |
|||
infobox:setArgs(args) |
|||
</source> |
|||
<code>args</code> should be a <code>table</code> with key value pairs representing parameter names and values. |
|||
==== getRawArgs ==== |
|||
<source lang="lua"> |
|||
infobox:getRawArgs() |
|||
</source> |
|||
This function returns the "private" <code>rawArgs</code> associative array containing the raw values passed in from <code>setArgs()</code>. |
|||
==== getProcessedArgs ==== |
|||
<source lang="lua"> |
|||
infobox:getProcessedArgs() |
|||
</source> |
|||
This function returns the "private" <code>procArgs</code> associative array after being processed. |
|||
==== getArgs ==== |
|||
<source lang="lua"> |
|||
infobox:getArgs(which) |
|||
</source> |
|||
<code>which</code> |
|||
This function returns the "private" <code>rawArgs</code> or <code>procArgs</code> associative arrays depending on the value of <code>which</code>. |
|||
==== setCategoryMap ==== |
|||
''This function is optional.'' |
|||
<br> |
|||
''This function is chainable.'' |
|||
<source lang="lua"> |
|||
infobox:setCategoryMap(catMap) |
|||
</source> |
|||
==== getCategories ==== |
|||
<source lang="lua"> |
|||
infobox:getCategories() |
|||
</source> |
|||
==== processArgs ==== |
|||
''This function is '''required'''.'' |
|||
<br> |
|||
''This function is chainable.'' |
|||
<source lang="lua"> |
|||
infobox:processArgs() |
|||
</source> |
|||
==== addHeader ==== |
|||
''This function is optional, but '''recommended'''.'' |
|||
<br> |
|||
''This function is chainable.'' |
|||
<source lang="lua"> |
|||
infobox:addHeader(arg, options) |
|||
</source> |
|||
==== addImage ==== |
|||
''This function is optional, but '''recommended'''.'' |
|||
<br> |
|||
''This function is chainable.'' |
|||
<source lang="lua"> |
|||
infobox:addImage(cols, options) |
|||
</source> |
|||
==== addRow ==== |
|||
''This function is optional, but '''recommended'''.'' |
|||
<br> |
|||
''This function is chainable.'' |
|||
<source lang="lua"> |
|||
infobox:addRow(cols, options) |
|||
</source> |
|||
==== tostring ==== |
|||
''This function is '''required'''.'' |
|||
<source lang="lua"> |
|||
infobox:tostring() |
|||
</source> |
|||
=== Private functions === |
|||
While these are not necessarily "private", these functions are not intended to be called externally. |
|||
==== getContent ==== |
|||
<source lang="lua"> |
|||
infobox:getContent(paramName) |
|||
</source> |
|||
==== shouldShow ==== |
|||
<source lang="lua"> |
|||
infobox:shouldShow(paramNames) |
|||
</source> |
|||
==== addSpacer ==== |
|||
<source lang="lua"> |
|||
infobox:addSpacer() |
|||
</source> |
|||
==== addLinks ==== |
|||
<source lang="lua"> |
|||
infobox:addLinks() |
|||
</source> |
Revision as of 03:14, 6 August 2022
This is a documentation subpage for Module:InfoboxBuilder. It contains usage information, categories and other content that is not part of the original module page. |
This module depends on the following other modules: |
Building an Infobox
For an infobox to be built without errors, certain essential functions must be called before others. The following table details groups of functions and their priorities. The lower the number, the higher the priority. The functions setHeaderTextColor() and setHeaderBackgroundColor() are not required, but their CSS changes will not be applied if called later. In addition, the functions that add rows to the table, addHeader(), addImage(), and addRow() are not all required, but is it recommended to use at least addHeader() and addRow().
Priority | Functions |
---|---|
1 |
|
2 |
|
3 |
|
4 |
|
5 |
|
6 |
|
Import the module
local InfoboxBuilder = require('Module:InfoboxBuilder')
Unpack the frame arguments
function p.main(frame)
local args = frame:getParent().args
...
Create the infobox object
local infobox = InfoboxBuilder.new()
Set the infobox name
Setting the infobox name sets the template that the infobox links to inside of the navbar.
infobox:setName('Infobox')
Define the parameters
When defining the parameters, the arguments will be processed and postprocessed when given a function or table. pFunc is an optional processing function or table that will transform the raw argument value into a specific format. dFunc is an optional postprocessing function or table that will transform the processed argument for display purposes. An optional default value for the raw argument can be set using the default option.
An example of using pFunc and dFunc would be to have pFunc be a function that splits a comma separated list into a table in Lua and have dFunc be a function that turns a table into an unordered list in HTML.
infobox:setParams {
...
}
Pass in the arguments
infobox:setArgs(args)
Process the arguments
Processing the arguments will set default value (if it exists) and turn the raw argument passed in from setArgs(args) into a processed format for each parameter. This step is required or else the infobox will not work.
infobox:processArgs()
Specify a category map
A category map can be optionally set. This uses the processed (not postprocessed) argument and generates the correct categories.
infobox:setCategoryMap({
...
})
Prepare
Create the look of the infobox by adding headers, images, or rows. If the values shown in these cells use the value from parameters, it will use the postprocessed value.
-- add a header or subheader
infobox:addHeader(
{...},
{...}
)
-- add an image
infobox:addImage(
{...},
{...}
)
-- add a row
infobox:addRow(
{...},
{...}
)
Build
To build the infobox from data into an HTML table, call the tostring() function.
infobox:tostring()
Get the categories from the category map
To get the categories, call the getCategories() function.
infobox:getCategories()
Functions
For the following functions, assume an InfoboxBuilder object called "infobox" already exists.
local infobox = InfoboxBuilder.new()
Public functions
new
This function is required.
InfoboxBuilder.new()
Creates a new InfoboxBuilder object.
setName
This function is required.
This function is chainable.
infobox:setName(arg)
arg
should be a string
. Setting the infobox name will link the navbar to the correct template page and template talk page.
setHeaderTextColor
This function is optional.
This function is chainable.
infobox:setHeaderTextColor(arg)
arg
should be a string
that contains a valid CSS color (hex code, rgb value, hsl value, etc.). Calling this function will change the color of the text in the infobox's headers and subheaders. The changes will not apply to headers added before this function is called, so it is recommended to call this function early.
setHeaderBackgroundColor
This function is optional.
This function is chainable.
infobox:setHeaderBackgroundColor(arg)
arg
should be a string
that contains a valid CSS color (hex code, rgb value, hsl value, etc.). Calling this function will change the background color of the infobox's headers and subheaders. The changes will not apply to headers added before this function is called, so it is recommended to call this function early.
setParams
This function is required.
This function is chainable.
infobox:setParams(...)
This function sets the valid parameters, their default values, and their formatting.
The arguments passed in should be tables of format:
{
name = <paramName>,
pFunc = <processFunc>,
dFunc = <displayFunc>,
default = <default>
}
paramName
should be a valid string
that is unique. This name serves the key used to grab the raw values from the args
table passed in from setArgs()
. It also serves as the key for each parameter and will be referenced later.
processFunc
should be a function
or a table
that transforms the raw value of the argument passed in. The result of this function or table should be something that displayFunc
an use as a parameter. This value is optional.
displayFunc
should be a function
that transforms the processed value of the argument into something that can be displayed (ex. an HTML list). This value is optional.
default
should be a string that serves as the default value if no raw value is present for the key in the args
table. This value is optional.
- Predefined processing functions and tables
There are no predefined functions and tables at this time. The following table contains proposed functions.
Function or table | Use |
---|---|
split | Splits a string into a numerical array with a specific delimiter |
- Predefined display functions
There are no predefined display functions at this time. The following table contains proposed functions.
Function | Use |
---|---|
link | Creates a link when given a numerical array of one or two elements. |
blist | Creates a bulleted list from a numerical array. |
ulist | Creates an unbulleted list from a numerical array. |
hlist | Creates a horizontal list from a numerical array. |
olist | Creates an ordered list from a numerical array. |
setArgs
This function is required.
This function is chainable.
infobox:setArgs(args)
args
should be a table
with key value pairs representing parameter names and values.
getRawArgs
infobox:getRawArgs()
This function returns the "private" rawArgs
associative array containing the raw values passed in from setArgs()
.
getProcessedArgs
infobox:getProcessedArgs()
This function returns the "private" procArgs
associative array after being processed.
getArgs
infobox:getArgs(which)
which
This function returns the "private" rawArgs
or procArgs
associative arrays depending on the value of which
.
setCategoryMap
This function is optional.
This function is chainable.
infobox:setCategoryMap(catMap)
getCategories
infobox:getCategories()
processArgs
This function is required.
This function is chainable.
infobox:processArgs()
addHeader
This function is optional, but recommended.
This function is chainable.
infobox:addHeader(arg, options)
addImage
This function is optional, but recommended.
This function is chainable.
infobox:addImage(cols, options)
addRow
This function is optional, but recommended.
This function is chainable.
infobox:addRow(cols, options)
tostring
This function is required.
infobox:tostring()
Private functions
While these are not necessarily "private", these functions are not intended to be called externally.
getContent
infobox:getContent(paramName)
shouldShow
infobox:shouldShow(paramNames)
addSpacer
infobox:addSpacer()
addLinks
infobox:addLinks()