mirror of
https://gerrit.wikimedia.org/r/mediawiki/extensions/Gadgets
synced 2024-11-28 01:00:02 +00:00
99 lines
4.4 KiB
Plaintext
99 lines
4.4 KiB
Plaintext
--------------------------------------------------------------------------
|
|
README for the Gadgets extension
|
|
Copyright © 2007 Daniel Kinzler
|
|
Licenses: GNU General Public Licence (GPL)
|
|
GNU Free Documentation License (GFDL)
|
|
--------------------------------------------------------------------------
|
|
|
|
The Gadgets extension provides a way for users to pick JavaScript or CSS
|
|
based "gadgets" that other wiki users provide.
|
|
|
|
<http://mediawiki.org/wiki/Extension:Gadgets>
|
|
|
|
The Gadgets extension was originally written by Daniel Kinzler in 2007
|
|
and is released under the GNU General Public Licence (GPL).
|
|
The internationalization files may contain contributions by several people;
|
|
they should be mentioned in each file individually.
|
|
|
|
== Installing ==
|
|
Copy the Gadgets directory into the extensions folder of your
|
|
MediaWiki installation. Then add the following lines to your
|
|
LocalSettings.php file (near the end):
|
|
|
|
require_once( "$IP/extensions/Gadgets/Gadgets.php" );
|
|
|
|
== Usage ==
|
|
The list of available gadgets is defined on MediaWiki:Gadgets-definition.
|
|
Gadgets defined there show up in the "Gadgets" section of
|
|
Special:Preferences, so users can pick the gadgets they would like to use.
|
|
An overview of the gadgets defined by MediaWiki:Gadgets-definition is also
|
|
shown on Special:Gadgets, along with links to the respective system
|
|
messages, for easy editing.
|
|
|
|
Each line in MediaWiki:Gadgets-definition that start with one or more "*"
|
|
(asterisk) characters defines a gadget; it must have the following form:
|
|
|
|
* mygadget|mygadget.js|mygadget.css[option1|option2]
|
|
|
|
That is, each line consists of fields separated by a "|" (pipe) character.
|
|
The first field ("mygadget" in the example) is the gadgets internal name,
|
|
and references a system message (MediaWiki:Gadget-mygadget in the example)
|
|
that contains a short description of the gadget, using wiki syntax.
|
|
Note that the internal name must start with a ASCII letter, and must
|
|
contain only ASCII letter and numbers, hyphens ("-"), underscores ("_"),
|
|
colons (":"), and periods (".") (spaces are also allowed but converted to
|
|
underscores ("_"), like for page titles).
|
|
|
|
The remaining fields on the line refer to the JavaScript or CSS code that
|
|
makes up the gadget, contained in system messages
|
|
(MediaWiki:Gadget-mygadget.js and MediaWiki:Gadget-mygadget.css in the
|
|
example); the names of those messages must end with ".js" or ".css",
|
|
respectively. A gadget can use any number of code messages, specifically,
|
|
common code can be put into a code message used by several gadgets, in
|
|
addition to their own specific code, e.g:
|
|
|
|
* frobinator|commonStuff.js|frob.js|frob.css|pretty.css
|
|
* l33t|commonStuff.js|tools.js|l33t.js
|
|
|
|
The list of gadgets in MediaWiki:Gadgets-definition can be broken into
|
|
sections using lines that start and end with two or more "=" (equals)
|
|
characters, enclosing the name of a system message that defines the
|
|
section's name - for example:
|
|
|
|
== editing-gadgets ==
|
|
|
|
This would define a new section, with the title defined on the page
|
|
MediaWiki:Gadget-section-editing-gadgets
|
|
|
|
== Options ==
|
|
Options are optionally appended to the end of the gadget declaration.
|
|
They are enclosed in square brackets ("[...]") and are separated by pipe
|
|
character ("|").
|
|
|
|
Currently, there are two options: rights required to use the gadget, and
|
|
whether the gadget should be enaled for everyone by default.
|
|
|
|
The rights option looks like "[rights:delete,userrights]". Note that it
|
|
requires specific rights, not groups the user belongs to. This option is
|
|
case-sensitive, but ignores whitespace, i.e. "[ rights: foo , bar ]" is a
|
|
valid declaration, but not "[Rights:Foo]".
|
|
|
|
The "default" option, if present, makes this gadget enabled for every
|
|
eligible user who has not specifically opted out of it by unchecking it in
|
|
their preferences. The option looks like that: "[default]".
|
|
|
|
Options may be combined in any number or order, i.e. "[rights:foo, bar]",
|
|
"[default]", "[rights:boz|default]" and "[default|rights:quux]" are all valid
|
|
declarations.
|
|
|
|
== Caveats ==
|
|
|
|
* Requires MediaWiki 1.11alpha, revision 24477 or later.
|
|
* Gadgets do not apply to Special:Preferences, so users can always disable
|
|
any broken gadgets they may have enabled.
|
|
* Uses BeforePageDisplay hook, thus only works with MonoBook based skins;
|
|
specifically, does not work with CologneBlue.
|
|
* Gadget code is included after user code - that means that user JS has no
|
|
access to things defined in gadgets, and user CSS is overwritten by CSS
|
|
from gadgets. (pending a better way to insert things into the HTML head)
|