Learning to write userscript

Good day to all who wish to join the world of user scripts (they are userscript , userJS , userscripts ).

In this article I want to talk about what users users are, what they eat and, most importantly, how they are cooked !

Warning: assumes minimal knowledge of javascript.
In practice, it has been proven: users can write users who are not familiar with programming, but possess the assiduity and desire to learn javascript!
You can learn about javascript and how to handle it on javascript.ru .

')

What are user scripts?

Briefly: a user script is a program written in JavaScript, stored on a user's computer and connected by a browser on certain pages. A user script is a file with a .user.js extension (it is by extension that browsers understand that the file is a user script) containing metadata and javascript code directly.

When connecting to a page, userscript is executed in the same way as regular javascript scripts.
The user script has access to the DOM tree of the page in the context of which it is executed.
In modern browsers, userscript has access to localStorage and other HTML5 APIs.

User scripts are supported by all major modern browsers (and even IE7 and higher are supported somehow).

The most famous user scripts portal is userscripts.org . Here you can find a script repository, tools for managing your scripts on the portal and, what is not unimportant, a responsive forum (all in English).

A bit of general theory

The most common are the scripts under the GreaseMonkey extension for the Firefox browser .
Detailed information on GreaseMonkey and writing userscripts for GreaseMonkey can be found at http://wiki.greasespot.net .
It so happened historically that this browser was (and remains to this day) the first in which support for userscripts was performed at a high level.

Not all scripts written for GreaseMonkey can run in other browsers. The reason for the curvature is that many scripts use the GM API , a set of javascript functions specific to GreaseMonkey.

However, the easiest way to write users scripts under the Google Chrome browser .
There are several reasons for this:

1. Simple scripts do not need GM API support (library available in GreaseMonkey)
2. Google Chrome, unlike Firefox + GreaseMonkey, has a great debugger.
3. Error messages of user scripts in Firefox are terrible! If you do not have the gift of telepathy, solid knowledge of GreaseMonkey and javascript, writing a user script can turn into torment!
4. Google Chrome does not require extensions to support users scripts. The interface for removing / disabling userscripts is available out of the box.

Obvious cons of Google Chrome:

1. No access to the "native" window.
2. The @include metadata directive is not supported. The @ match directive is buggy, we can say that it is also not supported.

Features of userscript

The user scripts code can be viewed by anyone, armed with a notepad.
Basic knowledge of javascript allows you to cut off the threat of installing spyware and malicious scripts by simply analyzing the script code (you have to use the brain).

Important: If you do not trust the author of the script, the main thing is to make sure that the script does not send user data (cookies, entered text) to third-party services !

All userscripts are launched after all the main elements of the page have loaded, but the pictures have not yet been loaded. We can say that userscripts are loaded on the event DOMContentLoaded .
In any case, window.onload checks are not needed .

Each browser imposes its own restrictions on the execution of userscripts, but in general, users can do almost everything that scripts on a page can do.
Most often, userscripts are used to change the page interface or to add buns, blackjack and whores (userscripts for social networks).
There are also advanced userscripts, which are independent programs (auction and game bots, helper plugins, etc.).

Anatomy of userscripts

User Script is a text file with the extension user.js. At the beginning of the file is a block of metadata - a description of the script itself. After the block of metadata follows javascript-code, which will be executed by the browser.

Consider a test script that shows an alert with text on a specific page.

// ==UserScript== // @name myUserJS // @description     // @author Vasya Pupkin // @license MIT // @version 1.0 // @include http://userscripts.org/* // ==/UserScript== // [1]    ,   (opera, ie) (function (window, undefined) { // [2]  window var w; if (typeof unsafeWindow != undefined) { w = unsafeWindow } else { w = window; } //       javascript-. //      . //      w     window // :  jquery.min.js // (function(a,b){function ci(a) ... a.jQuery=a.$=d})(w); // [3]      //             if (w.self != w.top) { return; } // [4]     @include if (/http:\/\/userscripts.org/.test(w.location.href)) { //     alert("Userscripts    ."); } })(window); 

Important: This script is a wrapper for cross-browser user scripts. The same script, but with English comments, can be pulled off pastebin.com and used with impunity.

At the very beginning there is a block of metadata (as a comment).

 // ==UserScript== // ... // ==/UserScript== 

This block consists of user script description directives. The table below shows the main directives and their purpose.

Important: All directives, as well as the metadata block itself, may be missing.

Directive	Purpose
@ name	The name of the user script. This name will be displayed in the management interface. userscripts. If there is no directive, then the name user script will be the same as the file name.
@ description	Description of user script. This description will be displayed in the management interface. userscripts.
@ namespace	Namespace Defines the uniqueness of a set of scripts. Here you can enter the name of the domain that belongs to you. Or any other line. Consider that this is the second name of the script. Mandatory directive for Trixie!
@ author	Author's name.
@ license	The name of the license for which the user script is distributed.
@ version	Version number of user script. Unfortunately, there is no auto-update mechanism in any browser, therefore, the version number is just the numbers that are displayed on the interface.
@include	Directive describing the url of the page, on which you need to run userscript. Supports wildcard * (applicable in GreaseMoneky, Opera, IE). For each individual url, you need to use a separate @ include directive.
@ exclude	Directive describing the url of the page, where you do not need to run userscript. Supports wildcard * (applicable to GreaseMonkey, Opera, IE). For each separate url you need to use a separate @ exclude directive.
@ match	Same as @include, but with more stringent restrictions. (applicable to GreaseMonkey older than 0.9.8, Google Chrome). You can learn more about restrictions and directive format. read on this page . For each separate url you need to use a separate @ match directive.

Important: As practice has shown, you should not rely on the @ match directive in userscripts.
Google Chrome periodically refuses to consider @ match
and launches userscripts on all pages.
To prevent this situation in userscripts,
that will run not only in Firefox,
You need to add a code to check the address of the page (see link [4] in the code of userscript) .

Important: In the absence of @ include or @ match directives, userscripts will run on all pages .

A number of tricks are used in our user script:

1. In order for userscripts to have the same behavior and not to pollute the global scope, the code turns into a closure (see [1] in the script code) .
2. To properly connect libraries inside userscript and to bypass some tricky features of GreaseMonkey, it is necessary to “normalize” the link to the window's global scope (see [2] in the script code) .
3. In order for the user script not to run several times on the same page, it is necessary to stop the work when the user script is started in frames (see [3] in the script code) .
4. In order for the user script to run only on the pages we need, it is necessary to explicitly check the url of the page (see [4] in the script code) .
5. Thanks to this structure, user scripts can be relatively easily converted to a bookmarklet .

Result

Our user script is ready to use!
No, seriously, you can copy the user script code to a file, name it my.user.js, and drop the resulting file into the browser (use Chrome or Firefox with GreaseMonkey installed).

Of course, our user script does not have serious functions, the code looks scary and unattractive (for the uninitiated person). But in the end we got a template for cross-browser users scripts .
This means that userscript can be run in almost any modern browser!
And that's great!

The question remains: how to “distribute” our script to users (after all, we wrote the script not only for ourselves)?
Options:

• Register on the userscripts.org portal and upload the scripts there.
  
• Create a repository on code.google.com or github.com .
  
• Create your own simple service / website / page.
  Important: If you want GreaseMonkey users to automatically open the user scripts installation dialog, give the file straight from the file system (the file url should end in .user.js). Otherwise, the user will see the source code of the script and the panel with the “install” button. This button does not work!
  

The recipe for non-programmers (~ 70% of scripts are written using similar methods):

1. We think of what our userscript will do (repaint links, for example)
2. We take a template from the article
3. Save to my.user.js file
4. Delete the line with alert (...) .
5. Go to the forum (userscripts.org or any javascript forum).
6. We spam, flood and reach people with questions like “repaint links”, “give code”, etc.
7. We change the metadata and check the url of the page to the ones we need.
8. We insert the code received on the forum into userscript.
9. Save the file.
10. ...
11. PROFIT !! 1!

Useful links:

• Userscripts.org
  
• wiki.greasespot.net
  
• Userscript -> Firefox Extension Compiler
  
• Writing userscripts
  
• @ Match directive rules
  

---

List of articles:

1. » Learning to write userscript
2. Userscripts. Deepen.
3. Userscripts. We pack user scripts for Chrome
4. Usersctripts. Cross Domain Queries

PS I would like to see the Userscripts blog on Habré. For no one GreaseMonkey one.