Metadata Block: Difference between revisions

	; Greasemonkey Manual
Using Greasemonkey
	Installing Scripts
	Monkey Menu
	Getting Help
User Script Authoring
	Editing
	Environment
	API

← Older edit Newer edit →

Revision as of 02:58, 20 March 2009

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 your script, but is usually near the top. 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.

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

top

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.20080609.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.20080609.0.

top | back

@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. If you are creating one locally, authors may choose the URI specification standard of http://localhost for the URI value as being an anonymous local script, but runs the risk of another script with the same name and namespace overwriting it.
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.

top | back

@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.

top | back

@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 script's @include and have it take effect.

top | back

@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.

top | back

@resource

Value: String

Compatibility: Greasemonkey 0.8.0+

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

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 include local and remote resources into the current script at first install but not successive installs. A user is required to uninstall the current user script before installing a newer version if new resource keys or require keys are present.
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.

top | back

@require

Value: String

Compatibility: Greasemonkey 0.8.0+

Usage: // @require foo.js

This metadata block key property may be used to include local or remote scripts into the current script at first install, but not successive installs.
Once a script is installed, changing the @require or @resource values will have no effect. The script must be uninstalled and reinstalled.

Similarly, if a user is updating their script and it contains new values, they must uninstall the current user script before installing a newer version .

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 Google AJAX Libraries API or YUI).

top | back

@unwrap

Value: undefined

Compatibility: Greasemonkey 0.8.1+

Usage: // @unwrap

Removes the anonymous function wrapper around scripts. For debug purposes.
Also referenced as a metadata imperative. This metadata block key property must not include any data parameter after it or it may be ignored altogether.

top | back

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.

This is by no means an exhaustive list, nor is it meant to be.

@copyright

Value: String

Compatibility: userscripts.org

Usage: // @copyright Year, Author (Author Homepage)

Example:

top | back

@license

@licence

Value: String

Compatibility: userscripts.org

Usage: // @license License Type; License Homepage

Example:

// @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
Compatibility: userscripts.org
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
Compatibility: userscripts.org
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 your script as their meta.js routine will automatically insert this key/value for you via a http request to http://userscripts.org/scripts/source/scriptid.meta.js

top | back

@uso:version

Value: String or Number
Compatibility: userscripts.org
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 your script as their meta.js routine will automatically insert this key/value for you via a http request to http://userscripts.org/scripts/source/scriptid.meta.js

top | back

@contributor

Value: String
Usage: // @contributor Contributor Name (Contributor Homepage)
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

@author

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

top | back

@homepage

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

top | back

Examples

Standard | Knowing Your Own Metadata | jQuery require

Standard example

// ==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
// ==/UserScript==

top | back

Knowing Your Own Metadata example

/*

Routine utilizing E4X (ECMAScript for XML) hack to retrieve a copy of the initial file metadata block entries
  and http metadata block entries.

NOTES:
  - If a user changes the include/exclude rules via Manage User Scripts, they will not be reflected in this copy.
  - Remember to change the uso:script metadata block key to your scriptid hosted on userscripts.org

*/

function parseHeaders(metadataBlock) {
  var headers = { include:[], exclude:[], resource:[], require:[], license:[], contributor:[], uso:{} };
  var name, value, key, host;

    var lines = metadataBlock.split(/\n/).filter(/\/\/ @/);
    for each (var line in lines) {
      [, name, value] = line.match(/\/\/ @(\S+)\s*(.*)/);

      switch (name) {
        case "licence":
          name = "license";
          break;
      }

      [, key ] = name.match( /([^:]+)$/ );
      [, host] = name.match( /^([^:]+)/ );

      if (host == key)
        if (headers[key] instanceof Array)
          headers[key].push(value);
        else
          headers[key] = value;
      else
        if (headers[host][key] instanceof Array)
          headers[host][key].push(value);
        else
          headers[host][key] = value;
    }

    headers["licence"] = headers["license"];

  return headers;
}

var fileMETA = parseHeaders(<><![CDATA[
// ==UserScript==
// @name          My Script
// @namespace     http://www.example.com/gmscripts
// @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.org/*
// @exclude       http://www.example.org/foo
// @require       foo.js
// @resource      resourceName1 resource1.png
// @resource      resourceName2 http://www.example.com/resource2.png
// @uso:script    scriptid
// ==/UserScript==
]]></>.toString());

GM_xmlhttpRequest({
  method:"GET",
  url:"http://userscripts.org/scripts/source/" + fileMETA["uso"]["script"] + ".meta.js",
  headers:{
    "Accept":"text/xml"
  },
  onload:function(response) {
    var httpMETA = parseHeaders(response.responseText);

    GM_log([
      "\n---------- Local ----------",
      fileMETA["name"] + " version " + fileMETA["version"],
      fileMETA["copyright"],
      fileMETA["license"],
      fileMETA["description"],
      fileMETA["include"],
      fileMETA["exclude"],
      "\n---------- Remote ----------",
      httpMETA["name"] + " version " + httpMETA["version"],
      httpMETA["copyright"],
      httpMETA["license"],
      httpMETA["description"],
      httpMETA["include"],
      httpMETA["exclude"],
      httpMETA["uso"]["script"],
      httpMETA["uso"]["version"]
    ].join("\n"));
  }
});

top | back

jQuery require example

// ==UserScript==
// @name          Hello jQuery
// @namespace     http://www.example.com/examples
// @description   jQuery test script
// @include       *
// @require       http://code.jquery.com/jquery-latest.js
// ==/UserScript==

$(document).ready(function() {
  $("a").click(function() {
    alert('Hello world!');
  });
});

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.
top

See AlsoAPI reference

top

Notes

top

Metadata Block: Difference between revisions

Revision as of 02:58, 20 March 2009

Description

Syntax

Properties

@name

@namespace

@description

@include

@exclude

@resource

@require

@unwrap

Other Keys

@copyright

@license

@licence

@version

@uso:script

@uso:version

@contributor

@author

@homepage

Examples

Standard example

Knowing Your Own Metadata example

jQuery require example

Caveats

See Also

Notes

Navigation menu

Page actions

Page actions

Personal tools

Navigation

Search

Tools