Module:VersionMessageBox: Difference between revisions

From Against the Storm Official Wiki
m (modified the styling some more)
(Updated with css style classes, and changed version checking to be more robust for major versions only)
Line 1: Line 1:
-------------------------------------------------------------------------------
---
-- This module renders the {{Version}} template.
--- This module renders the {{Version}} template.
-- https://hoodedhorse.com/wiki/Against_the_Storm/Template:Version
--- https://hoodedhorse.com/wiki/Against_the_Storm/Template:Version
--
---
-- This template #invokes VersionMessageBox.checkVersion(frame), below.
--- This template #invokes VersionMessageBox.checkVersion(frame), below.
--
---
-- The template requires one argument provided by wiki page writers using the  
--- The template requires one argument provided by wiki page writers using the
-- template, which is the version of the game when the wiki page was last  
--- template, which is the version of the game when the wiki page was last
-- updated. There is a second argument provided by the template itself that the
--- updated. There is a second argument provided by the template itself that the
-- page writers canont overwrite, which always refers to the current version of
--- page writers canont overwrite, which always refers to the current version of
-- the game. The current version is identified by the wiki as  
--- the game. The current version is identified by the wiki as
-- {{CurrentVersion}}.
--- {{CurrentVersion}}.
--
---
-- Depending on the arguments, this module creates a message box that displays
--- Depending on the arguments, this module creates a message box that displays
-- when a reader opens a page that hasn't been reviewed and updated since the
--- when a reader opens a page that hasn't been reviewed and updated since the
-- version changed. The message box tells the reader what version of the game
--- version changed. The message box tells the reader what version of the game
-- the page was udpated with, the current version, and an encouraging note to
--- the page was udpated with, the current version, and an encouraging note to
-- help keep the wiki up to date.
--- help keep the wiki up to date.
-- @module VersionMessageBox
--- @module VersionMessageBox
local VersionMessageBox = {}
local VersionMessageBox = {}


--
 
-- Constants
 
--
local StyleUtils = require("Module:StyleUtils")
-- specialization names
 
 
 
--region Private constants
 
local PATTERN_CAPTURE_MAJOR_VERSION = "(%d+%.%d+)"
 
local CSS_VERSION_MESSAGE_BOX = "max-width: 500px; margin-left: auto; padding: 15px; border: 1px solid #8ab3ff; border-radius: 12px; background: #dbe8ff; font-size: 10px"
local CSS_VERSION_MESSAGE_BOX = "max-width: 500px; margin-left: auto; padding: 15px; border: 1px solid #8ab3ff; border-radius: 12px; background: #dbe8ff; font-size: 10px"
local CSS_CLASS_VERSION_MESSAGE_BOX = "ATS-version-message-box"
 
local CSS_COLOR_VERSION_BACKGROUND = "#dbe8ff"
--endregion
local CSS_COLOR_VERSION_BORDER = "#8ab3ff"
 
local MESSAGE_BOX_ICON = "Hourglass_Icon_.png"




--region Private methods


--
---
-- Main rendering function
--- Renders the message box.
--
---
--- Renders a div with the appropriate CSS class for correct display. The div
--- contains the message about the version of the page and the current version
--- of the game. And it includes a statement encouraging people to keep the
--- wiki up to date.
---
--- @param argLastUpdated string the version of the game when the page was updated
--- @param argCurrentVersion string the current version of the game
--- @return string the HTML markup for a message box
local function renderMessageBox(argLastUpdated, argCurrentVersion)


-------------------------------------------------------------------------------
local div = mw.html.create('div')
-- Checks whether a message box is necessary.
 
--
div:addClass(CSS_CLASS_VERSION_MESSAGE_BOX)
-- If the page is outdated, calls the method to draw the message box and adds  
div:cssText(CSS_VERSION_MESSAGE_BOX)
-- the right category to the page.
 
-- @param frame a table describing the MediaWiki frame; frame['args'] is a
messageText = "This page was last updated during version '''" .. argLastUpdated .. "'''." ..
-- table containg the template arguments; frame['args']['updated'] is the first
"The game is now in version '''" .. argCurrentVersion .. "'''.<br />" ..
-- argument; frame['args']['currentVersion'] is the second argument.
"Some information may be out of date. " ..
-- @return a string containing the wiki markup for a message box, or an empty
"Help us keep the wiki up to date by comparing this article against the patch notes and updating this page."
-- string if the page is updated
 
div:wikitext("[[File:" .. MESSAGE_BOX_ICON .. "|left|x48px|link=|Out of date]] ")
  :tag('div'):cssText("margin-left: 60px")
  :wikitext(messageText)
 
return div
end
 
 
---
--- Extracts just the major version parts of the numbers and returns whether
--- the content is out of date.
---
---@param versionWhenLastUpdated string the version it was last updated
---@param currentVersion string the current version
---@return boolean true if the last updated is before the current major version
local function isOutOfDate(versionWhenLastUpdated, currentVersion)
 
local lastUpdated = tonumber(versionWhenLastUpdated:match(PATTERN_CAPTURE_MAJOR_VERSION) or 0)
local current = tonumber(currentVersion:match(PATTERN_CAPTURE_MAJOR_VERSION) or 0)
 
return current > lastUpdated
end
 
--endregion
 
 
 
--region Public methods
 
---
--- Checks whether a message box is necessary.
---
--- If the page is outdated, calls the method to draw the message box and adds
--- the right category to the page.
---
---@param frame table the template's calling context
---@return string wiki markup for a message box, or a blank string if it's up-to-date
function VersionMessageBox.checkVersion(frame)
function VersionMessageBox.checkVersion(frame)
 
-- extract the arguments we care about from the frame
-- extract the arguments we care about from the frame
local argLastUpdated = frame.args.updated
local argLastUpdated = frame.args.updated
local argCurrentVersion = frame.args.currentVersion
local argCurrentVersion = frame.args.currentVersion
 
-- validate that there are version values to use
-- validate that there are version values to use
if not argLastUpdated or "" == argLastUpdated then
if not argLastUpdated or "" == argLastUpdated then
Line 59: Line 111:
return "Version error: template did not identify current version correctly"
return "Version error: template did not identify current version correctly"
end
end
 
-- let's try it for a while just checking whether they are different. In the
if isOutOfDate(argLastUpdated, argCurrentVersion) then
-- future, we may need to add actual numerical-comparison checks.
 
if argLastUpdated == argCurrentVersion then
local html = renderMessageBox(argLastUpdated, argCurrentVersion)
return tostring(html)
else
-- the page is up to date, nothing else needed
-- the page is up to date, nothing else needed
return ""
return ""
else
-- render the message box
local html = VersionMessageBox.renderMessageBox(argLastUpdated, argCurrentVersion)
-- add the category at the bottom.
--[[ mw:addCategory("Pages needing version review") this doesn't work --]]
return tostring(html)
end
end
end
end


--endregion


---
-- Renders the message box.
--
-- Renders a div with the appropriate CSS class for correct display. The div
-- contains the message about the version of the page and the current version of
-- the game. And it includes a statement encouraging people to keep the wiki up
-- to date.
-- @param argLastUpdated the version of the game when the page was updated
-- @param argCurrentVersion the current version of the game
-- @return the HTML markup for a message box
function VersionMessageBox.renderMessageBox(argLastUpdated, argCurrentVersion)
local div = mw.html.create('div')
div:addClass(CSS_CLASS_VERSION_MESSAGE_BOX)
div:cssText(CSS_VERSION_MESSAGE_BOX)
messageText = "This page was last updated during version '''" .. argLastUpdated .. "'''." ..
"The game is now in version '''" .. argCurrentVersion .. "'''.<br />" ..
"Some information may be out of date. " ..
"Help us keep the wiki up to date by comparing this article against the patch notes and updating this page."
div:wikitext("[[File:" .. MESSAGE_BOX_ICON .. "|left|x48px|link=|Out of date]] ")
:tag('div'):cssText("margin-left: 60px")
:wikitext(messageText)
return div
end
-- return when required into another module
return VersionMessageBox
return VersionMessageBox

Revision as of 04:43, 24 December 2023

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

---
--- This module renders the {{Version}} template.
--- https://hoodedhorse.com/wiki/Against_the_Storm/Template:Version
---
--- This template #invokes VersionMessageBox.checkVersion(frame), below.
---
--- The template requires one argument provided by wiki page writers using the
--- template, which is the version of the game when the wiki page was last
--- updated. There is a second argument provided by the template itself that the
--- page writers canont overwrite, which always refers to the current version of
--- the game. The current version is identified by the wiki as
--- {{CurrentVersion}}.
---
--- Depending on the arguments, this module creates a message box that displays
--- when a reader opens a page that hasn't been reviewed and updated since the
--- version changed. The message box tells the reader what version of the game
--- the page was udpated with, the current version, and an encouraging note to
--- help keep the wiki up to date.
--- @module VersionMessageBox
local VersionMessageBox = {}



local StyleUtils = require("Module:StyleUtils")



--region Private constants

local PATTERN_CAPTURE_MAJOR_VERSION = "(%d+%.%d+)"

local CSS_VERSION_MESSAGE_BOX = "max-width: 500px; margin-left: auto; padding: 15px; border: 1px solid #8ab3ff; border-radius: 12px; background: #dbe8ff; font-size: 10px"

--endregion



--region Private methods

---
--- Renders the message box.
---
--- Renders a div with the appropriate CSS class for correct display. The div
--- contains the message about the version of the page and the current version
--- of the game. And it includes a statement encouraging people to keep the
--- wiki up to date.
---
--- @param argLastUpdated string the version of the game when the page was updated
--- @param argCurrentVersion string the current version of the game
--- @return string the HTML markup for a message box
local function renderMessageBox(argLastUpdated, argCurrentVersion)

	local div = mw.html.create('div')

	div:addClass(CSS_CLASS_VERSION_MESSAGE_BOX)
	div:cssText(CSS_VERSION_MESSAGE_BOX)

	messageText = "This page was last updated during version '''" .. argLastUpdated .. "'''." ..
			"The game is now in version '''" .. argCurrentVersion .. "'''.<br />" ..
			"Some information may be out of date. " ..
			"Help us keep the wiki up to date by comparing this article against the patch notes and updating this page."

	div:wikitext("[[File:" .. MESSAGE_BOX_ICON .. "|left|x48px|link=|Out of date]] ")
	   :tag('div'):cssText("margin-left: 60px")
	   :wikitext(messageText)

	return div
end


---
--- Extracts just the major version parts of the numbers and returns whether
--- the content is out of date.
---
---@param versionWhenLastUpdated string the version it was last updated
---@param currentVersion string the current version
---@return boolean true if the last updated is before the current major version
local function isOutOfDate(versionWhenLastUpdated, currentVersion)

	local lastUpdated = tonumber(versionWhenLastUpdated:match(PATTERN_CAPTURE_MAJOR_VERSION) or 0)
	local current = tonumber(currentVersion:match(PATTERN_CAPTURE_MAJOR_VERSION) or 0)

	return current > lastUpdated
end

--endregion



--region Public methods

---
--- Checks whether a message box is necessary.
---
--- If the page is outdated, calls the method to draw the message box and adds
--- the right category to the page.
---
---@param frame table the template's calling context
---@return string wiki markup for a message box, or a blank string if it's up-to-date
function VersionMessageBox.checkVersion(frame)

	-- extract the arguments we care about from the frame
	local argLastUpdated = frame.args.updated
	local argCurrentVersion = frame.args.currentVersion

	-- validate that there are version values to use
	if not argLastUpdated or "" == argLastUpdated then
		return "Version error: please provide the game version with which you updated this page"
	end
	if not argCurrentVersion or "" == argCurrentVersion then
		return "Version error: template did not identify current version correctly"
	end

	if isOutOfDate(argLastUpdated, argCurrentVersion) then

		local html = renderMessageBox(argLastUpdated, argCurrentVersion)
		return tostring(html)
	else
		-- the page is up to date, nothing else needed
		return ""
	end
end

--endregion

return VersionMessageBox