Twinkle is a JavaScript library and application that gives Wikipedians a quick way of performing common maintenance tasks, such as nominating pages for deletion and cleaning up vandalism.
It is based upon the morebits.js
library, which forms the basis for many Wikipedia scripts and editing tools.
See Wikipedia:Twinkle on the English Wikipedia for more information.
AzaToth is the original author and maintainer of the tool, as well as the morebits.js
library.
morebits.js
: The central library used by Twinkle and many other scripts. Contains code to interact with the MediaWiki API, display forms and dialogs, generate status logs, and do various other useful things. The vast majority of code in here is not Twinkle-specific.morebits.css
: Styling to accompanymorebits.js
. The portlet styles relating to the Modern skin are Twinkle-specific and should arguably be in atwinkle.css
file.sync.pl
: A Perl script to update on-wiki gadgets, or update the repository based on on-wiki changes. See below for full documentation.twinkle.js
: General Twinkle-specific code, mostly related to preferences and exposing Twinkle in the UI. Significantly, it contains the default set of preferences of Twinkle.modules
: Contains the individual Twinkle modules. Descriptions for these can be found in header comments or in the Twinkle documentation. The moduletwinkleconfig.js
powers the Twinkle preferences panel.
Other files not mentioned here are probably obsolete.
There are two ways to upload Twinkle scripts to Wikipedia or another destination. You can do it manually (recommended) or with a Perl script.
After the files are synced, MediaWiki:Gadgets-definition should contain the following lines:
* Twinkle[ResourceLoader|dependencies=mediawiki.user,mediawiki.util,mediawiki.RegExp,mediawiki.notify,jquery.ui.dialog,jquery.tipsy,moment|rights=autoconfirmed|type=general|peers=Twinkle-pagestyles]|morebits.js|morebits.css|Twinkle.js|twinkleprod.js|twinkleimage.js|twinklebatchundelete.js|twinklewarn.js|twinklespeedy.js|friendlyshared.js|twinklediff.js|twinkleunlink.js|friendlytag.js|twinkledeprod.js|friendlywelcome.js|twinklexfd.js|twinklebatchdelete.js|twinklebatchprotect.js|twinkleconfig.js|twinklefluff.js|twinkleprotect.js|twinklearv.js|twinkleblock.js|friendlytalkback.js|Twinkle.css
* Twinkle-pagestyles[hidden|skins=vector]|Twinkle-pagestyles.css
Twinkle-pagestyles
is a hidden peer gadget of Twinkle. Before Twinkle has loaded, it adds space where the TW menu would go in the Vector skin, so that the top bar does not "jump".
Each Twinkle module and dependency lives on the wiki as a separate file. The list of modules and what pages they should be on are as follows:
twinkle.js
→ MediaWiki:Gadget-Twinkle.jstwinkle.css
→ MediaWiki:Gadget-Twinkle.csstwinkle-pagestyles.css
→ MediaWiki:Gadget-Twinkle-pagestyles.cssmorebits.js
→ MediaWiki:Gadget-morebits.jsmorebits.css
→ MediaWiki:Gadget-morebits.cssmodules/twinkleprod.js
→ MediaWiki:Gadget-twinkleprod.jsmodules/twinkleimage.js
→ MediaWiki:Gadget-twinkleimage.jsmodules/twinklebatchundelete.js
→ MediaWiki:Gadget-twinklebatchundelete.jsmodules/twinklewarn.js
→ MediaWiki:Gadget-twinklewarn.jsmodules/twinklespeedy.js
→ MediaWiki:Gadget-twinklespeedy.jsmodules/friendlyshared.js
→ MediaWiki:Gadget-friendlyshared.jsmodules/twinklediff.js
→ MediaWiki:Gadget-twinklediff.jsmodules/twinkleunlink.js
→ MediaWiki:Gadget-twinkleunlink.jsmodules/friendlytag.js
→ MediaWiki:Gadget-friendlytag.jsmodules/twinkledeprod.js
→ MediaWiki:Gadget-twinkledeprod.jsmodules/friendlywelcome.js
→ MediaWiki:Gadget-friendlywelcome.jsmodules/twinklexfd.js
→ MediaWiki:Gadget-twinklexfd.jsmodules/twinklebatchdelete.js
→ MediaWiki:Gadget-twinklebatchdelete.jsmodules/twinklebatchprotect.js
→ MediaWiki:Gadget-twinklebatchprotect.jsmodules/twinkleconfig.js
→ MediaWiki:Gadget-twinkleconfig.jsmodules/twinklefluff.js
→ MediaWiki:Gadget-twinklefluff.jsmodules/twinkleprotect.js
→ MediaWiki:Gadget-twinkleprotect.jsmodules/twinklearv.js
→ MediaWiki:Gadget-twinklearv.jsmodules/friendlytalkback.js
→ MediaWiki:Gadget-friendlytalkback.jsmodules/twinkleblock.js
→ MediaWiki:Gadget-twinkleblock.js
There is a synchronization script called sync.pl
, which can be used to pull and push files to Wikipedia.
The program depends on a few modules, namely MediaWiki::API
, Git::Repository
, File::Slurper
, and Getopt::Long::Descriptive
. These can be installed easily using App::cpanminus
:
cpanm --sudo install MediaWiki::API Git::Repository File::Slurper Getopt::Long::Descriptive
You may prefer to install them through your operating system's packaing tool (e.g. apt-get install libgetopt-long-descriptive-perl
) although you can install them through cpanm too.
When running the program, you can enter your credentials on the command line using the --username
and --password
parameters, but it is recommended to save them in a file called ~/.twinklerc
using the following format:
username = username
password = password
lang = en
family = wikipedia
base = User:Username
where base
is the wiki path to prefix the files for pull
and push
. The script ignores the modules/
part of the file path when downloading/uploading.
Notice that your working directory must be clean; if not, either stash
or commit
your changes.
To pull
user Foobar's changes (i.e. User:Foobar/morebits.js
), do:
./sync.pl --base User:Foobar --pull twinkle.js morebits.js ...
To push
your changes to Foobar's wiki page, do:
./sync.pl --base User:Foobar --push twinkle.js morebits.js ...
There is also a deploy
command for interface-admins to deploy Twinkle files live to their MediaWiki:Gadget locations. You will need to set up a bot password at Special:BotPasswords.
./sync.pl --deploy twinkle.js morebits.js ...
You may also deploy
all files via
make deploy
Note that for syncing to a custom wiki (read: not the English Wikipedia), you will also need to specify the --lang and --family parameters too. For instance, to sync the files with test.wmflabs.org
you should specify --lang=test --family=wmflabs
. If you intend to use make deploy
to deploy all the files at once, you may also need to pass the necessary parameters through the makefile to the sync script like this example:
make ARGS="--lang=test --family=wmflabs" deploy
When deploy
ing or push
ing, the script will attempt to parse the latest on-wiki edit summary to find the most recently used commit, and will use that to create an edit summary from the commits since then. If it cannot find anything that looks like a commit hash, it will prompt you to enter one for each file.
While old legacy code has many different and incoherent styles, it has been decided to utilize a more coherent style throughout the code.
The jQuery Core Style Guideline is what we will hereafter use as our style guideline.
Needless to say, there are exceptions. The main sticking point is spacing around parentheses. Older Twinkle code looks like if ( condition ) {
, but newer code tends to use if (condition) {
. The best convention here is to follow the style of surrounding code.