Module:BuildingLink

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

-------------------------------------------------------------------------------
-- This module renders the {{Building_link}} template.
-- https://hoodedhorse.com/wiki/Against_the_Storm/Template:Building_link
--
-- The template #invokes BuildingLink.renderLink(frame), below.
--
-- The template requires an argument, the name of the building to which to link.
-- Optionally, the template accepts a second argument to render an icon next to 
-- the link. The building is passed to Module:WorkshopsData, which is used to
-- identify the wiki page to link to.
--
-- Using the data returned, this module creates an icon and the name of the 
-- building, and wraps both in a link to the building's wiki page. If no icon
-- size is specified, only the name of the building will be rendered by the
-- template.
--
-- The icons are sized consistently by using existing wiki templates, {{ImgS}},
-- {{ImgM}}, etc. The sizes of the icons are not stored or known by this module.
-- @module BuildingLink
local BuildingLink = {}

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



--
-- Constants
--
-- Indexes for accessing the data retrieved from WorkshopsData
local INDEX_ICON_PREFIX = 1
local INDEX_WORKSHOP_NAME = 2

local ICONFILENAME_SUFFIX = "_icon"

-- 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"



---
-- Main rendering function
--
-- Renders an icon the name of a building linked to a wiki page corresponding
-- to the provided building.
--
-- Uses MediaWiki markup to display the name of a wiki page and an icon that has 
-- been uploaded to the wiki. Both must be known by Module:BuildingData, or the
-- template's behavior may be different than expected.
-- @param frame the template's calling context, with parameters
-- @return wiki markup
function BuildingLink.renderLink(frame)
	
	-- Extract the template parameters.
	local argBuildingName = frame.args.building
	local argIconsize = frame.args.iconsize
	
	-- Validate that there's a name to use
	if not argBuildingName or "" == argBuildingName then
		return "The Building Link template a name of a building."
	end
	
	-- Look it up from the data source
	local workshop = WorkshopsData.getAllDataForWorkshop(argBuildingName)
	
	if not workshop then
		return "Cannot find a building with that name: " .. argBuildingName .. "."
	end
	
	local workshopName = workshop[INDEX_WORKSHOP_NAME]
	local workshopIconFilename = workshop[INDEX_ICON_PREFIX] .. ICONFILENAME_SUFFIX
	
	-- Wiki link to the building's page just uses the in-game name.
	local linkPart = "[[" .. workshopName .. "]]"
	
	-- store the requested size for use in a moment
	local size = ""
	
	-- Check the requested size against the allowed options. Expand the 
	-- corresponding template.
	if SIZE_M == argIconsize then
		size = frame:expandTemplate{title=TEMPLATE_IMGMED}
	elseif SIZE_L == argIconsize then
		size = frame:expandTemplate{title=TEMPLATE_IMGLARGE}
	elseif SIZE_H == argIconsize then
		size = frame:expandTemplate{title=TEMPLATE_IMGHUGE}
	else
		-- However, if the argument did not match one of the valid sizes, or if
		-- it's just SIZE_S, then we just return the link itself, with no icon.
		return linkPart
	end
	
	-- combine the size and filename to form the iconPart
	local iconPart = "[[File:" .. workshopIconFilename .. ".png|" .. size .. "|link=" .. workshopName .. "|alt=" .. workshopName .. "|" .. workshopName .. "]]"
	
	-- combine the file part with the link part
	return iconPart .. " " .. linkPart
end



-- return when required into another module
return BuildingLink