Using Extension Builder

Before You Begin

Before you can build and install an extension, you need to install a developer certificate. You obtain a certificate by signing up for the Safari Developer Program at http://developer.apple.com. Install your certificate by double-clicking the certificate file. This launches Keychain Access on Mac, or the Certificate Import Wizard on Windows.

Opening Extension Builder

To access Extension Builder, first enable the Safari developer tools by clicking “Show Develop menu in menu bar” in the Advanced pane of Safari preferences, as shown in Figure 2-1. (To learn more about the Safari developer tools, see Safari Developer Tools Guide).

Next, choose Show Extension Builder from the Develop menu. If no previous work has been done in Extension Builder, the Extension Builder window is largely empty except for the + button. Don’t worry; that’s normal.

The Extension Builder Interface

Click the + button to create a new folder to hold your extension. You are prompted to either Add Extension (choose an existing extension folder) or create a New Extension. Choose New Extension. You’re prompted to give the folder a name and location. The folder is created with the .safariextension extension.

A generic extension icon is displayed with a label derived from your folder name. Add your extension’s HTML, CSS, JavaScript, and media files to this folder. If you include an Icon.png or Icon-64.png file, the icon changes to show it, otherwise the icon remains generic. Your certificate information is also displayed. The information is shown in the format: Safari Developer: (Developer ID) email@address.

Click your extension’s icon to bring up the main Extension Builder interface, as shown in Figure 2-2.

At the top of the window is your extension’s icon, title, the name of the extension folder, and your developer ID. The following interactive fields are displayed below:

• Display Name—The visible name of your extension. Required.

• Author—Your name or your company name.

• Description—A brief description of what your extension does.

• Website—The website that users should visit for information and support.

• Bundle Identifier—OS X bundle identifiers are alphanumeric strings in reverse DNS format. Use your type of organization (com, gov, edu, org, and so on), your company name, and the extension name, separated by dots. For example, com.MyCompany.myExtension. Required.

• Update Manifest—The URL to use when checking for available updates. For more information, see “Updating Extensions.”

• Display Version—The displayed version number for your extension. Required.

• Bundle Version—The internal version number used by the operating system. One or more digits with period separators, such as 1 or 4.1.1. This is the version number Safari uses when checking for updates. Required.

• Extension Website Access—Use this field to restrict your extension’s access to external websites. Your choices are as follows:

  • None—Your extension cannot access webpages by injecting scripts or style sheets.

  • Some—Your extension has access to webpages specified in the Allowed Domains field. If this field is left blank, your extension has no website access.

  • All—Your extension can access webpages from any domain.

  If you choose Some or All, you can further choose to allow your extension access to secure sites (HTTPS URLs) or not, as shown in Figure 2-3.

  

  When listing domains and pages your extension is allowed to access, you can use the asterisk as a wildcard character. For more information on access and permissions, see “Access and Permissions.”

• Global Page File—A page loaded once, when Safari loads your extension. This page is not displayed. It is intended for JavaScript functions that handle response to commands, messages, and other events.

• Database Quota—The space you want to allocate for HTML5 client-side database storage for your extension. For more information, see “Settings and Local Storage.”

• Bars—An extension bar is space below the bookmarks bar and above the tab bar reserved for your extension. If you want to display persistent data in the browser frame, create an extension bar. Add an HTML file to your extension folder as the source for your extension bar and click New Bar, then choose the file from the pop-up menu. You are prompted to enter a label to identify your bar in the View menu. For more information, see “Adding Extension Bars.”

• Context Menu Items—Items your extension adds to contextual menus. Click New Context Menu Item to add an item. The interface expands to allow you to enter a title, identifier, and command for each context menu item. For more information, see “Adding Contextual Menu Items.”

• Toolbar Items—Buttons you are adding to the main Safari toolbar (not an extension bar). Click New Toolbar Item and you are prompted to enter a label, palette label, tooltip, image file, identifier, and command. The code that listens for the button click and executes the command goes in either your global HTML page or an extension bar. For details, see “Adding Buttons to the Main Safari Toolbar.”

• Menus—Pop-up menus you associate with a toolbar item you have created.

• Popovers—Pop-up windows containing HTML content that you associate with a toolbar item you have created.

• Start Scripts—Scripts to execute before a webpage is interpreted, usually a script that blocks unwanted content.

• End Scripts—Scripts to execute when the page load event occurs (roughly when a function specified in the body onload attribute would execute). Most scripts are End Scripts.

  For more information, see “Injecting Scripts.”

• Style Sheets—User style sheets to apply to browser content. For more information, see “Injecting Styles.”

• Whitelist—When injecting scripts or style sheets, only URLs specified in the whitelist are affected. If no whitelist is specified, all URLs are on the whitelist.

• Blacklist—When injecting scripts or style sheets, any URLs specified on the blacklist are skipped (scripts and style sheets are not injected).

  Add URLs to the whitelist or blacklist by clicking New URL Pattern.

  A URL pattern can include the * character to match any string. The * character can be used in any part of the Domain or Path, but not the Scheme.

  Examples:

  • http://*/*—matches all HTTP URLs.

  • http://*.apple.com/*—matches all webpages from apple.com.

  • http://developer.apple.com/*—matches all webpages from developer.apple.com.

  • https://secure.A_BankForExample.com/accounts/*—matches all webpages from the accounts directory of secure.A_BankForExample.com that are delivered over HTTPS.

  • http://www.example.com/thepath/thepage.html—matches one webpage.

  For more information, see “Access and Permissions.”

• Extension Settings—Persistent settings for your extension. Click New Settings Item to add a setting. Hidden settings are not displayed to the user. All other settings appear in a pane for your extension in Safari preferences. Each setting has a key (identifier), a type (such as a checkbox or text field), and an optional default value. For details, see “Settings and Local Storage.”

Building a Simple Extension

In order to create an extension, you need a minimum of two files:

1. A certificate (to obtain a certificate, join the Safari Developer Program at http://developer.apple.com).

   Install your certificate using Keychain Access (OS X) or the Extension Certificate Wizard (Windows). Double-clicking the certificate file launches the appropriate application.

2. A resource file, such as an HTML page, script, or CSS file. To create an extension bar, you need an HTML file.

   As the resource file for this example, create an HTML page that displays “Hello World” and save it as helloworld.html. An example is shown in Listing 2-1.

Listing 2-1  helloworld.html

<!DOCTYPE html>

<html>

<head>

<title>Hello World</title>

</head>

<body>Hello World!</body>

</html>

Follow these steps to create an extension bar that displays “Hello World”.

1. Click the + button in Extension Builder and choose New Extension. Extension Builder creates an empty folder with the extension .safariextension and prompts you for a name and location. Name the new extension folder HelloWorld and have Extension Builder put it in your Documents folder. A generic icon is displayed with the name HelloWorld.

   This brings up the main Extension Builder interface, as shown in Figure 2-2.

2. Put the helloworld.html file in the HelloWorld.safariextension folder.

   (You don’t use Extension Builder for this step—just drag the file into the folder.)

3. Click New Bar in Extension Builder, enter a label such as Hello World, and choose helloworld.htmlfrom the pop-up menu. This tells Extension Builder to use helloworld.html as the source file for a new extension bar. The label appears in the View menu.

4. Click the Install button. Extension Builder creates a compressed folder with the extension .safariextz. This is your extension package. The package is installed, and a new extension bar is added to your browser window that displays “Hello World,” as illustrated in Figure 2-4.

   

Notice that you can toggle the bar’s visibility by name in the View menu, and disable or enable the extension itself in the Extensions pane of Safari preferences. You can edit and save helloworld.html to experiment with it. Click Reload in Extension Builder to build and install the modified version.