Module:ResourceLink

Documentation for this module may be created at Module:ResourceLink/doc

---
--- This module renders the Resource_link template to draw an icon and link in
--- wiki markup.
---
--- The template requires an argument, the name of the resource to which
--- to link. Optionally, the template accepts a second argument to change the
--- size of the icon that accompanies the text hyperlink.
---
--- By default, the icon will default to a small size appropriate for display
--- in-line with other text. For display in tables to help with recognition,
--- use iconsize=med.
---
--- See the template documentation for more information about parameters and
--- errors and to see examples.
---
--- @module ResourceLink
local ResourceLink = {}



local GoodsData = require("Module:GoodsData")



--region Private constants

local FLAG_NO_ICON = "none"

local DEFAULT_ICON_SIZE_TEMPLATE = "ImgS"
local MAP_ICON_SIZE_TEMPLATES = {
	["small"] = DEFAULT_ICON_SIZE_TEMPLATE,
	["med"] = "ImgM",
	["large"] = "ImgL",
	["huge"] = "ImgH"
}

local NBSP = " "

--endregion



--region Private methods

---
--- Writes the wiki markup for the icon and the link. Uses the private constant
--- map to look up the size template and expands that template to conform to
--- standard size for the wiki.
---
---@param goodName string the name of the goods' page to link to
---@param goodIconFilename string the complete filename to write
---@param iconSize string "none", "small", "med", "large", or "huge"
---@return string wiki markup of icon and hyperlink
local function makeResourceLink(goodName, goodIconFilename, iconSize)

	local linkPart = "[[" .. goodName .. "]]"
	local iconPart = ""

	if iconSize and iconSize ~= FLAG_NO_ICON then

		local iconTemplate = MAP_ICON_SIZE_TEMPLATES[iconSize] or DEFAULT_ICON_SIZE_TEMPLATE
		local pxSize = mw.getCurrentFrame():expandTemplate{ title=iconTemplate }

		if goodIconFilename and goodIconFilename ~= "" then
			iconPart = "[[File: " .. goodIconFilename .. "|" .. pxSize .. "|link=" .. goodName
					.. "|alt=" .. goodName .. "|" .. goodName .. "]]"
					.. NBSP
		end

	end

	return iconPart .. linkPart
end

--endregion



--region Public methods

---
--- Create a resource link by passing the ID of the resource rather than
--- through the template. Useful for calling from other modules.
---
---@param goodID string the ID of the good to link to
---@param iconSize string "small", "med", "large", or "huge"
---@return string wiki markup of icon and link
function ResourceLink.resourceLinkWithID(goodID, iconSize)

	-- At runtime, this should never be nil or empty.
	if not goodID or goodID == "" then
		error("No good specified to which to make a link.")
	end

	local goodName = GoodsData.getGoodNameByID(goodID)

	if not goodName then
		return "No goods found with that ID: " .. goodID .. "."
	end

	local goodIconFilename = GoodsData.getGoodIconByID(goodID)

	return makeResourceLink(goodName, goodIconFilename, iconSize)
end



---
--- Called from Template:Resource_link to create a link, with an icon, to the
--- page for the specified goods.
---
---@param frame table the Mediawiki context from the template
---@return string wikimarkup representing an icon and link
function ResourceLink.resourceLink(frame)

	-- Extract template parameters.
	local argResource = frame.args["resource"]
	local argIconSize = frame.args["iconsize"]

	if not argResource or argResource == "" then
		return "The Resource_link template requires the name of a resource."
	end

	local goodIconFilename = GoodsData.getGoodIcon(argResource)
	if not goodIconFilename then
		return "No goods found with that name: " .. argResource .. "."
	end

	return makeResourceLink(argResource, goodIconFilename, argIconSize)
end

--endregion

return ResourceLink