User talk:Conrad.Irwin/Api.js

The API wrapper
The  is a Javascript convenience wrapper around the MediaWiki API. Documentation here merely describes the wrapper, for an overview of what the API can do, read the Mediawiki Page. It evolved out of the API wrapper at the top of User:Conrad.Irwin/editor.js - as with all of my code, please feel free to fix bugs or add features as you find them or require them.

Step 1: Bind to /w/api.php
The first two give you an API which is unrestricted, anything that the server will let you do can be done by the wrapper. The third option must use the JSON callback method of communication which restricts the number of operations that you can perform - see API:Data formats for more information.

NOTE: You can force JsMwApi to pretend that a remote wiki is local by passing "local" as the second parameter to the constructor. This will only work if you are developing in an environment not restricted by the cross-domain security restrictions found in browsers.

Step 2: Making API requests
The value returned by  is a function that takes two parameters, the first is the query you wish to perform, the second is the callback that will be called when a reply has been recieved from the api:

Encoding parameters
In general you can either pass a string or an object as the first parameter to an API call. If you pass a string, it will be sent to api.php unchanged, so you should have already encoded it correctly. If you pass an object it will be turned into a string and encoded correctly on your behalf. The following fragment makes two identical calls to the api:

The conversion of an object is done by encoding all of its {key: value} pairs and then joining them with ampersands:

NOTE: In order to facilitate the writing of extensions, the encoder will also recurse along and into arrays constructing a query string by joining all of the subqueries together. This means that in order to update a set of parameters, you can simply create a new array with the old parameters as the first element and the new parameters as the second element. A null item will be dropped, so you need never look at the parameters you are updating. See the page extension for clarification.

Step 3: Handling response
The callback function that you passed to the api will be called with one argument, which is either the raw result from the api or null if an error was detected.

Overriding the error handler
When an XmlHttpResponse to a local api fails, or when a response contains a top-level api error or warning (but not an error of a submodule, i.e. a failed login is a successful API query) the error handler is called. By default this just logs the error to the console (if the console exists) and calls the original callback with null, this can be overwritten in two ways. Either you create the function  which overrides the default for all instances of JsMwApi on the page; or (preferredly) you attach an error handler to an instance of JsMwApi directly. . You can always go back to the default using. The parameters passed into this function are the XmlHttpRequest that was used to retreive the result (or null for the remote_request), the callback function that was passed with this query, and (possibly) the object obtained by decoding the server response as JSON.

Extensions
You can add properties to JsMwApi instances by attaching properties to JsMwApi.prototype, as is standard for javascript. The only extension that has been written so far is one to allow easier interaction with one particular page, but it would also be nice to have one to help with list handling.

JsMwApi.page(title)
This extension allows you to interact with one particular page on a Wiki. It provides an API wrapper that sets the titles= and title= parameters automatically, so you can do things like:

The main advantage to using the wrapper is for the functions that it in turn provides:

.edit
The edit function wraps the complication of dealing with tokens, it can either be called as  or

The optional parameters are passed onto the api call, and the edit_callback is later called with three arguments:
 * 1) The current text of the page
 * 2) A save_function
 * 3) The raw api result.

The save_function accepts three parameters,
 * 1) The new text to save
 * 2) The extra options for this edit (optional), for example: {summary: "Test edit", minor: true}
 * 3) The callback to be notified when the page save is complete (compulsary).

For example: If you prefer a less-nested style of programming, you can declare the functions in advance:

.parse
Much simpler than the edit function, this function can be called as  or. In the first case, the callback will be called with parsed wikitext of the page "test", and in the second it will be called with the wikitext specified parsed with "test" as the title. In both cases the second parameter passed to the callback is the original result from the api.

.parseFragment
This exists so that you can parse tiny fragments without MediaWiki wrapping them in &lt;p> &lt;/p> tags. It will only work if you pass a small, correctly formed, inline fragment of HTML. Unlike .parse, the wikitext parameter is compulsary.