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:BuildingData, which is used to
-- identify the wiki page to link to. It also handles some basic normalization 
-- to tolerate some small mistakes in spelling, spacing, or punctuation.
--
-- 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.
-- 
-- If there is a known building that does not have an icon (might be the case if
-- the data is being updated), then a question-mark icon will take the place of 
-- the building's icon. This is so that people using this template will not 
-- mistake a missing icon for an issue with this template and can efficienty 
-- troubleshoot.
--
-- 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 BuildingData = require("Module:BuildingData") -- lookup table for buildings



--
-- Constants
--
-- names of the templates used to size the icons consistently
local TEMPLATE_IMGSMALL = "ImgS"
local TEMPLATE_IMGMED = "ImgM"
local TEMPLATE_IMGLARGE = "ImgL"
local TEMPLATE_IMGHUGE = "ImgH"

-- string options for icon size arguments
local S_SML = "small"
local S_MED = "med"
local S_LRG = "large"
local S_HUG = "huge"

-- filename to use if there is no known icon for a known building
local REPLACEMENT_FILENAME = "Question_mark.png"



--
-- 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  a table describing the MediaWiki frame; frame['args'] is a 
-- table containg the template arguments; frame['args']['building'] is the first
-- argument, assigned to the key 'building'; frame['args']['iconsize'] is the 
-- second argument, assigned to the key 'iconsize'
-- @return a string containing the wiki markup for an icon and an internal wiki 
-- page link (or an error if a problem occured)
function BuildingLink.renderLink(frame)
	
	-- extract the arguments we care about from the frame
	local argBuildingName = frame.args.building
	local argIconsize = frame.args.iconsize
	
	-- validate that there's a building name to use
	if not argBuildingName or "" == argBuildingName then
		return "BuildingLink error: no building given"
	end
	
	-- get the page name to make sure there was one
	local building = BuildingData.getPagename(argBuildingName)
	if not building or "" == building then
		return "BuildingLink error: " .. argBuildingName .." not found"
	end
	
	-- the wiki markup for the internal link to the building's wiki page
	local linkPart = "[[" .. building .. "]]"
	
	-- If there's no icon size specified, or if it's specified to be small 
	-- (which is too small for building icons), then we can return the wiki link 
	-- right away.
	-- This is the default behavior.
	if not argIconsize or "" == argIconsize or "small" == argIconsize then
		return linkPart
	end
	
	--
	-- At this point, an icon size is requested.
	--
	
	-- store the requested size for use in a moment
	local size = ""
	
	-- Check the requested size against the allowed options. Expand the 
	-- corresponding template.
	if S_MED == argIconsize then
		size = frame:expandTemplate{title=TEMPLATE_IMGMED}
	elseif S_LRG == argIconsize then
		size = frame:expandTemplate{title=TEMPLATE_IMGLARGE}
	elseif S_HUG == argIconsize then
		size = frame:expandTemplate{title=TEMPLATE_IMGHUGE}
	else
		-- However, if the argument did not match one of the valid sizes, then
		-- we just return the link itself, with no icon.
		return linkPart
	end
	
	-- If the icon filename doesn't exist, we can still continue by substituting 
	-- a question mark icon instead.
	local icon = BuildingData.getIconFilename(argBuildingName)
	if not icon or "" == icon then
		icon = REPLACEMENT_FILENAME
	end
	
	-- combine the size and filename to form the iconPart
	local iconPart = "[[File:" .. icon .. "|" .. size .. "|link=" .. building .. "|alt=" .. building .. "|" .. building .. "]]"
	
	-- combine the file part with the link part, separated by one space
	return iconPart .. " " .. linkPart
end



-- return when required into another module
return BuildingLink