Safari Extensions Development Guide

Accessing Resources Within Your Extension Folder

Your global HTML page, extension bars, injected scripts, and style sheets can all access resources within your extension folder, such as .js files, images, and other media. The resources must reside within your .safariextension folder when Extension Builder builds the extension (creates the compressed .safariextz package).

Using Relative URLs

Relative URLs are resolved differently for injected scripts and other extension resources.

Used from an injected script, relative URLs are relative to the webpage the script is injected into. From within an injected script—or any of its subresources, such as included scripts—resources in the extension folder can be loaded only by using an absolute URL (see Using Absolute URLs).

For all other extension resources, including injected style sheets, relative URLs are relative to the source file within the extension folder.

This means you can access resources within the extension folder using relative URLs from the global page, extension bars, injected style sheets, or any of their subresources.

You can have nested folders within your extension folder. For example, your extension folder could contain a Scripts folder and an Images folder.

MyExtension.safariextz/

Scripts/

myScript.js

Images/

myImage.png

You can traverse the folder hierarchy with a relative URL by using ../ to go up a level. For example, from a script in the Scripts folder, you could load an image in the Images folder using this snippet:

img.src='../Images/myImage.png'.

Important: Do not begin a relative URL with a leading forward slash (/). Relative URLs must be relative to the file they are loaded from, not relative to the extension’s folder.

This restriction applies in Safari 5.0.1 and later. If your extension uses relative URLs to access resources in your folder, and the extension was tested using Safari 5.0, you should retest it using Safari 5.0.1 or later to confirm that it does not use relative URLs that begin with the forward slash character.

Using Absolute URLs

You can use absolute URLs to access resources in your extension folder from any part of your extension.

Use of the file:/// scheme is not allowed. Absolute URLs begin with safari.extension.baseURI, followed by the path within the folder and the filename. For example, using an absolute URL from a JavaScript function looks like this:

img.src = safari.extension.baseURI + 'Images/myImage.png'

Important: The base URI ends in a forward slash. Do not begin the path with another.

You must use JavaScript to obtain the absolute URL, as it changes each time Safari is launched. To load a resource from an HTML or CSS file using an absolute URL, you need to add some JavaScript to the source file.

Example: Loading a Background Image in CSS

An injected style sheet can add a background image to a website using images stored inside the extension. The easiest way to do this is to use a relative URL directly in CSS. For example:

body { background-image:url('../Images/paper.jpg'); }

To accomplish the same thing using an absolute URL, insert a few lines of JavaScript into your style sheet: