Module:Icon

This module contains several functions for rendering icons from the game, for use with both wikitext templates as well as from other Lua modules.

Wikitext functions

These functions are designed to be used directly in templates via {{#invoke:}}.

`renderGameIcon`

Renders the in-game icon of something.

Parameters

type: The type of thing being shown - quest, item, currency, action, achievement, etc. Usually pulled from Property:Has context. Used to determine whether the icon should have a frame, and if so, what kind.
frameType: Can be specified instead of type if you need to render an icon with a specific frame type without doing a type lookup. Usually pulled from Property:Has game icon frame type. Can be one of standard, hq, trait, achievement, or none (for non-frame icons).
icon: Icon file reference, including File: namespace and file extension. Usually pulled from Property:Has game icon.
link: Where the icon should link when clicked, usually the article name of the relevant concept.
size: Icon size. One of small (20px), mid (30px), or big (40px). Defaults to big.

For item icons specifically, these parameters can also be used:

hq: If set, renders a high-quality  item.
dyeCount: If set, renders an item with a number of dye slots. Usually pulled from Property:Has dye channels.

Example

{{#invoke: Icon | renderGameIcon
| type = Action
| icon = File:Transpose.png
| link = Transpose
| size = big
}}

`renderGameIconWithLabel`

Renders an in-game icon, alongside a label which links back to the thing, plus an optional quantity.

Parameters

All parameters taken by renderGameIcon, plus:

text: Label text. This text will be a link that directs to the link parameter. Pass nothing or set to "x" to hide the label (useful to display quantity in a condensed way).
qty: Quantity, displayed between the item icon and the label.
allowWrap: By default, icon and label will be grouped in a container that prevents text wrapping. Set this parameter to disable that behavior. This should only really be used in infoboxes and other narrow templates.

Examples

{{#invoke: Icon | renderGameIconWithLabel
| type = Action
| icon = File:Cure.png
| link = Cure
| size = small
| text = Freecure isn't real and can't hurt you
}}

Freecure isn't real and can't hurt you

Lua functions

These functions are designed to be called from other Lua modules and accept Lua values as their parameters instead of mw.frame objects. To use any of these functions, load the module first with e.g.

local icon = require("Module:Icon")

`plainIcon`

Displays a non-framed icon from the game, for example quest icons.

Parameters

Takes a single table parameter with the following keys:

icon: Icon file reference, including File: namespace and file extension.
link: Where the icon should link when clicked, usually the article name of the relevant concept.
size: Icon size. One of small, mid, or large. Defaults to small.

Returns

A wikitext string.

Example

local questIcon = icon.plainIcon({
    icon = "File:Quest icon.png",
    link = "Quest",
    size = "big",
})

`frameIcon`

Displays a framed icon from the game, for example an item or action.

Parameters

Takes a single table parameter with the following keys:

icon: Icon file reference, including File: namespace and file extension.
link: Where the icon should link when clicked, usually the article name of the relevant concept.
frame: Frame type for the icon. Can be standard (default), hq, trait, or achievement.
dyeCount: For items, the number of dye slots the item has. Default is 0.
size: Icon size. One of small, mid, or large. Defaults to small.

Returns

An HTML builder node.

Example

local traitIcon = icon.frameIcon({
    icon = "File:Heavier shot.png",
    link = "Heavier Shot",
    frame = "trait",
    size = "big",
})

--[[
	A module for rendering icons from the game.

	Provides both library functions for use in other modules, and template
	functions for use with {{#invoke}}.
]]

-- This table defines how icons for various types of things should be rendered.
-- Each key is a possible value of [[Property:Has context]], lowercased.
-- Values can be one of:
-- * "none", for non-frame icons
-- * "standard", for frame icons using the standard frame
-- * "hq", for frame icons using the HQ item frame
-- * "trait", for frame icons using the trait frame
-- * "achievement", for frame icons using the achievement frame
local iconFrames = {
	["achievement"] = "achievement",
	["action"] = "standard",
	["critical engagement"] = "none",
	["currency"] = "none",
	["duty"] = "none",
	["enemy"] = "none",
	["quest"] = "none",
	["fate"] = "none",
	["item"] = "standard",
	["location"] = "none",
	["minion"] = "standard",
	["mount"] = "standard",
	["stellar mission"] = "none",
	["trait"] = "trait",
}
-- default for anything not listed in this table is "standard"
-- TODO: remove this once we have a comprehensive list of "Has context" values
--       and we can enumerate all of them instead of relying on this
setmetatable(iconFrames, {__index = function() return "standard" end})

-- CSS classes assigned to a frame icon based on desired frame type
local frameClasses = {
	standard = nil, -- default in CSS
	trait = "standard-frame-icon-trait",
	achievement = "standard-frame-icon-achievement",
	hq = "standard-frame-icon-hq",
}

-- CSS classes assigned to frame icons at different sizes
local frameIconSizeClasses = {
	small = "small",
	mid = "mid",
	big = nil, -- default in CSS
}

-- Pixel dimensions of frame icons at different sizes
local frameIconSizeDimensions = {
	small = 20,
	mid = 30,
	big = 40
}

-- Pixel dimensions of non-frame icons at different sizes
local plainIconSizeDimensions = {
	small = 24,
	mid = 36,
	big = 48,
}

local yesno = require("Module:Yesno")

local p = {}

--- Renders a non-framed icon from the game.
-- @param icon
-- @param link
-- @param size
-- @return wikitext
function p.plainIcon(args)
	return ("[[%s|%dpx|link=%s%s]]"):format(
		args.icon,
		plainIconSizeDimensions[args.size],
		args.link,
		args.alt and ("|alt=" .. args.alt) or ""
	)
end

local function statusIcon(args)
	local result = mw.html.create("span"):addClass("text-icon"):wikitext(
		("[[%s|%dpx|link=%s%s]]"):format(
			args.icon,
			plainIconSizeDimensions[args.size],
			args.link,
			args.alt and ("|alt=" .. args.alt) or ""
		)
	)

	if args.frame == "buff" then
		result:css({position = "relative", top = "2px"})
	elseif args.frame == "debuff" then
		result:css({position = "relative", bottom = "2px"})
	end

	return result
end

--- Renders frame icon dye slots if there are any
-- @return HTML builder node
local function dyeSlots(dyeCount)
	if not dyeCount or dyeCount < 1 then
		return ""
	end

	local span = mw.html.create("span"):addClass("standard-frame-icon-dye-slots")
	for i = 1, dyeCount do
		span:node(mw.html.create("span"))
	end
	return span
end

--- Renders an icon image inside a frame.
-- @param icon Image to use as icon, including "File:" namespace and ".png" extension
-- @param link Optional link for the icon, defaults to the icon image's file page
-- @param size Icon size, one of "small", "mid", "big"
-- @param frame Optional frame type, one of "standard" (default), "trait", "achievement", "hq"
-- @param dyeCount Optional number of dye slots for items. One of 0 (default), 1, 2
-- @return HTML builder node
function p.frameIcon(args)
	args.dyeCount = args.dyeCount or 0
	args.link = args.link or args.icon -- default to icon page if no link is provided

	return mw.html.create("span")
		:addClass("plainlinks")
		:addClass("standard-frame-icon")
		:addClass(frameClasses[args.frame])
		:addClass(frameIconSizeClasses[args.size])
		:wikitext(
			("[[%s|%dpx|link=%s%s]]"):format(
				args.icon,
				frameIconSizeDimensions[args.size],
				args.link,
				args.alt and ("|alt=" .. args.alt) or ""
			)
		)
		:node(dyeSlots(args.dyeCount))
end

--- internal helper for generic template usage where type of icon isn't known beforehand and we're relying on SMW data
-- @param icon
-- @param alt
-- @param link
-- @param size
-- @param type
-- @param frameType
-- @param hq For items only
-- @param dyeCount For items only
local function gameIcon(args)
	-- normalize common optional parameters
	local size = args.size
	if not size or size == "" then
		size = "small"
	end

	local link = args.link or args.icon -- default to icon page if no link is provided

	local alt = args.alt
	if alt == "" then
		alt = nil
	end

	-- if there is no icon, render a missing icon
	local icon = args.icon
	if not icon or icon == "" then
		return p.frameIcon({
			icon = "File:Unknown item icon.png",
			link = link,
			size = size,
			frame = "standard",
			alt = "Unknown icon",
		})
	end

	-- Identify frame type. If frame type is provided directly, use that;
	-- otherwise, look up frame type based on object type/"Has context" value
	local frameType = args.frameType
	if not frameType or frameType == "" then
		frameType = iconFrames[args.type:lower()]
	end

	-- plain icons
	if frameType == "none" then
		return p.plainIcon({
			icon = icon,
			alt = alt,
			link = link,
			size = size,
		})
	end

	-- status effect icons
	if ({buff = true, debuff = true, status = true})[frameType] then
		return statusIcon({
			frame = frameType,
			icon = icon,
			alt = alt,
			link = link,
			size = size,
		})
	end

	-- frame icons
	-- upgrade standard frame to HQ frame if requested
	if frameType == "standard" and args.hq then
		frameType = "hq"
	end

	return p.frameIcon({
		icon = icon,
		alt = alt,
		link = link,
		size = size,
		frame = frameType,
		dyeCount = args.dyeCount,
	})
end

-- function to be invoked from templates that don't display labels
function p.renderGameIcon(frame)
	return gameIcon({
		icon = frame.args.icon,
		alt = frame.args.alt,
		link = frame.args.link,
		size = frame.args.size,
		type = frame.args.type,
		frameType = frame.args.frameType,
		hq = yesno(frame.args.hq),
		dyeCount = tonumber(frame.args.dyeCount) or 0,
	})
end

-- implementation for {{Game icon}} and other templates that do display labels
function p.renderGameIconWithLabel(frame)
	-- if qty is empty then don't render it
	local qty = frame.args.qty
	if qty == "" then
		qty = nil
	end

	-- if text is empty or set to "x" (in template usage) don't render it
	local text = frame.args.text
	if text == "" or text == "x" then
		text = nil
	end

	-- if alt is empty, use text by default
	-- (intentionally setting alt to be empty should never be supported, it's
	-- an important accessibility property and hurts nothing to be present)
	local alt = frame.args.alt
	if not alt or alt == "" then
		alt = text
	end

	local span = mw.html.create("span")
	-- set text wrapping
	if not yesno(frame.args.allowWrap) then
		span:css("white-space", "nowrap")
	end

	-- render icon using other passed parameters
	span:node(gameIcon({
		icon = frame.args.icon,
		alt = alt,
		link = frame.args.link,
		size = frame.args.size,
		type = frame.args.type,
		frameType = frame.args.frameType,
		hq = yesno(frame.args.hq),
		dyeCount = tonumber(frame.args.dyeCount) or 0,
	}))

	-- render quantity, if present
	if qty then
		span:node(" " .. qty:gsub("-", "–"))
	end

	-- render text link, if any
	if text then
		span:node((" [[%s|%s]]"):format(frame.args.link or frame.args.icon, text))
	end

	return span
end

return p

Module:Icon

Contents

Wikitext functions

`renderGameIcon`

Parameters

Example

`renderGameIconWithLabel`

Parameters

Examples

Lua functions

`plainIcon`

Parameters

Returns

Example

`frameIcon`

Parameters

Returns

Example

Navigation menu

Module:Icon

Wikitext functions

renderGameIcon

Parameters

Example

renderGameIconWithLabel

Parameters

Examples

Lua functions

plainIcon

Parameters

Returns

Example

frameIcon

Parameters

Returns

Example

Navigation menu

Search

`renderGameIcon`

`renderGameIconWithLabel`

`plainIcon`

`frameIcon`