How-To: Build a Safari Extension

The best place to start with any new programming job is a simple “Hello World.” With this walkthrough for creating a basic Safari extension, we’ll create a skeleton to build a toolbar button from. If you know HTML, CSS, and JavaScript, you are already 95 percent of the way to your first Safari extension.

To learn more about using Safari, check out our Safari 101 screencast on TechUniversity (subscription required).

Get Registered

Safari Extensions need to be signed to be installed, so before writing any code, head over to the Safari Developer Center to register as a Safari Developer. It’s free to join, and binds to your Apple ID from your MobileMe or iTunes account. You will have to follow the steps in the online wizard to create your own signed certificate, which you’ll use to create your extension. Once the certificate is created, just double-click to install it. Safari will automatically use this certificate when building your extensions.

Enable the Develop Menu & Extensions

Building Safari Extensions starts inside of Safari, but to get there you have to enable the Develop menu. To do so, go to Safari Preferences, select the “Advanced” tab on the end, then check the last option on the page, labeled “Show Develop menu in menu bar.”

You’ll see the new menu appear, click on it, check “Enable Extensions,” and select “Show Extension Builder.”

Create a New Extension

In the Extension Builder, click on the plus sign in the bottom left hand corner, then select “New Extension.” Choose a place to put the source code for your extension; I always put my code in a “Code” folder under my home directory. Give it a meaningful name, like “Hello World.” In the new form, fill out the “Extension Info” section, and change the Bundle Identifier under “Extension Details” to com.theappleblog.helloworld. Under “Extension Website Access” set “Access Level” to All, and check “Include Secure Pages.”

Open the Project Folder

This is where it gets a little confusing. It seems like Apple would like you to be able to build the entire extension in Safari, but they only give you half the tools to do it. The next option on the list is “Extension Global Page,” in a drop down menu, but there is no option to create one. Once the extension project folder is created (it’ll be in that folder you selected when you created your new extension), you need to open it up and add a couple of files to it. Since we are building a toolbar extension, you will need two files: an image in PNG format, and an HTML file which will hold our JavaScript. You can download both the HTML and the PNG file to use here. Add those two files to the project folder, and switch back to the Extension Builder. Now, when you click on the drop down menu under Extension Global Page, you should see the option for “global.html”, go ahead and select that.

Next, in the “Extension Chrome” section, click the “New Toolbar Item” button. That should drop down a new form with seven options. Fill out the form like this example:

Write Some Code

Open the global.html file in your favorite text editor. In this file is all of the logic for the extension. When our icon on the Safari toolbar is pressed, it will send an event named “sayHello”. Safari will parse our global.html file and see if that event is defined. Since we are checking for that event with the line if (event.command === “sayHello”), our JavaScript will trigger whenever that button is pressed. It’s important that the command defined in the Extension Builder matches the event.command we are looking for in global.html. When the event is matched, Safari will run any JavaScript inside the if statement which, in our case, is a simple alert box.

If you are familiar with JavaScript, you’ll be able to tell right away what you can do here. If not, just know that you can replace the line alert(“Hello World”); with whatever valid JavaScript you’d like.

With the Toolbar Items menu is filled out, you should be ready to build the extension. Click on the “Build Package” button in the top right corner of the Extension Builder. Save the extension to your desktop, then double-click on it to install it in Safari. You should notice a new button on the toolbar sporting the nifty TAB logo. Click on it, and you should see an alert window pop up saying hello.

Debug Workflow

If you don’t already have the global.html file open, go ahead and open it in your favorite text editor again. Change the text of the alert to say “Hello Jon,” or whatever you would like. Save the file without closing the text editor, then switch back to the Extension Builder and click “Reload.” Now switch to Safari and hit your button again, it should now display the new text in the alert window.

Build Something Awesome

This article has barely scratched the surface of what Safari Extensions can do. For more in-depth information, read through the Developers Guide on the Apple web site. I can’t wait to see what awesome extensions creative developers come up with.