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, mid, or large. Defaults to small.

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

`renderGameIconFromQuery`

Renders an icon and label for something selected by the provided SMW {{#ask:}} query. Link is inferred from the query result.

Parameters

size
hq
text
qty
allowWrap: As described in § renderGameIcon and § renderGameIconWithLabel.

Examples

{{#invoke: Icon | renderGameIconFromQuery
| query = [[Has context::Item]][[Has internal ID::4]]
| size = big
}}

Wind Shard

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",
})

`gameIconFromQuery`

Executes an SMW query and renders icon and label for the resulting object. Link is inferred from query result.

Parameters

Takes a single table parameter with the following keys:

query: SMW query string.
size
hq
text
qty
allowWrap: As described in § renderGameIcon and § renderGameIconWithLabel, but with hq and allowWrap being proper Lua booleans rather than strings.

Returns

Wikitext string.

Examples

local myIcon = icon.gameIconFromQuery({
    query = "[[Has context::Item]][[Has internal ID::4]]",
    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)
	if not args.size or args.size == "" then
		args.size = "small"
	end
	args.link = args.link or args.icon -- default to icon page if no link is provided

	return ("[[%s|%dpx|link=%s]]"):format(
		args.icon,
		plainIconSizeDimensions[args.size],
		args.link
	)
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

	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)
	if not args.icon then
		error("icon is required")
	end
	if not args.size or args.size == "" then
		args.size = "small"
	end
	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]]"):format(
				args.icon,
				frameIconSizeDimensions[args.size],
				args.link
			)
		)
		: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 link
-- @param size
-- @param type
-- @param frameType
-- @param hq For items only
-- @param dyeCount For items only
local function gameIcon(args)
	-- 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 = args.icon,
			link = args.link,
			size = args.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 = args.icon,
		link = args.link,
		size = args.size,
		frame = frameType,
		dyeCount = args.dyeCount,
	})
end

-- function to be invoked from templates that don't display labels
function p.renderGameIcon(frame)
	return gameIcon({
		-- normalize parameters
		icon = frame.args.icon,
		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

	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 - this is a bit hacky but w/e
	span:node(p.renderGameIcon(frame))

	-- render quantity, if present
	if qty then
		span:node(" " .. qty)
	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

--- internal helper for generic template usage where items/etc need to be looked
--- up via SMW query. really just a helper to invoke {{#ask}} with some fancy
--- parameters and format the result with {{Game icon format}}, which in turn
--- just calls back to this module's p.renderGameIconWithLabel. very cursed.
function p.gameIconFromQuery(args)
	return mw.getCurrentFrame():callParserFunction("#ask", {
		args.query,
		"?=Pagename",
		"?Has context",
		"?Has game icon",
		"?Has canonical name",
		"?Has dye channels",
        limit = 1,
        searchlabel = "",
		format = "plainlist",
		link = "none",
		["named args"] = "yes",
		template = "Game icon format",
		userparam = ("%s;%s;%s;%s;%s"):format(
			args.text or "",
			args.size or "",
			args.hq and "y" or "",
			args.qty or "",
			args.allowWrap and "y" or ""
		)
	})
end

--- gameIconWithQuery wrapped for use with {{#invoke}}
function p.renderGameIconFromQuery(frame)
	return p.gameIconFromQuery({
		query = frame.args.query,
		text = frame.args.text,
		size = frame.args.size,
		hq = yesno(frame.args.hq),
		qty = frame.args.qty,
		allowWrap = yesno(frame.args.allowWrap)
	})
end

return p

Module:Icon

Contents

Wikitext functions

`renderGameIcon`

Parameters

Example

`renderGameIconWithLabel`

Parameters

Examples

`renderGameIconFromQuery`

Parameters

Examples

Lua functions

`plainIcon`

Parameters

Returns

Example

`frameIcon`

Parameters

Returns

Example

`gameIconFromQuery`

Parameters

Returns

Examples

Navigation menu

Module:Icon

Wikitext functions

renderGameIcon

Parameters

Example

renderGameIconWithLabel

Parameters

Examples

renderGameIconFromQuery

Parameters

Examples

Lua functions

plainIcon

Parameters

Returns

Example

frameIcon

Parameters

Returns

Example

gameIconFromQuery

Parameters

Returns

Examples

Navigation menu

Search

`renderGameIcon`

`renderGameIconWithLabel`

`renderGameIconFromQuery`

`plainIcon`

`frameIcon`

`gameIconFromQuery`