15 Comments

Summary:

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 using just a little bit of frontend code.

safariextensionbuilder_thumb

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.

Related stories

  1. Someone pleeeease build a framework for building in one step a Safari extension, a Chrome extension and a Firefox Jetpack extension…

    Share
    1. Mason Glidden Sunday, June 13, 2010

      Someone ported AddBlock from Chrome to Safari, and made a porting library.

      Not sure how well it works, but here it is:
      http://safariadblock.com/port.js

      Share
  2. So if all logic is done via JavaScript how does the GMail checker work or do Google have some JavaScript API to check your gmail message count?

    Share
    1. Ignore that, just looked at the source code for GMail Checker

      Share
  3. Thanks for this. This laid out extensions for me very simply :)

    Share
    1. I’m glad you liked it!

      Share
  4. ooww, i’ve just known it if in safari we can add extension..
    nice info..

    Share
  5. Hi,
    Thanks for this.
    I duplicated your instructions and it worked perfectly.
    I am trying to make a new extension that will simply open a new browser window.
    I replaced the alert line with:
    window.open();
    but I can’t get it to work.
    please help! thanks.

    Share
    1. I was working on my own problem (selectively injecting CSS) but came across a reference that might help you.

      Share
      1. Thank you- substituted that line, and it worked.

        Share
  6. I followed the tutorial and it worked well. However I don’t get the significance of the bundle identifier. Without putting your “com.theappleblog.helloworld” it won’t work.

    What is the significance of the bundle identifier?

    Thanks.

    Share
  7. Thanks so much for this tutorial!

    Share
  8. Everything worked for me, except the new toolbar icon is showing up as a black box instead of the green AppleBlog-esque image that it supposedly should be. And I have the Image setting for the Toolbar Item set to tabicon.png. Thoughts

    Share
    1. The toolbar item can’t actually show a coloured icon or picture like that. What it does is use the transparent/non-ttransparent areas of the image to work out which parts of the button should be black and which shouldn’t.

      To test that out, create a 16×16 pixels image, make a fancy shape and colour it in all different colours. Then save it into the project folder as a PNG and use Extension Builder to change the toolbar button image to that one. It’ll show up as just black in the shape of whatever you drew.

      Share
      1. Ah, so it works like the Tab-Bar Icons on the iPhone. I guess the tabicon.png that is included in the zip for this tutorial needs to be adjusted accordingly.

        Share

Comments have been disabled for this post