HowTo:Create a user script

A "user script" is typically a JavaScript program that allows you to change how a website behaves. Within Wikipedia, Uncyclopedia, and other MediaWiki wikis, user scripts are often used to allow users have extra features that they wouldn't have without them, like the use of Twinkle to easily warn, block, or welcome users.

Now you probably came to this article to find an answer to the question in the title: "How do you create a MediaWiki user script?" I'll go over that now.

The API

Firstly, you need to be able to understand the MediaWiki API. The API has several different actions, all corresponding to either a GET request or POST request. A few GET requests are "revisions" (which requests the history and/or the actual content of a given page), "parse" (to convert the content of a page from wikitext to HTML), "search" (self-explanatory), and "query" (to request general information not covered by the other GET requests). A few POST requests are "edit" (self-explanatory), "revisiondelete" (to hide or suppress a revision), "rollback" (to revert a user's recent contributions using the rollback feature), and "block" (to block a user).

Have I confused you yet? No? Well then here's some basic JavaScript to let you make use of the API. It will request the gender, edit count, and user rights of a user named "JJPMaster" (that's me!).

var params = {
		action: 'query',
		list: 'users',
		ususers: 'JJPMaster',
		usprop: 'gender|editcount|groups',
		format: 'json'
	},
	api = new mw.Api();
	  var users = data.query.users,
		  u;
	  for ( u in users ) {
		  console.log( users[ u ].name + " has " + users[ u ].editcount + " edits.");
	  }
} );

What is the output of this request? It's written in JSON (JavaScript Object Notation), and it's right below.

{
    "batchcomplete": "",
    "query": {
        "users": [
            {
                "userid": 31726653,
                "name": "JJPMaster",
                "editcount": 3975,
                "groups": [
                    "abusefilter-helper",
                    "extendedconfirmed",
                    "interface-admin",
                    "rollback",
                    "thumbsucker",
                    "*",
                    "user",
                    "autoconfirmed"
                ],
                "gender": "female"
            }
        ]
    }
}

Are you bored yet? If not, let's create a script that will edit a page, rather than just ask for information about a given user and/or page. This script will edit a page with the title of User:JJPMaster/sandbox, by replacing the text with "This edit is being automatically made as part of my new blog post.", and will mark it as a minor edit.

var params = {
		action: 'edit',
		title: 'User:JJPMaster/sandbox',
		text: 'This edit is being automatically made as part of my new blog post.',
		minor: true
	},
	api = new mw.Api();
	
api.postWithToken( 'csrf', params ).done( function ( data ) {
	console.log( data );
} );

Output can be seen in this diff.

We can see that the API actually lets us do stuff, but what can we do to make this script useful? Perhaps a script that automatically adds an "{{ICU}}" to the top of an article? We can use the API for that too!

We can create a function that uses the API to add an ICU to an article, and then create a special link that, when clicked, runs that function. We can use jQuery's ".click" parameter to do this. Specifically, the edit will add "{{ICU|~~~~~}}" to wgPageName (that's the MediaWiki variable that is defined as the page the user is looking at), with the summary "Adding ICU tag to article", and the edit will be marked as minor.

var ICU = mw.util.addPortletLink("p-cactions", "#", "ICU", "medium-blog-post", "Add an ICU tag to this article", null, "#ca-move");
$(ICU).click(Tag);

function Tag()
{
	var params = {
		action: 'edit',
		title: mw.config.get('wgPageName'),
		prependtext: '{{ICU|~~' + '~~' + '~}}',
		summary: 'Adding ICU tag to article',
		minor: true
	},
	api = new mw.Api();
	api.postWithToken( 'csrf', params ).done( function ( data ) {
	console.log( 'ICU\'d succesfully.' );
	mw.notify('ICU complete!')
} );
	
}

The output can be found in this diff.

Using the API, we can do things like this, but sometimes on an even larger scale. Scripts like Wikipedia's Twinkle, RedWarn, and Lupin's anti-vandal tool all use the API to do whatever the script developer wants them to do, albeit far beyond what I've shown you in this barely educational article.

Conclusion

If a website has an API, that's a very good thing. Just don't create a sequel to Twitter's RedScareBot…

See also

• HowTo:Reskin Uncyclopedia – This same article, but with CSS

• JavaScript – The programming language we're using here

External links

• Original blog post – Medium

• MediaWiki official documentation on the API – MediaWiki.org

• Wikipedia's tutorial for creating user scripts – Wikipedia

• The specific code used in this tutorial – GitHub Gist