Star Wars Fanon:API

This is a documentation of the Wookieepedia reusable JavaScript file (MediaWiki:Functions.js). This file is site-independent and can be used on any Wikia wiki.

Bootstrapping

 * Copy MediaWiki:Functions.js to your wiki.
 * Add the following to your MediaWiki:Common.js:

importScript('MediaWiki:Functions.js');


 * Add the following call to your first onload hook:

initFunctionsJS;

Why isn't feature X present?
It contains code that is or was once used in Wookieepedia's Monobook.js/Common.js, refactored to be reusable. Nothing more, nothing less.

ContentLoader
Used by: requestComboFill, doPreload

This class encapsulates different implementations of XMLHttpRequest, hiding their complexities behind a (slightly) simpler API.

The primary purpose of the ContentLoader class is to fetch web pages as text (either HTML text or wikitext, which can be obtained on MediaWiki by adding the "action=raw" parameter). It can be also used to do POST requests, although on MediaWiki the usefulness of this feature is dubious.

Subject to the Same Origin Policy, which is hardcoded in modern web browsers (can only be used on the same wiki/subdomain, not across Wikia).

Even though slightly more high-level than XMLHttpRequest, it's still fairly low-level and should only be used by advanced users.

Constructor
constructor ContentLoader;

Creates a new ContentLoader object.

Public fields
[get] boolean cache;

Specifies whether caching is enabled. Default: true.

[set] function callback;

The function that gets called after the data arrive from the HTTP server. When it is called, "this" is the ContentLoader object. State can be stored and retrieved using its global fields. Usually, the code that sends the request creates new fields in the ContentLoader object to store the state, which is then retrieved in the callback.

[get] string text;

Used in the callback function to retrieve the HTML code or plaintext of the retrieved page.

[get] Document document;

Used in the callback function as the root element of the DOM tree if the retrieved page is an XML document.

Public methods
void enableCache(boolean cache = true);

Enables or disables caching. If the user calls this method, it must be done before send.

void send(string url, string postdata = null, string contentType = 'application/x-www-form-urlencoded');

Sends an HTTP request to the server and immediately returns without waiting for it to complete. When the request arrives, the callback function will be called.

If postdata is null, a GET request is sent. Otherwise, a POST request is sent with the content type set per the contentType parameter.

The "url" parameter can be either an absolute address (http://starwars.wikia.com/index.php?...) or a relative address (/index.php?...). The relative form is preferred for the sake of portability.

ClassTester
Used by: getElementsByClass, getParentByClass

Tests HTML DOM elements, determining if they belong to the specified CSS class.

Constructor
constructor ClassTester(string className);

Creates a new ClassTester object testing for a specific class name.

Public methods
boolean isMatch(Element e);

Returns a value indicating if the specified DOM element belongs to the CSS class.

Standard object enhancements
string String::trim;

Used by: (indirectly) window.pageName; Removes whitespace from the beginning and end of a string and returns the result.

Global variables
[get] boolean window.storagePresent;

If this variable is set to true, the browser supports the globalStorage object. Equivalent to (typeof(globalStorage) != 'undefined').

As of this writing, only Firefox 2.0+ supports the globalStorage object.

[get] string window.pageName;

Depends on: getFirstHeading, (indirectly) String::trim; Contains the pagename, as it was before any title modifications took place. (This means initFunctionsJS needs to be called before any title manipulation.)

Array manipulation
int arrayFind(mixed[] array, mixed value);

Searches an array for an element and returns its index, or -1 if it's not in the array.

void arrayRemove(mixed[] array, mixed value);

Removes the first occurrence of an element in an array, if it is there.

DOM manipulation
Element[] getElementsByClass(string className, Element e = document, string tag = '*');

Used by: getFirstHeading, substUsername, rewriteHover

Depends on: ClassTester

Returns an array of all DOM elements that are (direct or indirect) children of a given DOM element and have the specified CSS class. The search can be limited to a specific tag name. If no tag name is given, it searches for any suitable elements regardless of the tag name.

Element getParentByClass(string className, Element e);

Depends on: ClassTester

Returns the "nearest" parent element of a given DOM element that has the specified CSS class. If no such element is found all the way to the DOM root, returns null.

HTML/URL helpers
void insertAtCursor(HTMLTextArea field, string text);

Used by: (indirectly) doPreload

Inserts text into the cursor position at the given textarea DOM element. If the browser doesn't support this, it falls back to adding the new text at the end of the textarea content.

string queryString(string key);

Returns the parameter as it appears in the query string (URL). Resembles $_GET[key] in PHP.

Example: if the request is /index.php?title=Main_Page&action=edit, queryString('title') returns 'Main_Page', and queryString('action') returns 'edit'.

Wiki-specific functions
Element getFirstHeading;

Depends on: getElementsByClass

Returns the h1.firstHeading element (the header element that contains the page name).

void requestComboFill(string comboID, string pageName);

Depends on: ContentLoader

Retrieves the wikitext of the specified page (on the same wiki) and fills the specified (by id) combo box with it.

The page must be of the same format as wikia:starwars:Template:Stdsummaries, and must not be in the MediaWiki namespace.

void doPreload(string pageName);

Depends on: ContentLoader, (indirectly) insertAtCursor

Retrieves the wikitext of the specified page and inserts it into the edit box at the cursor position.

void rewriteSearchFormLink;

Makes the link associated with File:Search logo.png in the search box (if it is uploaded) point to the wiki's search page instead of Wikia.

void substUsername;

Depends on: getElementsByClass

Inserts the name of the user viewing the page into [selector: span.insertusername].

wikia:starwars:Template:USERNAME can be copied to the wiki for convenience and used (without parameters) where the username needs to be inserted.

void rewriteHover;

Depends on: getElementsByClass

Adds an onmousehover handler to all [selector: #hover-global .hoverable] elements. This handler adds the CSS class "over" to an element when the mouse is over it and removes it when the mouse leaves it. It is essentially a workaround for the IE6 :hover bug (:hover CSS declarations are not respected for anything but links).

CSS maintainers are requested to use both element:hover and element.over in the same declaration, as a fallback for non-JavaScript-enabled clients (except IE6; in non-JavaScript-enabled IE6, none of these declarations will work).