Wikipedia:Dazzle!/Tech
|
| ||||||
A lot of the information on this page is out of date! I am rewriting a lot of the code behind Dazzle! right now before the script gets to big for major modifications to be feasible, and as such I will be redoing this page once the rewrite is complete!
This page serves to document the JavaScript library used to make Dazzle! work; it is also perfectly suited to use in other Wikipedia user scripts. Neither the toolkit nor this documentation is fully complete, although I do not anticipate any significant changes will be made to the code; just additions. The code of the toolkit itself is located at User:Drilnoth/toolkit.js.
This page is divided into three "top-level" sections, each of which covers one "area" of the toolkit. Each function, method, and object then has its own subsection.
The toolkit should be fully compatible with all major browsers (including Internet Explorer) and the major Wikipedia skins (monobook and vector).
Floatbox object[edit]
A "floatbox" is an object which overlays itself on top of the rest of the page, and contains whatever content is specified by JavaScript.
Floatbox()[edit]
new Floatbox(String boxname[, String color])
Documentation to come...
Helper functions[edit]
These functions help to shorten JavaScript code in various ways by providing "shortcuts" for common tasks in Wikipedia user scripting, along with some functions that don't fit into another category.
enc()[edit]
enc(String i)
enc() is equivalent to encodeURIComponent(). It simply passes i to the latter function and returns the overall result.
Returns: The encoded text.
id()[edit]
id(String id)
id() is equivalent to document.getElementById(). It simply passes id to the latter function and returns the overall result.
Returns: An element of id id.
add_child()[edit]
add_child(Node target, String type[, String txt])
add_child() creates a node of type type and appends it to target. If the optional argument txt is specified, then a new text node is also created and appended to the newly created node.
Returns: The newly created node.
add_input()[edit]
add_child(Node target, String type, String name)
add_input() creates an <input> node with two parameters defined by type and name, and appends it to target. It is important to use add_input() instead of add_child(, "input") because the latter is not compatible with Internet Explorer.
Returns: The newly created node.
add_note()[edit]
add_note(String id)
add_note() adds a hidden <span> element to the end of the document body with an id of id. On its own, this note has no effect; however, you can later check for the existence of the note using id(). One example use of this is in the callback of an Ajax request; if two responses must be returned before performing some action, you can use a combination of add_note() and if statements in order to check that both edits have been completed (see, for example, the latter parts of User:Drilnoth/dazzle/prod.js where API requests are actually being made).
Returns: Nothing; the created element can only be retrieved using id().
Wiki methods[edit]
The wiki object holds a number of methods which can be used to query the Wikipedia API and to obtain other information about the wiki itself. Unlike the rest of the toolkit, these methods are currently enwiki-specific and will not work on other wikis.
wiki.query()[edit]
wiki.query(String url[, String format])
wiki.query() makes a simple, synchronous Ajax POST request of the API. url should be a list of parameters for the request; do not include the leading "?" or the "format" parameter, and remember to encode variables which may be problematic in a URL. The optional format argument specifies the format of the returned value (e.g., "json"). If format' is not specified, it defaults to "xml".
Returns: The return value depends on the format. If the format is "xml" or not specified, the method returns the responseXML of the request, ready to be read or manipulated by JavaScript. If the format is "json", the method evaluate the response and returns that, so that the response is seen as a JavaScript object. If the format is anything else, the method simply returns the entire request, which must then be evaluated or read manually.
wiki.query_async()[edit]
wiki.query_async(String url, String callback)
wiki.query_async() makes an asynchronous Ajax POST request of the API. url should be a list of parameters for the request; do not include the leading "?", and remember to encode variables which may be problematic in a URL. callback is a string containing JavaScript code, which is evaluated and run when the request is completed. If no action is wanted upon request completion, just use an empty string.
This method is primarily used in the creation of other methods, such as wiki.edit(), and it is not often used on its own.
Returns: Nothing.
wiki.edit()[edit]
wiki.edit(String url, String callback)
wiki.edit() uses wiki.query_async() to make an edit to Wikipedia. It takes the same arguments as the latter method, but no "action" or "token" parameter is needed.
Returns: Nothing.
wiki.del()[edit]
wiki.del(String url, String callback)
wiki.del() uses wiki.query_async() to delete a page on Wikipedia. It takes the same arguments as the latter method, but no "action" or "token" parameter is needed. Remember that only administrators can delete pages, including through the use of this method.
Returns: Nothing.
wiki.token()[edit]
wiki.token(String type[, String pagename])
wiki.token() synchronously retrieves an encoded and ready-to-use token from the API, which is required in order to edit a page and perform other actions, such as protecting a page. The first argument should be the type of the token wanted; for simple edits, this should be "edit". The second, optional argument is the name of the page that you want the token for; by default, it uses the current page. (note that the API still seems to be able to edit OK even if a token was obtained for a page other than the current one). This is primarily useful in the construction of other methods, such as wiki.del(), and it is not often used on its own.
Returns: An encoded token of the specified type, ready to be used in another Ajax request without the use of enc().
wiki.page_content()[edit]
wiki.page_content([String pagename])
wiki.page_content() takes a single argument: The name of a wiki page, which does not need to be encoded. If pagename is not specified, it uses the current page's name. It makes an Ajax request synchronously.
Returns: The wikicode of the current revision of pagename.
wiki.page_creator()[edit]
wiki.page_creator([String pagename])
wiki.page_creator() takes a single argument: The name of a wiki page, which does not need to be encoded. If pagename is not specified, it uses the current page's name. It makes an Ajax request synchronously.
Returns: The name of the first editor of pagename, which is usually the creator or uploader.
wiki.userpage_user()[edit]
wiki.userpage_user([String pagename])
wiki.userpage_user() takes a single argument: The name of a wiki user or user talk page, which should not need to be encoded. If pagename is not specified, it uses the current page's name.
Returns: The name of the user whose userspace pagename is a part of, stripping any subpage and namespace text.