Module:VersionMessageBox

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

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

	messageText = "This page was last updated during version " ..
			StyleUtils.BOLD .. argLastUpdated .. StyleUtils.BOLD .. ". " ..
			"The game is now in version " ..
			StyleUtils.BOLD .. argCurrentVersion .. StyleUtils.BOLD .. ". " ..
			"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."

	local div = mw.html.create("div")
	StyleUtils.styleVersionMessageBox(div)
	div:newline()

	div:tag("p"):wikitext(messageText)
			:done():newline()
	:done()

	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