Module:SpeciesLink: Difference between revisions

From Against the Storm Official Wiki
No edit summary
No edit summary
Line 1: Line 1:
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
-- This module renders the {{Species _link}} template.
-- This module renders the {{Species _link}} template.
-- https://hoodedhorse.com/wiki/Against_the_Storm/Template:Resource_link
-- https://hoodedhorse.com/wiki/Against_the_Storm/Template:Species_link
--
--
-- This template #invokes SpeciesLink.renderLink(frame), below.
-- This template #invokes SpeciesLink.renderLink(frame), below.
Line 8: Line 8:
-- Optionally, the template accepts a second argument to change the size of the
-- Optionally, the template accepts a second argument to change the size of the
-- icon that accompanies the text hyperlink. The Species is passed to  
-- icon that accompanies the text hyperlink. The Species is passed to  
-- Module:ResourceData, which is used to identify the wiki page to link to. It  
-- 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,
-- also handles some basic normalization to tolerate small mistakes in spelling,
-- spacing, or punctuation.
-- spacing, or punctuation.
Line 31: Line 31:
-- Dependencies
-- Dependencies
--
--
local ResourceData = require("Module:ResourceData") -- lookup table for resources
local SpeciesData = require("Module:SpeciesData") -- lookup table for Speciess




Line 64: Line 64:
--  
--  
-- Uses MediaWiki markup to display the name of a wiki page and an icon that has  
-- 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:ResourceData, or the  
-- been uploaded to the wiki. Both must be known by Module:SpeciesData, or the  
-- template's behavior may be different than expected.
-- template's behavior may be different than expected.
-- @param frame  a table describing the MediaWiki frame; frame['args'] is a  
-- @param frame  a table describing the MediaWiki frame; frame['args'] is a  
Line 75: Line 75:
-- extract the arguments we care about from the frame
-- extract the arguments we care about from the frame
local argResourceName = frame.args.Species
local argSpeciesName = frame.args.Species
local argIconsize = frame.args.iconsize
local argIconsize = frame.args.iconsize
-- validate that there's a Species name to use
-- validate that there's a Species name to use
if not argResourceName or "" == argResourceName then
if not argSpeciesName or "" == argSpeciesName then
return "SpeciesLink error: no Species given"
return "SpeciesLink error: no Species given"
end
end
-- get the page name to make sure there was one
-- get the page name to make sure there was one
local Species = ResourceData.getPagename(argResourceName)
local Species = SpeciesData.getPagename(argSpeciesName)
if not Species or "" == Species then
if not Species or "" == Species then
return "SpeciesLink error: " .. argResourceName .." not found"
return "SpeciesLink error: " .. argSpeciesName .." not found"
end
end
Line 110: Line 110:
-- If the icon filename doesn't exist, we can still continue by substituting  
-- If the icon filename doesn't exist, we can still continue by substituting  
-- a question mark icon instead.
-- a question mark icon instead.
local icon = ResourceData.getIconFilename(argResourceName)
local icon = SpeciesData.getIconFilename(argSpeciesName)
if not icon or "" == icon then
if not icon or "" == icon then
icon = REPLACEMENT_FILENAME
icon = REPLACEMENT_FILENAME

Revision as of 10:01, 11 November 2023

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 Speciess



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