Mediawiki: Difference between revisions
(31 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
== Install == |
|||
=== Install on Debian === |
|||
MediaWiki is available as a regular package. This is the recommendation way to keep security patches up-to-date: |
|||
<source lang=bash> |
|||
sudo apt install mediawiki |
|||
</source> |
|||
=== Install a 2nd wiki on Debian === |
|||
On debian, the mediawiki installed with the package is installed in {{file|/var/lib/mediawiki}}. This folder contains many symlinks to the package files in {{file|/usr/share/mediawiki}} directories. |
|||
We can create a second mediawiki instance, but it needs some copy and clean up. Let's assume we want to create a second wiki instance at {{file|/var/lib/mediawiki-bis}}. |
|||
* We basically copy everything in {{file|/var/lib/mediawiki}}, preserving existing symlinks. |
|||
* We clean up folder {{cache}}. |
|||
* We clean up folder {{config}}. |
|||
* We clean up folder {{images}}. |
|||
* We clean up folder {{upload}}. |
|||
* We delete {{file|LocalSettings.php}}. |
|||
* We start installation again. |
|||
* Install {{file|LocalSettings.php}} in {{file|/etc/mediawiki}} and symlink to it |
|||
<source lang=bash> |
|||
mkdir /var/lib/mediawiki-bis |
|||
cd /var/lib/mediawiki-bis |
|||
cp -rp /var/lib/mediawiki/* . |
|||
rm -rf cache/* |
|||
rm -rf config/* |
|||
rm -rf images/* |
|||
rm -rf upload/* |
|||
cp /var/lib/mediawiki/images/README images/ |
|||
rm LocalSettings.php |
|||
# ... Run install via browser, and copy LocalSettings to /etc/mediawiki/LocalSettings-bis.php |
|||
ln -sf /etc/mediawiki/LocalSettings-bis.php LocalSettings.php |
|||
</source> |
|||
;Troubleshoot |
|||
* If during install, script detects that a mediawiki instance is already running, just temporarily rename file {{file|/etc/mediawiki/LocalSettings.php}}. |
|||
== Hints and Tips == |
== Hints and Tips == |
||
=== Purge wiki page cache === |
=== Purge wiki page cache === |
||
Line 40: | Line 79: | ||
One can edit any CSS property above to change the default size of the wiki text. We choose to edit #content so that it only affects the wiki text part (including first header). |
One can edit any CSS property above to change the default size of the wiki text. We choose to edit #content so that it only affects the wiki text part (including first header). |
||
=== Make collapsible element === |
|||
See https://www.mediawiki.org/wiki/Manual:Collapsible_elements. |
|||
Examples: |
|||
{| class="wikitable" width=100% |
|||
|- |
|||
| width=33% | |
|||
<!-- overflow:auto; to fix collapsed display, because the toggle link has float:right; --> |
|||
<div class="mw-collapsible mw-collapsed" style="width:100%; overflow:auto;"> |
|||
* Some intro text ('''expand''' for details) |
|||
<div class="mw-collapsible-content"> |
|||
A very long text<br/> |
|||
A very long text<br/> |
|||
A very long text<br/> |
|||
</div></div> |
|||
| |
|||
<source lang="xml"> |
|||
<!-- overflow:auto; to fix collapsed display, because the toggle link has float:right; --> |
|||
<div class="mw-collapsible mw-collapsed" style="width:100%; overflow:auto;"> |
|||
* Some intro text ('''expand''' for details) |
|||
<div class="mw-collapsible-content"> |
|||
A very long text<br/> |
|||
A very long text<br/> |
|||
A very long text<br/> |
|||
</div></div> |
|||
</source> |
|||
|} |
|||
== Keyboard shortcuts == |
== Keyboard shortcuts == |
||
Line 45: | Line 112: | ||
* Reference page in [http://meta.wikimedia.org/wiki/Help:Keyboard_shortcuts wikipedia] |
* Reference page in [http://meta.wikimedia.org/wiki/Help:Keyboard_shortcuts wikipedia] |
||
* [http://meta.wikimedia.org/wiki/User_Styles#Changing_access_keys Page] explaining how to change keyboard shortcut using user custom stylesheet. |
* [http://meta.wikimedia.org/wiki/User_Styles#Changing_access_keys Page] explaining how to change keyboard shortcut using user custom stylesheet. |
||
* Most frequently-used HTML access keys (default access-key shortcut is < |
* Most frequently-used HTML access keys (default access-key shortcut is {{kb|<Alt+Shift>}} for ''Firefox'' and {{kb|<shift+Esc>}} for ''Opera''): |
||
{| class="wikitable" |
{| class="wikitable" |
||
! Action !! Key |
! Action !! Key !! Firefox |
||
|- |
|- |
||
| accesskey-edit || e |
| accesskey-edit || e || {{kb|<Alt+Shift+e>}} |
||
|- |
|- |
||
| accesskey- |
| accesskey-mainpage || z || {{kb|<Alt+Shift+z>}} |
||
|- |
|- |
||
| accesskey- |
| accesskey-preview || p || {{kb|<Alt+Shift+p>}} |
||
|- |
|- |
||
| accesskey- |
| accesskey-save || s || {{kb|<Alt+Shift+s>}} |
||
|- |
|||
| accesskey-search || f || {{kb|<Alt+Shift+f>}} |
|||
|} |
|} |
||
Line 76: | Line 145: | ||
== Troubleshooting == |
== Troubleshooting == |
||
=== Fix templates that always produce {{{1}}} === |
=== Fix templates that always produce {{{1}}} === |
||
;Update |
|||
:No longer an issue on recent MW apparently (at least >=1.27). |
|||
Templates in Mediawiki will fail if the parameters contains an equal sign. Consider for instance the template '''nb''': |
Templates in Mediawiki will fail if the parameters contains an equal sign. Consider for instance the template '''nb''': |
||
Line 87: | Line 159: | ||
{| class=wikitable width=50% |
{| class=wikitable width=50% |
||
|- |
|- |
||
|<code> |
|<code><nowiki>{{nb|<source lang=bash>echo Hello</source>}}</nowiki></code> |
||
|{{nb|<source lang=bash>echo Hello</source>}} |
|{{nb|<source lang=bash>echo Hello</source>}} |
||
|} |
|} |
||
Line 95: | Line 167: | ||
{| class=wikitable width=50% |
{| class=wikitable width=50% |
||
|- |
|- |
||
|<code> |
|<code><nowiki>{{nb|1=<source lang=bash>echo Hello</source>}}</nowiki></code> |
||
|{{nb|1=<source lang=bash>echo Hello</source>}} |
|{{nb|1=<source lang=bash>echo Hello</source>}} |
||
|} |
|} |
||
Line 133: | Line 205: | ||
== MediaWiki for developers == |
== MediaWiki for developers == |
||
;References |
;References |
||
* [https://www.mediawiki.org/wiki/Developer_hub '''Developer Hub''']. |
|||
* [https://www.mediawiki.org/wiki/Manual:Extensions Manual:Extensions] |
|||
* [https://www.mediawiki.org/wiki/Manual:Developing_extensions Manual:Developing_extensions] |
|||
* [https://www.mediawiki.org/wiki/Manual:Tag_extensions Manual:Tag_extensions] (writing extensions that provides new wiki tags) |
* [https://www.mediawiki.org/wiki/Manual:Tag_extensions Manual:Tag_extensions] (writing extensions that provides new wiki tags) |
||
* [http://www.mediawiki.org/wiki/Manual:Parser_functions Parser functions] |
* [http://www.mediawiki.org/wiki/Manual:Parser_functions Parser functions] |
||
Line 140: | Line 215: | ||
;Tips |
;Tips |
||
* In 99% of cases, extensions just need to use the method <code>recursiveTagParse</code> of the parser instead of <code>Parser::parse</code> (apparently this function is not re-entrant). |
* In 99% of cases, extensions just need to use the method <code>recursiveTagParse</code> of the parser instead of <code>Parser::parse</code> (apparently this function is not re-entrant). |
||
=== Debugging === |
|||
* [https://www.mediawiki.org/wiki/Manual:How_to_debug Mediawiki - How to debug] |
|||
To see PHP errors, add to {{file|LocalSettings.php}} (or can also edit {{file|php.ini}} or {{file|.htaccess}} [https://www.mediawiki.org/wiki/Manual:How_to_debug Mediawiki - How to debug]): |
|||
<source lang=php> |
|||
error_reporting( -1 ); |
|||
ini_set( 'display_errors', 1 ); |
|||
</source> |
|||
=== Globals === |
=== Globals === |
||
Some global variables defined by Mediawiki. Note that to use these variables, we must first declare them as global: |
|||
<source lang=php> |
|||
global $wgExtensionAssetsPath; |
|||
</source> |
|||
{| class=wikitable |
{| class=wikitable |
||
|- |
|- |
||
!Name!!Default!!Description |
!Name!!Default!!Description |
||
|- |
|||
|[https://www.mediawiki.org/wiki/Manual:$IP <code>$IP</code>]||<code>MW_INSTALL_PATH</code> env var||IP stands for Install Path. The variable holds the local file path to the base installation of your wiki. |
|||
|- |
|- |
||
|[https://www.mediawiki.org/wiki/Manual:$wgScriptPath <code>$wgScriptPath</code>]||<code>/wiki</code>||The base URL path (in relation to DOCUMENT ROOT). |
|[https://www.mediawiki.org/wiki/Manual:$wgScriptPath <code>$wgScriptPath</code>]||<code>/wiki</code>||The base URL path (in relation to DOCUMENT ROOT). |
||
Line 153: | Line 244: | ||
|} |
|} |
||
=== Modules === |
|||
* [https://www.mediawiki.org/wiki/ResourceLoader/Modules ResourceLoader/Modules] — This page lists modules that ship with MediaWiki core by default. |
|||
=== ResourceLoader === |
|||
;References: |
|||
* [https://www.mediawiki.org/wiki/ResourceLoader ResourceLoader] on MediaWiki |
|||
* [https://www.mediawiki.org/wiki/ResourceLoader/Developing_with_ResourceLoader Developing with ResourceLoader] |
|||
: Quick walkthrough, registering modules, etc. |
|||
* [https://www.mediawiki.org/wiki/Manual:$wgResourceModules <code>$wgResourceModules</code>] |
|||
* [https://doc.wikimedia.org/mediawiki-core/master/php/classResourceLoader.html ResourceLoader class reference] |
|||
* [https://www.mediawiki.org/wiki/ResourceLoader/Migration_guide_for_extension_developers Migration guide for extension developers] |
|||
;Add a CSS style module |
|||
:For instance, from Extension::Cite |
|||
<source lang=bash> |
|||
$wgHooks['BeforePageDisplay'][] = 'wfCiteBeforePageDisplay'; |
|||
$wgResourceModules['ext.rtlcite'] = array( |
|||
'localBasePath' => __DIR__ . '/modules', |
|||
'remoteExtPath' => 'Cite/modules' |
|||
'styles' => 'ext.rtlcite.css', |
|||
'position' => 'top', |
|||
); |
|||
function wfCiteBeforePageDisplay( $out, &$sk ) { |
|||
$out->addModuleStyles( 'ext.rtlcite' ); |
|||
return true; |
|||
} |
|||
</source> |
|||
:In the following example we add the module only if a tag is present |
|||
<source lang=bash> |
|||
$wgHooks['ParserFirstCallInit'][] = 'onParserSetup'; |
|||
$wgResourceModules['ext.fentt'] = array( |
|||
// ... |
|||
); |
|||
static function onParserSetup( Parser $parser ) { |
|||
$parser->setHook( 'fentt', 'renderFenTT' ); |
|||
} |
|||
$module_added = false; |
|||
function renderFenTT( $input, array $args, Parser $parser, PPFrame $frame ) { |
|||
global $module_added; |
|||
if( ! $module_added ) { |
|||
$parser->getOutput()->addModuleStyles('ext.fentt'); |
|||
self::$module_added = true; |
|||
} |
|||
// ... |
|||
} |
|||
</source> |
|||
;Troubleshoot: |
|||
* Module is listed in the <head> element, but corresponding CSS/JS does not appear in downloaded content |
|||
: Try to register the module (add to <code>$wgResourceModules</code>) at global level (i.e. not in the hook handle function that calls <code>$addModuleStyles</code>). |
|||
=== Hooks === |
|||
* [https://www.mediawiki.org/wiki/Manual:Hooks/BeforePageDisplay <code>$wgHooks['BeforePageDisplay'][]</code>] — Allows last minute changes to the output page, e.g. adding of CSS or JavaScript by extensions. |
|||
=== Javascript === |
|||
==== Modules ==== |
|||
JavaScript files are, like CSS files, also evaluated in the order they are defined in the <code>scripts</code> array (file {{file|extension.json}}). [https://www.mediawiki.org/wiki/ResourceLoader/Developing_with_ResourceLoader#Passing_information_from_PHP_to_Javascript] |
|||
If a module must export a global object, do: |
|||
<source lang=javascript> |
|||
// foo.js |
|||
var Foo = { |
|||
sayHello: function ( $element ) { |
|||
$element.append( '<p>Hello Module!</p>' ); |
|||
} |
|||
}; |
|||
window.Foo = Foo; |
|||
</source> |
|||
If a module must wait that the document be completely loaded before executing, do: |
|||
<source lang=javascript> |
|||
// init.js |
|||
$( function () { |
|||
// This code must not be executed before the document is loaded. |
|||
Foo.sayHello( $( '#hello' ) ); |
|||
}); |
|||
</source> |
|||
==== Export javascript libraries ==== |
|||
Some tips. |
|||
* Javascript libraries must be loaded with the ResourceLoader. |
|||
* JS libraries are loaded asynchronously. Moreover the global context is not the default global context, but the one of the ResourceLoader. If a library must export symbol to global context, they must attach it to the <code>window</code> object: |
|||
<source lang=javascript> |
|||
window.myjslib = myjslib; |
|||
</source> |
|||
* Some libraries don't export to window, but does so like in node.js (see [http://khan.io/2013/08/16/node-js-how-exports-and-module-exports-works/ node.js — how exports and module.exports works]). So they attach to an object <code>module.exports</code> If that's the case, we must export it ourselves. |
|||
: In {{file|extension.json}}, we have: |
|||
<source lang=javascript> |
|||
"ResourceModules": { |
|||
"scripts": [ "myjslib.js", "myjslib.export.js" ] |
|||
} |
|||
</source> |
|||
: assuming that {{file|myjslib.js}} export to <code>module.exports</code>, we fix that in library {{file|myjslib.export.js}}: |
|||
<source lang=javascript> |
|||
// Let's export i18next correctly |
|||
window.myjslib = window.myjslib || module.exports; // Don't export twice |
|||
$.myjslib = $.myjslib || module.exports; // Alternatively we can attach to jQuery context |
|||
myjslib = $.myjslib; // Export to default context |
|||
</source> |
|||
:We must do this '''immediately''' after loading the library, because another library could overwrite <code>module.exports</code>. |
|||
==== ResourceLoader Core Modules ==== |
|||
See '''[https://www.mediawiki.org/wiki/ResourceLoader/Core_modules ResourceLoader Core Modules]'''. |
|||
These contains |
|||
* The '''mediawiki''' module |
|||
* The '''OOjs''' module |
|||
* The '''jQuery''' module and plugins |
|||
:jQuery plugins are available as ResourceLoader module that can be added as a '''module dependency''' in {{file|extension.json}} (for instance module <code>jquery.ui.button</code>). |
|||
To make sure that a module is available, either add it as dependency, or use the code [https://www.mediawiki.org/wiki/ResourceLoader/Developing_with_ResourceLoader]: |
|||
<source lang=javascript> |
|||
mw.loader.using( ['mediawiki.util','mediawiki.Title'] ).then( function () { |
|||
/* This callback is invoked as soon as the modules are available. */ |
|||
} ); |
|||
</source> |
|||
There is also an error callback: |
|||
<source lang=javascript> |
|||
mw.loader.using([ 'mediawiki.util', 'jquery.placeholder', 'jquery.spinner' ], function(){ |
|||
console.warn( 'Ready callback was executed.', arguments ); |
|||
}, function(){ |
|||
console.warn( 'Error callback was executed.', arguments ); |
|||
}); |
|||
</source> |
|||
==== Passing information from PHP to Javascript ==== |
|||
See https://www.mediawiki.org/wiki/ResourceLoader/Developing_with_ResourceLoader#Passing_information_from_PHP_to_Javascript. |
|||
* Store data in HTML. |
|||
* Or use [https://www.mediawiki.org/wiki/Manual:OutputPage.php <code>OutputPage::AddJsConfigVars</code>]. Pay attention however that '''PHP parser code are not necessarily run each time a page is visited''' (eg. if using memcached). If the parser must transfer data to JS context, one solution is to generate inline javascript in <code><script></code> tag. |
|||
==== Run with jQuery support or in RL context ==== |
|||
To run our inline script with jQuery support, use the ResourceLoader queue <code>RLQ</code> [https://www.mediawiki.org/wiki/Topic:T0bq15ycney6xs25], [https://www.mediawiki.org/wiki/Topic:Tdplyqpyhfoirplu]: |
|||
<source lang=javascript> |
|||
RLQ.push(function () { |
|||
console.log('This runs with jQuery support', $); |
|||
}); |
|||
// or |
|||
(window.RLQ=window.RLQ||[]).push(function(){ |
|||
$(function() { console.log("test") }); |
|||
}); |
|||
</source> |
|||
Note that this is only useful for inlined scripts. Script loaded with the ResourceLoader may always assume that jQuery is available (since MW 1.17). |
|||
==== Add an external script ==== |
|||
More solutions on [https://stackoverflow.com/questions/29902768/how-to-add-custom-global-javascript-to-mediawiki Stack Overflow]. For external script, call <code>addHeadItem</code>: |
|||
<source lang=php> |
|||
# Add onBeforePageDisplay function to BeforePageDisplay Hook |
|||
$wgHooks['BeforePageDisplay'][] ='onBeforePageDisplay'; |
|||
function onBeforePageDisplay( OutputPage &$out, Skin &$skin ) |
|||
{ |
|||
$script = '<script type="text/javascript" src="https://example.com/javascript.js"></script>'; |
|||
$out->addHeadItem("itemName", $script); |
|||
return true; |
|||
}; |
|||
</source> |
|||
Be aware that the script will be loaded in the default context, '''which is not the same as the ResourceLoader context that contains all loaded RL modules'''. So this script will not have access to RL libraries. To get access, add a callback to the ResourceLoader queue (see previous section). |
|||
==== Extension template ==== |
|||
The [https://www.mediawiki.org/wiki/Manual:Developing_extensions Manual:Developing_extensions] page gives us the structure that all extensions must follow. |
|||
Several templates are available: |
|||
* [https://github.com/JonasGroeger/cookiecutter-mediawiki-extension cookiecutter-mediawiki-extension]. |
|||
* [https://www.mediawiki.org/wiki/Extension:BoilerPlate Extension:BoilerPlate] |
|||
* [http://tools.wmflabs.org/mwstew/ MWStew]. |
|||
;extension.json |
|||
:Since MW 1.25, all extension comes with a description file {{file|extension.json}}. See [https://www.mediawiki.org/wiki/Manual:Extension.json/Schema Extension.json schema] for the list of all possible entries. |
|||
=== Troubleshooting an extension === |
|||
;First reflexes |
|||
* Test extension in Chrome and Firefox. |
|||
* Open up the browser debug window (Ctrl-Shift-C) and check the Console for javascript errors, file not found. Check also the network tab. |
|||
* Try to load extension in an older version, and bisect the version where the extension fails. |
|||
:* Look at the MediaWiki release note for breaking changes. |
|||
;Attention points |
|||
* MW + cache sucks. If changing PHP code, better edit a test page, add one character and save. This will flush the cache easily. |
|||
* If changing JS code, then Shift+F5 in browser should refresh it. |
|||
;Using foreign JS |
|||
* These are probably ''minified''. It helps greatly to replace them with pretty-printed version (e.g. https://www.prettifyjs.net/) |
|||
* Insert <code>console.log(...)</code> statement to help debugging. |
|||
;Example: PgnJS extension, migration to mw1.35 |
|||
* Extension fails on MW 1.35 |
|||
* Looking at MW 1.35 breaking changes, we see that <code>jquery.ui.*</code> have been removed. This is used in PgnJS {{file|extension.json}}. |
|||
* Open up Firefox/Chrome debugging interface (Ctrl+Shift+C). |
|||
:* In Console, we see errors about <code>Error: Unknown module: jquery.ui.core</code> |
|||
:* Changing <code>"dependencies": [ "jquery.ui.core", "jquery.ui.widget" ]</code> to <code>"dependencies": [ "jquery.ui" ]</code> fixes the problem. |
|||
:* However we see we still get a deprecated warning. |
|||
;Example 2: PgnJS extension, migration to latest PgnViewerJS |
|||
* We first create a static file {{file|example.html}} just to make sure that the apache server is configured correctly (no perm issue) |
|||
:* This will gives the value of the path to use internally (PgnViewerJS expect this path in a variable <code>__globalCustomDomain</code>. |
|||
== How-To == |
|||
=== Add an extension stylesheet in HTML head element === |
=== Add an extension stylesheet in HTML head element === |
||
The goal is to add a stylesheet <code><link></code> tag in the HTML <code><head></code> element, either ALWAYS or CONDITIONALLY, and/or STATIC link or DYNAMIC link (from page content). |
The goal is to add a stylesheet <code><link></code> tag in the HTML <code><head></code> element, either ALWAYS or CONDITIONALLY, and/or STATIC link or DYNAMIC link (from page content). |
||
Line 163: | Line 453: | ||
</source> |
</source> |
||
Criteria |
;Criteria |
||
* Must work with recent MW version, and use stable API. |
* Must work with recent MW version, and use stable API. |
||
* Must be page-caching friendly. |
* Must be page-caching friendly. |
||
* If link is added conditionally, avoid parsing twice the page content. Can we use some context information? |
* If link is added conditionally, avoid parsing twice the page content. Can we use some context information? |
||
;Relevant hooks |
|||
* https://www.mediawiki.org/wiki/Manual:Hooks/OutputPageBeforeHTML |
* https://www.mediawiki.org/wiki/Manual:Hooks/OutputPageBeforeHTML |
||
* https://www.mediawiki.org/wiki/Manual:Hooks/BeforePageDisplay |
* https://www.mediawiki.org/wiki/Manual:Hooks/BeforePageDisplay |
||
* https://www.mediawiki.org/wiki/Manual:Hooks/ParserFirstCallInit |
* https://www.mediawiki.org/wiki/Manual:Hooks/ParserFirstCallInit |
||
;Relevant example extensions |
|||
List of relevant extensions: |
|||
* https://www.mediawiki.org/wiki/Category:HTML_head_extensions |
* https://www.mediawiki.org/wiki/Category:HTML_head_extensions |
||
: list of extensions designed to modify information in the HTML <code><head></code> element |
: list of extensions designed to modify information in the HTML <code><head></code> element |
||
Line 191: | Line 480: | ||
* <code>$parser->getOutput()->addHeadItem( "..." )</code> not working on mobile device. |
* <code>$parser->getOutput()->addHeadItem( "..." )</code> not working on mobile device. |
||
:It works on desktop, on my tablet, but not on my smartphone. Why? |
:It works on desktop, on my tablet, but not on my smartphone. Why? |
||
:The fix is to load the module with <code>[https://doc.wikimedia.org/mediawiki-core/master/php/classOutputPage.html addModuleStyles()]($modules)</code>, as done for instance in [http://www.mediawiki.org/wiki/Extension:Cite Extension:Cite] |
|||
:* Because mobile turns off ResourceLoader module by default [https://www.mediawiki.org/wiki/ResourceLoader/Writing_a_MobileFrontend_friendly_ResourceLoader_module]? And because <code>addHeadItem</code> is similar to adding a ResourceLoader module? |
|||
:* Because <code>addHeadItem</code> actually takes two parameters [https://doc.wikimedia.org/mediawiki-core/master/php/classOutputPage.html#ad37dc926166096712154a6e2e3ca33d8]? |
|||
;Questions |
|||
:Possible solutions: |
|||
* On Wikimedia, there is a link at the bottom to toggle between mobile / desktop view. Handy to test a site in mobile mode. How can we get it installed? By upgrading to the latest MW? or installing Mobile extension |
|||
:* Check [https://www.mediawiki.org/wiki/ResourceLoader/Writing_a_MobileFrontend_friendly_ResourceLoader_module ResourceLoader/Writing a MobileFrontend friendly ResourceLoader module]. |
|||
:* Install [https://www.mediawiki.org/wiki/Extension:MobileApp Extension:MobileApp]? |
|||
;The Solution |
|||
:* Install [https://www.mediawiki.org/wiki/Extension:MobileFrontend Extension:MobileFrontend]? |
|||
<source lang=bash> |
|||
:* Use a <code>[https://doc.wikimedia.org/mediawiki-core/master/php/classOutputPage.html addModuleStyles()]($modules)</code> instead? But what is a module recognized by the ResourceLoader? |
|||
if (defined('MEDIAWIKI')) { |
|||
:Questions |
|||
$wgHooks['ParserFirstCallInit'][] = 'MWFenTT::onParserFirstCallInit'; |
|||
:* On Wikimedia, there is a link at the bottom to toggle between mobile / desktop view. Handy to test a site in mobile mode. How can we get it installed? By upgrading to the latest MW? or installing Mobile extension |
|||
$wgResourceModules['ext.FenTT'] = array( |
|||
'localBasePath' => __DIR__, |
|||
'remoteExtPath' => 'FenTT', |
|||
'styles' => 'FenTT.css', |
|||
'position' => 'top', |
|||
); |
|||
class MWFenTT { |
|||
private static $css_module_added = false; |
|||
static function onParserFirstCallInit( Parser $parser ) { |
|||
// Register parser handler for tag <fentt> |
|||
$parser->setHook( 'fentt', 'MWFenTT::renderFentt' ) |
|||
} |
|||
static function renderFentt( $input, array $args, Parser $parser, PPFrame $frame ) { |
|||
if( ! self::$css_module_added ) { |
|||
// Tell ResourceLoader that we need our css module |
|||
$parser->getOutput()->addModuleStyles( 'ext.FenTT' ); |
|||
self::$css_module_added = true; |
|||
} |
|||
return FenTT::renderFentt($input,$args); |
|||
} |
|||
} |
|||
} |
|||
</source> |
|||
== Extensions == |
|||
* [[MediaWiki GeSHi]] |
|||
* [[MediaWiki RawFile]] |
|||
== MediaWiki for Mobile == |
== MediaWiki for Mobile == |
||
Line 210: | Line 530: | ||
* To apply CSS to a mobile skin, edit [[MediaWiki:Mobile.css]], the counterpart of [[MediaWiki:Common.css]]. |
* To apply CSS to a mobile skin, edit [[MediaWiki:Mobile.css]], the counterpart of [[MediaWiki:Common.css]]. |
||
== Extensions == |
=== Extensions for Mobile === |
||
* [https://www.mediawiki.org/wiki/Extension:MobileFrontend Extension:MobileFrontend] |
|||
* [[MediaWiki GeSHi]] |
|||
: See also [https://www.mediawiki.org/wiki/ResourceLoader/Writing_a_MobileFrontend_friendly_ResourceLoader_module Writing a MobileFrontend friendly ResourceLoader module] |
|||
* [[MediaWiki RawFile]] |
|||
== Administration == |
== Administration == |
||
Line 231: | Line 551: | ||
Use local command <code>importImages.php</code> [http://www.mediawiki.org/wiki/Manual:ImportImages.php]. |
Use local command <code>importImages.php</code> [http://www.mediawiki.org/wiki/Manual:ImportImages.php]. |
||
php maintenance/importImages.php --comment "Rubik's cube position, better perspective" /opt/www/daemenj/web/kiwi.noekeon.org/miki/rb png |
php maintenance/importImages.php --comment "Rubik's cube position, better perspective" /opt/www/daemenj/web/kiwi.noekeon.org/miki/rb png |
||
Or to force a specific user: |
|||
sudo -u www-data php maintenance/importImages.php --comment "Rubik OLL cases, from http://www.cubewhiz.com/oll.php" tmp/ |
Latest revision as of 10:30, 21 April 2022
Install
Install on Debian
MediaWiki is available as a regular package. This is the recommendation way to keep security patches up-to-date:
sudo apt install mediawiki
Install a 2nd wiki on Debian
On debian, the mediawiki installed with the package is installed in /var/lib/mediawiki. This folder contains many symlinks to the package files in /usr/share/mediawiki directories.
We can create a second mediawiki instance, but it needs some copy and clean up. Let's assume we want to create a second wiki instance at /var/lib/mediawiki-bis.
- We basically copy everything in /var/lib/mediawiki, preserving existing symlinks.
- We clean up folder Template:Cache.
- We clean up folder Template:Config.
- We clean up folder Template:Images.
- We clean up folder Template:Upload.
- We delete LocalSettings.php.
- We start installation again.
- Install LocalSettings.php in /etc/mediawiki and symlink to it
mkdir /var/lib/mediawiki-bis
cd /var/lib/mediawiki-bis
cp -rp /var/lib/mediawiki/* .
rm -rf cache/*
rm -rf config/*
rm -rf images/*
rm -rf upload/*
cp /var/lib/mediawiki/images/README images/
rm LocalSettings.php
# ... Run install via browser, and copy LocalSettings to /etc/mediawiki/LocalSettings-bis.php
ln -sf /etc/mediawiki/LocalSettings-bis.php LocalSettings.php
- Troubleshoot
- If during install, script detects that a mediawiki instance is already running, just temporarily rename file /etc/mediawiki/LocalSettings.php.
Hints and Tips
Purge wiki page cache
- When changing templates, purge the browser & mediawiki cache. To purge the cache of a single page, add &action=purge to the URL (see [1] for more)
Increase default font size
The easiest way is to add the following to wiki common stylesheet (MediaWiki:Common.css):
/***** Increase default text size ****/
#content {font-size: 1.2em}
body.page-Main_Page #content {font-size: inherit}
The second line overrides effect of first line so that the new font size does not apply to the Main Page.
There are in fact several ways to increase the font size. Using Opera's DragonFly debug environment (Ctrl-Shift-I), it is easy to see how the font size of a normal wiki text is computed (css is filtered for property font-size):
Computed Style font-size: 15.36px; Inherited from div #bodyContent { font-size: 0.8em } Inherited from div#content { font-size: larger }Inherited from bodybody { font-size: 1.0em }Inherited from htmlhtml { font-size: 1.0em }
Note that em refers to the size of the current font, after application of all inherited styles. In the case above it means that the size of a standard wiki text is not 0.8em as given by div#bodyContent, but well 16px * 1.0 * 1.0 * 1.2 * 0.8 = 15.36px.
One can edit any CSS property above to change the default size of the wiki text. We choose to edit #content so that it only affects the wiki text part (including first header).
Make collapsible element
See https://www.mediawiki.org/wiki/Manual:Collapsible_elements.
Examples:
A very long text |
<!-- overflow:auto; to fix collapsed display, because the toggle link has float:right; -->
<div class="mw-collapsible mw-collapsed" style="width:100%; overflow:auto;">
* Some intro text ('''expand''' for details)
<div class="mw-collapsible-content">
A very long text<br/>
A very long text<br/>
A very long text<br/>
</div></div>
|
Keyboard shortcuts
- Reference page in wikipedia
- Page explaining how to change keyboard shortcut using user custom stylesheet.
- Most frequently-used HTML access keys (default access-key shortcut is <Alt+Shift> for Firefox and <shift+Esc> for Opera):
Action | Key | Firefox |
---|---|---|
accesskey-edit | e | <Alt+Shift+e> |
accesskey-mainpage | z | <Alt+Shift+z> |
accesskey-preview | p | <Alt+Shift+p> |
accesskey-save | s | <Alt+Shift+s> |
accesskey-search | f | <Alt+Shift+f> |
Access Restriction
See these pages for implementing access restriction in MediaWiki:
- A page that implement per-page access restriction [2].
- Another way to hide pages [3].
- See sourceforge project.
- Yet another extension [4].
- Security problem with access restriction extension:
- Some information on how to create custom namespaces [7].
Miscellaneous
- Page Special:Version
- produces a complete list of all extensions installed on the wiki.
Troubleshooting
Fix templates that always produce {{{1}}}
- Update
- No longer an issue on recent MW apparently (at least >=1.27).
Templates in Mediawiki will fail if the parameters contains an equal sign. Consider for instance the template nb:
<div class="noborder"> {{{1}}}</div>
Let's enclose a <source>
tag:
{{nb|<source lang=bash>echo Hello</source>}}
|
echo Hello
|
The fix is simply to prepend 1=
to the parameter value:
{{nb|1=<source lang=bash>echo Hello</source>}}
|
echo Hello
|
Tag attributes not expanded in templates
To have tag attributes expanded in wiki templates (in particular when these attributes contain template parameters), use the special construction {{#tag:tagname|content|attr1=val1|attr2=val2}}
. See also #tag
magic word and bugzilla 61341 for more information.
This is used in template Template:Rawfiledownloadexample:
You can download file "{{{name}}}" below, just click this link: {{#tag:file|{{{name}}}|name={{{name}}}|tag=pre}}. {{#tag:pre|{{{content}}}}}
The example
{{Rawfiledownloadexample|name=myfile.txt|content=Once upon a time There was a Tag Tag was clickable And clicked it was}}
expands into to the following with action ?action=raw&templates=expand
:
You can download file "myfile.sh" below, just click this link: <file|name="myfile.sh" tag="pre">myfile.sh</file>.
<pre>Once upon a time
There was a Tag
Tag was clickable
And clicked it was</pre>
Can't upload file
Error message:
Could not create directory mwstore://local-backend/local-public/ when Uploading.
The problem is due to wrong ownership / permission in mediawiki folder [8]:
sudo chown -R www-data /var/www/mediawiki
MediaWiki for developers
- References
- Developer Hub.
- Manual:Extensions
- Manual:Developing_extensions
- Manual:Tag_extensions (writing extensions that provides new wiki tags)
- Parser functions
- How do I render wikitext in my extension ?
- Manual:RequestContext
- Tips
- In 99% of cases, extensions just need to use the method
recursiveTagParse
of the parser instead ofParser::parse
(apparently this function is not re-entrant).
Debugging
To see PHP errors, add to LocalSettings.php (or can also edit php.ini or .htaccess Mediawiki - How to debug):
error_reporting( -1 );
ini_set( 'display_errors', 1 );
Globals
Some global variables defined by Mediawiki. Note that to use these variables, we must first declare them as global:
global $wgExtensionAssetsPath;
Name | Default | Description |
---|---|---|
$IP |
MW_INSTALL_PATH env var |
IP stands for Install Path. The variable holds the local file path to the base installation of your wiki. |
$wgScriptPath |
/wiki |
The base URL path (in relation to DOCUMENT ROOT). |
$wgExtensionAssetsPath |
{$wgScriptPath}/extensions |
URL to extensions directory. Used to provide a base URL for extension assets like extension-specific images and scripts. Note the difference between
|
Modules
- ResourceLoader/Modules — This page lists modules that ship with MediaWiki core by default.
ResourceLoader
- References
- ResourceLoader on MediaWiki
- Developing with ResourceLoader
- Quick walkthrough, registering modules, etc.
- Add a CSS style module
- For instance, from Extension::Cite
$wgHooks['BeforePageDisplay'][] = 'wfCiteBeforePageDisplay';
$wgResourceModules['ext.rtlcite'] = array(
'localBasePath' => __DIR__ . '/modules',
'remoteExtPath' => 'Cite/modules'
'styles' => 'ext.rtlcite.css',
'position' => 'top',
);
function wfCiteBeforePageDisplay( $out, &$sk ) {
$out->addModuleStyles( 'ext.rtlcite' );
return true;
}
- In the following example we add the module only if a tag is present
$wgHooks['ParserFirstCallInit'][] = 'onParserSetup';
$wgResourceModules['ext.fentt'] = array(
// ...
);
static function onParserSetup( Parser $parser ) {
$parser->setHook( 'fentt', 'renderFenTT' );
}
$module_added = false;
function renderFenTT( $input, array $args, Parser $parser, PPFrame $frame ) {
global $module_added;
if( ! $module_added ) {
$parser->getOutput()->addModuleStyles('ext.fentt');
self::$module_added = true;
}
// ...
}
- Troubleshoot
- Module is listed in the <head> element, but corresponding CSS/JS does not appear in downloaded content
- Try to register the module (add to
$wgResourceModules
) at global level (i.e. not in the hook handle function that calls$addModuleStyles
).
Hooks
$wgHooks['BeforePageDisplay'
[]
] — Allows last minute changes to the output page, e.g. adding of CSS or JavaScript by extensions.
Javascript
Modules
JavaScript files are, like CSS files, also evaluated in the order they are defined in the scripts
array (file extension.json). [9]
If a module must export a global object, do:
// foo.js
var Foo = {
sayHello: function ( $element ) {
$element.append( '<p>Hello Module!</p>' );
}
};
window.Foo = Foo;
If a module must wait that the document be completely loaded before executing, do:
// init.js
$( function () {
// This code must not be executed before the document is loaded.
Foo.sayHello( $( '#hello' ) );
});
Export javascript libraries
Some tips.
- Javascript libraries must be loaded with the ResourceLoader.
- JS libraries are loaded asynchronously. Moreover the global context is not the default global context, but the one of the ResourceLoader. If a library must export symbol to global context, they must attach it to the
window
object:
window.myjslib = myjslib;
- Some libraries don't export to window, but does so like in node.js (see node.js — how exports and module.exports works). So they attach to an object
module.exports
If that's the case, we must export it ourselves.
- In extension.json, we have:
"ResourceModules": {
"scripts": [ "myjslib.js", "myjslib.export.js" ]
}
- assuming that myjslib.js export to
module.exports
, we fix that in library myjslib.export.js:
// Let's export i18next correctly
window.myjslib = window.myjslib || module.exports; // Don't export twice
$.myjslib = $.myjslib || module.exports; // Alternatively we can attach to jQuery context
myjslib = $.myjslib; // Export to default context
- We must do this immediately after loading the library, because another library could overwrite
module.exports
.
ResourceLoader Core Modules
See ResourceLoader Core Modules.
These contains
- The mediawiki module
- The OOjs module
- The jQuery module and plugins
- jQuery plugins are available as ResourceLoader module that can be added as a module dependency in extension.json (for instance module
jquery.ui.button
).
To make sure that a module is available, either add it as dependency, or use the code [10]:
mw.loader.using( ['mediawiki.util','mediawiki.Title'] ).then( function () {
/* This callback is invoked as soon as the modules are available. */
} );
There is also an error callback:
mw.loader.using([ 'mediawiki.util', 'jquery.placeholder', 'jquery.spinner' ], function(){
console.warn( 'Ready callback was executed.', arguments );
}, function(){
console.warn( 'Error callback was executed.', arguments );
});
Passing information from PHP to Javascript
- Store data in HTML.
- Or use
OutputPage::AddJsConfigVars
. Pay attention however that PHP parser code are not necessarily run each time a page is visited (eg. if using memcached). If the parser must transfer data to JS context, one solution is to generate inline javascript in<script>
tag.
Run with jQuery support or in RL context
To run our inline script with jQuery support, use the ResourceLoader queue RLQ
[11], [12]:
RLQ.push(function () {
console.log('This runs with jQuery support', $);
});
// or
(window.RLQ=window.RLQ||[]).push(function(){
$(function() { console.log("test") });
});
Note that this is only useful for inlined scripts. Script loaded with the ResourceLoader may always assume that jQuery is available (since MW 1.17).
Add an external script
More solutions on Stack Overflow. For external script, call addHeadItem
:
# Add onBeforePageDisplay function to BeforePageDisplay Hook
$wgHooks['BeforePageDisplay'][] ='onBeforePageDisplay';
function onBeforePageDisplay( OutputPage &$out, Skin &$skin )
{
$script = '<script type="text/javascript" src="https://example.com/javascript.js"></script>';
$out->addHeadItem("itemName", $script);
return true;
};
Be aware that the script will be loaded in the default context, which is not the same as the ResourceLoader context that contains all loaded RL modules. So this script will not have access to RL libraries. To get access, add a callback to the ResourceLoader queue (see previous section).
Extension template
The Manual:Developing_extensions page gives us the structure that all extensions must follow.
Several templates are available:
- extension.json
- Since MW 1.25, all extension comes with a description file extension.json. See Extension.json schema for the list of all possible entries.
Troubleshooting an extension
- First reflexes
- Test extension in Chrome and Firefox.
- Open up the browser debug window (Ctrl-Shift-C) and check the Console for javascript errors, file not found. Check also the network tab.
- Try to load extension in an older version, and bisect the version where the extension fails.
- Look at the MediaWiki release note for breaking changes.
- Attention points
- MW + cache sucks. If changing PHP code, better edit a test page, add one character and save. This will flush the cache easily.
- If changing JS code, then Shift+F5 in browser should refresh it.
- Using foreign JS
- These are probably minified. It helps greatly to replace them with pretty-printed version (e.g. https://www.prettifyjs.net/)
- Insert
console.log(...)
statement to help debugging.
- Example
- PgnJS extension, migration to mw1.35
- Extension fails on MW 1.35
- Looking at MW 1.35 breaking changes, we see that
jquery.ui.*
have been removed. This is used in PgnJS extension.json. - Open up Firefox/Chrome debugging interface (Ctrl+Shift+C).
- In Console, we see errors about
Error: Unknown module: jquery.ui.core
- Changing
"dependencies": [ "jquery.ui.core", "jquery.ui.widget" ]
to"dependencies": [ "jquery.ui" ]
fixes the problem. - However we see we still get a deprecated warning.
- In Console, we see errors about
- Example 2
- PgnJS extension, migration to latest PgnViewerJS
- We first create a static file example.html just to make sure that the apache server is configured correctly (no perm issue)
- This will gives the value of the path to use internally (PgnViewerJS expect this path in a variable
__globalCustomDomain
.
- This will gives the value of the path to use internally (PgnViewerJS expect this path in a variable
How-To
Add an extension stylesheet in HTML head element
The goal is to add a stylesheet <link>
tag in the HTML <head>
element, either ALWAYS or CONDITIONALLY, and/or STATIC link or DYNAMIC link (from page content).
<head>
...
<link rel="stylesheet" href="..." />
...
</head>
- Criteria
- Must work with recent MW version, and use stable API.
- Must be page-caching friendly.
- If link is added conditionally, avoid parsing twice the page content. Can we use some context information?
- Relevant hooks
- https://www.mediawiki.org/wiki/Manual:Hooks/OutputPageBeforeHTML
- https://www.mediawiki.org/wiki/Manual:Hooks/BeforePageDisplay
- https://www.mediawiki.org/wiki/Manual:Hooks/ParserFirstCallInit
- Relevant example extensions
- list of extensions designed to modify information in the HTML
<head>
element
- For MW 1.16.x and above. Use hook
RawPageViewBeforeOutput
to sanitize CSS, andParserFirstCallInit
to add a head item with$parser->getOutput()->addHeadItem( $headItem );
.
- For MW 1.16+. Use a
ParserFirstCallInit
hook, then add a<style>
element using$wgParser->mOutput->addHeadItem
when it encounters a<css>
tag. Looks an excellent candidate for our stuff!
- Inserts <script> (i.e. Javascript) or <link> (i.e. CSS) code at the bottom of the page's head or within the page's body. Securely inserts arbitrary code to the page's head using <addtohead>.
- For MW 1.10, 1.11. Likely too complex for our use. Insert a metatag as an HTML comment, which is then parsed again (via
preg_match_all
) inOutputPageBeforeHTML
hook.
- Found simply by ... looking for .css files in MW extensions/ directory!
- Uses hooks
ParserFirstCallInit
(to register parser hooks for Cite tags like<ref>
) andBeforePageDisplay
(to add modules, including the call toaddModuleStyles
). But... checking the page source it turns out that Cite css file is *always* loaded by the dynamic resource loader, even when the tag is not used on the page. Is that a problem?
- Troubleshooting
$parser->getOutput()->addHeadItem( "..." )
not working on mobile device.
- It works on desktop, on my tablet, but not on my smartphone. Why?
- The fix is to load the module with
addModuleStyles()($modules)
, as done for instance in Extension:Cite
- Questions
- On Wikimedia, there is a link at the bottom to toggle between mobile / desktop view. Handy to test a site in mobile mode. How can we get it installed? By upgrading to the latest MW? or installing Mobile extension
- The Solution
if (defined('MEDIAWIKI')) {
$wgHooks['ParserFirstCallInit'][] = 'MWFenTT::onParserFirstCallInit';
$wgResourceModules['ext.FenTT'] = array(
'localBasePath' => __DIR__,
'remoteExtPath' => 'FenTT',
'styles' => 'FenTT.css',
'position' => 'top',
);
class MWFenTT {
private static $css_module_added = false;
static function onParserFirstCallInit( Parser $parser ) {
// Register parser handler for tag <fentt>
$parser->setHook( 'fentt', 'MWFenTT::renderFentt' )
}
static function renderFentt( $input, array $args, Parser $parser, PPFrame $frame ) {
if( ! self::$css_module_added ) {
// Tell ResourceLoader that we need our css module
$parser->getOutput()->addModuleStyles( 'ext.FenTT' );
self::$css_module_added = true;
}
return FenTT::renderFentt($input,$args);
}
}
}
Extensions
MediaWiki for Mobile
- References
- CSS
- To apply CSS to a mobile skin, edit MediaWiki:Mobile.css, the counterpart of MediaWiki:Common.css.
Extensions for Mobile
Administration
Delete a page permanently
This procedure allows for permanently deleting a page from the wiki database, including the whole history. After this, there will be no trace left of the content of that page, except for a trace in the delete log indicating the date when the page was deleted and the reason (if any given).
- First, as admin user, go to the page to delete.
- In the menu, select 'Delete', select and type in a reason, then click "Delete page".
- From now on, the page is deleted, but history is still in the database. Deletion can be reverted by going to the delete log page (Special:Log/delete)
- On the wiki server, run the maintenance script named
deleteArchivedRevisions.php
. This will permanently delete the page history from the wiki db.
cd /var/lib/mediawiki/maintenance
php ./deleteArchivedRevisions.php --delete
Upload lots of file at once
Use local command importImages.php
[13].
php maintenance/importImages.php --comment "Rubik's cube position, better perspective" /opt/www/daemenj/web/kiwi.noekeon.org/miki/rb png
Or to force a specific user:
sudo -u www-data php maintenance/importImages.php --comment "Rubik OLL cases, from http://www.cubewhiz.com/oll.php" tmp/