Using Extension Builder

You can use Safari’s Extension Builder tool to build, install, reload, and uninstall extensions.

Before You Begin

Before you can build and install an extension, you need to install a developer certificate. For more information, see Developer Certificates.

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 Web Inspector Guide).

Figure 2-1  Enabling the developer tools

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.

Figure 2-2  Extension Builder interface

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:

Building a Simple Extension

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

  1. An Apple Developer certificate. For more information, see Developer Certificates.

  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>
<title>Hello World</title>
<body>Hello World!</body>

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.

    Figure 2-4  Hello World

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.