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:

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

baseURI

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

readonly attribute DOMString baseURI
Availability

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.

displayVersion

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

readonly attribute DOMString displayVersion

globalPage

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

readonly attribute SafariExtensionGlobalPage globalPage
Availability

menus

All of the menus of an extension.

readonly attribute array menus
Discussion

If there are no menus, the array is empty.

Availability

popovers

All of the popovers of an extension.

readonly attribute array popovers
Discussion

If there are no popovers, the array is empty.

Availability

secureSettings

The storage object for an extension’s secure settings.

readonly attribute SafariExtensionSecureSettings secureSettings
Discussion

Use settings for normal settings.

Availability

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

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

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

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.

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.