Safari Developer Library

Developer

SafariExtension Class Reference

Options
Deployment Target:

On This Page

SafariExtension

A SafariExtension instance represents your extension outside of the web content; an instance of the class is accessible as safari.extension. The counterpart class to SafariExtension 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 the change is made. 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. 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.

  • bars Property

    All of the bars provided by the target extension.

    Declaration

    readonly attribute array bars

    Discussion

    An instance of the SafariExtensionBar class represents a bar that your extension provides. Each instance of a bar in this property array belongs to a single extension. A bar typically appears below Safari's address bar and the Favorites bar. An extension can add any number of bars to Safari. Adding bars is optional. If there are no SafariExtensionBar instances provided by the extension, the array is empty. The native Safari bars are not affected.

    If multiple windows are open, there might be duplicate bars in the array. Each instance of a bar is indexed for every instance of SafariBrowserWindow the bar appears in. When updating a bar, you should update it in every window.

  • baseURI Property

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

    Declaration

    readonly attribute DOMString baseURI

  • globalPage Property

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

    Declaration

    readonly attribute SafariExtensionGlobalPage globalPage

  • All of the toolbar items of an extension.

    Declaration

    readonly attribute array toolbarItems

    Discussion

    If there are no SafariExtensionToolbarItem instances, this is an empty array.

    If multiple windows are open, there might be duplicate toolbar items in the array. Each toolbar item is indexed for every instance of SafariBrowserWindow it appears in. When updating a toolbar item, you should update it in every window.

  • menus Property

    All of the menus of an extension.

    Declaration

    readonly attribute array menus

    Discussion

    If there are no menus, the array is empty.

  • Creates and returns a new menu.

    Declaration

    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.

  • Removes the specified menu.

    Declaration

    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.

  • popovers Property

    All of the popovers of an extension.

    Declaration

    readonly attribute array popovers

    Discussion

    If there are no popovers, the array is empty.

  • Creates and returns a new popover.

    Declaration

    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.

  • Removes the specified popover.

    Declaration

    void removePopover (in DOMString identifier)

    Parameters

    identifier

    The unique identifier for the popover being removed.

  • Adds a content script from a string.

    Declaration

    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 on which the script should be run.

    blacklist

    A list of patterns matching URLs of pages on which the script should not be run.

    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, which allows you to block resources from being loaded.

  • Adds a content script from a URL.

    Declaration

    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 on which the script should be run.

    blacklist

    A list of patterns matching URLs of pages on which the script should not be run.

    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, which allows you to block resources from being loaded.

  • Adds a content style sheet from a string.

    Declaration

    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 to which the script should be applied.

    blacklist

    A list of patterns matching URLs of pages to which the script should not be applied.

    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.

  • Adds a content style sheet from a URL.

    Declaration

    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 to which the script should be applied.

    blacklist

    A list of patterns matching URLs of pages to which the script should not be applied.

    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.

  • Removes the specified content script.

    Declaration

    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.

  • Removes all content scripts added by this extension.

    Declaration

    void removeContentScripts ()

    Discussion

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

  • Removes the specified content style sheet.

    Declaration

    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.

  • Removes all content style sheets added by this extension.

    Declaration

    void removeContentStyleSheets ()

    Discussion

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

  • Loads content-blocking rules from an object.

    Declaration

    voidsetContentBlocker (in any contentBlocker, in function callback)

    Parameters

    contentBlocker

    A JSON string or JSON object containing content-blocking rules.

    callback

    The callback to invoke after successfully loading the content-blocking rules.

    Discussion

    This method lets you configure your content-blocking rules based on user input, overriding any previous calls to the setContentBlocker method and any content blocker set in Info.plist. Passing null or undefined will clear any content blocker the extension has previously set. The callback receives a JavaScript error object that describes any errors that occurred while compiling the content blocker. The setContentBlocker method only affects future page loads.

    See Dynamically Changing Content-Blocking Rules.

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

    Declaration

    readonly attribute DOMString displayVersion

    Availability

    Available in Safari 6.0 and later.

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

    Declaration

    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.