Introduction to userscripts
Contents
- What are userscripts?
- Demonstration
- How to use them
- How to write your own
- The GM_* API
- How to publish your userscript
- Some gotchas
- Related technologies
- Conclusion
What are userscripts?
A userscript is a JavaScript script that your browser
will execute every time you visit a website.
It could make cosmetic changes,
or add functionality to the website.
You can customise your web experience.
Make the web the way you want it (within limits)
Demo
StackExchange Tweaks
Engineers.sg Tweaks
More demos
Wikimedia Page History in Sidebar
Wikipedia Inline Article Viewer
WikiIndent
FaviconizeGoogle
Endless Google
Related Links Pager
How can I use them?
You need to install a userscripting extension:
Greasemonkey
Tampermonkey
Violentmonkey
GrimeApe
Nope!
Chrome
side-loading
Disabled?
Bookmarklet
injection
Yikes!
Firefox only
Closed source (lots of features, recommended)
New
Installing a script
Visit one of these userscript sites:
userscripts.org userscripts-mirror.org
(ancient, pre-2011)
openuserjs.org (pleasant UI, recommended)
greasyfork.org (popular)
Or in fact anywhere: https://*/*.user.js
Tampermonkey windows
The main dropdown
Dashboard
Settings
Script editor
Creating a userscript
Live coding demo
Userscripts versus JavaScripts
Many userscripts could be simply loaded directly into the page, and will work just fine.
But there are also advanced features available, which some userscripts take advantage of...
Userscripts don't run in page scope.
For security, each script runs in a separate scope.
The metadata block
@include
@exclude
(glob or /regexp/)
@match
(New, safer globbing, can help to match TLDs)
See full docs on greasespot.net
The metadata block
(advanced)
@require
@resource
@run-at
The GM_* API
GM_addStyle()
GM_setValue()
GM_getValue()
GM_xmlhttpRequest()
Each one you use must have a @grant
See full docs on greasespot.net
Limitations
If the site changes its layout or CSS classes,
your userscript may break!
#maintenance
Cannot (should not) use frameworks
(unless the site has jQuery exposed)
Cannot interact with (modern) bundled JavaScript
(Exception: YouTube exposes some globals)
Limitations
The dev environment is not ideal.
Neither Greasemonkey nor Tampermonkey let you load userscripts directly from the filesystem.
If you like to store things in git, you will need to copy back and forth.
Gotchas
If you create a multiple site userscript that adds its own things to the DOM, your elements will inevitably inherit unwanted CSS from the page.
You can try to reset this.
The only true solution is to use an iframe. Argh.
Publishing
Publishing
You can paste your script directly onto the website to upload it. Or...
OpenUserJS can auto-import from GitHub.
For GreasyFork I simply tell it that the script's upstream is the RAW .user.js file on GitHub.
Publishing
@name
@description
@author
@namespace
(URL of your profile or your script)
@license
@version
Publishing gotchas
Must add a @license field
And it must be open source
Otherwise openuserjs.org will not accept your script.
I have been using: // @license ISC
Publishing gotchas
Must add a @grant field
If you aren't using any of the GM_ API:
// @grant none
// @grant GM_addStyle
// @grant GM_setValue
// @grant GM_getValue
Publishing gotchas
Remember to bump the version number every time you push.
Otherwise the sites and/or your user clients will not download the new version.
Related technologies
userstyles.org
Like userscripting but for CSS
(Using the "Stylish" extension, or using any userscripts extension)
Bookmarklets
Example: https://www.squarefree.com/bookmarklets/
Make Bookmarklets from Javascript URLs
FallbackGMAPI (GM_* shim/polyfill)
Example: https://joeytwiddle.github.io/code/other/gm_scripts/joeys_userscripts_and_bookmarklets_overview.html
GrimeApe (2009)
Worked on browsers without needing an extension.
Used a proxy to inject GrimeApe and userscripts into the HTML.
Monkey patching window.alert()
A story for another time...
Good for learning JavaScript?
Forces you to learn DOM fundamentals.
(But does not help you learn frameworks.)
Lots of small example scripts to play with.
(But lots of them are bad quality!)
Not starting with an empty page.
The web is your playground!
Resources
Introduction to userscripts
By Joey Clark
