GM.getResourceUrl: Difference between revisions

From GreaseSpot Wiki
Jump to navigationJump to search
m (Text replace - "[[Metadata_block" to "[[Metadata Block")
(simplify)
Line 3: Line 3:
== Description ==
== Description ==


This [[API_reference|API]] method loads an external resource, such as an image, and returns the string containing the base64 encoded data: URL scheme for use in the DOM.
Given a defined [[Metadata Block#.40resource|@resource]], this method returns it as a URL.
 
Compatibility: [[Version_history#0.8.20080609.0|Greasemonkey 0.8.0+]]


== Syntax ==
== Syntax ==


'''GM_getResourceURL(''' ''resourceName'' ''')'''
{{Function|GM_getResourceURL|resourceName}}
 
=== Arguments ===
 
; <code>resourceName</code>
: <code>String</code> The name provided when the [[Metadata Block#.40resource|@resource]] was defined, follow that link for valid naming restrictions.
 
=== Returns ===


:Value: Function
<code>String</code>.
:Returns: String
A base64 encoded <code>data:</code> URI.
:Compatibility: [[Version_history#0.8.20080609.0|Greasemonkey 0.8.0+]]


:{| cellpadding="5" style="border-style:solid; background:#FFFFE0;"
Note: This can be used anywhere a <code>data:</code> URI will work (E.G. <code><img></code> or <code><script></code>).
|+ Parameters
This does not include <code><object></code> or <code><embed></code>.
!style="background:#CC9900;"|'''Properties'''
|-
| <code><span style="background:#FFFFE0;">[[#resourceName |resourceName]]</span></code>
|}
:* All properties are optional except [[#resourceName|resourceName]].


=== Properties ===
=== Raises ===
----
==== <code>resourceName</code> ====
:Value: String
:Usage: <code>'''resourceName''' = "metadata_block_resourceName";</code>
:* 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.
:* This value is used in retrieval of the same-named resource specified in the corresponding metadata block [[Metadata Block#.40resource |@resource]] key. After it is retrieved, it will be base64 encoded into the [http://www.ietf.org/rfc/rfc2397.txt "data" URL scheme], and returned upon completion of this API method.


Throws an <code>Error</code> when the named resource does not exist.


== Examples ==
== Examples ==
<pre class='sample'>
<pre class='sample'>
// ==UserScript==
// ==UserScript==
// @name          My Script
// @resource logo http://www.example.com/logo.png
// @namespace    <nowiki>http://www.example.com/gmscripts/</nowiki>
// @description  Scripting is fun
// @include      <nowiki>http://www.example.com/*</nowiki>
// @resource     fooLogo http://www.example.com/logo.png
// ==/UserScript==
// ==/UserScript==


(function() {
var img = document.createElement('img');
  // some code
img.src = GM_getResourceURL("logo");
 
document.body.appendChild(img);
  var fooLogo = GM_getResourceURL("fooLogo");
 
  // some code
 
})();
</pre>
</pre>


[[Category:API_Reference|G]]
[[Category:API_Reference|G]]

Revision as of 21:50, 8 February 2010


Description

Given a defined @resource, this method returns it as a URL.

Compatibility: Greasemonkey 0.8.0+

Syntax

function GM_getResourceURL( resourceName )

Arguments

resourceName
String The name provided when the @resource was defined, follow that link for valid naming restrictions.

Returns

String. A base64 encoded data: URI.

Note: This can be used anywhere a data: URI will work (E.G. <img> or <script>). This does not include <object> or <embed>.

Raises

Throws an Error when the named resource does not exist.

Examples

// ==UserScript==
// @resource logo http://www.example.com/logo.png
// ==/UserScript==

var img = document.createElement('img');
img.src = GM_getResourceURL("logo");
document.body.appendChild(img);