SafariExtension Class Reference

Technology area	Safari Extensions
Availability	Available in Safari 5.0 and later.

Overview

The SafariExtension class represents your extension outside of the web content; an instance of the class is accessible as safari.extension. Its counterpart class for scripts running within the web content is SafariContentExtension.

Adding and removing style sheets and scripts. Adding or removing a content style sheet applies to pages immediately. Adding or removing a content script applies only to pages opened or reloaded after that point. Removing a style sheet or a script that is in the Info.plist file removes it only from the current browser session.

Whitelists and blacklists. A content script or style sheet may specify a blacklist and a whitelist; both are optional. For a description of the pattern format, see “The Extension Builder Interface” in Safari Extensions Development Guide. The script or style sheet will be applied to a page only in the following cases:

The whitelist and blacklist are both empty.
The whitelist is empty, and the page’s URL does not match anything on the blacklist.
The page’s URL matches a pattern on the whitelist, and the blacklist is empty.
The page’s URL matches a pattern on the whitelist and it does not match anything on the blacklist.

Tasks

Working with Extensions

Working with Menus

Working with Popovers

Adding and Removing Scripts and Style Sheets

Determining Version Numbers

Storing Settings

Properties

bars

All of the bars of an extension.

readonly attribute array bars

Discussion

If there are no bars, the array is empty.

If multiple windows are open, there might be duplicates. Each bar appears separately for every window it appears in. When updating a bar, you should usually update it in every window.

Availability

Available in Safari 5.0 and later.

baseURI

The URI that corresponds to the root of the extension’s bundle.

readonly attribute DOMString baseURI

Availability

Available in Safari 5.0 and later.

bundleVersion

The version number of the extension Safari uses to check for updates.

readonly attribute DOMString bundleVersion

Discussion

Version numbers are one or more digits with period separators, such as 1 or 4.1.1.

Availability

Available in Safari 6.0 and later.

displayVersion

The version number of the extension displayed to the user in the Extensions preference pane.

readonly attribute DOMString displayVersion

Availability

Available in Safari 6.0 and later.

globalPage

The extension’s global page, or null if the extension doesn’t have a global page.

readonly attribute SafariExtensionGlobalPage globalPage

Availability

Available in Safari 5.0 and later.

menus

All of the menus of an extension.

readonly attribute array menus

Discussion

If there are no menus, the array is empty.

Availability

Available in Safari 5.1 and later.

popovers

All of the popovers of an extension.

readonly attribute array popovers

Discussion

If there are no popovers, the array is empty.

Availability

Available in Safari 5.1 and later.

secureSettings

The storage object for an extension’s secure settings.

readonly attribute SafariExtensionSecureSettings secureSettings

Discussion

Use settings for normal settings.

Availability

Available in Safari 5.0 and later.

settings

The storage object for an extension’s normal settings.

readonly attribute SafariExtensionSettings settings

Discussion

Do not store sensitive information with this method, such as passwords or credit card numbers. Use secureSettings instead.

Availability

Available in Safari 5.0 and later.

toolbarItems

All of the toolbar items of an extension.

readonly attribute array toolbarItems

Discussion

If there are no toolbar items, this is an empty array.

If multiple windows are open, there might be duplicates. Each toolbar item appears separately for every window it appears in. When updating a toolbar item, you should usually update it in every window.

Availability

Available in Safari 5.0 and later.

Methods

addContentScript

Adds a content script from a string.

DOMString addContentScript (in DOMString source, in array whitelist, in array blacklist, in boolean runAtEnd);

Parameters

source: The source code of the script.
whitelist: A list of patterns matching URLs of pages that the script should be run on.
blacklist: A list of patterns matching URLs of pages that the script should not be run on.
runAtEnd: If true, the script waits until the page is fully loaded before running.

Return Value

If the script was successfully added, a generated URL that can be used to remove the script; otherwise, null.

Discussion

If runAtEnd is true, the script is run as soon as the page has completely finished loading. Otherwise, it is run as soon as the DOM is ready, before loading subresources such as images and the contents of frames, allowing you to block resources from being loaded.

Availability

Available in Safari 5.0 and later.

addContentScriptFromURL

Adds a content script from a URL.

DOMString addContentScriptFromURL (in DOMString url, in array whitelist, in array blacklist, in boolean runAtEnd);

Parameters

url: The URL of the script.
whitelist: A list of patterns matching URLs of pages that the script should be run on.
blacklist: A list of patterns matching URLs of pages that the script should not be run on.
runAtEnd: If true, the script waits until the page is fully loaded before running.

Return Value

If the script was successfully added, the supplied URL; otherwise, null.

Discussion

Availability

Available in Safari 5.0 and later.

addContentStyleSheet

Adds a content style sheet from a string.

DOMString addContentStyleSheet (in DOMString source, in array whitelist, in array blacklist);

Parameters

source: The source code of the style sheet.
whitelist: A list of patterns matching URLs of pages that the script should be applied to.
blacklist: A list of patterns matching URLs of pages that the script should not be applied to.

Return Value

If the style sheet was successfully added, a generated URL that can be used to remove it; otherwise, null.

Discussion

The style sheet behaves like a user-level style sheet. It is loaded after user-level style sheets and it can override them, as well as overriding page-level style sheets.

Pages that are already loaded are updated to use the style sheet after it is added.

Availability

Available in Safari 5.0 and later.

addContentStyleSheetFromURL

Adds a content style sheet from a URL.

DOMString addContentStyleSheetFromURL (in DOMString url, in array whitelist, in array blacklist);

Parameters

url: The URL of the style sheet.
whitelist: A list of patterns matching URLs of pages that the script should be applied to.
blacklist: A list of patterns matching URLs of pages that the script should not be applied to.

Return Value

If the style sheet was successfully added, the supplied URL; otherwise, null.

Discussion

The style sheet behaves like a user-level style sheet. It is loaded after user-level style sheets and it can override them, as well as overriding page-level style sheets.

Pages that are already loaded are updated to use the style sheet after it is added.

Availability

Available in Safari 5.0 and later.

createMenu

Creates and returns a new menu.

SafariExtensionMenu createMenu (in DOMString identifier);

Parameters

identifier: The unique identifier for the menu.

Return Value

The new menu object.

Discussion

If identifier is not unique, an exception is thrown.

Availability

Available in Safari 5.1 and later.

createPopover

Creates and returns a new popover.

SafariExtensionPopover createPopover (in DOMString identifier, in DOMString url, in unsigned int width, in unsigned int height);

Parameters

identifier: The unique identifier for the popover.
url: The URL of the content displayed in the popover.
width: The width, in pixels. This parameter is optional; the default value is 400.
height: The height, in pixels. This parameter is optional; the default value is 300.

Return Value

The new popover object.

Discussion

The URL of the content displayed must begin with safari-extension: and it must be a resource in the extension’s bundle.

If identifier is not unique, an exception is thrown.

Availability

Available in Safari 5.1 and later.

removeContentScript

Removes the specified content script.

void removeContentScript (in DOMString url);

Parameters

url: The URL of the script being removed.

Discussion

Content scripts specified in the Info.plist are removed only for the current browser session.

Availability

Available in Safari 5.0 and later.

removeContentScripts

Removes all content scripts added by this extension.

void removeContentScripts ();

Discussion

Content scripts specified in the Info.plist are removed only for the current browser session.

Availability

Available in Safari 5.0 and later.

removeContentStyleSheet

Removes the specified content style sheet.

void removeContentStyleSheet (in DOMString url);

Parameters

url: The URL of the style sheet being removed.

Discussion

Content style sheets specified in the Info.plist are removed only for the current browser session.

Availability

Available in Safari 5.0 and later.

removeContentStyleSheets

Removes all content style sheets added by this extension.

void removeContentStyleSheets ();

Discussion

Content style sheets specified in the Info.plist are removed only for the current browser session.

Availability

Available in Safari 5.0 and later.

removeMenu

Removes the specified menu.

void removeMenu (in DOMString identifier);

Parameters

identifier: The unique identifier for the menu being removed.

Discussion

If the menu with the given identifier is currently being displayed to the user, an exception is thrown.

If there is no menu with the given identifier, this method does nothing.

Availability

Available in Safari 5.1 and later.

removePopover

Removes the specified popover.

void removePopover (in DOMString identifier);

Parameters

identifier: The unique identifier for the popover being removed.

Availability

Available in Safari 5.1 and later.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.