Module:ResourceLink: Difference between revisions

From Against the Storm Official Wiki
m (fixing duplicate icon extension)
(Streamlined and updated to use new GoodsData. Also streamlined the documentation, to be less duplicative with the template doc but still helpful. Also created a method modules can call directly with an ID)
Line 1: Line 1:
-------------------------------------------------------------------------------
---
-- This module renders the {{Resource _link}} template.
--- This module renders the Resource_link template to draw an icon and link in
-- https://hoodedhorse.com/wiki/Against_the_Storm/Template:Resource_link
--- wiki markup.
--
---
-- This template #invokes ResourceLink.renderLink(frame), below.
--- The template requires an argument, the name of the resource to which
--
--- to link. Optionally, the template accepts a second argument to change the
-- The template requires an argument, the name of the resource to which to link.
--- size of the icon that accompanies the text hyperlink.
-- Optionally, the template accepts a second argument to change the size of the
---
-- icon that accompanies the text hyperlink. The resource is passed to
--- By default, the icon will default to a small size appropriate for display
-- Module:GoodsData, which is used to identify the wiki page to link to.
--- in-line with other text. For display in tables to help with recognition,
--
--- use iconsize=med.
-- Using the data returned, this module creates an icon and the name of the
---
-- resource, and wraps both in a link to the resource's wiki page. If no icon
--- See the template documentation for more information about parameters and
-- size is specified, the icon will default to a size appropriate for display
--- errors and to see examples.
-- in-line with other text.
---
--
--- @module ResourceLink
-- The icons are sized consistently by using existing wiki templates, {{ImgS}},
-- {{ImgM}}, etc. The sizes of icons are not stored or known by this module.
-- @module ResourceLink
local ResourceLink = {}
local ResourceLink = {}


---
 
-- Dependencies
 
--
local GoodsData = require("Module:GoodsData")
local GoodsData = require("Module:GoodsData")




--region Private constants
local FLAG_NO_ICON = "none"
local DEFAULT_ICON_SIZE_TEMPLATE = "ImgM"
local MAP_ICON_SIZE_TEMPLATES = {
["small"] = "ImgS",
["med"] = DEFAULT_ICON_SIZE_TEMPLATE,
["large"] = "ImgL",
["huge"] = "ImgH"
}
local NBSP = " "
--endregion
--region Private methods


---
---
-- Constants
--- 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
-- Indexes for the data returned from GoodsData.
--- standard size for the wiki.
local INDEX_GOOD_NAME = "displayName"
---
local INDEX_GOOD_ICON_FILENAME = "iconName"
---@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


-- Parameter options for icon size.
local SIZE_S = "small"
local SIZE_M = "med"
local SIZE_L = "large"
local SIZE_H = "huge"
-- Use size templates for consistency.
local TEMPLATE_IMGSMALL = "ImgS"
local TEMPLATE_IMGMED = "ImgM"
local TEMPLATE_IMGLARGE = "ImgL"
local TEMPLATE_IMGHUGE = "ImgH"




--region Public methods


---
---
-- Main rendering function
--- Create a resource link by passing the ID of the resource rather than
--
--- through the template. Useful for calling from other modules.
-- Renders an icon the name of a resource linked to a wiki page corresponding
---
-- to the provided resource.
---@param goodID string the ID of the good to link to
--  
---@param iconSize string "small", "med", "large", or "huge"
-- Uses MediaWiki markup to display the name of a wiki page and an icon that has
---@return string wiki markup of icon and link
-- been uploaded to the wiki. Both must be known by Module:GoodsData, or there
function ResourceLink.resourceLinkWithID(goodID, iconSize)
-- will be a display problem.
 
-- @param frame the template's calling context, with parameters
-- At runtime, this should never be nil or empty.
-- @return wiki markup
if not goodID or goodID == "" then
function ResourceLink.renderLink(frame)
error("No good specified to which to make a link.")
-- Extract the template parameters.
local argResourceName = frame.args.resource
local argIconsize = frame.args.iconsize
-- Validate that there's a resource name to use
if not argResourceName or "" == argResourceName then
return "The Resource Link template a name of a resource."
end
end
 
-- Look up the resource from GoodsData
local goodName = GoodsData.getGoodNameByID(goodID)
local good = GoodsData.getAllDataForGood(argResourceName)
 
if not goodName then
if not good then
return "No goods found with that ID: " .. goodID .. "."
return "Cannot find a resource with that name: " .. argResourceName .."."
end
end
 
local goodName = good[INDEX_GOOD_NAME]
local goodIconFilename = GoodsData.getGoodIconByID(goodID)
local goodIconFilename = good[INDEX_GOOD_ICON_FILENAME]
 
return makeResourceLink(goodName, goodIconFilename, iconSize)
-- the wiki markup for the internal link to the resource's wiki page
end
local linkPart = "[[" .. goodName .. "]]"
 
 
-- store the requested size for use in a moment
 
local size = ""
---
--- Called from Template:Resource_link to create a link, with an icon, to the
-- Expand the size template for the requested size.
--- page for the specified goods.
if SIZE_M == argIconsize then
---
size = frame:expandTemplate{title=TEMPLATE_IMGMED}
---@param frame table the Mediawiki context from the template
elseif SIZE_L == argIconsize then
---@return string wikimarkup representing an icon and link
size = frame:expandTemplate{title=TEMPLATE_IMGLARGE}
function ResourceLink.resourceLink(frame)
elseif SIZE_H == argIconsize then
 
size = frame:expandTemplate{title=TEMPLATE_IMGHUGE}
-- Extract template parameters.
else
local argResource = frame.args["resource"]
-- Default to small size if the argument wasn't valid.
local argIconSize = frame.args["iconsize"]
size = frame:expandTemplate{title=TEMPLATE_IMGSMALL}
 
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
end
 
-- combine the size and filename to form the iconPart
return makeResourceLink(argResource, goodIconFilename, argIconSize)
local iconPart = "[[File:" .. goodIconFilename .. "|" .. size .. "|link=" .. goodName .. "|alt=" .. goodName .. "|" .. goodName .. "]]"
-- combine the file part with the link part
return iconPart .. " " .. linkPart
end
end


--endregion


-- return when required into another module
return ResourceLink
return ResourceLink

Revision as of 21:54, 18 November 2023

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 = "ImgM"
local MAP_ICON_SIZE_TEMPLATES = {
	["small"] = "ImgS",
	["med"] = DEFAULT_ICON_SIZE_TEMPLATE,
	["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