-- This module implements .
-- Get required modules.local getArgs = require('Module:Arguments').getArgs
-- Get the config table.local cfg = mw.loadData('Module:Documentation/config/sandbox')
local p =
-- Often-used functions.local ugsub = mw.ustring.gsublocal format = mw.ustring.format
------------------------------------------------------------------------------ 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 "foo-message" had the value 'Foo $2 bar $1.', -- message('foo-message',) 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
return ugsub(msg, '$([1-9][0-9]*)', getMessageVal)end
p.message = message
local function makeWikilink(page, display) if display then return format('%s', page, display) else return format('%s', page) endend
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 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 -- 'documentation-toolbar' return format('
(%s)', message('toolbar-class'), table.concat(ret, ' | ') )endp.makeToolbar = makeToolbar
------------------------------------------------------------------------------ Argument processing----------------------------------------------------------------------------
local function makeInvokeFunc(funcName) return function (frame) local args = getArgs(frame,) return p[funcName](args) endend
------------------------------------------------------------------------------ Entry points----------------------------------------------------------------------------
function p.nonexistent(frame) if mw.title.getCurrentTitle.subpageText
p.main = makeInvokeFunc('_main')
function p._main(args) ---- This function defines logic flow for the module. -- @args - table of arguments passed by the user -- local env = p.getEnvironment(args) local root = mw.html.create root :wikitext(p._getModuleWikitext(args, env)) :wikitext(p.protectionTemplate(env)) :wikitext(p.sandboxNotice(args, env)) :tag('div') -- 'documentation-container' :addClass(message('container')) :attr('role', 'complementary') :attr('aria-labelledby', args.heading ~= and 'documentation-heading' or nil) :attr('aria-label', args.heading
------------------------------------------------------------------------------ Environment settings----------------------------------------------------------------------------
function p.getEnvironment(args) -- 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,)
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) else title = mw.title.getCurrentTitle end return title end
function envFuncs.templateTitle -- local subjectSpace = env.subjectSpace local title = env.title local subpage = title.subpageText if subpage
message('testcases-subpage') then return mw.title.makeTitle(subjectSpace, title.baseText) else return mw.title.makeTitle(subjectSpace, title.text) end end
function envFuncs.docTitle -- local title = env.title local docname = args[1] -- User-specified doc page. local docpage if docname then docpage = docname else docpage = env.docpageBase .. '/' .. message('doc-subpage') end return mw.title.new(docpage) end function envFuncs.sandboxTitle -- return mw.title.new(env.docpageBase .. '/' .. message('sandbox-subpage')) end function envFuncs.testcasesTitle -- return mw.title.new(env.docpageBase .. '/' .. message('testcases-subpage')) end
function envFuncs.protectionLevels -- The protection levels table of the title object. return env.title.protectionLevels 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
6 or subjectSpace
14 then return subjectSpace + 1 else return subjectSpace end end
function envFuncs.docpageBase -- 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 . local templateTitle = env.templateTitle local sandboxTitle = env.sandboxTitle if templateTitle.exists and sandboxTitle.exists then local compareUrl = mw.uri.canonicalUrl('Special:ComparePages', ) return tostring(compareUrl) else return nil end end
return envend
------------------------------------------------------------------------------ Auxiliary templates----------------------------------------------------------------------------
p.getModuleWikitext = makeInvokeFunc('_getModuleWikitext')
function p._getModuleWikitext(args, env) local currentTitle = mw.title.getCurrentTitle if currentTitle.contentModel ~= 'Scribunto' then return end pcall(require, currentTitle.prefixedText) -- if it fails, we don't care local moduleWikitext = package.loaded["Module:Module wikitext"] if moduleWikitext then return moduleWikitext.main endend
function p.sandboxNotice(args, env) --[=[ -- Generates a sandbox notice for display above sandbox pages. -- @args - a table of arguments passed by the user -- @env - environment table containing title objects, etc., generated with p.getEnvironment -- -- Messages: -- 'sandbox-notice-image' --> '[[File:Sandbox.svg|50px|alt=|link=]]' -- 'sandbox-notice-blurb' --> 'This is the $1 for $2.' -- 'sandbox-notice-diff-blurb' --> 'This is the $1 for $2 ($3).' -- 'sandbox-notice-pagetype-template' --> 'template sandbox page' -- 'sandbox-notice-pagetype-module' --> 'module sandbox page' -- 'sandbox-notice-pagetype-other' --> 'sandbox page' -- 'sandbox-notice-compare-link-display' --> 'diff' -- 'sandbox-notice-testcases-blurb' --> 'See also the companion subpage for $1.' -- 'sandbox-notice-testcases-link-display' --> 'test cases' -- 'sandbox-category' --> 'Template sandboxes' -- 'module-sandbox-category' --> 'Module sandboxes' -- 'other-sandbox-category' --> 'Sandboxes outside of template or module namespace' --]=] local title = env.title local sandboxTitle = env.sandboxTitle local templateTitle = env.templateTitle local subjectSpace = env.subjectSpace if not (subjectSpace and title and sandboxTitle and templateTitle and mw.title.equals(title, sandboxTitle)) then return nil end -- Build the table of arguments to pass to . We need just two fields, "image" and "text". local omargs = 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 (diff)." local text = local pagetype, sandboxCat if subjectSpace
828 then pagetype = message('sandbox-notice-pagetype-module') sandboxCat = message('module-sandbox-category') else pagetype = message('sandbox-notice-pagetype-other') sandboxCat = message('other-sandbox-category') end local templateLink = makeWikilink(templateTitle.prefixedText) local compareUrl = env.compareUrl if compareUrl then local compareDisplay = message('sandbox-notice-compare-link-display') local compareLink = makeUrlLink(compareUrl, compareDisplay) text = text .. message('sandbox-notice-diff-blurb',) else text = text .. message('sandbox-notice-blurb',) end -- Get the test cases page blurb if the page exists. This is something like -- "See also the companion subpage for test cases." local testcasesTitle = env.testcasesTitle if testcasesTitle and testcasesTitle.exists then local testcasesLinkDisplay = message('sandbox-notice-testcases-link-display') local testcasesLink = makeWikilink(testcasesTitle.prefixedText, testcasesLinkDisplay) if testcasesTitle.contentModel
-- 'documentation-clear' return '
' .. require('Module:Message box').main('ombox', omargs)end
function p.protectionTemplate(env) -- Generates the padlock icon in the top right. -- @env - environment table containing title objects, etc., generated with p.getEnvironment -- Messages: -- 'protection-template' --> 'pp-template' -- 'protection-template-args' --> local protectionLevels = env.protectionLevels if not protectionLevels then return nil end local editProt = protectionLevels.edit and protectionLevels.edit[1] local moveProt = protectionLevels.move and protectionLevels.move[1] if editProt then -- The page is edit-protected. return require('Module:Protection banner')._main elseif moveProt and moveProt ~= 'autoconfirmed' then -- The page is move-protected but not edit-protected. Exclude move -- protection with the level "autoconfirmed", as this is equivalent to -- no move protection at all. return require('Module:Protection banner')._main else return nil endend
------------------------------------------------------------------------------ Start box----------------------------------------------------------------------------
p.startBox = makeInvokeFunc('_startBox')
function p._startBox(args, env) ---- This function generates the start box. -- @args - a table of arguments passed by the user -- @env - environment table containing title objects, etc., generated with p.getEnvironment -- -- The actual work is done by p.makeStartBoxLinksData and p.renderStartBoxLinks which make -- the [view] [edit] [history] [purge] links, and by p.makeStartBoxData and p.renderStartBox -- which generate the box HTML. -- env = env or p.getEnvironment(args) local links local content = args.content local linksData = p.makeStartBoxLinksData(args, env) if not content or args[1] then -- No need to include the links if the documentation is on the template page itself. if linksData then links = p.renderStartBoxLinks(linksData) end else links = "[" .. linksData.helpLink .. "]" 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 endend
function p.makeStartBoxLinksData(args, env) -- local subjectSpace = env.subjectSpace local title = env.title local docTitle = env.docTitle if not title or not docTitle then return nil end if docTitle and docTitle.isRedirect then docTitle = docTitle.redirectTarget end
-- Create link if /doc doesn't exist. local preload = args.preload if not preload then if subjectSpace
828 then -- Module namespace helpLink = message('help-module-link') else helpLink = message('help-template-link') end end return end
function p.renderStartBoxLinks(data) ---- Generates the [view][edit][history][purge] or [create][purge] links from the data table. -- @data - a table of data generated by p.makeStartBoxLinksData -- local docTitle = data.docTitle -- yes, we do intend to purge the template page on which the documentation appears local purgeLink = makeWikilink("Special:Purge/" .. data.title.prefixedText, data.purgeLinkDisplay) local helpLink = data.helpLink if docTitle.exists then local viewLink = makeWikilink(docTitle.prefixedText, data.viewLinkDisplay) local editLink = makeWikilink("Special:EditPage/" .. docTitle.prefixedText, data.editLinkDisplay) local historyLink = makeWikilink("Special:PageHistory/" .. docTitle.prefixedText, data.historyLinkDisplay) return "[" .. viewLink .. "] [" .. editLink .. "] [" .. historyLink .. "] [" .. helpLink .. "] [" .. purgeLink .. "]" else local createLink = makeUrlLink(docTitle:canonicalUrl, data.createLinkDisplay) return "[" .. createLink .. "] [" .. helpLink .. "] [" .. purgeLink .. "]" end return retend
function p.makeStartBoxData(args, env, links) --[=[ -- Does initial processing of data to pass to the start-box render function, p.renderStartBox. -- @args - a table of arguments passed by the user -- @env - environment table containing title objects, etc., generated with p.getEnvironment -- @links - a string containing the [view][edit][history][purge] links - could be nil if there's an error. -- -- Messages: -- 'documentation-icon-wikitext' --> '' -- 'template-namespace-heading' --> 'Template documentation' -- 'module-namespace-heading' --> 'Module documentation' -- 'file-namespace-heading' --> 'Summary' -- 'other-namespaces-heading' --> 'Documentation' -- 'testcases-create-link-display' --> 'create' --]=] 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
10 then -- Template namespace data.heading = message('documentation-icon-wikitext') .. ' ' .. message('template-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 else -- 'documentation-heading' data.headingClass = message('main-div-heading-class') end -- Data for the [view][edit][history][purge] or [create] links. if links then -- 'mw-editsection-like plainlinks' data.linksClass = message('start-box-link-classes') data.links = links end return dataend
function p.renderStartBox(data) -- Renders the start box html. -- @data - a table of data generated by p.makeStartBoxData. local sbox = mw.html.create('div') sbox -- 'documentation-startbox' :addClass(message('start-box-class')) :newline :tag('span') :addClass(data.headingClass) :attr('id', 'documentation-heading') :cssText(data.headingStyleText) :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) -- Displays the documentation contents -- @args - a table of arguments passed by the user -- @env - environment table containing title objects, etc., generated with p.getEnvironment env = env or p.getEnvironment(args) local docTitle = env.docTitle local content = args.content if not content and docTitle and docTitle.exists then content = args._content or mw.getCurrentFrame:expandTemplate end -- The line breaks below are necessary so that "
" at the start and end -- of docs are interpreted correctly. return '\n' .. (content or ) .. '\n' end
p.contentTitle = makeInvokeFunc('_contentTitle')
function p._contentTitle(args, env) env = env or p.getEnvironment(args) local docTitle = env.docTitle if not args.content and docTitle and docTitle.exists then return docTitle.prefixedText else return endend
------------------------------------------------------------------------------ End box----------------------------------------------------------------------------
p.endBox = makeInvokeFunc('_endBox')
function p._endBox(args, env) --[=[ -- This function generates the end box (also known as the link box). -- @args - a table of arguments passed by the user -- @env - environment table containing title objects, etc., generated with p.getEnvironment -- --]=] -- Get environment data. env = env or p.getEnvironment(args) 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. local linkBox = args['link box'] if linkBox
2 or subjectSpace
10 ) then return nil end
-- Assemble the link box. local text = if linkBox then text = text .. linkBox else text = text .. (p.makeDocPageBlurb(args, env) or ) -- "This documentation is transcluded from Foo." if subjectSpace
10 or subjectSpace
return '\n' .. tostring(box)end
function p.makeDocPageBlurb(args, env) --[=[
-- Makes the blurb "This documentation is transcluded from [[Template:Foo]] (edit, history)". -- @args - a table of arguments passed by the user -- @env - environment table containing title objects, etc., generated with p.getEnvironment -- -- Messages: -- 'edit-link-display' --> 'edit' -- 'history-link-display' --> 'history' -- 'transcluded-from-blurb' --> -- 'The above documentation -- is transcluded from $1.' -- 'module-preload' --> 'Template:Documentation/preload-module-doc' -- 'create-link-display' --> 'create' -- 'create-module-doc-blurb' --> -- 'You might want to $1 a documentation page for this Scribunto module.' --]=] local docTitle = env.docTitle if not docTitle then return nil end if docTitle.exists then -- /doc exists; link to it. local docLink = makeWikilink(docTitle.prefixedText) local editDisplay = message('edit-link-display') local editLink = makeWikilink("Special:EditPage/" .. docTitle.prefixedText, editDisplay) local historyDisplay = message('history-link-display') local historyLink = makeWikilink("Special:PageHistory/" .. docTitle.prefixedText, historyDisplay) return message('transcluded-from-blurb',) .. ' ' .. makeToolbar(editLink, historyLink) .. '
' elseif env.subjectSpace
function p.makeExperimentBlurb(args, env) --diff) and testcases (edit) pages." -- @args - a table of arguments passed by the user -- @env - environment table containing title objects, etc., generated with p.getEnvironment -- -- Messages: -- 'sandbox-link-display' --> 'sandbox' -- 'sandbox-edit-link-display' --> 'edit' -- 'compare-link-display' --> 'diff' -- 'module-sandbox-preload' --> 'Template:Documentation/preload-module-sandbox' -- 'template-sandbox-preload' --> 'Template:Documentation/preload-sandbox' -- 'sandbox-create-link-display' --> 'create' -- 'mirror-edit-summary' --> 'Create sandbox version of $1' -- 'mirror-link-display' --> 'mirror' -- 'mirror-link-preload' --> 'Template:Documentation/mirror' -- 'sandbox-link-display' --> 'sandbox' -- 'testcases-link-display' --> 'testcases' -- 'testcases-edit-link-display'--> 'edit' -- 'template-sandbox-preload' --> 'Template:Documentation/preload-sandbox' -- 'testcases-create-link-display' --> 'create' -- 'testcases-link-display' --> 'testcases' -- 'testcases-edit-link-display' --> 'edit' -- 'module-testcases-preload' --> 'Template:Documentation/preload-module-testcases' -- 'template-testcases-preload' --> 'Template:Documentation/preload-testcases' -- 'experiment-blurb-module' --> 'Editors can experiment in this module's $1 and $2 pages.' -- 'experiment-blurb-template' --> 'Editors can experiment in this template's $1 and $2 pages.' -- 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 sandboxEditDisplay = message('sandbox-edit-link-display') local sandboxEditLink = makeWikilink("Special:EditPage/" .. sandboxPage, 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 mirrorUrl = sandboxTitle:canonicalUrl end 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:canonicalUrl local testcasesEditDisplay = message('testcases-edit-link-display') local testcasesEditLink = makeWikilink("Special:EditPage/" .. testcasesPage, testcasesEditDisplay) -- for Modules, add testcases run link if exists if testcasesTitle.contentModel
828 then testcasesPreload = message('module-testcases-preload') else testcasesPreload = message('template-testcases-preload') end local testcasesCreateUrl = testcasesTitle:canonicalUrl local testcasesCreateDisplay = message('testcases-create-link-display') local testcasesCreateLink = makeUrlLink(testcasesCreateUrl, testcasesCreateDisplay) testcasesLinks = message('testcases-link-display') .. ' ' .. makeToolbar(testcasesCreateLink) end local messageName if subjectSpace
function p.makeCategoriesBlurb(args, env) -- local docTitle = env.docTitle if not docTitle then return nil end local docPathLink = makeWikilink(docTitle.prefixedText, message('doc-link-display')) return message('add-categories-blurb',)end
function p.makeSubpagesBlurb(args, env) -- local subjectSpace = env.subjectSpace local templateTitle = env.templateTitle if not subjectSpace or not templateTitle then return nil end local pagetype if subjectSpace
828 then pagetype = message('module-pagetype') else pagetype = message('default-pagetype') end local subpagesLink = makeWikilink('Special:PrefixIndex/' .. templateTitle.prefixedText .. '/', message('subpages-link-display',) ) return message('subpages-blurb',)end
------------------------------------------------------------------------------ Tracking categories----------------------------------------------------------------------------
function p.addTrackingCategories(env) -- local title = env.title local subjectSpace = env.subjectSpace if not title or not subjectSpace then return nil end local subpage = title.subpageText if message('display-strange-usage-category', nil, 'boolean') and (subpage
message('testcases-subpage') ) then return makeCategoryLink(message('strange-usage-category')) end return end
return p