Metadata Block

From GreaseSpot Wiki
Revision as of 21:51, 3 February 2010 by Arantius (talk | contribs) (→‎@license)
Jump to navigationJump to search

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

Template:Samp

and ends with

Template:Samp

Everything between those lines is in the format

Template:Samp

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.

Other Keys | Examples | Caveats | See Also | Notes

Syntax

// ==UserScript==

// == @key value

// ==/UserScript==

Value: Object
Compatibility: Greasemonkey 0.2.5+
Keys
Properties
@name @include @resource @unwrap
@namespace @exclude @require
@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.
  • 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 Greasemonkey 0.8.0, new scripts will be stored under their own folder name in the gm_scripts folder and also include spaces to underscores conversion and other special characters. The scripts directory is also backed up into a folder called gm_scripts_08bak when migrating to version 0.8.0.


@namespace

Value: String
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 and one will be overwritten by the other.
  • 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 userscripts.org and let Greasemonkey supply one automatically. If you are creating one locally, authors may choose the URI specification standard of http://localhost for the value as being an anonymous local script.
  • Common String Values
  • Greasemonkey addon supplied
Usage: Omitted @namespace in source userscript file
Examples:
Automatic host to namespace mapping
Script Host Chosen Namespace
http://userscripts.org/scripts/source/scriptid.user.js userscripts.org
http://example.org/scripts/filename.user.js example.org
http://localhost/scripts/filename.user.js localhost
  • tag URI
Usage: "tag:" taggingEntity ":" specific [ "#" fragment ]
  • 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:
@namespace tag:johndoe@example.com,2009:johndoe
@namespace tag:johndoe@example.net,2010-05:johndoe/pathto
@namespace tag:userscripts.org,2005-06-19T23:33:49Z:JohnDoe:DescriptionWithNoSpaces:etc:etc:etc
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:
@namespace anotherjesse
@namespace userid + vanityid + Firstname Lastname
  • XML URI
Usage: scheme "://" domain [ "." tld ][ "/" pathto ]
Examples:
@namespace http://localhost
@namespace http://localhost.localdomain
@namespace http://userscripts.org/users/userid
@namespace http://example.org/pathto/script
See Also: https://developer.mozilla.org/en/Namespaces
  • The 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.


@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.
  • You cannot edit a live scripts @include and have it take effect.


@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.
  • You cannot edit a live scripts @exclude and have it take effect.


@resource

Value: String
Compatibility: Greasemonkey 0.8.0+
Usage: // @resource resourceName http://www.example.com/resource.png
  • 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 @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.


@require

Value: String
Compatibility: Greasemonkey 0.8.0+
Usage: // @require foo.js
  • 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 @include.
  • As with all metadata values that are stored in 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 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.


@unwrap

Value: undefined
Compatibility: Greasemonkey 0.8.1+
Usage: // @unwrap
  • 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 debugging purposes.
  • By default most versions of Greasemonkey automatically encapsulate each script in an anonymous function wrapper. In other words:
  • (function(){ /* script source */ })();
  • 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 var sidebar = "foo";. This will return a script error of Illegal value, and script execution will cease. See also #108.


Other Keys

Some user scripts contain other special keys in the metadata block.

These unsupported metadata keys serve no technical purpose and are ignored by the Greasemonkey extension, but can be read by human beings or utilized by other code.

Keys
Properties
userscripts.org user contributed
@copyright @uso:script @uso:rating @attribution
@license @uso:version @uso:installs @contributor
@version @uso:timestamp @uso:reviews @author
@uso:hash @uso:discussions @homepage
@uso:fans
  • This is by no means an exhaustive list, nor is it meant to be.
@copyright
Value: String
Usage: // @copyright Year, Author (Author Homepage)
  • It is strongly recommended to use this key to identify a scripts copyright author and homepage. Usually a script repository such as 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:
// @copyright 2009+, John Doe (http://www.example.com/projecthomepage)

top | back

@licence
Value: String
Usage: // @license License Type; License Homepage
  • 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 recommended 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 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:
    Code (or module) licenses
    These are typically for all code including binaries, scripts, HTML and CSS.
    Content licenses
    These are typically documents such as guides, wikis and images. The data:image URI scheme is considered content.
  • Example: (GPL is a Code License and CC is a Content License)
// @license GPL version 3 or any later version; http://www.gnu.org/copyleft/gpl.html
// @license (CC) Attribution Non-Commercial Share Alike; http://creativecommons.org/licenses/by-nc-sa/3.0/

top | back

@version
Value: String or Number
Usage: // @version 0.0.1
  • 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 new Date().getTime().

top | back

@uso:script
Value: String or Number
Usage: // @uso:script scriptid
  • 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 http://userscripts.org/scripts/source/scriptid.meta.js

top | back

@uso:version
Value: String or Number
Usage: // @uso:version versionid
  • 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 http://userscripts.org/scripts/source/scriptid.meta.js

top | back

@uso:timestamp
Value: String
Usage: // @uso:timestamp Wed, 17 Jun 2009 22:50:26 +0000
  • 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 http://userscripts.org/scripts/source/scriptid.meta.js

top | back

@uso:hash
Value: String
Usage: // @uso:hash 30d54f8ba24c0c6ec5710866e9b0839b2066a815
  • 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 http://userscripts.org/scripts/source/scriptid.meta.js

top | back

@uso:rating
Value: String or Number
Usage: // @uso:rating 4.00
  • 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 http://userscripts.org/scripts/source/scriptid.meta.js

top | back

@uso:installs
@uso:reviews
@uso:discussions
@uso:fans
Value: String or Number
Usage:
// @uso:installs count
// @uso:reviews count
// @uso:discussions count
// @uso:fans count
  • 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 http://userscripts.org/scripts/source/scriptid.meta.js

top | back

@attribution
Value: String
Usage: // @attribution Attribution Name (Attribution Script Homepage)
  • There can be any number of @attribution keys in a script for multiple attribution support.
  • Attribution may only be used if source @license type is compatible.
  • Example:
// @attribution Jane Doe (http://www.example.com/janedoe/scriptid)
// @attribution Jack Doe (http://www.example.com/jackdoe/scriptid)
// @attribution Jill Doe (http://www.example.com/jilldoe/scriptid)

top | back

@author
Value: String
Usage: // @author John Doe
  • (Suggest not using this key in favor of @copyright)

top | back

@contributor
Value: String
Usage: // @contributor Contributor Name (Contributor Homepage)
  • There can be any number of @contributor keys in a script for multiple contributor support.
  • Example:
// @contributor Jane Doe (http://www.example.com/janedoe)
// @contributor Jack Doe (http://www.example.com/jackdoe)
// @contributor Jill Doe (http://www.example.com/jilldoe)

top | back

@homepage
Value: URI
Usage: // @homepage http://www.example.com/myhomepage
  • (Suggest not using this key in favor of @copyright)

top | back

Examples

Core | Knowing Your Own Metadata | jQuery require

Core

Template:Samp

top | 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 @namespace, and allows Greasemonkey to supply one, it will not be reflected in this copy.
  • Remember to change the @uso:script key to match the scriptid hosted on userscripts.org

Template:Good samp

top | back

jQuery require

Template:Good samp

top | back

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.

See Also

Notes