Third-Party Libraries: Difference between revisions
m Reverted edits by 201.66.132.224 (Talk) to last revision by Arantius |
m moved general-purpose info about @require higher up the page |
||
| Line 3: | Line 3: | ||
Most general purpose libraries are not written to operate within the Greasemonkey [[sandbox]] and thus may not work properly, so tread carefully. | Most general purpose libraries are not written to operate within the Greasemonkey [[sandbox]] and thus may not work properly, so tread carefully. | ||
Note that @require works by downloading the files once, at install time, and is thus fast and efficient. | |||
== Caveats == | == Caveats == | ||
| Line 13: | Line 15: | ||
For a simple example, here is a way to load and use jQuery in your user scripts. | For a simple example, here is a way to load and use jQuery in your user scripts. | ||
<pre class='sample-good'> | <pre class='sample-good'> | ||
Revision as of 18:21, 4 May 2011
With the @require metadata imperative, one can include entire extra files into a user script. This can also be used for including entire third-party libraries like jQuery or YUI.
Most general purpose libraries are not written to operate within the Greasemonkey sandbox and thus may not work properly, so tread carefully.
Note that @require works by downloading the files once, at install time, and is thus fast and efficient.
Caveats
As of Greasemonkey 0.8.x, an @require directive added to an already installed script will not be recognized. Reinstall the script to force Greasemonkey to recognize the @require directive. You can simply drag-and-drop the script onto a Firefox browser window, or again in Firefox choose File>Open and select the user script, to reinstall it.
jQuery
For a simple example, here is a way to load and use jQuery in your user scripts.
// ==UserScript==
// @name jQuery Example
// @require http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js
// ==/UserScript==
// Append some text to the element with id someText using the jQuery library.
$("#someText").append(" more text.");
Compatibility
Some versions of jQuery will not run inside the Greasemonkey sandbox. As of this writing, 1.3.2 does work, but 1.4.1 does not. It is possible to patch 1.4 versions of jQuery to work, see jQuery Forum: Importing jQuery 1.4.1 into greasemonkey scripts generates an error.
Links and References
- http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js
- StackOverflow: How to embed additional jQuery plugins into Greasemonkey
- jQuery Forum: Importing jQuery 1.4.1 into greasemonkey scripts generates an error
jQuery UI
The jQuery UI framework version 1.5.2 should be compatible, but 1.8.4 is not.
jQuery Tools
Version 1.2.4 of jQuery Tools is reported to be at least minimally compatible.
YUI
Sometimes using the @resource imperative alongside @require can be helpful.
YUI has a nice tool to bundle your required libraries on the fly. After you receive your script source (Loading Script and CSS Directly box) use the @require key for the script and @resource for the CSS (if any).
For example:
// ==UserScript==
// @name YUI Example
// @require http://yui.yahooapis.com/combo?2.8.0r4/build/yahoo-dom-event/yahoo-dom-event.js&2.8.0r4/build/element/element-min.js&2.8.0r4/build/datasource/datasource-min.js&2.8.0r4/build/datatable/datatable-min.js
// @resource yCSS http://yui.yahooapis.com/combo?2.8.0r4/build/datatable/assets/skins/sam/datatable.css
// ==/UserScript==
// add Yahoo! css to head
var yCSS = GM_getResourceText("yCSS");
GM_addStyle(yCSS);
Without @require
For older versions of Greasemonkey (before 0.8) or for other user script managers, there is an alternative approach. This, however, does not have the download-once-at-install-time benefit, so you should not reference servers that you do not own (i.e. jquery.com or yahoo.com). Read about this technique at jQuery & Greasemonkey.
