Safari Extensions Development Guide Contents About Safari Extensions 9 At a Glance 10 What’s the Difference Between an Extension and a Plug-in? 10 Extensions Have Their Own JavaScript API 10 Extensions Run in a Sandbox 10 You Create Extensions Right in Safari 11 You Can Define User Settings in Extension Builder 11 Debug Your Extension with Safari’s Built-in Tools 12 Update Your Extension Automatically from the Web 12 Prerequisites 12 See Also 12 Extensions Overview 13 Safari Extension Certificates 13 What Your Extension Can Do 13 The Extension Parts List 14 Extension Architecture 15 The Safari Extensions JavaScript API 16 Classes and Properties 16 The Application and Extension Objects 17 Web Content Interaction 17 Events—Commands, Messages, and Proxies 18 How to Create Extensions 19 Global HTML Page 20 Extension Bar Files 20 Popover Files 21 Injected Scripts and Style Sheets 22 The plist Files 22 Security 23 Don’t Insert Imported Text Using innerHTML or document.write 23 Don’t Use eval with Imported Text 23 Don’t Use HTTP to Add HTML, CSS, or Scripts 23 Private Browsing 23 2015-06-08 | Copyright © 2015 Apple Inc. All Rights Reserved. 2 Contents Using Extension Builder 25 Before You Begin 25 Opening Extension Builder 25 The Extension Builder Interface 26 Building a Simple Extension 30 Accessing Resources Within Your Extension Folder 32 Using Relative URLs 32 Using Absolute URLs 33 Example: Loading a Background Image in CSS 33 Security 34 Adding Extension Bars 35 About Extension Bars 35 The extension.bars Array 36 Domain, URLs, and Access 36 Displaying Content in an Extension Bar 37 Creating an Extension Control Bar 37 Working with Windows and Tabs 39 Interacting with Injected Scripts 41 Message-Passing Example 42 Adding a Global HTML Page 45 Adding a Global Page in Extension Builder 45 Handling Toolbar Items 46 Handling Contextual Menu Items 46 Support Logic for Extension Bars and Popovers 47 Support Logic for Injected Scripts 50 Working with Windows and Tabs 50 Adding Buttons to the Main Safari Toolbar 52 Creating an Image 52 Setting Up Extension Builder 53 Responding to Commands 55 Deciding Where to Respond 56 If You Respond from a Global HTML Page 57 If You Respond from an Extension Bar 57 Example: Implementing a Reload Button 57 Adding Extension Menus 59 2015-06-08 | Copyright © 2015 Apple Inc. All Rights Reserved. 3 Contents Setting Up Menus in Extension Builder 59 Creating an Image (Optional) 61 Responding to Events 61 Modifying the Menu Dynamically 62 Adding Popovers 64 Creating the Popover Content File 64 Setting Up Popovers in Extension Builder 66 Responding to Events 67 Creating a Popover at Runtime 67 Adding Contextual Menu Items 69 Context Menu Events 69 Adding a Contextual Menu Item Using Extension Builder 70 Responding to Commands 70 Modifying the Default Behavior 71 Adding Context Information 72 Disabling the Contextual Menu 72 Adding Contextual Menu Items Programmatically 73 Changing the Contextual Menu Item Title 73 Deciding Where to Respond 74 If You Respond from a Global HTML Page 74 If You Respond from an Extension Bar 74 Example: Implementing a New Window Contextual Menu Item 74 Injecting Scripts 76 About Injected Scripts 76 Adding a Script 77 Injecting Styles 79 About Injected Style Sheets 79 Adding a Style Sheet 79 The Windows and Tabs API 81 SafariApplication 81 SafariBrowserWindow 82 SafariBrowserTab 82 Events 82 Working with Safari Reader 84 2015-06-08 | Copyright © 2015 Apple Inc. All Rights Reserved. 4 Contents Reader Events 84 Reader Methods and Properties 85 Injecting Style Sheets and Scripts into Reader 85 Injecting into Reader Dynamically 86 Sending Messages to Scripts Injected into Reader 86 Messages and Proxies 87 Message Structure 87 Sending Messages to an Injected Script 88 Tabs in Safari 6.1 and Later 89 Receiving Messages from an Injected Script 89 Example: Calling a Function from an Injected Script 90 Blocking Unwanted Content 92 Access and Permissions 95 The Global HTML Page, Popovers, and Extension Bars 95 Injected Scripts and Style Sheets 95 Extension Website Access 96 Whitelists and Blacklists 97 Settings and Local Storage 99 How to Create User Settings 99 Hidden Settings 100 Text Field Settings 100 Checkbox Settings 101 Slider Settings 101 Pop-Up Button Settings 102 List Box Settings 102 Radio Buttons Settings 103 Groups and Separators 103 How to Use the Settings API 103 Using HTML5 Local Storage 104 Debugging Extensions 106 Debugging Extension Bars 106 Debugging Injected Scripts 107 Debugging a Global HTML Page 108 Distributing Your Extension 109 Putting Your Extension on a Web Server 109 2015-06-08 | Copyright © 2015 Apple Inc. All Rights Reserved. 5 Contents Submitting Your Extension to the Safari Extensions Gallery 110 Updating Extensions 111 Document Revision History 113 2015-06-08 | Copyright © 2015 Apple Inc. All Rights Reserved. 6 Figures and Listings Extensions Overview 13 Figure 1-1 The extension architecture 16 Figure 1-2 Extension bar example 21 Using Extension Builder 25 Figure 2-1 Enabling the developer tools 25 Figure 2-2 Extension Builder interface 27 Figure 2-3 Access restrictions 28 Figure 2-4 Hello World 31 Listing 2-1 helloworld.html 30 Adding Extension Bars 35 Figure 4-1 Music player toolbar 39 Figure 4-2 Reference extension bar 41 Figure 4-3 Before and after 44 Listing 4-1 Music player bar 37 Listing 4-2 Safari developer reference bar 40 Listing 4-3 Extensionbar.html 42 Listing 4-4 Injected.js 43 Adding a Global HTML Page 45 Listing 5-1 Moving logic to your global page 47 Adding Buttons to the Main Safari Toolbar 52 Figure 6-1 Anti-aliased text in black on transparent background 53 Figure 6-2 Adding toolbar items 54 Listing 6-1 Reload command and validate handlers 57 Adding Extension Menus 59 Figure 7-1 Extension Menus pane 59 Figure 7-2 Attaching a menu to a toolbar item 60 Adding Popovers 64 Figure 8-1 Popovers pane 66 2015-06-08 | Copyright © 2015 Apple Inc. All Rights Reserved. 7 Figures and Listings Figure 8-2 Associating a popover with a toolbar item 66 Adding Contextual Menu Items 69 Figure 9-1 Contextual Menu Items pane 70 Figure 9-2 Adding a menu item 75 Listing 9-1 New window command handlers 75 Injecting Scripts 76 Figure 10-1 Specifying injected content 77 Listing 10-1 Modifying a webpage using DOM insertion 77 Injecting Styles 79 Figure 11-1 Specifying an injected style sheet 80 Working with Safari Reader 84 Listing 13-1 Reader “available” handler 84 Messages and Proxies 87 Listing 14-1 Injected.js 90 Listing 14-2 Global.html 91 Listing 14-3 Blocking content 92 Access and Permissions 95 Figure 15-1 Access to secure pages 97 Figure 15-2 Whitelist and Blacklist 97 Settings and Local Storage 99 Figure 16-1 Settings pane 99 Figure 16-2 Setting types 100 Figure 16-3 Extension storage 105 Listing 16-1 Responding to settings changes 104 Debugging Extensions 106 Figure 17-1 Inspecting extension bars 106 Figure 17-2 Inspecting injected scripts 107 Figure 17-3 Inspect Global Page button 108 2015-06-08 | Copyright © 2015 Apple Inc. All Rights Reserved. 8 About Safari Extensions Safari extensions provide a way for you to add features to the Safari browser. You can add custom buttons to the Safari toolbar, create bars of your own, add contextual menu items, display content in bars or tabs, and inject scripts and style sheets into webpages. In Safari 5.1 and later, you can add menus and popovers to toolbar items. You write Safari extensions using HTML, CSS, and JavaScript. A JavaScript API for extensions allows you to interact with the browser and web content in ways that scripts normally can’t. Important: To develop extensions for Safari, you need to sign up for the Apple Developer Program online at http://developer.apple.com. After joining the program, you must obtain a signed certificate in order for your extension to work; the extension will not load until your certificate is installed. To request a certificate, follow the “Certificates, Identifiers & Profiles” link from the Developer Member Center homepage. Safari extensions are supported in Safari 5.0 and later on the desktop (Mac and Windows). Safari extensions are not currently supported on iOS. 2015-06-08 | Copyright © 2015 Apple Inc. All Rights Reserved. 9 About Safari Extensions At a Glance At a Glance Safari extensions let you add persistent items to Safari—controls, menus and menu items, local or web-based content, and scripts that modify the content Safari presents. What’s the Difference Between an Extension and a Plug-in? A plug-in can add support for media types to a browser. An extension can add many different features. Extensions and plug-ins both expand a browser’s capabilities. Plug-ins let browsers display media that the browser can’t display natively or provide a particular media player experience. Extensions personalize and enhance the browser itself and can interact with HTML web content. A plug-in can’t interact with webpages except to display media of specific MIME types. A plug-in cannot add features to Safari, such as toolbar buttons or contextual menu items. A plug-in is a binary file that interfaces with the browser but is essentially an app in itself—the browser hands off specific media types to the plug-in to handle. An extension is a collection of HTML, JavaScript, and CSS files that the browser uses to expand its feature set. Extensions allow you to reformat webpages, block unwanted sites or unwanted material, display RSS feeds and other data in a bar or window, and do thousands of other things that plug-ins can’t do.