Module:SpeciesLink

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

-------------------------------------------------------------------------------
-- This module renders the {{Species _link}} template.
-- https://hoodedhorse.com/wiki/Against_the_Storm/Template:Species_link
--
-- This template #invokes SpeciesLink.renderLink(frame), below.
--
-- The template requires an argument, the name of the Species to which to link.
-- Optionally, the template accepts a second argument to change the size of the
-- icon that accompanies the text hyperlink. The Species is passed to 
-- Module:SpeciesData, which is used to identify the wiki page to link to. It 
-- also handles some basic normalization to tolerate small mistakes in spelling,
-- spacing, or punctuation.
--
-- Using the data returned, this module creates an icon and the name of the 
-- Species, and wraps both in a link to the Species's wiki page. If no icon
-- size is specified, the icon will default to a size appropriate for display
-- in-line with other text.
--
-- IF there is a known Species 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 Species'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 icons are not stored or known by this module.
-- @module SpeciesLink
local SpeciesLink = {}

--
-- Dependencies
--
local SpeciesData = require("Module:SpeciesData") -- lookup table for Species



--
-- 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 Species linked to a wiki page corresponding
-- to the provided Species.
-- 
-- 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:SpeciesData, 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']['Species'] is the first
-- argument, assigned to the key 'Species'; 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 SpeciesLink.renderLink(frame)
	
	-- extract the arguments we care about from the frame
	local argSpeciesName = frame.args.Species
	local argIconsize = frame.args.iconsize
	
	-- validate that there's a Species name to use
	if not argSpeciesName or "" == argSpeciesName then
		return "SpeciesLink error: no Species given"
	end
	
	-- get the page name to make sure there was one
	local Species = SpeciesData.getPagename(argSpeciesName)
	if not Species or "" == Species then
		return "SpeciesLink error: " .. argSpeciesName .." not found"
	end
	
	-- the wiki markup for the internal link to the Species's wiki page
	local linkPart = "[[" .. Species .. "]]"
	
	-- 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
		-- default to small size if the argument wasn't valid
		size = frame:expandTemplate{title=TEMPLATE_IMGSMALL}
	end
	
	-- If the icon filename doesn't exist, we can still continue by substituting 
	-- a question mark icon instead.
	local icon = SpeciesData.getIconFilename(argSpeciesName)
	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=" .. Species .. "|alt=" .. Species .. "|" .. Species .. "]]"
	
	-- combine the file part with the link part
	return iconPart .. " " .. linkPart
end



-- return when required into another module
return SpeciesLink