User:Bawolff/mwapilib

=Mwapilib2 (User:Bawolff/mwapilib2.js)= This does function chaining api access goodness. The main issues with it is it doesn't handle errors very gracefully. This library depends on User:Bawolff/mwapilib.js and will load it automatically. (If you're wondering, this was written before jQuery was available on wikimedia wikis, there might be better ways to do some of this with jquery).

Quick intro
This does api requests as a bunch of chained functions. They give context for how to do the request. Each chained function passes its output to the next one's input, kind of like unix pipes. To start off, you do api('initial input'). Chains end with a exec call. No requests are done until exec is reached.

Example
To Append foo to the end of Sandbox page: api('Wikinews:Sandbox').getPage.lift(function( pageText ) {return pageText + '\nTesting API';}).savePage.exec; Equivalently you can also do: api.inject('Wikinews:Sandbox').getPage.lift(function( pageText ) {return pageText + '\nTesting API';}).savePage.exec; or api.getPage('Wikinews:Sandbox').lift(function( pageText ) {return pageText + '\nTesting API';}).savePage.exec;

To change the default edit summary: api('Wikinews:Sandbox').setDefaultSummary('My edit summary').getPage.lift(function( pageText ) {return pageText + '\nTesting API';}).savePage.exec;

the different functions in detail
All chains start with api. Note, you cannot do api.api. If api is already defined as something else, you can use  instead.

.exec is also special as it denotes an end of a chain. Chains do not start executing until exec happens.

execute a function in the context
This is used to lift a function into the context of the chain. Example: api('foo').lift(function(input) { return 'a' + input; }).alert.exec Pops up with a message.
 * func
 * lift

Any other arguments fed to lift are given to function. api('foo').lift(function(a, b) { return a + b; }, 'baz').alert.exec // returns 'foobaz' Same as lift, except argument 2 that is fed to function is taken from stack. Any other arguments given to lift2 come as arg 3, 4, ... Pop up an alert box with current input. Useful for debugging.
 * lift2
 * alert

Changing input/output
api('foo').replace(/o/g, 'd').alert.exec; // Outputs "fdd" Change the input variable. api('foo').inject('bar').alert.exec // outputs 'bar' Negate input. Note that types are converted using standard js rules.
 * All the function ones like
 * replace
 * inject
 * not

Stack stuff
The function chain also has a stack of other variables. The following mess around with putting input on stack, taking stack onto input, etc. Additionally  uses the stuff on the stack.
 * pop
 * push
 * swap
 * dup

splitting chain
If you want to split chain into two parts that are run asynchronously.


 * runAsync
 * fork
 * doQuick

other control stuff
Stop doing chain if current input is false. often used with.
 * abortIfFalse

Configure how to make the request
Set the default edit summary. If summary given as first arg, leaves input alone, otherwise takes it from input Should the script follow input.
 * setDefaultSummary
 * setFollowRedirect

Actual making the request
Get a page api('Wikinews:Sandbox').getPage.alert.exec; Note this also sets the default save page target to the last gotten page. Save page. takes content from input, page name from last page requested with getPage, or first argument. api('Wikinews:Sandbox').getPage.replace(/sand/g, 'Island').savePage.exec; api('I Want food').savePage('Wikinews:Sandbox').exec (for use with flagged revision). Sight a revision. First argument is revision id, second is sight level (Default to 1). If first argument is undefined, uses revision saved in the chain. Parse wikitext (Taken from input), outputting html. First arg (if specified) is title to use for. Second argument is to supress pre-save transform if set to true. api('test').parse.alert.exec; //outputs &lt;a href.... Get wikitext for a page. Expand wikitext, giving wikitext without templates. Return number of pages in a category. Make a custom api request. Uses mwapilib1 (see below) Takes two arguments, both functions. first function is passed the return of the last func in chain, and should return a req object. or could be a req object (aka a associative array of args to pass to api: {action: 'query', meta: 'siteinfo'...) 2nd function takes the xmlDocument returned from the ajax, and does something with it. Returns true if page exists. can be used with abortIfFalse.
 * getPage
 * savePage
 * sightByRev
 * parse
 * parsePage (synonym )
 * expandTemplates
 * pagesInCat
 * makeRequest
 * checkPageExists

=Mwapilib1 (User:Bawolff/mwapilib.js)= User:Bawolff/mwapilib.js Is a javascript library i made in order to make it easier for user javascript (special:gadgets and what not) to use the mediawiki api. So far its really only used by me, but feel free to use it, copy it, modify it, whatever (but if you do please link back to the original).

To use
If you are on the english Wikinews, add  to the top of your js file. If your on a different wiki (say wikipedia) and you want to use it, use :

This will send a request to the api using the query module, with a prop type of info, and for the pages Main Page and Water cooler/technical. The API uses  to seperate multiple pages. See mw:Manual:API and http://en.wikinews.org/w/api.php for help on the api itself. When this request is sent (note: creating the request object itself does not send the request), it will return a page roughly equivalent to http://en.wikinews.org/w/api.php?action=query&prop=info&titles=Main%20Page|Wikinews:Water%20cooler/technical&format=xmlfm (specificly it will do |Wikinews:Water%20cooler/technical&format=xml) Which gives us:

Now before we actually send the request, we must first make a callback to handle the above data that we receive back from the server. Since the request is asynchronous, we must decide what to do with the data, before we actually send the request. The callback we make will be passed two arguments, the first being an  representing the response to the request, the second being the actual underlying   object used. In most cases (including this case) we only need the first argument.

In this example, our callback is going to find the lengths of the two pages, and tell it to us in an  box. Now we're ready to send the request. Which should pop up a box that looks like this: Page Length Report: Main Page: 5734 Wikinews:Water cooler/technical: 42700 (Numbers were real as of 10:10, 10 July 2009 (UTC). They will obviously change as people edit those pages)

Of course we didn't really check if the api sent us garbage. If there was an explicit error, such as an HTTP error, or an  tag in the api's response, a different callback is called (which by default puts an error message near the site notice (via. it can be overridden by passing a error callback as the second argument to. The error callback also takes two objects, the exception (an  object), and the original ajax. for example we could instead do: Which will alert us if an error happened (for example if we spelt query quey when originally creating our  object.

However if we made a non-blatant mistake on our end, such as trying to find the length of a non-existent page, or a page with an invalid title (for example  f{oo , our callback will see a  or a   respectivly. It will see the   attribute, but will fail finding the   attribute, returning null as the length. If we pass it an interwiki link, such as Main Page, our callback won't see it at all, as interwiki pagenames return  . In a real script you'd probably want to account for these possibilities.

Helper functions
The library also defines a series of helper functions, that make it easier to do certain common tasks. For example, if you wanted to add a new section of Sandbox you could do:

Chaining requests together
Sometimes you need to chain requests together [to be continued]