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

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'

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:

<script type = "text/javascript">
var myImage = safari.extension.baseURI + "Images/paper.jpg" ;
document.body.style.cssText = "background-image: url(" + myImage + ")";
</script>

Security

Use of the file:/// scheme is not allowed.

The base URI returns a unique value each time Safari is run. It must be obtained at least once per session by your extension. It does not persist from session to session and it is not predictable.

This prevents outside scripts from determining the base URI of your extension and accessing its resources.

You can capture the base URI for your extension in a string and reuse the string within your code during a session, but you cannot store the string and reuse it from session to session.