Customize a toolbar item for your Safari App Extension.
Safari has a user-customizable toolbar that can contain a selection of buttons. A Safari App Extension can provide a new toolbar item, and when the Safari App Extension is enabled, that item is added to the toolbar by default. The user may choose to hide your toolbar item by customizing the toolbar.
Your app extension can enable or disable the toolbar item or add badged text to it. When clicked, the toolbar item can either execute a command or display a popover. The decision of which behavior to implement is made at design time. (Popovers are described in more detail in Display a Popover for a Toolbar Item.)
Adding a toolbar item requires three steps:
Creating an image
Filling out the appropriate fields in the
Adding logic that’s triggered when the toolbar button is clicked
To learn how to add a toolbar item, see About Contextual Menu and Toolbar Item Keys.
Localize the Toolbar Label
Info file and include localized text for a custom key based on your toolbar identifier. For example, to provide a Polish translation for a toolbar item whose identifier is
translate, add the following entry to your strings file:
For more information, see Localizing Property List Values.
Dynamically Change the Image of a Toolbar Item
To update a toolbar item’s image dynamically, Safari uses the
set method for
SFSafari. Setting the image to
nil sets the default image.
Adjust the State of the Toolbar Item
Your app extension has some control over the toolbar item:
The app extension can enable or disable the button. Use
setif your toolbar item is usable only some of the time.
The app extension can add a string to the toolbar item as a badge. For example, if your extension contains a list of items that the user can see by clicking the button, you might badge the toolbar item using
setwith the number of unread items.
State changes can be triggered in either of these ways:
Safari can decide, based on the user's actions, that the button's state might need to be changed.
Your app extension can force a state change to happen explicitly.
Validate the Safari Toolbar Item
When an event occurs that may require your toolbar’s state to change, Safari calls your app extension’s event handler. The event handler receives parameters that indicate the window the toolbar is displayed in and a completion handler for your app extension to call. Your event handler should determine whether to enable or disable the toolbar button and whether to display a badge, and then should return this information to Safari.
The code below shows one possible implementation of the
validatemethod. In this case, the app extension has a list of items that it keeps track of, and it adds a badge to the toolbar item with the number of available items.
Set the Toolbar Information Explicitly
If you have a reference to an
SFSafari object, you can use it to get a proxy object for the toolbar item, and then use that object to set the toolbar’s status directly.
Add Commands to the Toolbar Item
If you configured your toolbar item to send a command, clicking the toolbar button in Safari causes your extension handler’s
toolbar method to be called. You can then process the click however you like. The window was passed in as a parameter, so this code retrieved the toolbar item for that window and updated its badge.
Another common usage when the toolbar item is activated is to forward the message to an injected script on the page, so that the page can be modified in some way. The code below shows one possible way to forward the toolbar action. This code retrieves the active tab on the window that was clicked, uses the tab to retrieve the page, and then dispatches a message to the page.
Display a Popover for a Toolbar Item
A popover is a window that pops up over an active window when the toolbar button is pressed—no navigation is required. It can be used to show a small amount of information or complete a small action. The popover closes automatically when the user changes focus (by clicking in another window, for example). The macOS Human Interface Guidelines describe how to best use popovers in Content Views.
In a Safari App Extension, you implement the popover content using native view and view controller objects based on AppKit. When your native application and your Safari App Extension share the same data model, this design also makes it easier to share other pieces of view code between the two. Safari and the operating system do all of the work to display this content within the Safari browser and to process events as they come in.
Your popover is implemented as a subclass of the
SFSafari class; as with other macOS development, typically you'll want to add your own outlets and actions to the view controller, and provide a XIB file for its user interface. The Xcode template for a Safari App Extension provides some boilerplate code to get you started. Use Auto Layout so that your content adapts to different sizes.
If your toolbar item is configured to display a popover, clicking the toolbar button in Safari causes your extension handler’s
popover method to be called. Your app extension should instantiate and return the popover view controller. In the template, the popover is implemented as a singleton object.
Before the popover is displayed, your handler’s
popover method is called. You can use this method to populate the contents of the window with new information. Similarly, after the popover disappears, the handler’s
popover method is called so that you can perform any necessary cleanup.