Module:ServiceLink

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

---
--- This module renders the Service_link template to draw an icon and link in
--- wiki markup.
---
--- The template requires an argument, the name of the service 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 ServiceLink
local ServiceLink = {}



local ServicesRecipesData = require("Module:ServicesRecipesData")



--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 name string the name of the services' page to link to
---@param iconFilename 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 makeLink(name, iconFilename, iconSize)

	local linkPart = "[[" .. name .. "]]"
	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 iconFilename and iconFilename ~= "" then
			iconPart = "[[File: " .. iconFilename .. "|" .. pxSize .. "|link=" .. name
					.. "|alt=" .. name .. "|" .. name .. "]]"
					.. NBSP
		end

	end

	return iconPart .. linkPart
end

--endregion



--region Public methods

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

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

	local name = ServicesRecipesData.getRecipeServiceNameByID(id)

	if not name then
		return "No service found with that ID: " .. id .. "."
	end

	local iconFilename = ServicesRecipesData.getRecipeServiceIconByID(id)

	return makeLink(name, iconFilename, iconSize)
end



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

	-- Extract template parameters.
	local argService = frame.args["service"]
	local argIconSize = frame.args["iconsize"]

	if not argService or argService == "" then
		return "The Service link template requires the name of a service."
	end

	local id = ServicesRecipesData.getAllRecipeIDsForServiceName(argService)

	if not id then
		return "No service found with that name: " .. argService .. "."
	end

	local iconFilename = ServicesRecipesData.getRecipeServiceIconByID(id[1])

	return makeLink(argService, iconFilename, argIconSize)
end

--endregion

return ServiceLink