Metadata Block: Difference between revisions

From GreaseSpot Wiki
Jump to navigationJump to search
m (→‎@copyright: Added strong suggestion for using this key... sf)
 
(101 intermediate revisions by 32 users not shown)
Line 1: Line 1:
__NOTOC__
{{Greasemonkey Manual TOC}}
== Description ==
== Description ==
The '''metadata block''' is a section of a [[user script]] that does not execute any code, but describes the script. It contains the script name, namespace, description, and [[include and exclude rules]].
The metadata block appears in JavaScript comments and may appear anywhere in the top level Greasemonkey code scope of the script, but is usually near the top of the file. It begins with the line
{{Core samp |1=<pre style="border: none; margin: inherit;">// ==UserScript==</pre>}}
and ends with
{{Core samp |1=<pre style="border: none; margin: inherit;">// ==/UserScript==</pre>}}
Everything between those lines is in the format


{{Core samp |1=<pre style="border: none; margin: inherit;">// @key    value</pre>}}
The '''metadata block''' is a section of a [[user script]] that describes the script.
It usually contains the script name, namespace, description, and [[include and exclude rules]].
The metadata block appears in JavaScript line comments and may appear anywhere in the top level Greasemonkey code scope of the script, but is usually near the top of the file.


If the metadata block includes a key that Greasemonkey does not understand, it will simply be ignored. Key names are typically constructed from alphanumeric characters. User script hosting sites may utilize a XML styled name prefix to identify the origin of the key. An example of this is ''prefix:key''.
If the metadata block includes a key that Greasemonkey does not understand, it will be ignored.
 
[[#Other_Keys|Other Keys]] | [[#Examples|Examples]] | [[#Caveats|Caveats]] | [[#See_Also|See Also]] | [[#Notes|Notes]]


== Syntax ==
== Syntax ==
'''// ==UserScript=='''


'''// == @'''''key'' '''value'''
The metadata block must follow the format:


'''// ==/UserScript=='''
<pre class='sample'>
// ==UserScript==
// @key value
// ==/UserScript==
</pre>


:Value: Object
It must use line comments (<code>//</code>) like above, not block comments (<code>/* */</code>).
:Compatibility: [[Version_history#0.2.5|Greasemonkey 0.2.5+]]
Note that the opening <code>// ==UserScript==</code> and closing <code>// ==/UserScript==</code> must be precisely at the beginning of its line.
Some keys may have multiple values.
In all cases the key and value(s) are separated by whitespace.
The closing <code>==/UserScript==</code> line should be at the end of the metadata block (not at the end of the script).


:{| cellpadding="5" style="border-style:solid; background:#FFFFE0;"
=== @description ===
|+ Keys
! colspan="4" style="background:#CC9900;"|'''Properties'''
|-
| <code><span style="background:#FFFFE0;">[[#.40name |@name]]</span></code> || <code><span style="background:#FFFFE0;">[[#.40include |@include]]</span></code> || <code><span style="background:#FFFFE0;">[[#.40resource |@resource]]</span></code> || <code><span style="background:#FFFFE0;">[[#.40unwrap |@unwrap]]</span></code>
|-
|<code><span style="background:#FFFFE0;">[[#.40namespace |@namespace]]</span></code> || <code><span style="background:#FFFFE0;">[[#.40exclude |@exclude]]</span></code> || <code><span style="background:#FFFFE0;">[[#.40require |@require]]</span></code>
|-
|<code><span style="background:#FFFFE0;">[[#.40description |@description]]</span></code>
|}
:* All properties are optional


[[#top|top]]
Example:
=== Properties ===
<pre class='sample'>// @description This script even does the laundry!</pre>
----


==== @name ====
Just a brief summary of what the script does, presented to the user as the script is installed, and in the manage dialog.


:Value: String
''As of Greasemonkey 2.2'': can be localized for multiple languages; see the [[#@name]] documentation for more detail.
:Usage: <code>// @'''name'''        My Script</code>
::* The name of the script. This appears in the [[Greasemonkey_Manual:Manage_Dialog|script manager]] and [[Greasemonkey_Manual:Monkey_Menu |monkey menu]], and is also used to determine whether to overwrite an old version of a script or to install it separately. If no name is provided, it will be inferred from the file name.
::* If the file name or the @name key exceeds 24 characters the file name will be truncated during installation not including spaces and other special characters. As of [[Version_history#0.8.20080609.0|Greasemonkey 0.8.0]], new scripts will be stored under their own folder name in the [[Scripts directory|gm_scripts folder]] and also include spaces to underscores conversion and other special characters. The [[Scripts directory|scripts directory]] is also backed up into a folder called gm_scripts_08bak when migrating to version [[Version_history#0.8.20080609.0|0.8.0]].
[[#top|top]] | [[#Syntax|back]]


==== @namespace ====
<!-- 4.x does not use this
=== @downloadURL ===


:Value: String
The URL to download this script from, when installing updates.
:Usage: <code>// @'''namespace'''    <nowiki>http://www.example.com/gmscripts</nowiki></code>
::* The namespace, along with the name, is used to determine whether to overwrite an old version of a script or to install it separately. A script author will usually put all of their scripts under one common namespace, and then assign each script a unique name. If two scripts have the same name, but a different namespace, they can co-exist. However, two scripts of the same name in the same namespace are assumed to be replacements for one another and one will be overwritten by the other.
::* While the namespace is '''non-semantic''', it should be your prefered internet homepage [http://labs.apache.org/webarch/uri/rfc/rfc3986.html URI] according to the [http://www.w3.org/Addressing W3C standards specification]. If no namespace is provided, it is assumed to be the domain from which the script is installed. Since a script can live on various servers or on a local file system, authors may choose to omit this key when publishing on [http://userscript.org userscripts.org] and let Greasemonkey supply one automatically. If you are creating one locally, authors may choose the [http://labs.apache.org/webarch/uri/rfc/rfc3986.html URI specification] standard of <code>http://localhost</code> for the value as being an anonymous local script.


::* Common String Values
<pre class='sample'>// @downloadURL https://www.example.com/myscript.user.js</pre>
:::* '''Greasemonkey addon supplied'''
::::Usage: Omitted [[#.40namespace |@namespace]] in source userscript file
Greasemonkey's default settings require this value to be secure (<tt><nowiki>https://...</nowiki></tt>) for updates to be applied.
::::Examples:
If it is not specified, the URL the script was originally installed from will be used.
::::{| cellpadding="5" style="border-style:solid; background:#FFFFE0;"
|+ ''Automatic host to namespace mapping''
!style="background:#CC9900;"|'''Script Host''' || style="background:#CC9900;"|'''Chosen Namespace'''
|-
|<code><span style="background:#FFFFE0;">http:&#47;/userscripts.org/scripts/source/''scriptid''.user.js</span></code> || <code><span style="background:#FFFFE0;">userscripts.org</span></code>
|-
|<code><span style="background:#FFFFE0;">http:&#47;/example.org/scripts/filename.user.js</span></code> || <code><span style="background:#FFFFE0;">example.org</span></code>
|-
|<code><span style="background:#FFFFE0;">http:&#47;/localhost/scripts/filename.user.js</span></code> || <code><span style="background:#FFFFE0;">localhost</span></code>
|-
|}


:::* '''tag URI'''
It is '''unusual''' to specify this value.
::::Usage: "tag:" taggingEntity ":" specific [ "#" fragment ]
Most scripts should omit it.
::::* If a date/time stamp field is omitted, it is assumed to be first item ''(e.g. 2005 becomes 2005-01-01T00:00:00Z)
::::Examples:
:::::<code>'''@namespace''' <nowiki>tag:johndoe@example.com,2009:johndoe</nowiki></code>
:::::<code>'''@namespace''' <nowiki>tag:johndoe@example.net,2010-05:johndoe/pathto</nowiki></code>
:::::<code>'''@namespace''' tag:userscripts.org,2005-06-19T23:33:49Z:JohnDoe:DescriptionWithNoSpaces:etc:etc:etc</code>
::::See Also: http://www.faqs.org/rfcs/rfc4151.html


:::* '''userscripts.org''' ''(User contributed)''
-->
::::Usage: id [[ " + " id ], [ " + " id ], ...]
::::* An id consists of either a full name, userid or vanityid.
::::* Multiple contributor attribution may be notated here by appending the plus symbol and the next id.
::::Examples:
:::::<code>'''@namespace''' anotherjesse</code>
:::::<code>'''@namespace''' ''userid'' + ''vanityid'' + ''Firstname'' ''Lastname''</code>


:::* '''XML URI'''
=== @exclude ===
::::Usage: scheme "://" domain [ "." tld ][ "/" pathto  ]
::::Examples:
:::::<code>'''@namespace''' http:&#47;/localhost</code>
:::::<code>'''@namespace''' http:&#47;/localhost.localdomain</code>
:::::<code>'''@namespace''' http:&#47;/userscripts.org/users/''userid''</code>
:::::<code>'''@namespace''' http:&#47;/example.org/pathto/script</code>
::::See Also: https://developer.mozilla.org/en/Namespaces


::* The [https://addons.mozilla.org/firefox/addon/722 NoScript] add-on currently utilizes namespace filtering, and may sanitize user scripts that are not listed in the XSS white-list section of the options dialog.
Examples: see [[#@include]]


[[#top|top]] | [[#Syntax|back]]
See [[Include and exclude rules]].
There can be any number of @exclude rules in a script.


==== @description ====
=== @grant ===
:Value: String
:Usage: <code>// @'''description'''    This script even does the laundry!</code>
::* Just a brief summary of what the script does, to present to the user who is installing it.


[[#top|top]] | [[#Syntax|back]]
See dedicated [[@grant]] page.


==== @include ====
=== @icon ===
:Value: String
:Usage: <code>// @'''include'''    <nowiki>http://www.example.com/*</nowiki></code>
::* Refer to ''[[Include and exclude rules]]''. There can be any number of @include rules in a script.
::* You cannot edit a live scripts @include and have it take effect.
[[#top|top]] | [[#Syntax|back]]


==== @exclude ====
Example:
:Value: String
<pre class='sample'>// @icon http://www.example.org/icon.png</pre>
:Usage: <code>// @'''exclude'''    <nowiki>http://www.example.com/foo/*</nowiki></code>
::* Refer to ''[[Include and exclude rules]]''. There can be any number of @exclude rules in a script.
::* You cannot edit a live scripts @exclude and have it take effect.
[[#top|top]] | [[#Syntax|back]]


==== @resource ====
The icon is, as of Greasemonkey 0.9.0, displayed in the script management interface.
:Value: String
Almost any image will work, but a 32x32 pixel size is best.
:Compatibility: [[Version_history#0.8.20080609.0|Greasemonkey 0.8.0+]]
This value ''may'' be specified relative to the URL the script itself is downloaded from.
:Usage: <code>// @'''resource'''    resourceName <nowiki>http://www.example.com/resource.png</nowiki></code>
::* There can be any number of @resource keys in a script.
::* While the resourceName is non-semantic, it is suggested that it should be compatible with JavaScript variable naming conventions and XML/CSS naming conventions to help keep things consistent.
::* Each resourceName must have a unique name.
::* This metadata block key property may be used to cache a local or remote resource into the current user script at installation time. Greasemonkey will not redownload these external dependencies every time the script is executed on a web page specified by [[#.40include |@include]].
::* Resources may include the scheme of file, http, https or ftp. If no scheme is provided, it is assumed to be the domain from which the script is installed including the full path.  They may be accessed through [[GM_getResourceText]] and [[GM_getResourceURL]] respectively.


[[#top|top]] | [[#Syntax|back]]
=== @include ===


==== @require ====
Examples:
<pre class='sample'>// @include http://www.example.com/*
// @include http://*
// @include *</pre>


:Value: String
See [[Include and exclude rules]].
:Compatibility: [[Version_history#0.8.20080609.0|Greasemonkey 0.8.0+]]
There can be any number of @include rules in a script.
:Usage: <code>// @'''require''' foo.js</code>
::* There can be any number of @require keys in a script.
::* This metadata block key property may be used to cache a local or remote script into the current user script at installation time. Greasemonkey will not redownload these external dependencies every time the script is executed on a web page specified by [[#.40include |@include]].
::* As with all metadata values that are stored in [[Config.xml |config.xml]], these are read at install time only.  Adding or removing @require entries will have no effect. The script must be reinstalled or the [[Config.xml |config.xml]] will need to be modified manually.
::* Script sources may include the scheme of file, http, https or ftp. If no scheme is provided, it is assumed to be the domain from which the script is installed including the full path.
:::* Some common JavaScript libraries may be obtained from the [http://code.google.com/apis/ajaxlibs/documentation/ Google AJAX Libraries API] or [http://developer.yahoo.com/yui/articles/hosting/ YUI]).


[[#top|top]] | [[#Syntax|back]]
=== @match ===


==== @unwrap ====
Examples:
<pre class='sample'>// @match https://www.example.com/*
// @match http://*.example.com/*</pre>


:Value: undefined
The <code>@match</code> metadata imperative is very similar to <code>@include</code>, however it is safer.
:Compatibility: [[Version_history#0.8.20090123.1|Greasemonkey 0.8.1+]]
It sets more strict rules on what the <code>*</code> character means.
:Usage: <code>// @'''unwrap'''</code>
::* Also referenced as a metadata imperative.  This metadata block key property must not include any value after it or it may be ignored altogether.
::* Removes the anonymous function wrapper around scripts.
:::* '''This key is strongly recommended to only be used for [[Global_object#Debugging|debugging]] purposes.'''
:::* By default most versions of Greasemonkey automatically encapsulate each script in an anonymous function wrapper. In other words:
::::* <code>(function(){ /* script source */ })();</code>
:::* Encapsulation of the script prevents name collisions of variables and objects used by [[XPCNativeWrapper]] and other objects typically inserted by the browser. If an unwrapped user script uses a reserved object name incorrectly, it will throw an error and script execution will most likely fail. One of the simplest ways to confirm this is to include '''@unwrap''' and have a script with a simple variable declaration of <code>var sidebar = "foo";</code>.  This will return a script error of Illegal value, and script execution will cease. See also [http://greasemonkey.devjavu.com/ticket/108 #108].


[[#top|top]] | [[#Syntax|back]]
For details, see the documentation on [https://developer.chrome.com/extensions/match_patterns Match Patterns] for Google Chrome.
Chrome implemented <code>@match</code> first, and Greasemonkey has been designed to be compatible.


== Other Keys ==
=== @name ===


Some [[user script]]s contain other special keys in the metadata block.
Example:
<pre class='sample'>// @name Example Script</pre>


'''These unsupported metadata keys serve no technical purpose and are ignored by the [[Greasemonkey|Greasemonkey extension]], but can be read by human beings or utilized by other code.'''
The name of the script.
This appears in the [[Greasemonkey_Manual:Monkey_Menu|monkey menu]], and is also the unique identifier of a script (within a [[#@namespace|namespace]]).
If no name is provided, it will be derived from the file name.


:{| cellpadding="5" style="border-style:solid; background-color:#FFFFFF;"
''As of Greasemonkey 2.2'': can be localized for multiple languages, for example:
|+ Keys
! colspan="4" style="color: #FFFFFF; background-color:#000000;"|'''Properties'''
|-
| colspan="3" style="text-align: center; color: #FFFFFF; background-color:#FF8800;"|'''userscripts.org'''
| colspan="1" style="text-align: center; color: #FFFFFF; background-color:#FF8800;"|'''user contributed'''
|-
|<code><span style="background-color:#FFFFFF;">[[#.40copyright |@copyright]]</span></code> || <code><span style="background-color:#FFFFFF;">[[#.40uso:script |@uso:script]]</span></code>        || <code><span style="background-color:#FFFFFF;">[[#.40uso:rating |@uso:rating]]</span></code>          || <code><span style="background-color:#FFFFFF;">[[#.40attribution |@attribution]]</span></code>
|-
|<code><span style="background-color:#FFFFFF;">[[#.40license |@license]]</span></code>    || <code><span style="background-color:#FFFFFF;">[[#.40uso:version |@uso:version]]</span></code>      || <code><span style="background-color:#FFFFFF;">[[#.40uso:installs |@uso:installs]]</span></code>      || <code><span style="background-color:#FFFFFF;">[[#.40contributor |@contributor]]</span></code>
|-
|<code><span style="background-color:#FFFFFF;">[[#.40version |@version]]</span></code>    || <code><span style="background-color:#FFFFFF;">[[#.40uso:timestamp |@uso:timestamp]]</span></code>  || <code><span style="background-color:#FFFFFF;">[[#.40uso:reviews |@uso:reviews]]</span></code>        || <code><span style="background-color:#FFFFFF;">[[#.40author |@author]]</span></code>
|-
|                                                                                          || <code><span style="background-color:#FFFFFF;">[[#.40uso:hash |@uso:hash]]</span></code>            || <code><span style="background-color:#FFFFFF;">[[#.40uso:discussions |@uso:discussions]]</span></code> || <code><span style="background-color:#FFFFFF;">[[#.40homepage |@homepage]]</span></code>     
|-
|                                                                                          ||                                                                                                    || <code><span style="background-color:#FFFFFF;">[[#.40uso:fans |@uso:fans]]</span></code>                                                                                                     
|}
:* This is by no means an exhaustive list, nor is it meant to be.
[[#top|top]]


===== @copyright =====
<pre class='sample'>
// @name      Example Script
// @name:cs    Uživatelské skripty
// @name:es-MX Ejemplo Script
// @name:ru    Пользовательские скрипты
</pre>


:Value: String
Add a colon and the locale code, which is the [http://www.w3.org/WAI/ER/IG/ert/iso639.htm ISO 639] language code and optionally a hyphen and [http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm ISO 3166] country code, when disambiguation is necessary.
:Usage: <code>// @'''copyright''' Year, Author (Author Homepage)</code>
When the user's browser is configured with the matching primary language, that value will be displayed instead.
::* It is '''strongly recommended''' to use this key to identify a scripts copyright author and homepage. Usually a script repository such as [http://userscripts.org userscripts.org] will be able to identify and track copyright via the ''userid'', versions and diffs but it is still suggested to include this for copyright verification purposes.
::* Example:
::: <code>// @copyright 2009+, John Doe (<nowiki>http://www.example.com/projecthomepage</nowiki>)</code>


[[#top|top]] | [[#Other Keys|back]]
=== @namespace ===


===== @license =====
Example:
===== @licence =====


:Value: String
<pre class='sample'>// @namespace http://www.example.com/gmscripts</pre>
:Usage: <code>// @'''license''' License Type; License Homepage</code>
::* There can be any number of @license keys in a script for multiple licensing however userscripts.org will only display the first occurrence as the primary.
::* It is '''strongly recommeded''' to use this key to describe who can use, copy, modify and distribute a script.
::* A list of common open-source license can be found at [http://www.opensource.org/licenses opensource.org].
::* In order to make an assertion on control of distribution of a script, it is important to keep in mind the following definitions:<dl><dt>Code ''(or module)'' licenses<dd>These are typically for all code including binaries and scripts.<dt>Content licenses<dd>These are typically documents such as guides, wikis and images. The <code>data:</code> URI is considered as an image.</dl>
::* Example: ''(GPL is a Code License and CC is a Content License)''
::: <code>// @license GPL version 3 or any later version; <nowiki>http://www.gnu.org/copyleft/gpl.html</nowiki></code>
::: <code>// @license (CC) Attribution Non-Commercial Share Alike; <nowiki>http://creativecommons.org/licenses/by-nc-sa/3.0/</nowiki></code>


[[#top|top]] | [[#Other Keys|back]]
The combination of namespace and name is the unique identifier for a Greasemonkey script.
If a script is being installed, and a script with that same name '''and''' namespace already exists, it will be replaced by the new script.
Otherwise, the new script is added to the set of installed scripts.
A script author will usually put all of their scripts under one common namespace, and then assign each script a unique name.


===== @version =====
While the namespace is non-semantic, a URL is often used.
Some authors use the common home page for the collection of scripts they have written.
But remember, the namespace can be any unique value.


:Value: String or Number
=== @noframes ===
:Usage: <code>// @'''version''' 0.0.1</code>
::* Typically this is in the industry standard form of major dot minor dot build
::* This key can also be used in some scripts that are self-updating. Usually, this will include a time stamp indicating the number of milliseconds that have expired since 1 January 1970 00:00:00 UCT, which can be generated by calling <code>new Date().getTime()</code>.


[[#top|top]] | [[#Other Keys|back]]
Example:
<pre class='sample'>// @noframes</pre>


===== @uso:script =====
When present, this imperative restricts the execution of the script.
The script will run only in the top-level document, never in nested frames.
It takes no arguments, it is either present or not present.
This is off (scripts run in frames) by default.


:Value: String or Number
=== @require ===
:Usage: <code>// @'''uso:script''' ''scriptid'' </code>
::* userscripts.org will dynamically create an ascending numerical value based on the next available script id in the repository.
:: '''NOTE:''' It is not necessary to define this key in a script as the meta.js routine will automatically return this key/value pairing via a http/https request to <nowiki>http://userscripts.org/scripts/source/</nowiki>''scriptid''.meta.js


[[#top|top]] | [[#Other Keys|back]]
Example:
<pre class='sample'>// @require http://www.example.com/example.js</pre>


===== @uso:version =====
There can be any number of @require keys in a script.
Each @require is downloaded once, when the script is installed, and stored on the user's hard drive alongside the script.
The URL specified may be relative to the URL the script is being installed from.


:Value: String or Number
Note that since [[Version_history#0.9.0|Greasemonkey 0.9.0]], if Greasemonkey detects that the <code>@require</code> value(s) have been altered, these new values will be used (thus each <code>@require</code> shall be re-downloaded).
:Usage: <code>// @'''uso:version''' ''versionid'' </code>
::* userscripts.org will dynamically create an ascending numerical value based on the next available version id in the repository.
:: '''NOTE:''' It is not necessary to define this key in a script as the meta.js routine will automatically return this key/value pairing via a http/https request to <nowiki>http://userscripts.org/scripts/source/</nowiki>''scriptid''.meta.js


[[#top|top]] | [[#Other Keys|back]]
See also:


===== @uso:timestamp =====
* [[:Category:@require Library]]
:Value: String
* [[#Adding Resources]]
:Usage: <code>// @'''uso:timestamp''' Wed, 17 Jun 2009 22:50:26 +0000 </code>
::* userscripts.org will return the last modified date of the current user script.
:: '''NOTE:''' It is not necessary to define this key in a script as the meta.js routine will automatically return this key/value pairing via a http/https request to <nowiki>http://userscripts.org/scripts/source/</nowiki>''scriptid''.meta.js


[[#top|top]] | [[#Other Keys|back]]
=== @resource ===


===== @uso:hash =====
Example:
:Value: String
<pre class='sample'>// @resource resourceName http://www.example.com/example.png</pre>
:Usage: <code>// @'''uso:hash''' 30d54f8ba24c0c6ec5710866e9b0839b2066a815 </code>
::* userscripts.org will return the sha1(60)sum for the current user script.
:: '''NOTE:''' It is not necessary to define this key in a script as the meta.js routine will automatically return this key/value pairing via a http/https request to <nowiki>http://userscripts.org/scripts/source/</nowiki>''scriptid''.meta.js


[[#top|top]] | [[#Other Keys|back]]
There can be any number of @resource keys in a script.


===== @uso:rating =====
While the resourceName is non-semantic, it should comply with JavaScript identifier restrictions.
:Value: String or Number
Each @resource must have a unique name.
:Usage: <code>// @'''uso:rating''' 4.00 </code>
::* userscripts.org will return the rating of the current user script. Currently this is an unweighted average of all the peer reviews accurate to two decimal places.
:: '''NOTE:''' It is not necessary to define this key in a script as the meta.js routine will automatically return this key/value pairing via a http/https request to <nowiki>http://userscripts.org/scripts/source/</nowiki>''scriptid''.meta.js


[[#top|top]] | [[#Other Keys|back]]
Each @resource is downloaded once, when the script is installed, and stored on the user's hard drive alongside the script.
The URL specified may be relative to the URL the script is being installed from.


===== @uso:installs =====
These named resources may be accessed through [[GM_getResourceURL|GM.getResourceURL]].
===== @uso:reviews =====
===== @uso:discussions =====
===== @uso:fans =====


:Value: String or Number
See also:
:Usage:
::: <code>// @'''uso:installs''' count </code>
::: <code>// @'''uso:reviews''' count </code>
::: <code>// @'''uso:discussions''' count </code>
::: <code>// @'''uso:fans''' count </code>
::* userscripts.org will return the current count for each respective type.
:: '''NOTE:''' It is not necessary to define these keys in a script as the meta.js routine will automatically return the key/value pairing via a http/https request to <nowiki>http://userscripts.org/scripts/source/</nowiki>''scriptid''.meta.js


[[#top|top]] | [[#Other Keys|back]]
* [[#Adding Resources]]


===== @attribution =====
=== @run-at ===


:Value: String
:Compatibility: Limited support in [[Version_history#4.0_2|Greasemonkey 4.0]].
:Usage: <code>// @'''attribution''' Attribution Name (Attribution Script Homepage)</code>
::* There can be any number of @attribution keys in a script for multiple attribution support.
::* Attribution may only be used if source [[#.40license|@license]] type is compatible.
::* Example:
::: <code>// @attribution Jane Doe (<nowiki>http://www.example.com/janedoe/scriptid</nowiki>)</code>
::: <code>// @attribution Jack Doe (<nowiki>http://www.example.com/jackdoe/scriptid</nowiki>)</code>
::: <code>// @attribution Jill Doe (<nowiki>http://www.example.com/jilldoe/scriptid</nowiki>)</code>


[[#top|top]] | [[#Other Keys|back]]
Example:
<pre class='sample'>// @run-at document-end</pre>


===== @author =====
This key supports three values:


:Value: String
; document-end
:Usage: <code>// @'''author''' John Doe</code>
: The default if no value is provided. The script will run after the main page is loaded, but before other resources (images, style sheets, etc.) have loaded.  The only guaranteed working value in Greasemonkey 4.x.
::* ''(Suggest not using this key in favor of [[#.40copyright |@copyright]])''
; document-start
: The script will run before any document begins loading, thus before any scripts run or images load.
; document-idle
: The script will run after the page and all resources (images, style sheets, etc.) are loaded and page scripts have run.


[[#top|top]] | [[#Other Keys|back]]
To detect if you are running at <code>document-start</code> time, check the value of <code>[https://developer.mozilla.org/en/DOM/document.readyState document.readyState]</code>.
For example:


===== @contributor =====
<pre class="sample">
if ('loading' == document.readyState) {
  alert("This script is running at document-start time.");
} else {
  alert("This script is running with document.readyState: " + document.readyState);
}
</pre>


:Value: String
Scripts running at <code>document-end</code> will have the value <code>interactive</code> here.
:Usage: <code>// @'''contributor''' Contributor Name (Contributor Homepage)</code>
::* There can be any number of @contributor keys in a script for multiple contributor support.
::* Example:
::: <code>// @contributor Jane Doe (<nowiki>http://www.example.com/janedoe</nowiki>)</code>
::: <code>// @contributor Jack Doe (<nowiki>http://www.example.com/jackdoe</nowiki>)</code>
::: <code>// @contributor Jill Doe (<nowiki>http://www.example.com/jilldoe</nowiki>)</code>


[[#top|top]] | [[#Other Keys|back]]
=== @version ===


===== @homepage =====
Example:
<pre class='sample'>// @version 1</pre>


:Value: URI
The version is used by the auto-update feature.
:Usage: <code>// @'''homepage''' <nowiki>http://www.example.com/myhomepage</nowiki></code>
When `@version` is set and if the auto-update feature is enabled, Greasemonkey will check periodically for new versions of the script by downloading it again (from same location where it was originally installed).
::* ''(Suggest not using this key in favor of [[#.40copyright |@copyright]])''
If the new downloaded `@version` is higher, the update will be installed.
 
Greasemonkey uses the [https://github.com/omichelsen/compare-versions#compare-versions compare-versions] library to determine when a version is higher/greater/newer.
[[#top|top]] | [[#Other Keys|back]]


== Examples ==
== Examples ==
[[#Core |Core]] | [[#Knowing Your Own Metadata |Knowing Your Own Metadata]] | [[#jQuery require |jQuery require]]
=== Core ===
{{Core samp |1=<pre style="border: none; margin: inherit;">
// ==UserScript==
// @name          My Script
// @namespace    <nowiki>http://www.example.com/gmscripts</nowiki>
// @description  Scripting is fun
// @include      <nowiki>http://www.example.com/*</nowiki>
// @include      <nowiki>http://www.example.org/*</nowiki>
// @exclude      <nowiki>http://www.example.org/foo</nowiki>
// @require      foo.js
// @resource      resourceName1 resource1.png
// @resource      resourceName2 <nowiki>http://www.example.com/resource2.png</nowiki>
// ==/UserScript==
</pre>}}
[[#top|top]] | [[#Examples|back]]
=== Knowing Your Own Metadata ===
Routine utilizing E4X (ECMAScript for XML) XMLList to retrieve a copy of the initial file metadata block entries and https metadata block entries.
:* If a user changes the include/exclude rules via Manage User Scripts, they will not be reflected in this copy.
:* If a user omits [[#.40namespace |@namespace]], and allows Greasemonkey to supply one, it will not be reflected in this copy.
:* Remember to change the [[#.40uso:script |@uso:script]] key to match the ''scriptid'' hosted on userscripts.org
{{Good samp |1=<pre style="border: none; margin: inherit;">
function parseHeaders(metadataBlock) {
  var headers = {};
  var line, name, prefix, header, key, value;
    var lines = metadataBlock.split(/\n/).filter(/\/\/ @/);
    for each (line in lines) {
      [, name, value] = line.match(/\/\/ @(\S+)\s*(.*)/);
      switch (name) {
        case "licence":
          name = "license";
          break;
      }
      [key, prefix] = name.split(/:/).reverse();
      if (prefix) {
        if (!headers[prefix])
          headers[prefix] = new Object;
        header = headers[prefix];
      } else
        header = headers;


      if (header[key] && !(header[key] instanceof Array))
<pre class='sample'>
        header[key] = new Array(header[key]);
 
      if (header[key] instanceof Array)
        header[key].push(value);
      else
        header[key] = value;
    }
 
    headers["licence"] = headers["license"];
 
  return headers;
}
 
var fileMETA = parseHeaders(<><![CDATA[
// ==UserScript==
// ==UserScript==
// @name          My Script
// @name          My Script
// @namespace    http://www.example.com/gmscripts
// @namespace    http://www.example.com/gmscripts
// @description  Scripting is fun
// @description  Scripting is fun
// @copyright    2009+, John Doe (http://www.example.com/~jdoe)
// @license      GPL version 3 or any later version; http://www.gnu.org/copyleft/gpl.html
// @version      0.0.1
// @include      http://www.example.com/*
// @include      http://www.example.com/*
// @include      http://www.example.org/*
// @include      http://www.example.org/*
Line 405: Line 222:
// @resource      resourceName1 resource1.png
// @resource      resourceName1 resource1.png
// @resource      resourceName2 http://www.example.com/resource2.png
// @resource      resourceName2 http://www.example.com/resource2.png
// @uso:script    scriptid
// @version      1.0
// @icon          http://www.example.net/icon.png
// ==/UserScript==
// ==/UserScript==
]]></>.toString());
</pre>
 
GM_xmlhttpRequest({
  method:"GET",
  url:"https://userscripts.org/scripts/source/" + fileMETA["uso"]["script"] + ".meta.js",
  headers:{
    "Accept":"text/javascript; charset=UTF-8"
  },
  overrideMimeType:"application/javascript; charset=UTF-8",
  onload:function(response) {
    var httpsMETA = parseHeaders(response.responseText);
 
    GM_log([
      "\n---------- Local ----------",
      fileMETA["name"] + " version " + fileMETA["version"],
      fileMETA["copyright"],
      fileMETA["license"],
      fileMETA["description"],
      fileMETA["include"],
      fileMETA["exclude"],
      "\n---------- Remote ----------",
      httpsMETA["name"] + " version " + httpsMETA["version"],
      httpsMETA["copyright"],
      httpsMETA["license"],
      httpsMETA["description"],
      httpsMETA["include"],
      httpsMETA["exclude"],
      httpsMETA["uso"]["script"],
      httpsMETA["uso"]["version"],
      httpsMETA["uso"]["timestamp"],
      httpsMETA["uso"]["hash"],
      httpsMETA["uso"]["installs"],
      httpsMETA["uso"]["reviews"],
      httpsMETA["uso"]["rating"],
      httpsMETA["uso"]["discussions"],
      httpsMETA["uso"]["fans"]
    ].join("\n"));
  }
});
</pre>}}
 
[[#top|top]] | [[#Examples|back]]
 
=== jQuery require ===
{{Good samp |1=<pre style="border: none; margin: inherit;">
// ==UserScript==
// @name          Hello jQuery
// @namespace    <nowiki>http://www.example.com/examples</nowiki>
// @description  jQuery test script
// @include      *
// @require      <nowiki>http://code.jquery.com/jquery-latest.js</nowiki>
// ==/UserScript==
 
$(document).ready(function() {
  $("a").click(function() {
    alert('Hello world!');
  });
});
</pre>}}
 
[[#top|top]] | [[#Examples|back]]


== Caveats ==
== Adding Resources ==


Changing the metadata of an installed script does not do anything, as this data is only accessed during installation. The script must be re-installed for these changes to take. Alternatively, [[config.xml]] can be modified manually.
Two metadata imperatives allow downloading files (once, at install time) for efficient reference:
First [[#@require|@require]], which includes a remote code resource.
Second [[#@resource|@resource]], which makes a remote data resource available.


[[#top|top]]
It is possible to add a new entry for either of these values, while editing a script that is already installed.
In either case, simply add the appropriate line and the referenced file will be downloaded and made available the next time the script runs.
If you specify a relative URL, then it will be interpreted as relative to the the URL the script was originally downloaded from.
<!--
If there was no original download URL (i.e. a brand new script created from a local file), then this will work if you also create an appropriately named file alongside the script.  (As of Greasemonkey 1.0.)
-->


== See Also ==
== See Also ==
:*[[API_reference|API reference]]


[[#top|top]]
* [[API reference]]
* [[Third-Party Libraries]]


== Notes ==
== Notes ==


[[#top|top]]
[[Category:API Reference]]
[[Category:API Reference|*{{FULLPAGENAME}}]]

Latest revision as of 01:56, 6 November 2023

Description

The metadata block is a section of a user script that describes the script. It usually contains the script name, namespace, description, and include and exclude rules. The metadata block appears in JavaScript line comments and may appear anywhere in the top level Greasemonkey code scope of the script, but is usually near the top of the file.

If the metadata block includes a key that Greasemonkey does not understand, it will be ignored.

Syntax

The metadata block must follow the format:

// ==UserScript==
// @key value
// ==/UserScript==

It must use line comments (//) like above, not block comments (/* */). Note that the opening // ==UserScript== and closing // ==/UserScript== must be precisely at the beginning of its line. Some keys may have multiple values. In all cases the key and value(s) are separated by whitespace. The closing ==/UserScript== line should be at the end of the metadata block (not at the end of the script).

@description

Example:

// @description This script even does the laundry!

Just a brief summary of what the script does, presented to the user as the script is installed, and in the manage dialog.

As of Greasemonkey 2.2: can be localized for multiple languages; see the #@name documentation for more detail.


@exclude

Examples: see #@include

See Include and exclude rules. There can be any number of @exclude rules in a script.

@grant

See dedicated @grant page.

@icon

Example:

// @icon http://www.example.org/icon.png

The icon is, as of Greasemonkey 0.9.0, displayed in the script management interface. Almost any image will work, but a 32x32 pixel size is best. This value may be specified relative to the URL the script itself is downloaded from.

@include

Examples:

// @include http://www.example.com/*
// @include http://*
// @include *

See Include and exclude rules. There can be any number of @include rules in a script.

@match

Examples:

// @match https://www.example.com/*
// @match http://*.example.com/*

The @match metadata imperative is very similar to @include, however it is safer. It sets more strict rules on what the * character means.

For details, see the documentation on Match Patterns for Google Chrome. Chrome implemented @match first, and Greasemonkey has been designed to be compatible.

@name

Example:

// @name Example Script

The name of the script. This appears in the monkey menu, and is also the unique identifier of a script (within a namespace). If no name is provided, it will be derived from the file name.

As of Greasemonkey 2.2: can be localized for multiple languages, for example:

// @name       Example Script
// @name:cs    Uživatelské skripty
// @name:es-MX Ejemplo Script 
// @name:ru    Пользовательские скрипты

Add a colon and the locale code, which is the ISO 639 language code and optionally a hyphen and ISO 3166 country code, when disambiguation is necessary. When the user's browser is configured with the matching primary language, that value will be displayed instead.

@namespace

Example:

// @namespace http://www.example.com/gmscripts

The combination of namespace and name is the unique identifier for a Greasemonkey script. If a script is being installed, and a script with that same name and namespace already exists, it will be replaced by the new script. Otherwise, the new script is added to the set of installed scripts. A script author will usually put all of their scripts under one common namespace, and then assign each script a unique name.

While the namespace is non-semantic, a URL is often used. Some authors use the common home page for the collection of scripts they have written. But remember, the namespace can be any unique value.

@noframes

Example:

// @noframes

When present, this imperative restricts the execution of the script. The script will run only in the top-level document, never in nested frames. It takes no arguments, it is either present or not present. This is off (scripts run in frames) by default.

@require

Example:

// @require http://www.example.com/example.js

There can be any number of @require keys in a script. Each @require is downloaded once, when the script is installed, and stored on the user's hard drive alongside the script. The URL specified may be relative to the URL the script is being installed from.

Note that since Greasemonkey 0.9.0, if Greasemonkey detects that the @require value(s) have been altered, these new values will be used (thus each @require shall be re-downloaded).

See also:

@resource

Example:

// @resource resourceName http://www.example.com/example.png

There can be any number of @resource keys in a script.

While the resourceName is non-semantic, it should comply with JavaScript identifier restrictions. Each @resource must have a unique name.

Each @resource is downloaded once, when the script is installed, and stored on the user's hard drive alongside the script. The URL specified may be relative to the URL the script is being installed from.

These named resources may be accessed through GM.getResourceURL.

See also:

@run-at

Compatibility: Limited support in Greasemonkey 4.0.

Example:

// @run-at document-end

This key supports three values:

document-end
The default if no value is provided. The script will run after the main page is loaded, but before other resources (images, style sheets, etc.) have loaded. The only guaranteed working value in Greasemonkey 4.x.
document-start
The script will run before any document begins loading, thus before any scripts run or images load.
document-idle
The script will run after the page and all resources (images, style sheets, etc.) are loaded and page scripts have run.

To detect if you are running at document-start time, check the value of document.readyState. For example:

if ('loading' == document.readyState) {
  alert("This script is running at document-start time.");
} else {
  alert("This script is running with document.readyState: " + document.readyState);
}

Scripts running at document-end will have the value interactive here.

@version

Example:

// @version 1

The version is used by the auto-update feature. When `@version` is set and if the auto-update feature is enabled, Greasemonkey will check periodically for new versions of the script by downloading it again (from same location where it was originally installed). If the new downloaded `@version` is higher, the update will be installed. Greasemonkey uses the compare-versions library to determine when a version is higher/greater/newer.

Examples

// ==UserScript==
// @name          My Script
// @namespace     http://www.example.com/gmscripts
// @description   Scripting is fun
// @include       http://www.example.com/*
// @include       http://www.example.org/*
// @exclude       http://www.example.org/foo
// @require       foo.js
// @resource      resourceName1 resource1.png
// @resource      resourceName2 http://www.example.com/resource2.png
// @version       1.0
// @icon          http://www.example.net/icon.png
// ==/UserScript==

Adding Resources

Two metadata imperatives allow downloading files (once, at install time) for efficient reference: First @require, which includes a remote code resource. Second @resource, which makes a remote data resource available.

It is possible to add a new entry for either of these values, while editing a script that is already installed. In either case, simply add the appropriate line and the referenced file will be downloaded and made available the next time the script runs. If you specify a relative URL, then it will be interpreted as relative to the the URL the script was originally downloaded from.

See Also

Notes