Script Summary: Toolkit library
Version: 1.0.4
License: Creative Commons Attribution-Noncommercial 3.0 United States License
Description
GM_toolkit is a collection of useful functions for the Scriptwright to use in scripts. As a Scriptwright, you can either copy-and-paste the ones you need into your script(s), or simply include it into your script(s) using the @require mechanism.
API Reference
Array functions
- boolean in_array(mixed needle, array haystack)
- Check whether needle is a value stored in the array haystack (pendant to the PHP function with the same name)
- array array_keys(array arr)
- Return all the keys of an array
String functions
The toolkit adds a prototype to Strings: string trim() removes leading and trailing spaces from strings. Additionally:
- string escapeRegExp(string str)
- escape RegExp special chars in string to make it RegExp safe
Common functions
- void addForcedStyle(string css)
- Adds "!important" to each style rule contained in css, then adds css using GM_addStyle
- void debug(mixed msg)
- calls GM_log(msg) only if a global variable DEBUG exists and is evaluated TRUE (i.e. DEBUG=1 or DEBUG=TRUE).
- boolean isset(mixed arguments)
- Check whether given variables are set. Pass any number of arguments: It only returns TRUE if all of them are set. To prevent an varname is not defined javascript error, use isset(window.varname) instead of isset(varname) when passing a variable directly. You do not need this for e.g. isset(obj.varname) when you are sure obj is defined.
- void makeMenuToggle(string key, boolean defaultVal, string toggleOn, string toggleOff, optional string prefix)
- Generate a toggle menu entry in the GreaseMonkey user script menu. Useful for booleans, like toggling a feature on/off on user request. The parameters specify the variable to toggle (key), its default value (defaultVal) in case it was not yet set, what to display for toggleOn (toggleOn) and toggleOff (toggleOff), plus an optional prefix for toggleOn/toggleOff (prefix). See also the examples below.
DOM functions
- object appendElement(string nodeID, string tag, string id, string classname, string textval, boolean retEl)
- Append an element with the given properties (tag, id, className, text) to the node specified by its ID, optionally returning the created node
- node createElement(string type, object attributes)
- Creates a node of the given type with the specified attributes and returns it (see examples below).
- array getElementsByClassName(string className, optional string tag, optional node element)
- Retrieve all elements of the specified class, optionally restricted to a given tag and, again optionally, to a given ancestor
- array getElementsByIdRegExp(RegExp regex, optional string tag, optional node element)
- Retrieve all elements whose ID matches the specified RegExp, optionally restricted to a given tag and, again optionally, to a given ancestor
- insertAfter(node newNode, node beforeNode)
- Inserts newNode into the DOM tree before beforeNode
- node nextSibling(node startSibling)
- Finds the next sibling while skipping possible whitespaces. If a nextSibling was found, it is returned - otherwise it returns FALSE.
- boolean removeElementById(string id)
- Remove the element specified by the given ID from the current document. Returns TRUE on success
- boolean removeElementByName(string name)
- Remove the element specified by the given name from the current document. Returns TRUE on success
- boolean removeElementsByClassName(string className, optional node ancestor)
- Remove all selement specified by the given className from below of the specified node (or the current document, if not specified). Returns FALSE if none found or one failed
- boolean removeElementsByTagName(string tagName, optional node ancestor)
- Remove all selement specified by the given tagName from below of the specified node (or the current document, if not specified). Returns FALSE if none found or one failed
- boolean GMT_addScript(string script)
- Adds the code specified to the current document. Returns TRUE on success.
Translation System
With the GM_trans class, the toolkit also offers a translation system to add multi-language capabilities to your script:
- void GM_trans.setLang(string lang)
- set the desired target language to translate into. Should be a 2-char language code like 'en' (English), 'fr' (French), or 'de' (German)
- string GM_trans.lang(string term, optional string var1,.., optional string varN)
- translate a defined term. If that term is not defined for the language set by GM_trans.setLang(), it will fallback to the definition for 'en'. If this is not defined either, the term is returned as-is. If var1..varN are specified, %1..%N in the translations are replaced by the corresponding optional parameters.
- void GM_trans.setTranslations(string lang, object trans)
- Setup translations for the language defined by lang (again, the 2-char language code as described for GM_transsetLang() above). If the given language was already set up, the specified translations will be added/updated. The trans object defines the translations in the form { 'term1': 'translation for term1', 'trans2': 'translation for term2', ... }. In the translations, you may use place holders %n, which will be replaced by the additional parameters given to GM_trans.lang() (see examples below).
Usage examples
Common stuff
// Add an item to the GM user script menu to toggle AtuLogin between permanent and oneTime
makeMenuToggle("rememberMe", true, "Permanent", "OneTime", "AutoLogin");
// get all DIVs having the CSS class 'hitme' assigned
var hitMeDivs = getElementsByClassName('hitme','div');
// get all paragraphs whose ID starts with 'bummer_' followed by digits only
var bummerPs = getElementsByIdRegExp(/^bummer_\d+$/,'p');
// add link for a stylesheet
var styles = createElement('link', {rel: 'stylesheet', type: 'text/css', href: basedir + 'style.css'});
document.getElementsByTagName('head')[0].appendChild(styles);Translation system
// Setup translations
GM_trans.setTranslations('en',{
'HaveNewVerOf': '<b>A new version of <i>%1</i> is available:</b>',
'InstalledVer': 'Installed Version:',
'AvailableVer': 'Available Version:'});
GM_trans.setTranslations('de',{
'HaveNewVerOf': '<b>Eine neue Version von <i>%1</i> ist verfügbar:</b>',
'InstalledVer': 'Installierte Version:',
'AvailableVer': 'Verfügbare Version:'});
// Set target language
GM_trans.setLang('de');
// Prepare some message
var oldVer = '1.0.1';
var newVer = '1.0.2';
var msg = GM_trans.lang('HaveNewVerOf','MyScript')+'<ul><li>'+GM_trans('InstalledVer')+oldVer+'</li><li>'+GM_trans.lang('AvailableVer')+newVer+'</li></ul>';
// msg contains: '<b>Eine neue Version von <i>MyScript</i> ist verfügbar:</b><ul><li>Installierte Version:1.0.1</li><li>Verfügbare Version:1.0.2</li></ul>'History of Changes
- v1.0.4 (2009-06-22) - more functionality added
- v1.0.3 (2009-06-19) - added more DOM functions and improved some existing
- v1.0.2 (2009-06-19) - added some more DOM functions
- v1.0.1 (2009-06-18) - new functionality added
- v1.0.0 (2009-06-18) - initial release
