You write Safari extensions using HTML, CSS, and JavaScript, with support for HTML5 and CSS3. A JavaScript API for extensions allows you to interact with the browser and web content in ways that scripts normally can’t.
Important: To develop extensions for Safari, you need to sign up for the Safari developer program online, at http://developer.apple.com. You need a signed certificate before your extension can be installed.
Safari extensions are supported in Safari 5.0 and later on the desktop (Mac OS X and Windows). Safari extensions are not currently supported on iOS.
At a Glance
Safari extensions let you add persistent items to Safari—controls, contextual menu items, local or web-based content, and scripts that modify the content Safari presents.
What’s the Difference Between an Extension and a Plug-in?
A plug-in can add support for media types to a browser. An extension can add many different features.
Extensions and plug-ins both expand a browser’s capabilities. Plug-ins let browsers display media that the browser can’t display natively or provide a particular media player experience. Extensions personalize and enhance the browser itself and can interact with HTML web content.
A plug-in can’t interact with webpages except to display media of specific MIME types. A plug-in cannot add features to Safari, such as toolbar buttons or contextual menu items.
A plug-in is a binary file that interfaces with the browser but is essentially an application in itself—the browser hands off specific media types to the plug-in to handle.
An extension is a collection of HTML, JavaScript, and CSS files that the browser uses to expand its feature set. Extensions allow you to reformat webpages, block unwanted sites or unwanted material, display RSS feeds and other data in a bar or window, and do thousands of other things that plug-ins can’t do.
Extensions have access to a special JavaScript API that lets them access the Safari application and web content. This API is documented in Safari Extensions Reference.
Relevant Chapter: “Extensions Overview”
Extensions Run in a Sandbox
Safari Extensions run in their own "sandbox" or container area. The designated container area for Safari Extensions is the execution of normal HTML, CSS, and JavaScript within the Safari application, and the specific JavaScript APIs documented here and the Safari Extensions Reference.
Important: Launching an installed Safari plug-in from an extension by using the HTML <OBJECT>, or <EMBED> elements is strongly discouraged, but not prohibited. Any other use of an extension as a method to launch code that executes outside of the Safari application is prohibited.
You Create Extensions Right in Safari
You create extensions using Extension Builder, which is built into Safari 5.0 and later. Open Extension Builder, tell it to create an extension folder, drag your HTML, JavaScript, and CSS style sheets into the folder, fill out the fields in Extension Builder, and you’re good to go.
The main ingredients of an extension are:
- Global HTML page—code that’s loaded once, when Safari launches or when your extension is enabled. This is the ideal place to put the code for buttons in the Safari toolbar or contextual menus. This page is never displayed; it’s just for logic.
- Extension bars (HTML, CSS, JavaScript, media)—extension bars can display controls and HTML content; extension bar files have access to the Safari application and can also contain code for Safari toolbar buttons or contextual menus.
- Injected scripts—scripts to be injected into browser content. These scripts can read, modify, add to, or delete content.
- Injected style sheets—user style sheets that can modify the display of web content by overriding or adding to the styles normally applied.
- Icon image—the icon for your extension.
You Can Define User Settings In Extension Builder
Your extension can have its own user settings, accessible to the user in the Extensions pane of Safari preferences. You define the settings, user interface items, and default values using Extension Builder.
There is also a settings API similar to HTML5 local storage for accessing and modifying settings programatically. You can use encrypted settings for security.
Relevant Chapter: “Settings and Local Storage”
Debug Your Extension With Safari’s Built-In Tools
You can use the Safari developer tools to help debug your extension. The developer tools report HTML errors and profile JavaScript, log messages to the console, and let you interactively set breakpoints, get variable values, and call functions. The debugging tools are supported for extension bars, global HTML pages, and injected scripts. Each extension bar and global page has its own console.
Relevant Chapter: “Debugging Extensions”
Update Your Extension Automatically from the Web
Safari provides a method to support checking for updates to an extension automatically: the Update Manifest. You specify a web address, and Safari periodically compares the installed version of your extension with the latest version on your website. If your website has a newer version, Safari offers the user an update.
Relevant Chapter: “Updating Extensions”
Prerequisites
You need to be familiar with HTML, JavaScript, and the basics of CSS. Familiarity with HTML5 and CSS3 is helpful. To add a button to the toolbar, you need to be able to create an image with an alpha channel (transparency).
See Also
Safari Extensions Reference - the JavaScript classes, methods, and properties that only Safari Extensions can use.
Safari DOM Additions Reference - the classes, methods, and properties that Safari exposes to JavaScript that are not available in all browsers.
Safari User Guide for Web Developers - the built-in web development tools that come with Safari.
Safari Extensions Conversion Guide - a guide to converting extensions written for other browsers.