Difference between revisions of "Greasemonkey Manual:Installing Scripts"

From GreaseSpot Wiki
Jump to navigationJump to search
m (Moved heading levels down here)
(Refactored this page to eliminate most runons, decreased punctuation, overdone wiki links and break up of monotony *phew* more to go to.)
Line 3: Line 3:
== About User Scripts ==
== About User Scripts ==


The purpose of [[Greasemonkey]] is to manage [[user script]]s.
The purpose of [[Greasemonkey]] is to manage user scripts.
[[User script]]s allow the ''user'' to control the way they use the web, by customizing it with scripting.
[[User script]]s allow the ''user'' to control the way they use the web, by customizing it with scripting.
[[Greasemonkey]] won't do any good without any scripts installed.
The [https://addons.mozilla.org/en-US/firefox/addon/748 Greasemonkey extension] won't do any good without any scripts installed.
So, the first thing an eager user should do is find and install (or write!) a useful script.


First, a word on finding [[user script]]s.
The first thing an eager user should do is find and install ''(or write!)'' a useful script.
They ''may'' be located anywhere, on the internet or off.
The [[Greasemonkey]] community, however, most often uses the general-purpose [[user script]]ing site created for it: http://userscripts.org/.


To install a script, navigate to it it with Firefox after installing [[Greasemonkey]].
:* A word on finding [[user script]]s. They may be located anywhere on the internet or even offline. The Greasemonkey community typically uses the general purpose user script repository site created for it at [http://userscripts.org/ http://userscripts.org].
This is most often done by clicking a link on a web page, but you may also drag-and-drop a local file into a Firefox window, or use the "File, Open..." dialog to open it.


An aside: What is a user script?
Installation of a script is most often done by clicking a link on a web page. One may also drag-and-drop a local file into the browser window, or optionally use the menu bar [http://support.mozilla.com/en-US/kb/Menu+Reference#Open_File_ File... Open File...] dialog to open it.
Any file that ends in <code>.user.js</code> is a user script.
 
If the URL of a link you click, or otherwise navigate to, ends with <code>.user.js</code>, then [[Greasemonkey]] will intercept the loading file, and present its installation dialog.
:* Any file that ends in '''<code>.user.js</code>''' is a valid Greasemonkey user script.
 
When the URL of a link is clicked or otherwise navigated to ends with <code>.user.js</code>, [[Greasemonkey]] will intercept the loading file by presenting the installation dialog.


== The Installation Dialog ==
== The Installation Dialog ==


[[Image:Install-dialog.png|thumb|150 px|Greasemonkey Installation Dialog]]
Whenever one navigates to a [[user script]] Greasemonkey will open its installation dialog instead of loading the script like a normal page.
A thumbnail of this dialog is shown to the left.
It displays the name and description of the script, if available, as well as the [[include and exclude rules]] that apply.
 
[[Image:Install-dialog.png|left|thumb|150px|GM Installation Dialog]]


Whenever you navigate to a [[user script]] as described above, Greasemonkey will open its installation dialog, instead of loading the script like a normal page.
;* The Install button
A thumbnail of this dialog is shown to the right.
This button will, of course, install the script in question.
It displays the name and description of the script, if available, as well as the [[include and exclude rules]] that apply.
Like the Firefox extension installation dialog, this button is disabled for a few seconds to avoid the same potential [http://www.squarefree.com/2004/07/01/race-conditions-in-security-dialogs security vulnerability].
 
;* The Cancel button
This button will cancel the installation of a script.


The install button will, of course, install the script in question.
;* The View Script Source button
Like the Firefox extension install dialog, the install button is disabled for a few seconds, to avoid the same potential [http://www.squarefree.com/2004/07/01/race-conditions-in-security-dialogs security vulnerability].
This button will allow viewing of the source code contained in the script.
Likewise, the cancel button will perform the obvious action.
At this point, [[Greasemonkey]] has already downloaded the [[user script]] in question to display the name and other details.


The third button is the View Script Source button, and will also perform the obvious action that the name implies.
When a user shows the script source, it displays the temporary file that Greasemonkey has already downloaded depicted in this [[:media:View-source.png|screenshot]]. This is intentionally engineered to avoid a potential security problem. An evil server could deliver one innocent script for viewing, and on the second load an evil script for installing.
At this point, [[Greasemonkey]] has already downloaded the [[user script]] in question, to display the name and other details.
This approach ensures that the script is downloaded only once.  Upon examination of the visible script source, ''this copy'' is the script that will be installed.
When you ask [[Greasemonkey]] to show you the script source, it shows you the temporary file that it has already downloaded, as in [[:media:View-source.png|this screenshot]].
This, also, is intentionally engineered to avoid a potential security problem, wherein an evil server could deliver one innocent script, for viewing, and on the second load an evil script, for installing.
This approach ensures that the script is downloaded only once, and that if you examine the source of a script, ''that'' is the script you will install.


Finally, in this view script source dialog, there is an info bar, similar to the extension installation security warning.
Finally, in this window there is an information bar at the top similar to the Firefox extension installation security warning. This bar includes another Install button much like the the prior dialog. Clicking this button will also install the script.
This bar includes an install button, which, like the button in the prior dialog, will also install the script.


== See Also ==
== See Also ==


* Shared script repository: http://userscripts.org/
* Shared script repository: [http://userscripts.org/ http://userscripts.org]

Revision as of 01:39, 8 April 2009

Book.png
Greasemonkey Manual
Using Greasemonkey
Installing Scripts
Monkey Menu
Getting Help
User Script Authoring
Editing
Environment
API

About User Scripts

The purpose of Greasemonkey is to manage user scripts. User scripts allow the user to control the way they use the web, by customizing it with scripting. The Greasemonkey extension won't do any good without any scripts installed.

The first thing an eager user should do is find and install (or write!) a useful script.

  • A word on finding user scripts. They may be located anywhere on the internet or even offline. The Greasemonkey community typically uses the general purpose user script repository site created for it at http://userscripts.org.

Installation of a script is most often done by clicking a link on a web page. One may also drag-and-drop a local file into the browser window, or optionally use the menu bar File... Open File... dialog to open it.

  • Any file that ends in .user.js is a valid Greasemonkey user script.

When the URL of a link is clicked or otherwise navigated to ends with .user.js, Greasemonkey will intercept the loading file by presenting the installation dialog.

The Installation Dialog

Whenever one navigates to a user script Greasemonkey will open its installation dialog instead of loading the script like a normal page. A thumbnail of this dialog is shown to the left. It displays the name and description of the script, if available, as well as the include and exclude rules that apply.

GM Installation Dialog
  • The Install button

This button will, of course, install the script in question. Like the Firefox extension installation dialog, this button is disabled for a few seconds to avoid the same potential security vulnerability.

  • The Cancel button

This button will cancel the installation of a script.

  • The View Script Source button

This button will allow viewing of the source code contained in the script. At this point, Greasemonkey has already downloaded the user script in question to display the name and other details.

When a user shows the script source, it displays the temporary file that Greasemonkey has already downloaded depicted in this screenshot. This is intentionally engineered to avoid a potential security problem. An evil server could deliver one innocent script for viewing, and on the second load an evil script for installing. This approach ensures that the script is downloaded only once. Upon examination of the visible script source, this copy is the script that will be installed.

Finally, in this window there is an information bar at the top similar to the Firefox extension installation security warning. This bar includes another Install button much like the the prior dialog. Clicking this button will also install the script.

See Also