A library of functions for displaying icons on pages or within other templates. For best performance, a chain of icons (sit in a row with nothing between) should be done with a single call.
Functions[]
This module relies on the exists()
and trim()
contained within Module:Util. All function calls from this module are prefixed with util
e.g. util.exists()
.
_generate()[]
This function is internal only and the main workhorse for p.Icons()
and p.innerIcon()
. This function builds the function list. The first task is determining the size of the icons.
if util.exists(iconSetting) then
iconSetting = util.trim(iconSetting)
if util.exists(iconSize[iconSetting]) then
iconSetting = iconSize[iconSetting]
end
else
iconSetting = iconSize["medium"]
end
-- This is for calls from other Lua modules as the above will result in nil
if util.exists(iconSetting) == false then
if util.exists(iconSize) then
iconSetting = iconSize
else
iconSetting = iconSize["medium"]
end
end
In wikitext mark up the rough equivalent would be:
{{#ifeq:{{{iconSetting}}}|medium|{{#switch:{{{iconSetting}}}|a = x14px |b = 16px| c= 20px|...|#default = {{{iconSize|x14px}}}}}}}
The next step is to break the comma separated lists into a table:
if util.exists(iconLinks) then
iconLinks = mw.text.split(iconLinks, ",")
end
if util.exists(tipOverride) then
tipOverride = mw.text.split(tipOverride, ",")
end
if util.exists(iconClass)then
iconClass = "|class=" .. tostring(iconClass);
else
iconClass = ""
end
This would be the equivalent of using multiple {{#explode:}} functions and variables to store each item as its own.
Once the data has been pre-processed a loop is used to run through each item in the list to generate the icon collection:
for k, v in ipairs(iconList) do
newIcon = iconData[util.trim(v)]
if util.exists(newIcon) then
currentIcon = newIcon.icon
if util.exists(tipOverride, k) then
currentTip = tipOverride[k]
else
if util.exists(iconLinks, k) then
currentTip = iconLinks[k]
else
currentTip = newIcon.tip
end
end
else
currentIcon = "Icon question.png"
currentTip = "Unrecognized icon name"
result = result .. "[[Category:Modules with invalid parameters]]"
end
--Create wikitext icon
dataLine = '[[File:' .. currentIcon .. '|' .. iconSetting
if util.exists(iconLinks, k) then
dataLine = dataLine .. '|link=' .. iconLinks[k]
else
dataLine = dataLine .. '|link='
end
if currentTip ~= nil then
dataLine = dataLine .. '|' .. currentTip
end
dataLine = dataLine .. iconClass .. ']]'
createTip = mw.html.create('span')
createTip:addClass( 'va-icon' )
:attr('title', currentTip)
:wikitext(dataLine)
result = result .. tostring(createTip)
if k < table.getn(iconList) then
result = result .. " "
end
end
Line 2 checks the data list at Module:Icons/data for the data relating to the icon short code and returns a result or nil
(does not exist) Depending on if a result was found the code continues, if there is no match a dummy icon is supplied at lines 14/15 and a maintenance category added at line 16.
If a match is found, the next task is to check if the tooltip is being overwritten, if it isn't being overwrite, it will then check if an page alternative link has been supplied, otherwise fall back to the default tooltip.
The wikitext equivalent would be
{{{tipOverride|{{{iconLinks|default}}}}}}
Now the correct icon, tooltip and link have been obtained, lines 21-31 build the image file in the format [[File:<icon>|<size>|link=<link>|<tooltip>|class=<class>]]
.
Lines 33-37 create the <span />
which contains the icon and inserts the icon inside. When rendered this will appear as <nowik><span class="va-icon" title="<tooltip>">icon</nowiki>
.
Finally lines 39-41 check if the item being created is the last in the list to be created. If not it will add a space at the end of the string so there is space between the icons on the page once completed.
Invocation parameters[]
The invocation parameters are passed through from p.Icons(frame)
or p.innerIcon(iconList, iconSetting, iconLinks, tipOverride, iconClass, iconSize)
. The variables align between these three functions and the below should be taken as an explanation for all three.
Label | Parameter | Variable | Description | Required | Example |
---|---|---|---|---|---|
Icons | 1 | iconList | A string list of icon short code(s) passed through to the module. For multiple codes being passed these should be split by a comma (,). | fo76,ww | |
Icon Size | 2 | iconSetting | The image size to be passed to all icons in the list. A custom size can be set (e.g. x26px) or one of the standard sizes can be applied:
To ensure all icons are consistent in size, it is recommended to control on the height (e.g. x14px) rather than the width (e.g. 14px) |
- Defaults are built in | |
Link | 3 | iconLinks | The page(s) the icon(s) links to. For multiple pages, article names are split with a comma (,) | Fallout 76,Wild Wasteland | |
Tooltip | 4 | tipOverride | The tooltip(s) shown when hovering over the icon(s), for multiple icons, the tooltips can be split with a comma (') | - Defaults are built in | Fire, EMP |
CSS Class | 4 | iconClass | CSS classes to be applied to the icons. If this is set it will apply to all icons in the group. Classes are written without the class= component. |
va-icon va-icon-blue |
p.Icons() and p.innerIcon()[]
These two functions are pass through functions to _generate()
. Before passing through the list of icons supplied is split.
The differences between the functions is where they should be used and that p.innerIcon()
doesn't pass through a table of icon sizes, just a predetermined size and can only be called from other lua modules. p.Icons()
is for all other namespaces and cannot be called from another module.
Invocation parameters[]
Due to the close nature of these two functions and _generate()
the invocation parameters are the same as listed above.
p.platforms()[]
p.platforms()
uses the same data set as the other functions, but only returns results for icons that have been marked as being a platform in the data set. In addition to this, it also uses Semantic Mediawiki so the data returned can be queried in Special:Ask.
Once the function has confirmed the icon in the list is a valid platform, it will create a hidden <span />
holding the semantic tag advising of the platform assigned from the default tooltip [[Has platform::<platform>]]
. The code then largely follows that of _generate()
to create the icon, with a blank link attribute. The two spans are then joined together before checking for the next platform.
If no platforms are found the code will return <sup>[Platforms needed]</sup>[[Category:Platforms needed]]
.
Invocation parameters[]
The only parameter taken by this function is the iconList parameter, holding the string of short codes.
p.documentation()[]
p.documentation()
is self generating documentation to display the icon produced by each short code. It first takes all the datasets available and sorts them into alphabetical order and creates a table header allowing for 3 icons in a row. For each short code it will put the short code in the first, third or fifth column and the icon in the second, fourth or sixth column based on where in the sorted dataset it resides.
Due to the ever expanding icon list, this function does run the risk of becoming oversized with time. If the character size is exceeded it may need splitting into two functions.
Invocation parameters[]
As a self contained function, there are not parameters that can be passed through.
Available icons[]
In addition, all abbreviations supported by {{Abb}}
can be used to produce an icon for the corresponding game.
local p = {}
local util = require( 'Module:Util' )
--[[
Icon data is now stored on the sub page /data to seperate functional code
for the dataset users will often need to update. This reduces the risk of
breaking the code by entering data in the wrong place and makes it easier to
manage the code itself by not having to pass through the large dataset at
the top.
]]
require( 'Module:Icons/data' )
local iconSize = {
--[[
All sizes are controlled on the height to ensure a string of icons maintain
a consistent line height
]]
["small"] = "x10px",
["medium"] = "x14px",
["normal"] = "x14px",
["big"] = "x20px",
}
--[[ 28/Oct/2021 Added class control table to array as to handle light/dark
themes. This was originally put into the frontend template, when class
handling should be back end. Adding the ['class'] = 'light' or
['class'] = 'dark' parameter to a icon's dataset on /data will enable it to
access a class if needed.
]]
--[[ 08/Nov/2021 Remove the class definition as to be able to just pass straight through
local class = {
['light'] = 'lighticon',
['dark'] = 'darkicon',
['general'] = 'generalicon'
}
]]
function _generate(iconList, iconSetting, iconLinks, tipOverride, iconClass, iconSize)
if util.exists(iconSetting) then
iconSetting = util.trim(iconSetting)
if util.exists(iconSize[iconSetting]) then
iconSetting = iconSize[iconSetting]
end
else
iconSetting = iconSize["medium"]
end
-- This is for calls from other Lua modules as the above will result in nil
if util.exists(iconSetting) == false then
if util.exists(iconSize) then
iconSetting = iconSize
else
iconSetting = 'x14px'
end
end
if util.exists(iconLinks) then
iconLinks = mw.text.split(iconLinks, ",")
end
if util.exists(tipOverride) then
tipOverride = mw.text.split(tipOverride, ",")
end
if util.exists(iconClass)then
iconClass = "|class=" .. tostring(iconClass);
else
iconClass = ""
end
local result = ""
for k, v in ipairs(iconList) do
newIcon = iconData[util.trim(v)]
if util.exists(newIcon) then
currentIcon = newIcon.icon
if util.exists(tipOverride, k) then
currentTip = tipOverride[k]
else
if util.exists(iconLinks, k) then
currentTip = iconLinks[k]
else
currentTip = newIcon.tip
end
end
else
currentIcon = "Icon question.png"
currentTip = "Unrecognized icon name"
result = result .. "[[Category:Modules with invalid parameters]]"
end
--Create wikitext icon
dataLine = '[[File:' .. currentIcon .. '|' .. iconSetting
if util.exists(iconLinks, k) then
dataLine = dataLine .. '|link=' .. iconLinks[k]
else
dataLine = dataLine .. '|link='
end
if currentTip ~= nil then
dataLine = dataLine .. '|' .. currentTip
end
dataLine = dataLine .. iconClass .. ']]'
createTip = mw.html.create('span')
createTip:addClass( 'va-icon' )
:attr('title', currentTip)
:wikitext(dataLine)
result = result .. tostring(createTip)
if k < table.getn(iconList) then
result = result .. " "
end
end
return result
end
-- Calls from other modules
function p.innerIcon(iconList, iconSetting, iconLinks, tipOverride, iconClass, iconSize)
iconList = mw.text.split(iconList, ',')
return _generate(iconList, iconSetting, iconLinks, tipOverride, iconClass, iconSize)
end
function p.Icons(frame)
--[[All icons are now lower case to reduce script errors from
incorrectly entering the icon code in a different case to the list]]
local iconList = mw.text.split(string.lower(frame.args[1]), ",")
local iconSetting = frame.args[2]
local iconLinks = frame.args[3]
local tipOverride = frame.args[4]
local iconClass = frame.args[5]
local iconSize = {
--[[
All sizes are controlled on the height to ensure a string of icons maintain
a consistent line height
]]
["small"] = "x10px",
["medium"] = "x14px",
["normal"] = "x14px",
["big"] = "x20px"
}
return _generate(iconList, iconSetting, iconLinks, tipOverride, iconClass, iconSize)
end
function p.platforms(frame)
--[[All icons are now lower case to reduce script errors from
incorrectly entering the icon code in a different case to the list]]
local icons = mw.text.split(string.lower(frame.args[1]), ",")
local result = ""
for k, v in ipairs(icons) do
currentIcon = iconData[util.trim(v)]
if util.exists(currentIcon, 'platform') == true then
createSM = mw.html.create('span')
createSM:css('display', 'none')
:wikitext('[[Has platform::' .. currentIcon.tip .. ']]')
:allDone()
createPlatform = mw.html.create('span')
if (util.exists(currentIcon.class)) then
iconClass = "|class=" .. tostring(currentIcon.class);
else
iconClass = ""
end
createPlatform:addClass('va-icon')
:attr('title', currentIcon.tip)
:wikitext('[[File:'
.. currentIcon.icon
.. '|alt='
.. currentIcon.tip
.. '|x14px|link='
.. iconClass..']]')
:allDone()
if (util.exists(iconData[util.trim(v)..' dark'])) then
currentDarkIcon = iconData[util.trim(v)..' dark']
createPlatformDark = mw.html.create('span')
if (util.exists(currentDarkIcon.class)) then
iconClass = "|class=" .. tostring(currentDarkIcon.class);
else
iconClass = ""
end
createPlatformDark:addClass('va-icon')
:attr('title', currentDarkIcon.tip)
:wikitext('[[File:'
.. currentDarkIcon.icon
.. '|alt='
.. currentDarkIcon.tip
.. '|x14px|link='
.. iconClass..']]')
:allDone()
createPlatform = tostring(createPlatform)..tostring(createPlatformDark)
end
--[[ Uncommenting tostring(createSM) below will enable
Semantic Mediawiki data tracking]]
result = result .. tostring(createSM)
.. tostring(createPlatform)
if k < table.getn(icons) then
result = result .. " "
end
end
end
if result == '' then
result = '<sup>[Platforms needed]</sup>[[Category:Platforms needed]]'
end
return result
end
function p.documentation()
keys = {}
for k in pairs(iconData) do
table.insert(keys, k)
end
table.sort(keys)
result = '{| class="va-table va-table-full"\n|-\n !prefix!!Icon!!prefix!!Icon!!prefix!!Icon\n|-\n'
set = 1
for k,v in ipairs(keys) do
i = iconData[v]
result = result .. "||'''" .. v .. "'''"
if util.exists(i) == true and i.class ~= nil then
newFile = mw.html.create(span)
--:addClass(class[i.class])
:wikitext('[[File:' .. iconData[v].icon .. '|25px]]')
else
newFile = mw.html.create(span)
:wikitext('[[File:' .. iconData[v].icon .. '|25px]]')
end
result = result .. '||' .. tostring(newFile)
if set == 3 then
result = result .. '\n|-\n'
end
if set < 3 then
set = set + 1
else
set = 1
end
end
result = result .. '\n|}'
return result
end
function p.Test(frame)
--Please empty when done debugging so other users know it is free to use
end
return p