About Safari Extensions

Safari extensions provide a way for developers to add features to the Safari browser. You can add custom buttons to the Safari toolbar, create bars of your own, add contextual menu items, display content, and inject scripts and stylesheets into webpages. This lets your extension behave in a wide variety of ways.

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.

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 ordinary 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/or 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 literally thousands of other things that plug-ins can’t do.

The Extension Architecture Has Two Parts

You can logically divide extensions into two parts: a part that interacts with the Safari application, and a part that interacts with web content.

The part of an extension that interacts with the Safari application resides in a global HTML page and/or in extension bars. The part that interacts with web content resides in JavaScript files or CSS stylesheets that are injected into content pages.

There is a strict division between these two parts, but you can send messages between them. Figure I-2 illustrates the architecture.

Extensions don't require both of these parts—an extension can operate just on the Safari application or just on web content.

Extensions Have Their Own JavaScript API

Extensions have access to a special JavaScript API that lets them access the Safari application and web content. Safari Extensions Reference documents the complete API.

The extensions API has four main parts:

• Safari Application APIs‚Äîlet your extension work with windows and tabs.

• Safari Extension APIs‚Äîlet you add and remove injected scripts, injected stylesheets, toolbar items, and contextual menu items from your extension.

• Injected Scripts‚Äîlet you read and modify web content.

• Events‚Äîlet you respond to mouse clicks on toolbar items or contextual menu items, and pass messages between the different parts of your extension.

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 stylesheets 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 stylesheets‚Äîuser stylesheets 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 Your Settings Using 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.

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.

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.

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).

---