Skip to content

Manual: Metadata Block

Jump to bottom Edit New page
Erik Vold edited this page Jul 15, 2013 · 72 revisions

Syntax

The metadata block of a user script must have the following format:

// ==UserScript==
// @key value_1 value_2 value_etc
// ==/UserScript==

It must use line comments // and not block comments /* */. If a key has multiple values, those values must be space-separated. The metadata block must be within the // ==UserScript== starting line and the // ==/UserScript== ending line.

Note: You can access your script's metadata at runtime with the GM_getMetadata API.

Keys

Scriptish strives to support all @keys provided by other user script engines. If there are any @keys you would like to see supported in Scriptish please create an issue (if one doesn't already exist).

Note: Unlike other user script engines, Scriptish @keys are not case sensitive.


@id (new in Scriptish!)

The id, a unique identifier, for the user script. Scriptish will use the id to distinguish different user scripts, e.g. when loading script user preferences (See about:config). Also, the id might be displayed in the error/web console as a prefix to error messages generated by user scripts.

// @id its-a-wonderful-userscript@someplace.com
// or
// @id plainoldtextstring

@name

The name of a user script. This is displayed to users in the Scriptish toolbar menu and in about:addons.

// @name A Wonderful Script

@namespace

This is used by other user script engines, in combination with @name, to create a unique identifier. Since Scriptish uses @id this is not currently used, but is still suggested as a possible way to group user scripts.

// @namespace http://someplace.com

@grant

This is used to grant access to GM_ APIs, if you do not request access to an API then you will not get it.

// @grant GM_setClipboard


@author

The original author of the user script, preferably with an e-mail address.

// @author Erik Vold <evold@mozilla.com> http://work.erikvold.com/

Note: We strongly recommend you use the format below, as it allows Scriptish to provide a better experience when presenting your user script in the Firefox Add-ons Manager.

// @author Fname MNames LName <email@company.com> http://website-url.com/

@developer

The names of co-developers for the user script.

// @developer Super Coder

@contributor

A contributor to the user script.

// @contributor Mary Jane <admin@420.com>

@version

The user script's version. This is displayed to the user in about:addons.

Note: User scripts should specify their versions using the Toolkit version format.

// @version 2.0

@description

A description of the user script. This is displayed to the user in about:addons.

// @description This user script kicks ass by applying boot to booty.

@homepage or @homepageURL or @website (new in Scriptish!)

A homepage URL for the user script. This is displayed to the user in about:addons.

// @homepageURL http://someplace.com/userscripts/something-wonderful.html

@supportURL (new in Scriptish!)

A support URL, currently not used.

// @supportURL http://github.com/scriptish/scriptish/issues

@updateURL (new in Scriptish!)

An update URL for the user script.

The @updateURL must be secure (i.e. a https:// URL) unless the "Require user scripts to update using HTTPS" option (Scriptish Options -> Advanced -> Update Security) is set.

Note: @version is required when using @updateURL, and it must use the Toolkit version format.

Note: If the @updateURL points to a .meta.js file, Scriptish will check that for updates. If it is determined a new script version is available, Scriptish will look for a .user.js file with the same file name, domain, and path. A .meta.js is typically used instead of the .user.js file to save bandwidth and improve response time.

// @updateURL https://somedomain.com/downloads/cool-script.meta.js

@icon, @iconURL or @defaulticon (new in Scriptish!)

An icon URL for the user script. This is displayed to the user in notifications made through GM_notification and in about:addons. The value can be a URL to an image, or a data: URL for an image.

// @icon http://someplace.com/img/kickass.png

Note: a 64px version of the icon can be provided following the icon URL, like so:

// @icon http://someplace.com/img/kickass.png http://someplace.com/img/kickass64.png

See @icon64 below for more information on the 64px version.


@icon64 or @icon64URL (new in Scriptish!)

A 64px icon URL for the user script. This is displayed to the user in a user script's details page within about:addons. The value can be a URL to an image, or a data: URL for an image.

// @icon64 http://someplace.com/img/kickass64.png

@screenshot (new in Scriptish!)

A screenshot URL for the user script. Multiple @screenshot keys are allowed. The image may be of any type that you could use on a website. You may also, optionally, provide a thumbnail version of the image as @screenshot's second value.

// @screenshot http://something.com/some/path/img.jpg http://something.com/some/path/thumb.jpg
// @screenshot http://something.com/some/path/img.jpg

@contributionURL (new in Scriptish!)

URL of a page to load if a user wishes to make a monetary contribution. This will be displayed in the user script's "More" page, accessible from the User Scripts list in the Add-ons Manager.

// @contributionURL https://m.e/donations

@contributionAmount (new in Scriptish!)

A suggested contribution amount. If @contributionURL is set, this will be displayed in the user script's "More" page, accessible from the User Scripts list in the Add-ons Manager.

Note: @contributionAmount is optional; only the @contributionURL is required for the contribution message to appear.

// @contributionAmount $1.00

### @domain *(new in Scriptish!)*

Describes the domain name(s) a user script is allowed to run on and access through GM_xmlhttpRequest. If @domain is not defined, it is assumed the user script needs access to all domains. Multiple @domain keys are allowed.

Note: Explicitly stating the domain name(s) your user script needs to access is highly recommended, since it will provide your users with a better understanding of your script.

// @domain google.com
// @domain www.google.com

@include

Describes the URL range on which the user script should run. Multiple @include keys are allowed.

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

Note: @include may also be a regular expression literal, but only the i flag is recognized (for case-insensitivity).

// @include /^https?:\/\/(?:www\.)?google\.com\/something\//i

@match

This comes from Google Chrome user scripts, and is a stricter version of @include. See Google Chrome's documentation on Match Patterns for further details.

// @match http://*
// @match http://*.google.com/*
// @match http://www.google.com/*

@exclude

Describes the URL range to exclude (even if the page is @include'd). The value format is the same as @include.


@run-at (new in Scriptish!)

This idea comes from the Google Chrome user script documentation (but was implemented first by Scriptish), and specifies when Scriptish will run user scripts. Scriptish (and Greasemonkey) load scripts on document-end by default, whereas Google Chrome defaults to document-idle.

The possible values for @run-at, in order of occurrence, are: document-start, document-end, document-idle and window-load.

Early Injection

Runs a script at the start of a page's life cycle.

// @run-at document-start

DOM Ready Injection

Runs a script when the DOMContentLoaded event fires.

// @run-at document-end

Idle Injection

Runs a script some time between document-end and immediately after the window-load (i.e. window.onload()) event fires.

// @run-at document-idle

Load Injection

Runs a script when the window.onload() event fires.

// @run-at window-load

@priority (new in Scriptish!)

Specifies a script's priority level. The greater the number the greater the priority. If two or more scripts have the same @run-at value, then @priority will determine the execution order (scripts are also delayed in this order).

// @priority 1  // higher priority
// @priority -1  // lower priority
// @priority -100  // very low priority
// @priority 0 // default value

@delay (new in Scriptish!)

Specifies a delay, in milliseconds, before the user script is ran.

// @delay 1000

@resource

The resourceName value (see example below) must comply with JavaScript identifier restrictions. Each @resource must have a unique name.

Each @resource is downloaded during the user script installation and stored on the user's hard drive in the same folder as the script. The @resource URL may be relative to the user script's download location.

// @resource resourceName http://www.example.com/example.png
// @resource resourceName2 /example2.png
// @resource css /styles.css

Example

GM_addStyle(GM_getResourceText('css'))

@css (New is Scriptish!)

Each @css file referred to is downloaded and stored with the userscript on the hard drive and is automatically applied to pages that the userscript is applied to. This makes writing css easier, separates css from javascript making both easier to read, and renders GM_addStyle and using Stylish in combination with Scriptish userscripts fairly redundant.


@require

Each @require is downloaded during the user script installation and stored on the hard drive in the same folder as the script. The @require URL may be relative to the user script's download location.

// @require http://www.someplace.com/tools.js
// @require /tools2.js

@jsversion (new in Scriptish!)

Specifies the version of JavaScript the user script was built to work on and, if supported, will be run on. If the @jsversion provided is not acceptable the default (the highest version supported by the user's browser) will be used.

// @jsversion 1.8

@noframes (new in Scriptish!)

If this key exists the user script will not run in iframes.

No value should be given for @noframes. If a value is provided the line will be ignored.

// @noframes
Add a custom footer
Add a custom sidebar
Clone this wiki locally