Extensions can have two parts—an application part, consisting af any global page or extension bars, and a content part, consisting of any injected scripts or stylesheets. The two parts have different access and permissions.
In addition, there are settings you can specify when building your extension that select the websites your extension can interact with.
Note: For security reasons, there are some things that no part of your extension can access. This includes files on the user’s hard disk outside of the extension package, as well as functions and variables defined in scripts loaded from the webpage’s domain.
The global HTML page and extension bars have access to the SafariApplication
and SafariExtension
classes. They can work with windows and tabs, extension settings, and add or remove extension items. They can also respond to commands from the Safari toolbar or the contextual menu that appears over a webpage.
The global HTML page and extension bars do not have access to the content of webpages, and they can communicate with injected scripts only by sending messages—they cannot access an injected script’s functions or variables directly.
The global page and extension bars do not have permission to use the JavaScript window.open()
method. They must use the Safari Extensions API. See “The Windows and Tabs API.”
Injected scripts have access to the SafariContentExtension
class. They have the same permission to access and modify the webpages they are injected into as scripts originating in the webpage’s own domain. They have permission to use the standard JavaScript API, as well as Safari-specific and Webkit-specific JavaScript APIs.
Injected scripts cannot access the SafariApplication
or SafariExtension
classes. They cannot respond to command events generated by the Safari toolbar or contextual menus, nor can they access functions or variables defined in the global HTML page or extension bars. They can, however, send messages to the global HTML page and extension bars, and the message data can be an object (such as an array, for example) declared in the injected script.
Injected scripts and stylesheets cannot access resources within the extension folder, such as images or other files, using relative URLs. Any relative URL in an injected script or stylesheet is interpreted as relative to the webpage. To access resources within the extension folder from an injected script or stylesheet, you must use an absolute URL. For details, see “Accessing Resources Within Your Extension Folder.”
You choose the webpages and domains your extension has access to in Extension Builder. Only the websites you choose have web content injected into them, and only those websites can be manipulated using the tab
object’s properties, such as title
and url
.
Use the Extension Website Access field in Extension Builder to restrict your extension’s access to external websites. Your choices are as follows:
None—Your extension cannot access webpages by injecting scripts or stylesheets, and most tab properties are undefined.
Some—Your extension can access webpages from a list of domains.
You are prompted for a list of domain patterns. For example: developer.apple.com
or www.example.org.jp
.
A leading *
character matches any string in the domain. For example: *.apple.com
matches www.apple.com
, developer.apple.com
, or any host name in the apple.com
domain. Similarly, *.co.jp
matches all co.jp
domains and *.jp
matches all .jp
domains.
All—Your extension’s access is not limited by a list of domain patterns. Potentially, your extension has access to all domains. Website access can be limited by using a whitelist and/or blacklist, however. See “Whitelists and Blacklists.”
Important: If you set your access to Some, and do not specify any domain patterns, your extension has no website access.
If you choose Some or All, you can further choose to allow your extension access to secure sites (HTTPS URLs) or not, as shown in Figure 12-1.
The whitelist and blacklist work in conjunction with the Extension Website Access field. First, access is limited by the Extension Website Access settings, then the whitelist and blacklist are applied.
If there is no whitelist or blacklist, no restrictions are added to your Extension Website Access.
If there is a whitelist, your scripts and styles are applied only to webpages whose URL match an entry on your whitelist.
If there is a blacklist, your scripts and styles are not applied to any webpages whose URL matches a blacklist entry.
Again, note that these restrictions are in addition to those set in the Extension Website Access field. If you specify Some access, for example, you have access only to the domains matching your provided domain patterns. Items in your whitelist and blacklist create additional restrictions within those domains. Be sure all the items in your whitelist are within a domain you have access to.
Add URLs to the whitelist or blacklist by clicking New URL Pattern as illustrated in Figure 12-2.
A URL pattern takes the form Scheme://Domain/Path.
Scheme can be http or https.
Domain
is the host domain, such as developer.apple.com or www.example.co.jp.
Path is the directory and/or webpage, such as safari/ or safari/library/navigation/index.html.
A URL pattern can include the * character to match any string. This allows you to specify all pages in a particular domain, for example, without having to create an exhaustive list.
The * character can be used anywhere in the domain or path, but not the scheme.
Examples:
http://*/*
—matches all http URLs
http://*.apple.com/*
—matches all webpages from apple.com
http://developer.apple.com/*
—matches all webpages from developer.apple.com
https://secure.example.com/accounts/*
—matches all webpages from the accounts directory of secure.example.com that are delivered over HTTPS.
http://www.example.com/thepath/thepage.html
—matches one webpage
Important: The format for URL patterns in a whitelist or blacklist is not the same as the format for domain patterns in Extension Website Access.
Last updated: 2010-08-03