Access and Permissions

The Global HTML Page, Popovers, and Extension Bars

The global HTML page, popovers, 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, popovers, 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, popovers, 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 and Style Sheets

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 style sheets cannot access resources within the extension folder, such as images or other files, using relative URLs. Any relative URL in an injected script or style sheet is interpreted as relative to the webpage. To access resources within the extension folder from an injected script or style sheet, you must use an absolute URL. For details, see “Accessing Resources Within Your Extension Folder.”

Extension Website Access

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 style sheets, 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 primary list of domain patterns. Potentially, your extension has access to all domains. Website access can be limited by using a whitelist and blacklist, however. See “Whitelists and Blacklists.”

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 15-1.

Whitelists and Blacklists

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 15-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 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. Here are some 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