Hello and welcome to this tutorial which is primarily focused on new Safari extension developers. The main goal of this tutorial is to demonstrate you how to build your own Safari extension from A to Z. We have chosen a good example of extension which involves various features that you have to learn. Within this tutorial, you will discover how simple and easy it is to create your own Safari extension.
This tutorial is divided into two parts:
Part 1 : Configuring the extension
In this part, you prepare the environment, enable Extension builder, create a toolbar icon, create and configure the popover.
Part 2 : Building the extension
In this part, you create (start and end) injected script, work with the Global Page, work with jQuery event listener, build the extension user interface (Popover), pass messages between scripts, build extension package.
Introducing the extension
We are asked to build a Safari extension that could log all visited links while you are surfing with a Safari browser. All we need to log is the date on which the link was clicked and the URL. This is an additional specification:
- The interface containing the log should be a sidebar or a popup window that could be shown by clicking on a button located in the toolbar.
- Information about logged click (date and URL) should be placed in a single row (line).
- The URL text should be clickable and underlined, when clicked it opens the URL in a new tab or window.
- The top row should correspond with the most recent clicked link.
- The log should be viewed in a medium-sized frame (maximum size: 400×500 pixels).
- When the log passes the bottom border of the frame a vertical scroll bar must be shown.
- When a row passes the right border of the frame, an excerpt of the URL must be shown followed by (…).
The mock-up below explains pretty much everything.
PART 1: Configuring the extension
This is everything we will need to build our extension:
- Operating System: Mac OS and Windows.Linux? I’m a Linux user and unfortunately there is no official version of Safari for Linux, so I have used Ubuntu Linux in the development stage and Windows on Oracle Virtual Box to test my extension on Safari.
- A recent version of Safari browser version 5 or higher (version 5.x.x recommended)
- Your favorite IDE or simply a text editor (In this tutorial I have used Sublime Text 2, you can download it from this link)
- A Safari Developer certificate is needed in order to use Extension Builder. Register by clicking this link then go to the Safari Extension Certificate Utility and follow the instructions.
After installing Safari, the first thing you need to do is to activate the develop menu in the menu Bar in order to use the Extension Builder.
Extension Builder is a powerful extension development utility included out-of-the-box with Safari.
To activate the develop menu go to the general setting menu and choose preferences then click Advances tab (as show below). By checking the box “show develop menu in menu bar” you will activate the develop menu.
It’s time now to open Extension Builder, so go to the develop menu (see the picture below) then click on “show extension builder”.
As shown in the picture below, when you start the Extension builder the first time you will discover that there is no extension.
In the next section we will start to configure our extension.
Configure our extension
Make sure that you have launched the Extension Builder then create a new extension by clicking the (add) icon button located in the bottom-left corner of the Extension Builder window.
When the file save dialog opens, type “VisitedLinksLogger” in the file name input box, then click on the Save button. (See the picture below).
When you have clicked on the Save button, behind the scenes, a new folder has been created in the desired location. This folder is the extension project root directory (you can see the folder below) that currently contains only one file named “Info.plist” in which project settings and metadata are stored.
First step we need to do is to provide information about our extension. Fill in Extension Info section as shown in the next picture. Feel free to provide your own information.
In Extension Website Access section set Access Level to ALL, then check “Include secure pages” in order to include all web sites.
During this current step we will define the Global Page file. A Global Page contains a code that’s loaded once, when Safari launches or when your extension is enabled. This page is never displayed.
To define your Global Page go to the extension root folder ”VisitedLinksLogger.safariextension” then create a new empty file named “global.html” thereafter go back to the Extension Builder and in the Extension Global Page section select “global.html” from the drop-down list.
As advised in the beginning of this tutorial our extension must include a button with icon in the toolbar.To create this toolbar button, start by downloading the icon from this link or you can choose your own. Note that it is highly recommended that the size of the icon should be 18×18 (pixels).
Once you have the icon you must place it in the root of the extension folder.In the next step we will configure the toolbar button using the Extension Builder. In order to create a new toolbar button click on “add new toolbar item” and fill in the information (label, Image and identifier) as seen below, then select your toolbar icon from the Image drop-down list.
Right now, nothing will happen if you try to click on the tool bar icon because we haven’t specified an event for it yet.
At the beginning of this tutorial we were asked to build a popup window that would contain visited links log and this popup should be shown or hidden when we click on the toolbar icon we added previously.
The appropriate choice that meets the specifications is to use a Popover; it’s the extension user interface in which visited links log will be shown. So don’t stress about how to build Popover interface, it requires a basic HTML and JS skills.
Like a regular webpage you will need to create a single HTML file in the extension root folder then name it “popover.html”.
Now let’s move once again to the Extension Builder in order to configure our Popover. Go to the Popovers section, click on add new Popover button then enter the information as shown in the picture below.
Here is a description of each property:
- Identifier : The name of the Popover
- File: popover html file (interface).
- Width and Height: popover dimension in pixel.
Up until now we have created a popover and a toolbar button but we have not yet configured this button to show the Popover when clicked. To configure our button we to go back to Toolbar Item 1 section and select myPopover from Popover drop-down list.
Our extension needs two kinds of scripts, a Start Script and End Script. Unlike the global page and Popover file we created in the last part, injected scripts are loaded each time a page is loaded. Here is the difference between a Start Script and an End Script:
- Start script: executes when the document has been created but before the webpage has been parsed.
- End Script: executes when the DOM is fully loaded
Download JQuery library 1.7 and higher or directly from this link, once the download is completed put the library (with .js extension) in the our extension root directory, then go back to Safari Extension Builder, in Start Scripts section click on “New Script” button then select added JQuery library from the drop-down list.
Create a new empty file “listener.js” and put it under the extension root directory then repeat the same steps in Start Script.Check that you have selected “listener.js” in the End Scripts drop-down list.
We have finished extension configuration, last thing to do is to install Your Extension by clicking “Install” button on the right-top corner of Extension builder.
Once you have clicked on Install, go to Safari main window and near the address bar you should see the extension button, when you click on this a blank popover will be displayed.
We have come to the end of the first part of the tutorial. During this part we have learned how to configure a Safari extension using Extension Builder which is a powerful extension development utility included out-of-the-box with Safari Browser.
The second part of the tutorial mainly focuses on the business logic side of our extension. We will dive into Injected Scripts, Global Page, passing messages between scripts and building the GUI. Please continue with second part here.