Metadata Block: Difference between revisions

From GreaseSpot Wiki
Jump to navigationJump to search
m (Javascript -> JavaScript)
(Symmetry update... and prep for v0.8.0 :D)
Line 1: Line 1:
__NOTOC__
== 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''' 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
The metadata block appears in JavaScript comments. It begins with the line


// == UserScript==
<code><pre>// ==UserScript==</pre></code>


and ends with
and ends with


// == /UserScript==
<code><pre>// ==/UserScript==</pre></code>


Everything between those lines is in the format
Everything between those lines is in the format


// @<var>key</var>   <var>value</var>
<code><pre>// @key   value</pre></code>


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


== Metadata keys ==
[[#Examples|Examples]] | [[#Other_Keys|Other Keys]] | [[#Caveats|Caveats]] | [[#Notes|Notes]]
 
== Syntax ==
'''// ==UserScript=='''
 
'''// == @'''''key'' '''value'''
 
'''// ==/UserScript=='''
 
:Value: Object
:Compatibility: [[Version_history#0.2.5|Greasemonkey 0.2.5+]]
 
:{| border="1" cellpadding="5"
|+ Keys
!|'''Properties'''
|-
| <code>[[#.40name |@name]]</code>
|-
|<code>[[#.40namespace |@namespace]]</code>
|-
|<code>[[#.40description |@description]]</code>
|-
|<code>[[#.40include |@include]]</code>
|-
|<code>[[#.40exclude |@exclude]]</code>
|}
:* All properties are optional
 
=== Properties ===
----
==== @name ====


=== @name ===
:Value: String
:Usage: <code>// @'''name'''        My Script</code>
::* 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.


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.
[[#top|top]] | [[#Syntax|back]]


=== @namespace ===
==== @namespace ====


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 a URI. 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 should specify this.
:Value: URI
: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. While the namespace is non-semantic, it should be a URI. 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 should specify this.


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


Just a description.
==== @description ====
: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.


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


Refer to ''[[Include and exclude rules]]''. There can be any number of @include and @exclude rules in a script.
==== @include ====
: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.


== Example ==
[[#top|top]] | [[#Syntax|back]]


==== @exclude ====
:Value: String
: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.
[[#top|top]] | [[#Syntax|back]]
== Examples ==
<code><pre>
  // ==UserScript==
  // ==UserScript==
  // @name          My Script
  // @name          My Script
Line 43: Line 96:
  // @exclude      <nowiki>http://www.example.org/foo</nowiki>
  // @exclude      <nowiki>http://www.example.org/foo</nowiki>
  // ==/UserScript==
  // ==/UserScript==
</pre></code>
[[#top|top]]


== Other Keys ==
== Other Keys ==


Some [[user script]]s contain other keys in the metadata block.
Some [[user script]]s contain other keys in the metadata block. Common keys are <code>@author</code>, <code>@version</code>, or <code>@homepage</code>. These metadata keys serve no technical purpose. They are ignored by the [[Greasemonkey|Greasemonkey extension]], but they can be read by human beings or other code.
Common keys are <code>@author</code>, <code>@version</code>, or <code>@homepage</code>.
 
These metadata keys serve no technical purpose.
[[#top|top]]
They are ignored by the [[Greasemonkey|Greasemonkey extension]], but they can be read by human beings or other code.


== Caveats ==
== 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.
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|top]]
== Notes ==
[[#top|top]]

Revision as of 07:00, 11 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 | Notes

Syntax

// ==UserScript==

// == @key value

// ==/UserScript==

Value: Object
Compatibility: Greasemonkey 0.2.5+
Keys
Properties
@name
@namespace
@description
@include
@exclude
  • 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.

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 a URI. 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 should specify this.

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/*

top | back

@exclude

Value: String
Usage: // @exclude http://www.example.com/foo/*

top | back

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

top

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.

top

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

Notes

top

Retrieved from "https://wiki.greasespot.net/index.php?title=Metadata_Block&oldid=2384"