Script Contents
The WM Library Script is a collection of javascript functions, class prototypes and enumerated values that you can use in your own Sidekick scripts. These tools are all packed into a single javascript file which you can include into your script just by asking for the file, like a book off the shelf, hence the name library.
How Do I Use It?
To make use of this library, all you need to do is paste this line into your script's userscript header block:
// @require http://userscripts.org/scripts/source/123889.user.js
Once inserted and uploaded to userscripts.org, this file will be prepended to your script when installed. The library and all of its contents will be available for use anywhere in your sidekick script, or by any other included scripts you choose to use. This is because all the functions and other contents are attached right to the sandbox the current script is running in.
Libraries and Sandboxes
The library is not actually written to the document, so the document cannot call or use the included functions or values. Nor can other scripts installed and activated separately access this library. This is because each activated script gets its own clean sandbox to play in. Sandboxes are kept separate from each other unless you go out of your way to expose your sandbox to the document, from which another sandbox can gain access to it.
Be careful when using included libraries, as every function or value defined before this library is loaded is overwritten if it has the same name. Likewise if you include other libraries after this one is loaded, any similarly named functions or values will overwrite those in this library.
DOM Assistance
function $
Returns a DOM element with matching id from document.documentElement or optional root element.
Syntax: $(id, optional root);
function click
Simulates the click event for the targeted DOM element.
Syntax: click(e);
function createElement
Returns a new DOM element of type a, with parameters b, and children c. Parameter a accepts a string equal to an HTML tagname. Parameter b is an object containing parameters to be set on the element after creation. Parameter c is an array of other DOM elements to append as children to the new element.
- The array passed in C can now contain NULL elements and not crash the script.
Syntax: createElement(a,optional b,optional c);
function remove
Drops the passed DOM element from its parent node.
Syntax: remove(e);
function selectNodes
Returns an xPathResult object containing DOM nodes that matches the xPath parameter. The params parameter is an object that can contain a doc, type and node variable, where doc becomes the document object from which nodes are selected; where node becomes the parent node from which to start the xPath search; where type is the resultType parameter for the contained document.evaluate function and defaults to type 6. See more at Mozilla Developers
Syntax: selectNodes(xPath, optional params);
function selectSingleNode
Returns the first single DOM element matching the xPath search string. The params object expects the same variables as selectNodes above, but type is default 9.
Syntax: selectSingleNode(xPath, optional params);
function forNodes
Performs a function on every DOM node returned by the xPath search. The params object works exactly as selectNodes above.
Syntax: forNodes(xPath, optional params, fx);
function slide
Moves an element from its current location toward a specified offset, where: e is the element to slide; (t,l,r, and b) are the top left right and bottom directional offsets for the move; s is the speed or interval (ms) at which to perform the slide; and p is the number of pixels per interval to slide. The slide is not performed on a for loop, but rather on a window timeout so as to not clog the cpu, or delay other actions, but may be affected in speed by other for loops in a script.
Syntax: slide(e,t,l,r,b,s,p);
CSS Assistance
function addGlobalStyle
Appends a style block to the document header containing css.
Syntax: addGlobalStyle(css);
string method addWord
Returns the calling string with space delimited word appended to the end.
Syntax: STRING.addWord(word);
string method removeWord
Returns the calling string with the first instance of space delimited word removed.
Syntax: STRING.removeWord(word);
string method toggleWord
Returns the calling string with space delimited word appended to the end if it did not already exist in the string, OR with space delimited word removed if it was found in the string.
Syntax: STRING.toggleWord(word);
string method containsWord
Returns true if the space delimited word is found in the calling string.
Syntax: STRING.containsWord(word);
string method replaceWord
Returns the calling string with the first instance of space delimited word replaced with space delimited word2.
Syntax: STRING.toggleWord(word, word2);
General
function getDocName
Returns the document.location.pathname of the current document object.
function timeStamp
Returns a unix time value equal to the current date/time.
function unique
Returns a guaranteed unique timeStamp() converted to base 36 (text) prefixed by an underscore.
function val
Returns the number value of object o.
Syntax: val(o);
function isArray
Returns true if object o is an array.
Syntax: isArray(o);
function isUndefined
Returns true if object o is undefined.
Syntax: isUndefined(o);
function exists
Returns true if object o is not undefined.
Syntax: exists(o);
function isString
Returns true if object o is a string object.
Syntax: isString(o);
function isGM
Returns true if GreaseMonkey is running on the page.
object log
Captures the most reasonable error and message logging device on the browser for use in creating messages. Can access: debug.print (from the WM debug code), GM_log, opera.postError, and console.log; in that order.
object Url
Provides a set of methods to decode/encode strings used as URLs.
Syntax: s2=Url.decode(s); OR s2=Url.encode(s);
String Add-ons
string method startsWith
Returns true if the calling string object starts with string s.
Syntax: STRING.startsWith(s);
string method endsWith
Returns true if the calling string object ends with string s.
Syntax: STRING.endsWith(s);
string method contains
Returns true if the calling string object contains string s.
Syntax: STRING.contains(s);
string method find
Returns true if the calling string object contains string s.
Syntax: STRING.find(s);
string method noSpaces
Returns the calling string with spaces removed.
Syntax: STRING.noSpaces();
string method upperWords
Returns the calling string with the first letter of every word in upper case.
Syntax: STRING.upperWords();
string method repeat
Returns the calling string repeated n times.
Syntax: STRING.repeat(n);
string method noLineBreaks
Returns the calling string with line breaks removed.
Syntax: STRING.noLineBreaks();
string method unQuote
Returns the calling string with surrounding quotes ("") removed.
Syntax: STRING.unQuote();
string method unBracket
Returns the calling string with surrounding brackets ([]) removed.
Syntax: STRING.unBracket();
string method trim
Returns the calling string with leading and trailing space removed.
Syntax: STRING.trim();
string method getUrlParam
Assuming the calling string is in the form "x=1&y=2&z=3", returns the value associated with requested parameter s, or an empty string if not found.
Syntax: STRING.getUrlParam(s);
string method removePrefix
Returns the calling string with leading string s removed if it exists.
Syntax: STRING.removePrefix(s);
string method removeSuffix
Returns the calling string with trailing string s removed if it exists.
Syntax: STRING.removeSuffix(s);
Array Add-ons
array method swap
Returns the calling array with index a and b swapped.
Syntax: ARRAY.swap(a, b);
array method inArray
Returns true if calling array contains value.
Syntax: ARRAY.inArray(value);
array method inArrayWhere
Returns the index of calling array where the first instance of value can be found.
Syntax: ARRAY.inArrayWhere(value);
array method last
Returns the value of the last index of the calling array.
Syntax: ARRAY.last();
array method noSpaces
Returns a copy of the calling array with all spaces removed from each index.
Syntax: ARRAY.noSpaces();
array method removeByValue
Returns the calling array with the first instance of value removed.
Syntax: ARRAY.removeByValue(value);
array method replace
Returns the calling array with the first instance of value replaced with value2.
Syntax: ARRAY.replace(value, value2);
array method remove
Returns the calling array with index i removed.
Syntax: ARRAY.remove(i);
array method pickRandom
Returns a random value from the calling array.
Syntax: ARRAY.pickRandom();
array method optimize
Returns the calling string sorted in decreasing length, which primes the array to be used as a text searching array.
Syntax: ARRAY.optimize();
Enumeration
enum string jsVoid
Returns "javascript:void(0)"
enum number second
Returns 1000 (ms)
enum number minute
Returns 20*second (ms)
enum number hour
Returns 60*minute (ms)
enum number day
Returns 24*hour (ms)
JSON Assistance
function mergeJSON
Returns a JSON object which is created by copying the contents any number of passed arguments, each being another JSON object. Objects passed later in the arguments list override those passed earlier in the arguments list.
Syntax: mergeJSON(arg1, arg2, arg2, ... argN);
Sidekick Specific
function createAccTextFromArray
Returns a JSON object containing a list of id's and values based on an array, where the id is equal to the toLowerCase noSpaces value in the array; and where the value is equal to the upperWords value in the array. ["tin"] gives "tin":"Tin". This data is suitable as a sidekick accText parameter. The function can accept an idPrefix which will cause all id's to be preceded by that value. The function can also accept a textSuffix which will cause all values to be appended with that value.
Syntax: createAccTextFromArray(arr, idPrefix, textSuffix);
function sendMessage
Changes the location.hash to the specified value, or upon failure, replaces the location with a dummy value with similar hash value. The function can accept a window handle to serve as the window parent of the location.hash to be modified, which defaults to window.top.
Syntax: sendMessage(s,hwnd);
enum integer MENU_ID_ENFORCE_NAME
Forces the menuFromData function to return an id based on each element's name rather than its calculated id. The id will come out as the name.noSpaces().toLowerCase() prepended by any idPrefix parameter given
function menuFromData
Appends one or more optionblock elements to a sidekick menu tree node menuNode based upon data found in the passed data array which contains objects in the form {id:"",name:"",event:""} where id becomes the menu item id, name becomes the visible text of that item, and event becomes the parent optionblock in which that object is contained. The function can accept a newItemList array which contains the id of any menu item to be marked as new and highlighted green. The function can also accept an idPrefix string which will prepend the id of every element created. The function can also accept a flags value which will modify the output of the function. See enums above.
Syntax: menuFromData(data, menuNode, optional newItemList, optional idPrefix, optional flags);
function accTextFromData
Returns a JSON object containing an id and value for each id and name parameter in the passed object array. The function accepts an idPrefix and textSuffix in the same way menuFromData functions above. It can also use the same flags as above.
Syntax: accTextFromData(data, optional idPrefix, optional textSuffix, optional flags);
function searchFromData
Returns an array containing every id in the passed object array prepended with the given idPrefix string.
Syntax: searchFromData(data, optional idPrefix);
function matListFromData
Returns an array containing every name in the passed object array.
Syntax: matListFromData(data);
struct sidekickAttachment
{
appID:"",
version:"",
name:"",
icon:"url",
desc:"",
tests:[{}],
menu:{},
flags:{},
alterLink:{},
thumbsSource:"" or [""],
synAppID:"" or [""],
addFilters:[{}],
accText:{},
}function Sidekick.dock
Sends an attachment string to the WM host script running on the same document. This attachment string is created by entering data through the params argument, which should contain an attachment struct shown above.
Syntax: Sidekick.dock(params);
function matchByParam
Returns an array of matching values from the passed array of objects where each returned object's specified param equals the specified value.
Syntax: matchByParam(arr,param,value);