| Technology area | Safari Extensions |
| 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 only removes it from the current browser session.
Whitelists and blacklists. A content script or style sheet may specify a blacklist and a whitelist; both are optional. See “The Extension Builder Interface” in Safari Extensions Development Guide for a description of the pattern format. 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.
addContentScript
addContentScriptFromURL
addContentStyleSheet
addContentStyleSheetFromURL
removeContentScript
removeContentScripts
removeContentStyleSheet
removeContentStyleSheets
All of the extension’s bars.
readonly attribute array bars
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.
The URI that corresponds to the root of the extension’s bundle.
readonly attribute DOMString baseURI
The extension’s global page, or null if the extension doesn’t have a global page.
readonly attribute SafariExtensionGlobalPage globalPage
A storage object for the extension’s secure settings.
readonly attribute SafariExtensionSecureSettings secureSettings
Use settings for normal settings.
A storage object for the extension’s normal settings.
readonly attribute SafariExtensionSettings settings
Do not store sensitive information with this method, such as passwords or credit card numbers. Use secureSettings instead.
All of the extension’s toolbar items.
readonly attribute array toolbarItems
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.
Adds a content script from a string.
DOMString addContentScript (in DOMString source, in array whitelist, in array blacklist, in boolean runAtEnd);
The source code of the script.
A list of patterns matching URLs of pages that the script should be run on.
A list of patterns matching URLs of pages that the script should not be run on.
If true, the script waits until the page is fully loaded before running.
If the script was successfully added, a generated URL that can be used to remove the script; otherwise, null.
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.
DOMString addContentScriptFromURL (in DOMString url, in array whitelist, in array blacklist, in boolean runAtEnd);
The URL of the script.
A list of patterns matching URLs of pages that the script should be run on.
A list of patterns matching URLs of pages that the script should not be run on.
If true, the script waits until the page is fully loaded before running.
If the script was successfully added, the supplied URL; otherwise, null.
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.
DOMString addContentStyleSheet (in DOMString source, in array whitelist, in array blacklist);
The source code of the style sheet.
A list of patterns matching URLs of pages that the script should be applied to.
A list of patterns matching URLs of pages that the script should not be applied to.
If the style sheet was successfully added, a generated URL that can be used to remove it; otherwise, null.
The style sheet behaves like a user-level style sheet. It is loaded after user-level style sheets, so 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.
DOMString addContentStyleSheetFromURL (in DOMString url, in array whitelist, in array blacklist);
The URL of the style sheet.
A list of patterns matching URLs of pages that the script should be applied to.
A list of patterns matching URLs of pages that the script should not be applied to.
If the style sheet was successfully added, the supplied URL; otherwise, null.
The style sheet behaves like a user-level style sheet. It is loaded after user-level style sheets, so 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.
void removeContentScript (in DOMString url);
The URL of the script being removed.
Content scripts specified in the Info.plist are removed only for the current browser session.
Removes all content scripts added by this extension.
void removeContentScripts (void);
Content scripts specified in the Info.plist are removed only for the current browser session.
Removes the specified content style sheet.
void removeContentStyleSheet (in DOMString url);
The URL of the style sheet being removed.
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.
void removeContentStyleSheets (void);
Content style sheets specified in the Info.plist are removed only for the current browser session.
Last updated: 2010-08-03