Metadata Block: Difference between revisions
From GreaseSpot Wiki
Jump to navigationJump to search
m →@namespace: Clarified the namespace standard versus GM's resolution |
No edit summary |
||
| Line 58: | Line 58: | ||
:Usage: <code>// @'''namespace''' <nowiki>http://www.example.com/gmscripts/</nowiki></code> | :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. | ::* 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. | ||
::* While the namespace is '''non-semantic''', it should be your prefered internet homepage [http://gbiv.com/protocols/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 http://userscripts.org] and let Greasemonkey supply one automatically. | ::* While the namespace is '''non-semantic''', it should be your prefered internet homepage [http://gbiv.com/protocols/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 http://userscripts.org] and let Greasemonkey supply one automatically. You may also omit the @namespace header, but such scripts run the risk of colliding with other scripts with the same @name which also don't have a @namespace header. | ||
::* The [https://addons.mozilla.org/en-US/firefox/addon/722 NoScript] add-on currently utilizes namespace filtering, and will properly sanitize user scripts that are not listed in the XSS white-list section of the options dialog. | ::* The [https://addons.mozilla.org/en-US/firefox/addon/722 NoScript] add-on currently utilizes namespace filtering, and will properly sanitize user scripts that are not listed in the XSS white-list section of the options dialog. | ||
[[#top|top]] | [[#Syntax|back]] | [[#top|top]] | [[#Syntax|back]] | ||
Revision as of 07:58, 21 December 2007
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. It begins with the line
// ==UserScript==
and ends with
// ==/UserScript==
Everything between those lines is in the format
// @key value
If the metadata block includes a key that Greasemonkey does not understand, it will simply be ignored.
Examples | Other Keys | Caveats | See Also | Notes
Syntax
// ==UserScript==
// == @key value
// ==/UserScript==
- Value: Object
- Compatibility: Greasemonkey 0.2.5+
Keys Properties @name@include@namespace@exclude@description
- All properties are optional
Properties
@name
- Value: String
- Usage:
// @name My Script- The name of the script. This appears in the script manager and 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.
@namespace
- Value: URI
- Usage:
// @namespace http://www.example.com/gmscripts/- 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.
- While the namespace is non-semantic, it should be your prefered internet homepage URI according to the 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://userscripts.org and let Greasemonkey supply one automatically. You may also omit the @namespace header, but such scripts run the risk of colliding with other scripts with the same @name which also don't have a @namespace header.
- The NoScript add-on currently utilizes namespace filtering, and will properly sanitize user scripts that are not listed in the XSS white-list section of the options dialog.
@description
- Value: String
- Usage:
// @description This script even does the laundry!- Just a brief summary of what the script does, to present to the user who is installing it.
@include
- Value: String
- Usage:
// @include http://www.example.com/*- Refer to Include and exclude rules. There can be any number of @include rules in a script.
@exclude
- Value: String
- Usage:
// @exclude http://www.example.com/foo/*- Refer to Include and exclude rules. There can be any number of @exclude rules in a script.
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
// ==/UserScript==
Other Keys
Some user scripts contain other keys in the metadata block. Common keys are @author, @version, or @homepage. These metadata keys serve no technical purpose. They are ignored by the Greasemonkey extension, but they can be read by human beings or other code.
Caveats
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.
