Article

About Contextual Menu and Toolbar Item Keys

Learn about adding contextual menu items and toolbar items to a Safari App Extension with information property list keys.

Overview

Contextual menu items and toolbar items give you ways to add more menu options and entry points to your Safari App Extension. These items can only be defined and adjusted using information property list keys.

Context Menu Items

The SFSafariContextMenu key lets your app extension add items to the context menu shown in webpages. See Contextual Menus for design guidelines.

Context menu in Safari

Its value must be an array, and must contain one dictionary with two subkeys for each menu item:

Subkey

Type

Description

Text

String

Required. A string that specifies the text to display for the context menu item.

Command

String

Required. A string that the context menu item sends when activated. It contains the name of the command you want sent to your app extension when the user selects your item.

For example, if you were to add two contextual menu items, your Info.plist file might look like the following:

<key>SFSafariContextMenu</key>
<array>
	<dict>
		<key>Text</key>
		<string>Search for selected text in MyApplication</string>
		<key>Command</key>
		<string>Search</string>
	</dict>
	<dict>
		<key>Text</key>
		<string>Add entry for selected text in MyApplication</string>
		<key>Command</key>
		<string>Add</string>
	</dict>
</array>

Toolbar Items

The SFSafariToolbarItem dictionary adds a toolbar item to Safari windows. See Toolbars for design guidelines.

Toolbar items in Safari

Each app extension can have only one toolbar item. The value for this key is a dictionary that describes the toolbar item.

There are four required keys for the toolbar item dictionary:

Subkey

Type

Description

Identifier

String

Required. A string identifier for the toolbar item. This isn't displayed to the user.

Label

String

Required. A string that's shown in the overflow menu, in the Customize palette, and on hover.

Image

String

Required. A string specifying the filename of a scalable PDF image. The image must be transparent. Add the image file to your extension's Xcode target.

Action

String

Required. A string specifying the command to send when the toolbar item is clicked. Available actions are Command (to send a command to the app extension) and Popover (to display a popover window). This action determines which methods you need to implement to handle button presses.

Here is an example dictionary, specified as XML:

<dict>
	<key>Action</key>
	<string>Command</string>
	<key>Identifier</key>
	<string>Button</string>
	<key>Image</key>
	<string>Toolbar.pdf</string>
	<key>Label</key>
	<string>My Item</string>
</dict>

Use the Image key to provide an image for the toolbar button. The toolbar button image may be resized or recolored by Safari when drawn to the screen. Your image should be a template image and follow the guidelines for toolbar items.

See Also

Contextual Menu and Toolbar Items

Adjusting Settings for a Toolbar Item

Customize a toolbar item for your Safari App Extension.

Adjusting Settings for Contextual Menu Items

Customize contextual menu items for your Safari App Extension.

SFSafariToolbarItem

A proxy for a Safari app extension toolbar item in a Safari window.

SFSafariExtensionViewController

The view controller for a popover associated with your app extension.