Article

Adjusting Settings for Contextual Menu Items

Customize contextual menu items for your Safari App Extension.

Overview

You can add items to the contextual menu that Safari shows when a user Control-clicks or right-clicks in a webpage. These actions trigger the following sequence of events:

  1. Safari sends an event to the web document, informing it that a contextual menu is about to be displayed.

  2. Safari displays the contextual menu.

  3. If the user chooses one of the items associated with your app extension, Safari calls your app extension’s handler to perform the command.

To learn how to add a contextual menu item, see About Contextual Menu and Toolbar Item Keys.

Localize the Contextual Menu Item

To localize a contextual menu, provide an InfoPlist.strings file and include localized text for a custom key based on your command string. For example, to provide a Polish translation for a menu item whose command string is Add, you’d add the following entry to your strings file:

"Context Menu Item Label for Command: Add" = “Dodaj”;

For more information, see Localizing Property List Values.

Validate and Change Text in a Contextual Menu Item

Use the validateContextMenuItemWithCommand:inPage:userInfo:validationHandler: method to validate a contextual menu item. The command parameter is the Command string you provided in the Info.plist entry for the menu item. The validationHandler parameter is a code block where you specify whether the menu item should be hidden and what text to use for it. Using this option, you can dynamically change the text of a context menu item.

To change the menu text:

validationHandler(NO, @“Updated text”);

To use the default text:

validationHandler(NO, nil)

To hide the menu item:

validationHandler(YES, nil);

Send Custom Information to Your App Extension

To pass information from the current webpage to your app extension when the user chooses your menu item, you’ll need to inject a JavaScript file; see Injecting a Script into a Webpage. When the user Control-clicks or right-clicks in a webpage, Safari sends out a contextmenu event. Your script can add a listener for this event, and react to it by inserting information into the user info dictionary. If the user later selects one of your contextual menu items, Safari sends this dictionary when it calls your app extension.

For example, to capture the currently selected text in a webpage:

document.addEventListener("contextmenu", handleContextMenu, false);
function handleContextMenu(event) {
    var selectedText =  window.getSelection().toString();
    safari.extension.setContextMenuEventUserInfo(event,
        { "selectedText": selectedText });
}

Handle Contextual Menu Item Commands in Your App Extension

When the user selects one of your contextual menu items, Safari sends the contextMenuItemSelectedWithCommand:inPage:userInfo: method to your SFSafariExtensionHandler subclass. The command parameter is the Command string you provided in the Info.plist entry for the menu item.

For example, if you add the Command string in your Info.plist entries for a contextual menu item, you might implement your context menu method to perform different actions for different commands:

@implementation MySafariExtensionHandler

- (void)contextMenuItemSelectedWithCommand:(NSString *)command
                                    inPage:(SFSafariPage *)page userInfo:(NSDictionary<NSString *, id> *)userInfo {
    if ([command isEqualToString:@"Search"]) {
        NSLog(@"User asked to search for selected text");
    } else if ([command isEqualToString:@"AddEntry"]) {
        NSLog(@"User asked to add new entry for selected text");
    }
}

@end

You can use the page parameter to access information about the current webpage, including the URL and page title, and to send messages back to your injected JavaScript file using the dispatchMessageToScriptWithName:userInfo: method.

See Also

Contextual Menu and Toolbar Items

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.

Adjusting Settings for a Toolbar Item

Customize a toolbar item for your Safari App Extension.