Extension:SpeciallyCursed
SpeciallyCursed Release status: experimental |
|
---|---|
Implementation | Special page |
Description | Allow wiki admins to create special pages through Lua modules |
Author(s) | Claire (BlankEclairtalk) |
Compatibility policy | Main branch maintains backward compatibility. |
MediaWiki | >= 1.42.0 |
Database changes | No |
License | GNU General Public License 2.0 or later |
Download | |
The SpeciallyCursed extension allows wiki interface administrators to define new special pages that are implemented entirely in Lua.
Note: The documentation assumes that you have knowledge of HTML and Lua (reference manual).
Installation
edit- Install Scribunto
- Clone the repository and place the file(s) in a directory called
SpeciallyCursed
in yourextensions/
folder. - Add the following code at the bottom of your LocalSettings.php file:
wfLoadExtension( 'SpeciallyCursed' );
- Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
Configuration
editTo add new special pages, edit the page MediaWiki:Speciallycursed-config.json. It is an object that specifies the new special pages to be created. The keys are the canonical special page names, and the values are objects that specify the special page's details. The values have the following items:
- module (string, required): The name of the module that implements the special page, excluding the Module namespace (example: "SpeciallyCursed/ComicLinkToWikiPage").
- group (string): The group to put the special page in. See Manual:Special pages § Special page group for more details (default: "other").
- aliases (object): The additional aliases for the special page. Its keys are language codes, and its values are an array of the titles for that language. See Manual:Special pages § The aliases file for more information. Keep in mind that the first item of the English version must be the (case-insensitively) equal to the canonical name of the special page (default:
{"en": ["<the canonical special page name in lowercase>"]}
).
All of the names specified can contain spaces (as they are converted to underscores internally). Additionally, all special pages are case-insensitive. If there are multiple special pages with the same canonical name but with different casings, the last one specified will take effect. Furthermore, any invalid entries (i.e. canonical special page or module titles with invalid characters) will be ignored.
MediaWiki version: | ≥ 1.43 Gerrit change 1071174 |
Note that on MediaWiki 1.43 and above, you must have the corresponding system message for the special page in order for it to show up on Special:SpecialPages.
Configuration examples
edit{
"ComicLinkToWikiPage": {
"module": "SpeciallyCursed/ComicLinkToWikiPage",
"group": "redirects",
"aliases": {
"en": [
"ComicLinkToWikiPage",
"Comic Link to Wiki Page"
]
}
},
"RandomQuote": {
"module": "RandomQuotes"
}
}
This defines two new special pages:
- Special:ComicLinkToWikiPage, inside the "redirects" group (i.e. under the section in Special:SpecialPages titled "Redirecting special pages"). The source code to this special page is in the page Module:SpeciallyCursed/ComicLinkToWikiPage, and it can be accessed via either Special:ComicLinkToWikiPage or Special:Comic Link to Wiki Page.
- Special:RandomQuote, inside the "other" group (i.e. under the section titled "Other special pages"). Its source code is in Module:RandomQuotes, and it can only be accessed through Special:RandomQuote.
Modules
editThe special pages will invoke the main
function of the module specified, and the modules have full access to Scribunto libraries. The return value of the main function is treated as the raw HTML of the special page, allowing you to place elements such as input boxes and forms with ease. It is highly recommended to at least fully protect all modules that are being used as a special page, as outside of being vandalised, they are also an XSS vector.
The main function takes in a frame
parameter, just like ordinary Scribunto modules. The frame has no arguments, but the frame's parent has the subpage as an argument (if any is specified, otherwise it will be none).
Example module
editSave the following to Module:SpeciallyCursed/Test:
local p = {}
local cursed = mw.ext.SpeciallyCursed
function p.main(frame)
local subpage = mw.dumpObject(frame:getParent().args[1])
local testParameter = mw.dumpObject(cursed.request.getText('test'))
local output = '<p><marquee>The world is your oyster!</marquee></p>'
output = output .. '<p>Subpage: ' .. cursed.escapeHtml(subpage) .. '</p>'
output = output .. '<p>?test: ' .. cursed.escapeHtml(testParameter) .. '</p>'
return output
end
return p
Protect that page, then save the following to MediaWiki:Speciallycursed-config.json:
{
"TestSpeciallyCursed": {
"module": "SpeciallyCursed/Test"
}
}
Afterwards, save "Test SpeciallyCursed" to MediaWiki:Testspeciallycursed, and finally navigate to Special:TestSpeciallyCursed to check the page out.
Retrieving the subpage
editTo get the subpage (the "123" in "Special:Log/123" for example), you'll need to access the first argument of the parent frame. Effectively, this means that to get the subpage, you do:
function p.main(frame)
local subpage = frame:getParent().args[1]
-- Do whatever you want with the subpage!
end
The value of subpage
depends on what title is accessed. To put it simply:
Title | Value of subpage
|
---|---|
Special:Test | nil
|
Special:Test/ | ""
|
Special:Test/Hug | "Hug"
|
Special:Test/Hug/Blahaj | "Hug/Blahaj"
|
mw.ext.SpeciallyCursed
editThe extension also provides a library to give Lua special pages the ability to read request information and to redirect the user to other pages. This extra functionality is only available to SpeciallyCursed pages however, and is not exposed to other modules or pages. Extra functionality can very well be added on request.
Credits
edit- Extension:BoilerPlate: Example extension that this extension is based off of
This extension is included in the following wiki farms/hosts and/or packages: This is not an authoritative list. Some wiki farms/hosts and/or packages may contain this extension even if they are not listed here. Always check with your wiki farms/hosts or bundle to confirm. |