Difference between revisions 51824 and 51825 on wikimaniawiki

-- This module implements {{documentation}}.

-- Get required modules.
local getArgs = require('Module:Arguments').getArgs
local htmlBuilder = require('Module:HtmlBuilder')
local messageBox = require('Module:Message box')

-- Get the config table.
local cfg = mw.loadData('Module:Documentation/config')

local p = {}

-- Often-used functions.
local ugsub = mw.ustring.gsub

----------------------------------------------------------------------------
-- Helper functions
--
-- These are defined as local functions, but are made available in the p
-- table for testing purposes.
----------------------------------------------------------------------------

local function message(cfgKey, valArray, expectType, valArray)
	--[[
	-- Gets a message from the cfg table and formats it if appropriate.
	-- The function raises an error if the value from the cfg table is not
	-- of the type expectType. The default type for expectType is 'string'.
	-- If the table valArray is present, strings such as $1, $2 etc. in the
	-- message are substituted with values from the table keys [1], [2] etc.
	-- For example, if the message cfg.fooMessage had the value 'Foo $2 bar $1.',
	-- message('fooMessage', 'string', {'baz', 'qux'}) would return "Foo qux bar baz."
	--]]
	local msg = cfg[cfgKey]
	if expectType andexpectType = expectType or 'string'
	if type(msg) ~= expectType then
		error('message: type error in message cfg.' .. cfgKey .. ' (' .. expectType .. ' expected, got ' .. type(msg) .. ')', 2)
	end
	if not valArray then
		return msg
	end

	local function getMessageVal(match)
(contracted; show full)	local root = htmlBuilder.create()
	root
		.wikitext(p.protectionTemplate(env))
		.wikitext(p.sandboxNotice(args, env))
		 -- This div tag is from {{documentation/start box}}, but moving it here
		 -- so that we don't have to worry about unclosed tags.
		.tag('div')
			.attr('id', message('mainDivId'
, 'string'))
			.addClass(message('mainDivClasses', 'string'))
			.newline()
			.wikitext(p._startBox(args, env))
			.wikitext(p._content(args, env))
			.tag('div')
				.css('clear', 'both') -- So right or left floating items don't stick out of the doc box.
				.newline()
				.done()
(contracted; show full)	function envFuncs.title()
		-- The title object for the current page, or a test page passed with args.page.
		local title
		local titleArg = args.page
		if titleArg then
			title = mw.title.new(titleArg)
			if not title then
				error(message('titleArgError',
 'string', {titleArg}))
			end
		else
			title = mw.title.getCurrentTitle()
		end
		return title
	end

	function envFuncs.templateTitle()
		-- The template (or module, etc.) title object.
		local title = env.title
		local subpage = title.subpageText
		if subpage == message('sandboxSubpage', 'string') or subpage == message('testcasesSubpage', 'string') then
			return title.basePageTitle
		else
			return title
		end
	end

	function envFuncs.docTitle()
		-- Title object of the /doc subpage.
		local title = env.title
		local docname = args[1] -- User-specified doc page.
		local docpage
		if docname then
			docpage = docname
		else
			docpage = env.docpageRoot .. '/' .. message('docSubpage', 'string')
		end
		return mw.title.new(docpage)
	end
	
	function envFuncs.sandboxTitle()
		-- Title object for the /sandbox subpage.
		return mw.title.new(env.docpageRoot .. '/' .. message('sandboxSubpage', 'string'))
	end
	
	function envFuncs.testcasesTitle()
		-- Title object for the /testcases subpage.
		return mw.title.new(env.docpageRoot .. '/' .. message('testcasesSubpage', 'string'))
	end
	
	function envFuncs.printTitle()
		-- Title object for the /Print subpage.
		return env.templateTitle:subPageTitle(message('printSubpage', 'string'))
	end

	function envFuncs.subjectSpace()
		-- The subject namespace number.
		return mw.site.namespaces[env.title.namespace].subject.id
	end

(contracted; show full)	local sandboxTitle = env.sandboxTitle
	local templateTitle = env.templateTitle
	if not (title and sandboxTitle and templateTitle and mw.title.equals(title, sandboxTitle)) then
		return nil
	end
	local omargs = {} -- Args for {{ombox}}.
	-- Get the image wikitext.
	omargs.image = message('sandboxNoticeImage'
, 'string')
	-- Get the text. We start with the opening blurb, which is something like
	-- "This is the template sandbox for [[Template:Foo]] (diff)."
	local text = ''
	local frame = mw.getCurrentFrame()
	local isPreviewing = frame:preprocess('{{REVISIONID}}') == '' -- True if the page is being previewed.
	local templateLink = makeWikilink(templateTitle.prefixedText)
	local compareUrl = env.compareUrl
	if isPreviewing or not compareUrl then
		-- 'This is the [[Wikipedia:Template test cases|template sandbox]] page for $1.'
		text = text .. message('sandboxNoticeBlurb', 'string', {templateLink})
	else
		-- 'This is the [[Wikipedia:Template test cases|template sandbox]] page for $1 ($2).'
		local compareDisplay = message('sandboxNoticeCompareLinkDisplay', 'string')
		local compareLink = makeUrlLink(compareUrl, compareDisplay)
		text = text .. message('sandboxNoticeDiffBlurb', 'string', {templateLink, compareLink})
	end
	-- Get the test cases page blurb if the page exists.
	local testcasesTitle = env.testcasesTitle
	if testcasesTitle and testcasesTitle.exists then
		local testcasesLinkDisplay = message('sandboxNoticeTestcasesLinkDisplay', 'string')
		local testcasesLink = makeWikilink(testcasesTitle.prefixedText, testcasesLinkDisplay)
		text = text .. '<br />' .. message('sandboxNoticeTestcasesBlurb', 'string', {testcasesLink})
	end
	-- Add the page to [[Category:Template sandboxes]].
	text = text .. makeCategoryLink(message('sandboxCategory', 'string'))
	omargs.text = text
	return messageBox.main('ombox', omargs)
end

function p.protectionTemplate(env)
	local title = env.title
	local protectionTemplate = message('protectionTemplate', 'string')
	if not (protectionTemplate and title.namespace == 10) then
		-- Don't display the protection template if we are not in the template namespace.
		return nil
	end
	local frame = mw.getCurrentFrame()
	local function getProtectionLevel(protectionType, page)
		-- Gets the protection level for page, or for the current page if page is not specified.
		local level = frame:callParserFunction('PROTECTIONLEVEL', protectionType, page)
		if level ~= '' then
			return level
		else
			return nil -- The parser function returns the blank string if there is no match.
		end
	end
	local prefixedTitle = title.prefixedText
	if getProtectionLevel('move', prefixedTitle) == 'sysop' or getProtectionLevel('edit', prefixedTitle) then
		-- The page is full-move protected, or full, template, or semi-protected.
		return frame:expandTemplate{title = protectionTemplate, args = message('protectionTemplateArgs', nil, 'table')}
	end
	return nil
end

----------------------------------------------------------------------------
-- Start box
----------------------------------------------------------------------------

p.startBox = makeInvokeFunc('_startBox')

function p._startBox(args, env)
	-- Generate [view][edit][history][purge] or [create] links.
	local links
	local content = args.content
	if not content then
		-- No need to include the links if the documentation is on the template page itself.
		local linksData = p.makeStartBoxLinksData(args, env)
		if linksData then
			links = p.renderStartBoxLinks(linksData)
		end
	end
	-- Generate the start box html.
	local data = p.makeStartBoxData(args, env, links)
	if data then
		return p.renderStartBox(data)
	else
		-- User specified no heading.
		return nil
	end
end

function p.makeStartBoxLinksData(args, env)
	local data = {}
	-- Get title objects.
	local title = env.title
	local docTitle = env.docTitle
	if not title or not docTitle then
		return nil
	end
	data.title = title
	data.docTitle = docTitle
	-- View, display, edit, and purge links if /doc exists.
	data.viewLinkDisplay = message('viewLinkDisplay', 'string')
	data.editLinkDisplay = message('editLinkDisplay', 'string')
	data.historyLinkDisplay = message('historyLinkDisplay', 'string')
	data.purgeLinkDisplay = message('purgeLinkDisplay', 'string')
	-- Create link if /doc doesn't exist.
	local preload = args.preload
	if not preload then
		if env.subjectSpace == 6 then -- File namespace
			preload = message('fileDocpagePreload', 'string')
		else
			preload = message('docpagePreload', 'string')
		end
	end
	data.preload = preload
	data.createLinkDisplay = message('createLinkDisplay', 'string')
	return data
end

function p.renderStartBoxLinks(data)
	-- Render the [view][edit][history][purge] or [create] links.
	local ret
	local docTitle = data.docTitle
(contracted; show full)	if heading == '' then
		-- Don't display the start box if the heading arg is defined but blank.
		return nil
	end
	if heading then
		data.heading = heading
	elseif subjectSpace == 10 then -- Template namespace
		data.heading = message('documentationIconWikitext'
, 'string') .. ' ' .. message('templateNamespaceHeading', 'string')
	elseif subjectSpace == 828 then -- Module namespace
		data.heading = message('documentationIconWikitext', 'string') .. ' ' .. message('moduleNamespaceHeading', 'string')
	elseif subjectSpace == 6 then -- File namespace
		data.heading = message('fileNamespaceHeading', 'string')
	else
		data.heading = message('otherNamespacesHeading', 'string')
	end
	
	-- Heading CSS
	local headingStyle = args['heading-style']
	if headingStyle then
		data.headingStyleText = headingStyle
	elseif subjectSpace == 10 then
		-- We are in the template or template talk namespaces.
		data.headingFontWeight = 'bold'
		data.headingFontSize = '125%'
	else
		data.headingFontSize = '150%'
	end
	
	-- [view][edit][history][purge] or [create] links.
	if links then
		data.linksClass = message('startBoxLinkclasses', 'string')
		data.linksId = message('startBoxLinkId', 'string')
		data.links = links
	end
	
	return data
end

function p.renderStartBox(data)
(contracted; show full)		)
	then
		return nil
	end

	-- Assemble the arguments for {{fmbox}}.
	local fmargs = {}
	fmargs.id = message('fmboxId'
, 'string') -- Sets 'documentation-meta-data'
	fmargs.image = message('fmboxImageNone', 'string') -- Sets 'none'
	fmargs.style = message('fmboxStyle', 'string') -- Sets 'background-color: #ecfcf4'
	fmargs.textstyle = message('fmboxTextstyle', 'string') -- 'font-style: italic;'

	-- Assemble the fmbox text field.
	local text = ''
	if linkBox then
		-- Use custom link box content if it is defined.
		text = text .. linkBox
	else
(contracted; show full)	local printTitle = env.printTitle
	if not printTitle then
		return nil
	end
	-- Make the print blurb.
	local ret
	if printTitle.exists then
		local printLink = makeWikilink(printTitle.prefixedText, message('printLinkDisplay'
, 'string'))
		ret = message('printBlurb', 'string', {printLink})
		local displayPrintCategory = message('displayPrintCategory', nil, 'boolean')
		if displayPrintCategory then
			ret = ret .. makeCategoryLink(message('printCategory', 'string'))
		end
	end
	return ret
end

function p.makeSubpagesBlurb(args, env)
	-- Get the template title object
	local subjectSpace = env.subjectSpace
	local templateTitle = env.templateTitle
	if not subjectSpace or not templateTitle then
		return nil
	end
	-- Make the subpages blurb.
	local pagetype
	if subjectSpace == 10 then
		pagetype = message('templatePagetype', 'string')
	elseif subjectSpace == 828 then
		pagetype = message('modulePagetype', 'string')
	else
		pagetype = message('defaultPagetype', 'string')
	end
	return makeWikilink(
		'Special:PrefixIndex/' .. templateTitle.prefixedText .. '/',
		message('subpagesLinkDisplay', 'string', {pagetype})
	)
end

function p.makeCategoriesBlurb(args, env)
	-- Get the title object.
	local docTitle = env.docTitle
	if not docTitle then
		return nil
	end
	-- Make the blurb.
	local docPathLink = makeWikilink(docTitle.prefixedText, message('docLinkDisplay', 'string'))
	return message('addCategoriesBlurb', 'string', {docPathLink})
end

function p.makeDocPageBlurb(args, env)
	-- Get the title object.
	local docTitle = env.docTitle
	if not docTitle then
		return nil
	end
	-- Make the blurb.
	local ret
	if docTitle.exists then
		-- /doc exists; link to it.
		local docLink = makeWikilink(docTitle.prefixedText)
		local editUrl = docTitle:fullUrl{action = 'edit'}
		local editDisplay = message('editLinkDisplay', 'string')
		local editLink = makeUrlLink(editUrl, editDisplay)
		local historyUrl = docTitle:fullUrl{action = 'history'}
		local historyDisplay = message('historyLinkDisplay', 'string')
		local historyLink = makeUrlLink(historyUrl, historyDisplay)
		ret = message('transcludedFromBlurb', 'string', {docLink})
			.. ' '
			.. makeToolbar(editLink, historyLink)
			.. '<br />'
	elseif env.subjectSpace == 828 then
		-- /doc does not exist; ask to create it.
		local createUrl = docTitle:fullUrl{action = 'edit', preload = message('modulePreload', 'string')}
		local createDisplay = message('createLinkDisplay', 'string')
		local createLink = makeUrlLink(createUrl, createDisplay)
		ret = message('createModuleDocBlurb', 'string', {createLink})
			.. '<br />'
	end
	return ret
end

function p.makeEndBoxExperimentBlurb(args, env)
	-- Renders the text "Editors can experiment in this template's sandbox (edit | diff) and testcases (edit) pages."
	-- Get environment data.
	local subjectSpace = env.subjectSpace
	local templateTitle = env.templateTitle
	local sandboxTitle = env.sandboxTitle
	local testcasesTitle = env.testcasesTitle
	local templatePage = templateTitle.prefixedText
	if not subjectSpace or not templateTitle or not sandboxTitle or not testcasesTitle then
		return nil
	end
	-- Make links.
	local sandboxLinks, testcasesLinks
	if sandboxTitle.exists then
		local sandboxPage = sandboxTitle.prefixedText
		local sandboxDisplay = message('sandboxLinkDisplay', 'string')
		local sandboxLink = makeWikilink(sandboxPage, sandboxDisplay)
		local sandboxEditUrl = sandboxTitle:fullUrl{action = 'edit'}
		local sandboxEditDisplay = message('sandboxEditLinkDisplay', 'string')
		local sandboxEditLink = makeUrlLink(sandboxEditUrl, sandboxEditDisplay)
		local compareUrl = env.compareUrl
		local compareLink
		if compareUrl then
			local compareDisplay = message('compareLinkDisplay', 'string')
			compareLink = makeUrlLink(compareUrl, compareDisplay)
		end
		sandboxLinks = sandboxLink .. ' ' .. makeToolbar(sandboxEditLink, compareLink)
	else
		local sandboxPreload
		if subjectSpace == 828 then
			sandboxPreload = message('moduleSandboxPreload', 'string')
		else
			sandboxPreload = message('templateSandboxPreload', 'string')
		end
		local sandboxCreateUrl = sandboxTitle:fullUrl{action = 'edit', preload = sandboxPreload}
		local sandboxCreateDisplay = message('sandboxCreateLinkDisplay', 'string')
		local sandboxCreateLink = makeUrlLink(sandboxCreateUrl, sandboxCreateDisplay)
		local mirrorSummary = message('mirrorEditSummary', 'string', {makeWikilink(templatePage)})
		local mirrorUrl = sandboxTitle:fullUrl{action = 'edit', preload = templatePage, summary = mirrorSummary}
		local mirrorDisplay = message('mirrorLinkDisplay', 'string')
		local mirrorLink = makeUrlLink(mirrorUrl, mirrorDisplay)
		sandboxLinks = message('sandboxLinkDisplay', 'string') .. ' ' .. makeToolbar(sandboxCreateLink, mirrorLink)
	end
	if testcasesTitle.exists then
		local testcasesPage = testcasesTitle.prefixedText
		local testcasesDisplay = message('testcasesLinkDisplay', 'string')
		local testcasesLink = makeWikilink(testcasesPage, testcasesDisplay)
		local testcasesEditUrl = testcasesTitle:fullUrl{action = 'edit'}
		local testcasesEditDisplay = message('testcasesEditLinkDisplay', 'string')
		local testcasesEditLink = makeUrlLink(testcasesEditUrl, testcasesEditDisplay)
		testcasesLinks = testcasesLink .. ' ' .. makeToolbar(testcasesEditLink)
	else
		local testcasesPreload
		if subjectSpace == 828 then
			testcasesPreload = message('moduleTestcasesPreload', 'string')
		else
			testcasesPreload = message('templateTestcasesPreload', 'string')
		end
		local testcasesCreateUrl = testcasesTitle:fullUrl{action = 'edit', preload = testcasesPreload}
		local testcasesCreateDisplay = message('testcasesCreateLinkDisplay', 'string')
		local testcasesCreateLink = makeUrlLink(testcasesCreateUrl, testcasesCreateDisplay)
		testcasesLinks = message('testcasesLinkDisplay', 'string') .. ' ' .. makeToolbar(testcasesCreateLink)
	end
	local messageName
	if subjectSpace == 828 then
		messageName = 'experimentBlurbModule'
	else
		messageName = 'experimentBlurbTemplate'
	end
	return message(messageName, 'string', {sandboxLinks, testcasesLinks})
end

----------------------------------------------------------------------------
-- Tracking categories
----------------------------------------------------------------------------

function p.addTrackingCategories(env)
	-- Check if {{documentation}} is transcluded on a /doc or /testcases page.
	local title = env.title
	local ret = ''
	local subpage = title.subpageText
	if message('displayStrangeUsageCategory', nil, 'boolean') and (subpage == message('docSubpage', 'string') or subpage == message('testcasesSubpage', 'string')) then
		local sort = (title.namespace == 0 and message('strangeUsageCategoryMainspaceSort', 'string') or '') .. title.prefixedText -- Sort on namespace.
		ret = ret .. makeCategoryLink(message('strangeUsageCategory', 'string'), sort)
	end
	return ret
end

return p