Safari Developer Library

Developer

SafariExtension Class Reference

Options
Deployment Target:

On This Page

SafariExtension

Inheritance


  • SafariExtension

Conforms To


Not Applicable

Import Statement


Not Applicable Not Applicable

Availability


Available in Safari 5.0 and later.

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. 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 of an extension.

    Declaration

    JavaScript

    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 Property

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

    Declaration

    JavaScript

    readonly attribute DOMString baseURI

    Availability

    Available in Safari 5.0 and later.

  • globalPage Property

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

    Declaration

    JavaScript

    readonly attribute SafariExtensionGlobalPage globalPage

    Availability

    Available in Safari 5.0 and later.

  • toolbarItems Property

    All of the toolbar items of an extension.

    Declaration

    JavaScript

    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.

  • menus Property

    All of the menus of an extension.

    Declaration

    JavaScript

    readonly attribute array menus

    Discussion

    If there are no menus, the array is empty.

    Availability

    Available in Safari 5.1 and later.

  • Creates and returns a new menu.

    Declaration

    JavaScript

    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.

  • Removes the specified menu.

    Declaration

    JavaScript

    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.

  • popovers Property

    All of the popovers of an extension.

    Declaration

    JavaScript

    readonly attribute array popovers

    Discussion

    If there are no popovers, the array is empty.

    Availability

    Available in Safari 5.1 and later.

  • Creates and returns a new popover.

    Declaration

    JavaScript

    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.

  • Removes the specified popover.

    Declaration

    JavaScript

    void removePopover (in DOMString identifier);

    Parameters

    identifier

    The unique identifier for the popover being removed.

    Availability

    Available in Safari 5.1 and later.

  • Adds a content script from a string.

    Declaration

    JavaScript

    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.

  • Adds a content script from a URL.

    Declaration

    JavaScript

    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.

  • Adds a content style sheet from a string.

    Declaration

    JavaScript

    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.

  • Adds a content style sheet from a URL.

    Declaration

    JavaScript

    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.

  • Removes the specified content script.

    Declaration

    JavaScript

    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.

  • Removes all content scripts added by this extension.

    Declaration

    JavaScript

    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.

  • Removes the specified content style sheet.

    Declaration

    JavaScript

    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.

  • Removes all content style sheets added by this extension.

    Declaration

    JavaScript

    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.

  • displayVersion Property

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

    Declaration

    JavaScript

    readonly attribute DOMString displayVersion

    Availability

    Available in Safari 6.0 and later.

  • bundleVersion Property

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

    Declaration

    JavaScript

    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.

  • settings Property

    The storage object for an extension’s normal settings.

    Declaration

    JavaScript

    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.

  • secureSettings Property

    The storage object for an extension’s secure settings.

    Declaration

    JavaScript

    readonly attribute SafariExtensionSecureSettings secureSettings

    Discussion

    Use settings for normal settings.

    Availability

    Available in Safari 5.0 and later.