Module:ResourceLink: Difference between revisions

From Against the Storm Official Wiki
(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)
(now with error checking!)
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
---
--- 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
--- @module ResourceLink
local ResourceLink = {}
local ResourceLink = {}




--region Dependencies


local GoodsData = require("Module:GoodsData")
local GoodsData = require("Module:GoodsData")
local VIEW_TEMPLATE = "Resource_link/view"
--endregion




Line 25: Line 15:
--region Private constants
--region Private constants


local FLAG_NO_ICON = "none"
local VALID_SIZE = {
 
["none"] = true,
local DEFAULT_ICON_SIZE_TEMPLATE = "ImgM"
["small"] = true,
local MAP_ICON_SIZE_TEMPLATES = {
["medium"] = true,
["small"] = "ImgS",
["large"] = true,
["med"] = DEFAULT_ICON_SIZE_TEMPLATE,
["huge"] = true,
["large"] = "ImgL",
["huge"] = "ImgH"
}
}
local NBSP = " "


--endregion
--endregion
Line 43: Line 29:
--region Private methods
--region Private methods


---validateResourceName retrieves the icon from the data module.
---
---
--- Writes the wiki markup for the icon and the link. Uses the private constant
---@param name string the display name of a resource
--- map to look up the size template and expands that template to conform to
---@return string the filename of the icon
--- standard size for the wiki.
local function validateResourceName(name)
---
---@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
local goodID = GoodsData.getGoodID(name)
iconPart = "[[File: " .. goodIconFilename .. "|" .. pxSize .. "|link=" .. goodName
local validatedIcon = GoodsData.getIcon(goodID)
.. "|alt=" .. goodName .. "|" .. goodName .. "]]"
.. NBSP
end


if not validatedIcon then
error("No resource found with name: " .. name .. ". Please see the template documentation for how to use the parameters")
end
end


return iconPart .. linkPart
return validatedIcon
end
end


Line 79: Line 51:
--region Public methods
--region Public methods


---main is called from the template to create a link, with an icon, to the page for the specified goods.
---
---
--- Create a resource link by passing the ID of the resource rather than
---@param frame table the Mediawiki template context
--- through the template. Useful for calling from other modules.
---@return string wikimarkup generated by the view template
---
function ResourceLink.main(frame)
---@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)
local name = frame.args.name
local iconSize = frame.args.size
local display = frame.args.display


if not goodName then
if not name or name == "" then
return "No goods found with that ID: " .. goodID .. "."
error("You must specify a resource. Please see the template documentation for how to use the parameters")
end
end


local goodIconFilename = GoodsData.getGoodIconByID(goodID)
-- Validate the name.
validatedIcon = validateResourceName(name)


return makeResourceLink(goodName, goodIconFilename, iconSize)
-- Handle default icon size.
end
if not iconSize or iconSize == "" or not VALID_SIZE[iconSize] then
 
iconSize = "small"
 
 
---
--- 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
end


local goodIconFilename = GoodsData.getGoodIcon(argResource)
-- The args to pass to the view.
if not goodIconFilename then
viewParameters = {
return "No goods found with that name: " .. argResource .. "."
["name"] = name,
end
["iconfilename"] = validatedIcon,
["iconsize"] = iconSize,
["display"] = display,
}


return makeResourceLink(argResource, goodIconFilename, argIconSize)
return frame:expandTemplate{
title = VIEW_TEMPLATE,
args = viewParameters,
}
end
end


Latest revision as of 02:44, 19 October 2024

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

--- @module ResourceLink
local ResourceLink = {}


--region Dependencies

local GoodsData = require("Module:GoodsData")

local VIEW_TEMPLATE = "Resource_link/view"

--endregion



--region Private constants

local VALID_SIZE = {
	["none"] = true,
	["small"] = true,
	["medium"] = true,
	["large"] = true,
	["huge"] = true,
}

--endregion



--region Private methods

---validateResourceName retrieves the icon from the data module.
---
---@param name string the display name of a resource
---@return string the filename of the icon
local function validateResourceName(name)

	local goodID = GoodsData.getGoodID(name)
	local validatedIcon = GoodsData.getIcon(goodID)

	if not validatedIcon then
		error("No resource found with name: " .. name .. ". Please see the template documentation for how to use the parameters")
	end

	return validatedIcon
end

--endregion



--region Public methods

---main is called from the template to create a link, with an icon, to the page for the specified goods.
---
---@param frame table the Mediawiki template context
---@return string wikimarkup generated by the view template
function ResourceLink.main(frame)

	local name = frame.args.name
	local iconSize = frame.args.size
	local display = frame.args.display

	if not name or name == "" then
		error("You must specify a resource. Please see the template documentation for how to use the parameters")
	end

	-- Validate the name.
	validatedIcon = validateResourceName(name)

	-- Handle default icon size.
	if not iconSize or iconSize == "" or not VALID_SIZE[iconSize] then
		iconSize = "small"
	end

	-- The args to pass to the view.
	viewParameters = {
		["name"] = name,
		["iconfilename"] = validatedIcon,
		["iconsize"] = iconSize,
		["display"] = display,
	}

	return frame:expandTemplate{
		title = VIEW_TEMPLATE,
		args = viewParameters,
	}
end

--endregion

return ResourceLink
Retrieved from "https://hoodedhorse.com/wiki/Against_the_Storm/index.php?title=Module:ResourceLink&oldid=8924"