Module:Documentation: Difference between revisions
From Roses, Tulips, & Liberty
Content deleted Content added
make 'string' the default message type in the message function to avoid having 'string' all over the place |
use hyphens for message names rather than camelCase, in line with MediaWiki |
||
Line 29: | Line 29: | ||
-- message are substituted with values from the table keys [1], [2] etc. |
-- 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.', |
-- For example, if the message cfg.fooMessage had the value 'Foo $2 bar $1.', |
||
-- message(' |
-- message('foo-message', {'baz', 'qux'}) would return "Foo qux bar baz." |
||
--]] |
--]] |
||
local msg = cfg[cfgKey] |
local msg = cfg[cfgKey] |
||
Line 127: | Line 127: | ||
-- so that we don't have to worry about unclosed tags. |
-- so that we don't have to worry about unclosed tags. |
||
.tag('div') |
.tag('div') |
||
.attr('id', message(' |
.attr('id', message('main-div-id')) |
||
.addClass(message(' |
.addClass(message('main-div-classes')) |
||
.newline() |
.newline() |
||
.wikitext(p._startBox(args, env)) |
.wikitext(p._startBox(args, env)) |
||
Line 196: | Line 196: | ||
title = mw.title.new(titleArg) |
title = mw.title.new(titleArg) |
||
if not title then |
if not title then |
||
error(message(' |
error(message('title-arg-error', {titleArg})) |
||
end |
end |
||
else |
else |
||
Line 208: | Line 208: | ||
local title = env.title |
local title = env.title |
||
local subpage = title.subpageText |
local subpage = title.subpageText |
||
if subpage == message(' |
if subpage == message('sandbox-subpage') or subpage == message('testcases-subpage') then |
||
return title.basePageTitle |
return title.basePageTitle |
||
else |
else |
||
Line 223: | Line 223: | ||
docpage = docname |
docpage = docname |
||
else |
else |
||
docpage = env.docpageRoot .. '/' .. message(' |
docpage = env.docpageRoot .. '/' .. message('doc-subpage') |
||
end |
end |
||
return mw.title.new(docpage) |
return mw.title.new(docpage) |
||
Line 230: | Line 230: | ||
function envFuncs.sandboxTitle() |
function envFuncs.sandboxTitle() |
||
-- Title object for the /sandbox subpage. |
-- Title object for the /sandbox subpage. |
||
return mw.title.new(env.docpageRoot .. '/' .. message(' |
return mw.title.new(env.docpageRoot .. '/' .. message('sandbox-subpage')) |
||
end |
end |
||
function envFuncs.testcasesTitle() |
function envFuncs.testcasesTitle() |
||
-- Title object for the /testcases subpage. |
-- Title object for the /testcases subpage. |
||
return mw.title.new(env.docpageRoot .. '/' .. message(' |
return mw.title.new(env.docpageRoot .. '/' .. message('testcases-subpage')) |
||
end |
end |
||
function envFuncs.printTitle() |
function envFuncs.printTitle() |
||
-- Title object for the /Print subpage. |
-- Title object for the /Print subpage. |
||
return env.templateTitle:subPageTitle(message(' |
return env.templateTitle:subPageTitle(message('print-subpage')) |
||
end |
end |
||
Line 297: | Line 297: | ||
local omargs = {} -- Args for {{ombox}}. |
local omargs = {} -- Args for {{ombox}}. |
||
-- Get the image wikitext. |
-- Get the image wikitext. |
||
omargs.image = message(' |
omargs.image = message('sandbox-notice-image') |
||
-- Get the text. We start with the opening blurb, which is something like |
-- Get the text. We start with the opening blurb, which is something like |
||
-- "This is the template sandbox for [[Template:Foo]] (diff)." |
-- "This is the template sandbox for [[Template:Foo]] (diff)." |
||
Line 307: | Line 307: | ||
if isPreviewing or not compareUrl then |
if isPreviewing or not compareUrl then |
||
-- 'This is the [[Wikipedia:Template test cases|template sandbox]] page for $1.' |
-- 'This is the [[Wikipedia:Template test cases|template sandbox]] page for $1.' |
||
text = text .. message(' |
text = text .. message('sandbox-notice-blurb', {templateLink}) |
||
else |
else |
||
-- 'This is the [[Wikipedia:Template test cases|template sandbox]] page for $1 ($2).' |
-- 'This is the [[Wikipedia:Template test cases|template sandbox]] page for $1 ($2).' |
||
local compareDisplay = message(' |
local compareDisplay = message('sandbox-notice-compare-link-display') |
||
local compareLink = makeUrlLink(compareUrl, compareDisplay) |
local compareLink = makeUrlLink(compareUrl, compareDisplay) |
||
text = text .. message(' |
text = text .. message('sandbox-notice-diff-blurb', {templateLink, compareLink}) |
||
end |
end |
||
-- Get the test cases page blurb if the page exists. |
-- Get the test cases page blurb if the page exists. |
||
local testcasesTitle = env.testcasesTitle |
local testcasesTitle = env.testcasesTitle |
||
if testcasesTitle and testcasesTitle.exists then |
if testcasesTitle and testcasesTitle.exists then |
||
local testcasesLinkDisplay = message(' |
local testcasesLinkDisplay = message('sandbox-notice-testcases-link-display') |
||
local testcasesLink = makeWikilink(testcasesTitle.prefixedText, testcasesLinkDisplay) |
local testcasesLink = makeWikilink(testcasesTitle.prefixedText, testcasesLinkDisplay) |
||
text = text .. '<br />' .. message(' |
text = text .. '<br />' .. message('sandbox-notice-testcases-blurb', {testcasesLink}) |
||
end |
end |
||
-- Add the page to [[Category:Template sandboxes]]. |
-- Add the page to [[Category:Template sandboxes]]. |
||
text = text .. makeCategoryLink(message(' |
text = text .. makeCategoryLink(message('sandbox-category')) |
||
omargs.text = text |
omargs.text = text |
||
return messageBox.main('ombox', omargs) |
return messageBox.main('ombox', omargs) |
||
Line 329: | Line 329: | ||
function p.protectionTemplate(env) |
function p.protectionTemplate(env) |
||
local title = env.title |
local title = env.title |
||
local protectionTemplate = message(' |
local protectionTemplate = message('protection-template') |
||
if not (protectionTemplate and title.namespace == 10) then |
if not (protectionTemplate and title.namespace == 10) then |
||
-- Don't display the protection template if we are not in the template namespace. |
-- Don't display the protection template if we are not in the template namespace. |
||
Line 347: | Line 347: | ||
if getProtectionLevel('move', prefixedTitle) == 'sysop' or getProtectionLevel('edit', prefixedTitle) then |
if getProtectionLevel('move', prefixedTitle) == 'sysop' or getProtectionLevel('edit', prefixedTitle) then |
||
-- The page is full-move protected, or full, template, or semi-protected. |
-- The page is full-move protected, or full, template, or semi-protected. |
||
return frame:expandTemplate{title = protectionTemplate, args = message(' |
return frame:expandTemplate{title = protectionTemplate, args = message('protection-template-args', nil, 'table')} |
||
end |
end |
||
return nil |
return nil |
||
Line 390: | Line 390: | ||
data.docTitle = docTitle |
data.docTitle = docTitle |
||
-- View, display, edit, and purge links if /doc exists. |
-- View, display, edit, and purge links if /doc exists. |
||
data.viewLinkDisplay = message(' |
data.viewLinkDisplay = message('view-link-display') |
||
data.editLinkDisplay = message(' |
data.editLinkDisplay = message('edit-link-display') |
||
data.historyLinkDisplay = message(' |
data.historyLinkDisplay = message('history-link-display') |
||
data.purgeLinkDisplay = message(' |
data.purgeLinkDisplay = message('purge-link-display') |
||
-- Create link if /doc doesn't exist. |
-- Create link if /doc doesn't exist. |
||
local preload = args.preload |
local preload = args.preload |
||
if not preload then |
if not preload then |
||
if env.subjectSpace == 6 then -- File namespace |
if env.subjectSpace == 6 then -- File namespace |
||
preload = message(' |
preload = message('file-docpage-preload') |
||
else |
else |
||
preload = message(' |
preload = message('docpage-preload') |
||
end |
end |
||
end |
end |
||
data.preload = preload |
data.preload = preload |
||
data.createLinkDisplay = message(' |
data.createLinkDisplay = message('create-link-display') |
||
return data |
return data |
||
end |
end |
||
Line 445: | Line 445: | ||
data.heading = heading |
data.heading = heading |
||
elseif subjectSpace == 10 then -- Template namespace |
elseif subjectSpace == 10 then -- Template namespace |
||
data.heading = message(' |
data.heading = message('documentation-icon-wikitext') .. ' ' .. message('template-namespace-heading') |
||
elseif subjectSpace == 828 then -- Module namespace |
elseif subjectSpace == 828 then -- Module namespace |
||
data.heading = message(' |
data.heading = message('documentation-icon-wikitext') .. ' ' .. message('module-namespace-heading') |
||
elseif subjectSpace == 6 then -- File namespace |
elseif subjectSpace == 6 then -- File namespace |
||
data.heading = message(' |
data.heading = message('file-namespace-heading') |
||
else |
else |
||
data.heading = message(' |
data.heading = message('other-namespaces-heading') |
||
end |
end |
||
Line 468: | Line 468: | ||
-- [view][edit][history][purge] or [create] links. |
-- [view][edit][history][purge] or [create] links. |
||
if links then |
if links then |
||
data.linksClass = message(' |
data.linksClass = message('start-box-linkclasses') |
||
data.linksId = message(' |
data.linksId = message('start-box-link-id') |
||
data.links = links |
data.links = links |
||
end |
end |
||
Line 549: | Line 549: | ||
-- Assemble the arguments for {{fmbox}}. |
-- Assemble the arguments for {{fmbox}}. |
||
local fmargs = {} |
local fmargs = {} |
||
fmargs.id = message(' |
fmargs.id = message('fmbox-id') -- Sets 'documentation-meta-data' |
||
fmargs.image = message(' |
fmargs.image = message('fmbox-image-none') -- Sets 'none' |
||
fmargs.style = message(' |
fmargs.style = message('fmbox-style') -- Sets 'background-color: #ecfcf4' |
||
fmargs.textstyle = message(' |
fmargs.textstyle = message('fmbox-textstyle') -- 'font-style: italic;' |
||
-- Assemble the fmbox text field. |
-- Assemble the fmbox text field. |
||
Line 597: | Line 597: | ||
local ret |
local ret |
||
if printTitle.exists then |
if printTitle.exists then |
||
local printLink = makeWikilink(printTitle.prefixedText, message(' |
local printLink = makeWikilink(printTitle.prefixedText, message('print-link-display')) |
||
ret = message(' |
ret = message('print-blurb', {printLink}) |
||
local displayPrintCategory = message(' |
local displayPrintCategory = message('display-print-category', nil, 'boolean') |
||
if displayPrintCategory then |
if displayPrintCategory then |
||
ret = ret .. makeCategoryLink(message(' |
ret = ret .. makeCategoryLink(message('print-category')) |
||
end |
end |
||
end |
end |
||
Line 617: | Line 617: | ||
local pagetype |
local pagetype |
||
if subjectSpace == 10 then |
if subjectSpace == 10 then |
||
pagetype = message(' |
pagetype = message('template-pagetype') |
||
elseif subjectSpace == 828 then |
elseif subjectSpace == 828 then |
||
pagetype = message(' |
pagetype = message('module-pagetype') |
||
else |
else |
||
pagetype = message(' |
pagetype = message('default-pagetype') |
||
end |
end |
||
return makeWikilink( |
return makeWikilink( |
||
'Special:PrefixIndex/' .. templateTitle.prefixedText .. '/', |
'Special:PrefixIndex/' .. templateTitle.prefixedText .. '/', |
||
message(' |
message('subpages-link-display', {pagetype}) |
||
) |
) |
||
end |
end |
||
Line 636: | Line 636: | ||
end |
end |
||
-- Make the blurb. |
-- Make the blurb. |
||
local docPathLink = makeWikilink(docTitle.prefixedText, message(' |
local docPathLink = makeWikilink(docTitle.prefixedText, message('doc-link-display')) |
||
return message(' |
return message('add-categories-blurb', {docPathLink}) |
||
end |
end |
||
Line 652: | Line 652: | ||
local docLink = makeWikilink(docTitle.prefixedText) |
local docLink = makeWikilink(docTitle.prefixedText) |
||
local editUrl = docTitle:fullUrl{action = 'edit'} |
local editUrl = docTitle:fullUrl{action = 'edit'} |
||
local editDisplay = message(' |
local editDisplay = message('edit-link-display') |
||
local editLink = makeUrlLink(editUrl, editDisplay) |
local editLink = makeUrlLink(editUrl, editDisplay) |
||
local historyUrl = docTitle:fullUrl{action = 'history'} |
local historyUrl = docTitle:fullUrl{action = 'history'} |
||
local historyDisplay = message(' |
local historyDisplay = message('history-link-display') |
||
local historyLink = makeUrlLink(historyUrl, historyDisplay) |
local historyLink = makeUrlLink(historyUrl, historyDisplay) |
||
ret = message(' |
ret = message('transcluded-from-blurb', {docLink}) |
||
.. ' ' |
.. ' ' |
||
.. makeToolbar(editLink, historyLink) |
.. makeToolbar(editLink, historyLink) |
||
Line 663: | Line 663: | ||
elseif env.subjectSpace == 828 then |
elseif env.subjectSpace == 828 then |
||
-- /doc does not exist; ask to create it. |
-- /doc does not exist; ask to create it. |
||
local createUrl = docTitle:fullUrl{action = 'edit', preload = message(' |
local createUrl = docTitle:fullUrl{action = 'edit', preload = message('module-preload')} |
||
local createDisplay = message(' |
local createDisplay = message('create-link-display') |
||
local createLink = makeUrlLink(createUrl, createDisplay) |
local createLink = makeUrlLink(createUrl, createDisplay) |
||
ret = message(' |
ret = message('create-module-doc-blurb', {createLink}) |
||
.. '<br />' |
.. '<br />' |
||
end |
end |
||
Line 687: | Line 687: | ||
if sandboxTitle.exists then |
if sandboxTitle.exists then |
||
local sandboxPage = sandboxTitle.prefixedText |
local sandboxPage = sandboxTitle.prefixedText |
||
local sandboxDisplay = message(' |
local sandboxDisplay = message('sandbox-link-display') |
||
local sandboxLink = makeWikilink(sandboxPage, sandboxDisplay) |
local sandboxLink = makeWikilink(sandboxPage, sandboxDisplay) |
||
local sandboxEditUrl = sandboxTitle:fullUrl{action = 'edit'} |
local sandboxEditUrl = sandboxTitle:fullUrl{action = 'edit'} |
||
local sandboxEditDisplay = message(' |
local sandboxEditDisplay = message('sandbox-edit-link-display') |
||
local sandboxEditLink = makeUrlLink(sandboxEditUrl, sandboxEditDisplay) |
local sandboxEditLink = makeUrlLink(sandboxEditUrl, sandboxEditDisplay) |
||
local compareUrl = env.compareUrl |
local compareUrl = env.compareUrl |
||
local compareLink |
local compareLink |
||
if compareUrl then |
if compareUrl then |
||
local compareDisplay = message(' |
local compareDisplay = message('compare-link-display') |
||
compareLink = makeUrlLink(compareUrl, compareDisplay) |
compareLink = makeUrlLink(compareUrl, compareDisplay) |
||
end |
end |
||
Line 702: | Line 702: | ||
local sandboxPreload |
local sandboxPreload |
||
if subjectSpace == 828 then |
if subjectSpace == 828 then |
||
sandboxPreload = message(' |
sandboxPreload = message('module-sandbox-preload') |
||
else |
else |
||
sandboxPreload = message(' |
sandboxPreload = message('template-sandbox-preload') |
||
end |
end |
||
local sandboxCreateUrl = sandboxTitle:fullUrl{action = 'edit', preload = sandboxPreload} |
local sandboxCreateUrl = sandboxTitle:fullUrl{action = 'edit', preload = sandboxPreload} |
||
local sandboxCreateDisplay = message(' |
local sandboxCreateDisplay = message('sandbox-create-link-display') |
||
local sandboxCreateLink = makeUrlLink(sandboxCreateUrl, sandboxCreateDisplay) |
local sandboxCreateLink = makeUrlLink(sandboxCreateUrl, sandboxCreateDisplay) |
||
local mirrorSummary = message(' |
local mirrorSummary = message('mirror-edit-summary', {makeWikilink(templatePage)}) |
||
local mirrorUrl = sandboxTitle:fullUrl{action = 'edit', preload = templatePage, summary = mirrorSummary} |
local mirrorUrl = sandboxTitle:fullUrl{action = 'edit', preload = templatePage, summary = mirrorSummary} |
||
local mirrorDisplay = message(' |
local mirrorDisplay = message('mirror-link-display') |
||
local mirrorLink = makeUrlLink(mirrorUrl, mirrorDisplay) |
local mirrorLink = makeUrlLink(mirrorUrl, mirrorDisplay) |
||
sandboxLinks = message(' |
sandboxLinks = message('sandbox-link-display') .. ' ' .. makeToolbar(sandboxCreateLink, mirrorLink) |
||
end |
end |
||
if testcasesTitle.exists then |
if testcasesTitle.exists then |
||
local testcasesPage = testcasesTitle.prefixedText |
local testcasesPage = testcasesTitle.prefixedText |
||
local testcasesDisplay = message(' |
local testcasesDisplay = message('testcases-link-display') |
||
local testcasesLink = makeWikilink(testcasesPage, testcasesDisplay) |
local testcasesLink = makeWikilink(testcasesPage, testcasesDisplay) |
||
local testcasesEditUrl = testcasesTitle:fullUrl{action = 'edit'} |
local testcasesEditUrl = testcasesTitle:fullUrl{action = 'edit'} |
||
local testcasesEditDisplay = message(' |
local testcasesEditDisplay = message('testcases-edit-link-display') |
||
local testcasesEditLink = makeUrlLink(testcasesEditUrl, testcasesEditDisplay) |
local testcasesEditLink = makeUrlLink(testcasesEditUrl, testcasesEditDisplay) |
||
testcasesLinks = testcasesLink .. ' ' .. makeToolbar(testcasesEditLink) |
testcasesLinks = testcasesLink .. ' ' .. makeToolbar(testcasesEditLink) |
||
Line 726: | Line 726: | ||
local testcasesPreload |
local testcasesPreload |
||
if subjectSpace == 828 then |
if subjectSpace == 828 then |
||
testcasesPreload = message(' |
testcasesPreload = message('module-testcases-preload') |
||
else |
else |
||
testcasesPreload = message(' |
testcasesPreload = message('template-testcases-preload') |
||
end |
end |
||
local testcasesCreateUrl = testcasesTitle:fullUrl{action = 'edit', preload = testcasesPreload} |
local testcasesCreateUrl = testcasesTitle:fullUrl{action = 'edit', preload = testcasesPreload} |
||
local testcasesCreateDisplay = message(' |
local testcasesCreateDisplay = message('testcases-create-link-display') |
||
local testcasesCreateLink = makeUrlLink(testcasesCreateUrl, testcasesCreateDisplay) |
local testcasesCreateLink = makeUrlLink(testcasesCreateUrl, testcasesCreateDisplay) |
||
testcasesLinks = message(' |
testcasesLinks = message('testcases-link-display') .. ' ' .. makeToolbar(testcasesCreateLink) |
||
end |
end |
||
local messageName |
local messageName |
||
Line 753: | Line 753: | ||
local ret = '' |
local ret = '' |
||
local subpage = title.subpageText |
local subpage = title.subpageText |
||
if message(' |
if message('display-strange-usage-category', nil, 'boolean') and (subpage == message('doc-subpage') or subpage == message('testcases-subpage')) then |
||
local sort = (title.namespace == 0 and message(' |
local sort = (title.namespace == 0 and message('strange-usage-category-mainspace-sort') or '') .. title.prefixedText -- Sort on namespace. |
||
ret = ret .. makeCategoryLink(message(' |
ret = ret .. makeCategoryLink(message('strange-usage-category'), sort) |
||
end |
end |
||
return ret |
return ret |
Revision as of 08:39, 20 January 2014
Documentation for this module may be created at Module:Documentation/doc
-- 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)
--[[
-- 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('foo-message', {'baz', 'qux'}) would return "Foo qux bar baz."
--]]
local msg = cfg[cfgKey]
expectType = 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)
match = tonumber(match)
return valArray[match] or error('message: no value found for key $' .. match .. ' in message cfg.' .. cfgKey, 4)
end
local ret = ugsub(msg, '$([1-9][0-9]*)', getMessageVal)
return ret
end
p.message = message
local function makeWikilink(page, display)
if display then
return mw.ustring.format('[[%s|%s]]', page, display)
else
return mw.ustring.format('[[%s]]', page)
end
end
p.makeWikilink = makeWikilink
local function makeCategoryLink(cat, sort)
local catns = mw.site.namespaces[14].name
return makeWikilink(catns .. ':' .. cat, sort)
end
p.makeCategoryLink = makeCategoryLink
local function makeUrlLink(url, display)
return mw.ustring.format('[%s %s]', url, display)
end
p.makeUrlLink = makeUrlLink
local function makeToolbar(...)
local ret = {}
local lim = select('#', ...)
if lim < 1 then
return nil
end
for i = 1, lim do
ret[#ret + 1] = select(i, ...)
end
return '<small style="font-style: normal;">(' .. table.concat(ret, ' | ') .. ')</small>'
end
p.makeToolbar = makeToolbar
----------------------------------------------------------------------------
-- Argument processing
----------------------------------------------------------------------------
local function makeInvokeFunc(funcName)
return function (frame)
local args = getArgs(frame, {
valueFunc = function (key, value)
if type(value) == 'string' then
value = value:match('^%s*(.-)%s*$') -- Remove whitespace.
if key == 'heading' or value ~= '' then
return value
else
return nil
end
else
return value
end
end
})
return p[funcName](args)
end
end
----------------------------------------------------------------------------
-- Main function
----------------------------------------------------------------------------
p.main = makeInvokeFunc('_main')
function p._main(args)
local env = p.getEnvironment(args)
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('main-div-id'))
.addClass(message('main-div-classes'))
.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()
.done()
.wikitext(p._endBox(args, env))
.newline()
.wikitext(p.addTrackingCategories(env))
return tostring(root)
end
----------------------------------------------------------------------------
-- Environment settings
----------------------------------------------------------------------------
function p.getEnvironment(args)
--[[
-- Returns a table with information about the environment, including title objects and other namespace- or
-- path-related data.
--
-- Title objects include:
-- env.title - the page we are making documentation for (usually the current title)
-- env.templateTitle - the template (or module, file, etc.)
-- env.docTitle - the /doc subpage.
-- env.sandboxTitle - the /sandbox subpage.
-- env.testcasesTitle - the /testcases subpage.
-- env.printTitle - the print version of the template, located at the /Print subpage.
--
-- Data includes:
-- env.subjectSpace - the number of the title's subject namespace.
-- env.docSpace - the number of the namespace the title puts its documentation in.
-- env.docpageRoot - the text of the base page of the /doc, /sandbox and /testcases pages, with namespace.
-- env.compareUrl - URL of the Special:ComparePages page comparing the sandbox with the template.
--
-- All table lookups are passed through pcall so that errors are caught. If an error occurs, the value
-- returned will be nil.
--]]
local env, envFuncs = {}, {}
-- Set up the metatable. If triggered we call the corresponding function in the envFuncs table. The value
-- returned by that function is memoized in the env table so that we don't call any of the functions
-- more than once. (Nils won't be memoized.)
setmetatable(env, {
__index = function (t, key)
local envFunc = envFuncs[key]
if envFunc then
local success, val = pcall(envFunc)
if success then
env[key] = val -- Memoise the value.
return val
end
end
return nil
end
})
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('title-arg-error', {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('sandbox-subpage') or subpage == message('testcases-subpage') 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('doc-subpage')
end
return mw.title.new(docpage)
end
function envFuncs.sandboxTitle()
-- Title object for the /sandbox subpage.
return mw.title.new(env.docpageRoot .. '/' .. message('sandbox-subpage'))
end
function envFuncs.testcasesTitle()
-- Title object for the /testcases subpage.
return mw.title.new(env.docpageRoot .. '/' .. message('testcases-subpage'))
end
function envFuncs.printTitle()
-- Title object for the /Print subpage.
return env.templateTitle:subPageTitle(message('print-subpage'))
end
function envFuncs.subjectSpace()
-- The subject namespace number.
return mw.site.namespaces[env.title.namespace].subject.id
end
function envFuncs.docSpace()
-- The documentation namespace number. For most namespaces this is the same as the
-- subject namespace. However, pages in the Article, File, MediaWiki or Category
-- namespaces must have their /doc, /sandbox and /testcases pages in talk space.
local subjectSpace = env.subjectSpace
if subjectSpace == 0 or subjectSpace == 6 or subjectSpace == 8 or subjectSpace == 14 then
return subjectSpace + 1
else
return subjectSpace
end
end
function envFuncs.docpageRoot()
-- The base page of the /doc, /sandbox, and /testcases subpages.
-- For some namespaces this is the talk page, rather than the template page.
local templateTitle = env.templateTitle
local docSpace = env.docSpace
local docSpaceText = mw.site.namespaces[docSpace].name
-- Assemble the link. docSpace is never the main namespace, so we can hardcode the colon.
return docSpaceText .. ':' .. templateTitle.text
end
function envFuncs.compareUrl()
-- Diff link between the sandbox and the main template using [[Special:ComparePages]].
local templateTitle = env.templateTitle
local sandboxTitle = env.sandboxTitle
local compareUrl = mw.uri.fullUrl(
'Special:ComparePages',
{page1 = templateTitle.prefixedText, page2 = sandboxTitle.prefixedText}
)
return tostring(compareUrl)
end
return env
end
----------------------------------------------------------------------------
-- Auxiliary templates
----------------------------------------------------------------------------
function p.sandboxNotice(args, env)
local title = env.title
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('sandbox-notice-image')
-- 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('sandbox-notice-blurb', {templateLink})
else
-- 'This is the [[Wikipedia:Template test cases|template sandbox]] page for $1 ($2).'
local compareDisplay = message('sandbox-notice-compare-link-display')
local compareLink = makeUrlLink(compareUrl, compareDisplay)
text = text .. message('sandbox-notice-diff-blurb', {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('sandbox-notice-testcases-link-display')
local testcasesLink = makeWikilink(testcasesTitle.prefixedText, testcasesLinkDisplay)
text = text .. '<br />' .. message('sandbox-notice-testcases-blurb', {testcasesLink})
end
-- Add the page to [[Category:Template sandboxes]].
text = text .. makeCategoryLink(message('sandbox-category'))
omargs.text = text
return messageBox.main('ombox', omargs)
end
function p.protectionTemplate(env)
local title = env.title
local protectionTemplate = message('protection-template')
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('protection-template-args', 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('view-link-display')
data.editLinkDisplay = message('edit-link-display')
data.historyLinkDisplay = message('history-link-display')
data.purgeLinkDisplay = message('purge-link-display')
-- Create link if /doc doesn't exist.
local preload = args.preload
if not preload then
if env.subjectSpace == 6 then -- File namespace
preload = message('file-docpage-preload')
else
preload = message('docpage-preload')
end
end
data.preload = preload
data.createLinkDisplay = message('create-link-display')
return data
end
function p.renderStartBoxLinks(data)
-- Render the [view][edit][history][purge] or [create] links.
local ret
local docTitle = data.docTitle
local title = data.title
if docTitle.exists then
local viewLink = makeWikilink(docTitle.prefixedText, data.viewLinkDisplay)
local editLink = makeUrlLink(docTitle:fullUrl{action = 'edit'}, data.editLinkDisplay)
local historyLink = makeUrlLink(docTitle:fullUrl{action = 'history'}, data.historyLinkDisplay)
local purgeLink = makeUrlLink(title:fullUrl{action = 'purge'}, data.purgeLinkDisplay)
ret = '[%s] [%s] [%s] [%s]'
ret = ret:gsub('%[', '[') -- Replace square brackets with HTML entities.
ret = ret:gsub('%]', ']')
ret = mw.ustring.format(ret, viewLink, editLink, historyLink, purgeLink)
else
ret = makeUrlLink(docTitle:fullUrl{action = 'edit', preload = data.preload}, data.createLinkDisplay)
end
end
function p.makeStartBoxData(args, env, links)
local subjectSpace = env.subjectSpace
if not subjectSpace then
-- Default to an "other namespaces" namespace, so that we get at least some output
-- if an error occurs.
subjectSpace = 2
end
local data = {}
-- Heading
local heading = args.heading -- Blank values are not removed.
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('documentation-icon-wikitext') .. ' ' .. message('template-namespace-heading')
elseif subjectSpace == 828 then -- Module namespace
data.heading = message('documentation-icon-wikitext') .. ' ' .. message('module-namespace-heading')
elseif subjectSpace == 6 then -- File namespace
data.heading = message('file-namespace-heading')
else
data.heading = message('other-namespaces-heading')
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('start-box-linkclasses')
data.linksId = message('start-box-link-id')
data.links = links
end
return data
end
function p.renderStartBox(data)
-- Renders the start box html.
local sbox = htmlBuilder.create('div')
sbox
.css('padding-bottom', '3px')
.css('border-bottom', '1px solid #aaa')
.css('margin-bottom', '1ex')
.newline()
.tag('span')
.cssText(data.headingStyleText)
.css('font-weight', data.headingFontWeight)
.css('font-size', data.headingFontSize)
.wikitext(data.heading)
local links = data.links
if links then
sbox.tag('span')
.addClass(data.linksClass)
.attr('id', data.linksId)
.wikitext(links)
end
return tostring(sbox)
end
----------------------------------------------------------------------------
-- Documentation content
----------------------------------------------------------------------------
p.content = makeInvokeFunc('_content')
function p._content(args, env)
local docTitle = env.docTitle
local content = args.content
if not content and docTitle and docTitle.exists then
local frame = mw.getCurrentFrame()
content = frame:preprocess('{{ ' .. docTitle.prefixedText .. ' }}')
end
-- The line breaks below are necessary so that "=== Headings ===" at the start and end
-- of docs are interpreted correctly.
return '\n' .. (content or '') .. '\n'
end
----------------------------------------------------------------------------
-- End box
----------------------------------------------------------------------------
p.endBox = makeInvokeFunc('_endBox')
function p._endBox(args, env)
-- This function generates the end box (also known as the link box).
-- Get environment data.
local subjectSpace = env.subjectSpace
local docTitle = env.docTitle
if not subjectSpace or not docTitle then
return nil
end
-- Check whether we should output the end box at all. Add the end
-- box by default if the documentation exists or if we are in the
-- user, module or template namespaces.
if linkBox == 'off'
or not (
docTitle.exists
or subjectSpace == 2
or subjectSpace == 828
or subjectSpace == 10
)
then
return nil
end
-- Assemble the arguments for {{fmbox}}.
local fmargs = {}
fmargs.id = message('fmbox-id') -- Sets 'documentation-meta-data'
fmargs.image = message('fmbox-image-none') -- Sets 'none'
fmargs.style = message('fmbox-style') -- Sets 'background-color: #ecfcf4'
fmargs.textstyle = message('fmbox-textstyle') -- '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
text = text .. (p.makeDocPageBlurb(args, env) or '')
-- Add links to /sandbox and /testcases when appropriate.
if subjectSpace == 2 or subjectSpace == 828 or subjectSpace == 10 then
-- We are in the user, module or template namespaces.
text = text .. p.makeEndBoxExperimentBlurb(args, env)
text = text .. '<br />'
-- Show the categories text, but not if "content" fed or "docname fed"
-- since then it is unclear where to add the categories.
if not content and not docnameFed then
text = text .. (p.makeCategoriesBlurb(args, env) or '')
end
-- Show the "subpages" link.
if subjectSpace ~= 6 then -- Don't show the link in file space.
text = text .. ' ' .. (p.makeSubpagesBlurb(args, env) or '')
end
-- Show the "print" link if it exists.
local printBlurb = p.makePrintBlurb(args, env)
if printBlurb then
text = text .. '<br />' .. printBlurb
end
end
end
fmargs.text = text
-- Return the fmbox output.
return messageBox.main('fmbox', fmargs)
end
function p.makePrintBlurb(args, env)
-- Get the /Print title object
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('print-link-display'))
ret = message('print-blurb', {printLink})
local displayPrintCategory = message('display-print-category', nil, 'boolean')
if displayPrintCategory then
ret = ret .. makeCategoryLink(message('print-category'))
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('template-pagetype')
elseif subjectSpace == 828 then
pagetype = message('module-pagetype')
else
pagetype = message('default-pagetype')
end
return makeWikilink(
'Special:PrefixIndex/' .. templateTitle.prefixedText .. '/',
message('subpages-link-display', {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('doc-link-display'))
return message('add-categories-blurb', {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('edit-link-display')
local editLink = makeUrlLink(editUrl, editDisplay)
local historyUrl = docTitle:fullUrl{action = 'history'}
local historyDisplay = message('history-link-display')
local historyLink = makeUrlLink(historyUrl, historyDisplay)
ret = message('transcluded-from-blurb', {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('module-preload')}
local createDisplay = message('create-link-display')
local createLink = makeUrlLink(createUrl, createDisplay)
ret = message('create-module-doc-blurb', {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('sandbox-link-display')
local sandboxLink = makeWikilink(sandboxPage, sandboxDisplay)
local sandboxEditUrl = sandboxTitle:fullUrl{action = 'edit'}
local sandboxEditDisplay = message('sandbox-edit-link-display')
local sandboxEditLink = makeUrlLink(sandboxEditUrl, sandboxEditDisplay)
local compareUrl = env.compareUrl
local compareLink
if compareUrl then
local compareDisplay = message('compare-link-display')
compareLink = makeUrlLink(compareUrl, compareDisplay)
end
sandboxLinks = sandboxLink .. ' ' .. makeToolbar(sandboxEditLink, compareLink)
else
local sandboxPreload
if subjectSpace == 828 then
sandboxPreload = message('module-sandbox-preload')
else
sandboxPreload = message('template-sandbox-preload')
end
local sandboxCreateUrl = sandboxTitle:fullUrl{action = 'edit', preload = sandboxPreload}
local sandboxCreateDisplay = message('sandbox-create-link-display')
local sandboxCreateLink = makeUrlLink(sandboxCreateUrl, sandboxCreateDisplay)
local mirrorSummary = message('mirror-edit-summary', {makeWikilink(templatePage)})
local mirrorUrl = sandboxTitle:fullUrl{action = 'edit', preload = templatePage, summary = mirrorSummary}
local mirrorDisplay = message('mirror-link-display')
local mirrorLink = makeUrlLink(mirrorUrl, mirrorDisplay)
sandboxLinks = message('sandbox-link-display') .. ' ' .. makeToolbar(sandboxCreateLink, mirrorLink)
end
if testcasesTitle.exists then
local testcasesPage = testcasesTitle.prefixedText
local testcasesDisplay = message('testcases-link-display')
local testcasesLink = makeWikilink(testcasesPage, testcasesDisplay)
local testcasesEditUrl = testcasesTitle:fullUrl{action = 'edit'}
local testcasesEditDisplay = message('testcases-edit-link-display')
local testcasesEditLink = makeUrlLink(testcasesEditUrl, testcasesEditDisplay)
testcasesLinks = testcasesLink .. ' ' .. makeToolbar(testcasesEditLink)
else
local testcasesPreload
if subjectSpace == 828 then
testcasesPreload = message('module-testcases-preload')
else
testcasesPreload = message('template-testcases-preload')
end
local testcasesCreateUrl = testcasesTitle:fullUrl{action = 'edit', preload = testcasesPreload}
local testcasesCreateDisplay = message('testcases-create-link-display')
local testcasesCreateLink = makeUrlLink(testcasesCreateUrl, testcasesCreateDisplay)
testcasesLinks = message('testcases-link-display') .. ' ' .. makeToolbar(testcasesCreateLink)
end
local messageName
if subjectSpace == 828 then
messageName = 'experimentBlurbModule'
else
messageName = 'experimentBlurbTemplate'
end
return message(messageName, {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('display-strange-usage-category', nil, 'boolean') and (subpage == message('doc-subpage') or subpage == message('testcases-subpage')) then
local sort = (title.namespace == 0 and message('strange-usage-category-mainspace-sort') or '') .. title.prefixedText -- Sort on namespace.
ret = ret .. makeCategoryLink(message('strange-usage-category'), sort)
end
return ret
end
return p