Article

Adding Actions

Add actions to the browser's context menu.

Overview

Define custom actions in your File Provider UI extension's Info.plist file. These actions appear in the context menu when the user long presses an item while browsing your file provider's content.

Add Actions to the Context Menu

Add an NSExtensionFileProviderActions key to the NSExtension dictionary in your Info.plist file:

<key>NSExtensionFileProviderActions</key>
<array>
	<dict>
		<key>NSExtensionFileProviderActionIdentifier</key>
		<string>com.example.MyFileProvider.setRating</string>
		<key>NSExtensionFileProviderActionName</key>
		<string>Rate</string>
	</dict>
</array>

The NSExtensionFileProviderActions key takes an array of dictionaries. Each dictionary represents a single action, and contains the keys shown in this table:

Key

Type

Description

NSExtensionFileProviderActionIdentifier

String

A unique identifier for the action.

NSExtensionFileProviderActionName

String (Localizable)

The localized name that appears in the context menu.

NSExtensionFileProviderActionActivationRule

Predicate

An optional predicate that determines whether the action appears in the context menu.

The following sequence of events occurs when the user selects one of your actions from the context menu:

  1. The system instantiates your FPUIActionExtensionViewController subclass.

  2. The system calls your view controller's prepare(forAction:itemIdentifiers:) method. You can override this method to configure the user interface for the selected action.

  3. The system presents your view controller to the user.

  4. After the user has finished performing the action, you call the provided FPUIActionExtensionContext object's cancelRequest(withError:) or completeRequest() method to complete the action.

Use Predicates to Enable and Disable Actions

The NSExtensionFileProviderActionActivationRule key lets you enable or disable actions based on the selected file provider item. Set the key's value to a predicate format string. The system uses this string to create an NSPredicate object, and then calls the predicate's evaluate(with:) method, passing in the selected item. Specifically, it passes in a dictionary with a single fileproviderItems key. The value is an array of NSFileProviderItem objects representing the selected items.

You can use predicates to test the value of any of the NSFileProviderItemProtocol object's properties. For example, the following predicate tests whether the isUploaded property is set to true.

SUBQUERY ( fileproviderItems, $fileproviderItem, $fileproviderItem.uploadded == YES ).@count > 0

You can also use predicates to test custom data that you've added to the item's userInfo dictionary. For example, the following predicate tests whether the com.example.testBit key has been set.

SUBQUERY ( fileproviderItems, $fileproviderItem, $fileproviderItem.userInfo."com.example.testBit" == YES ).@count > 0

If a predicate evaluates to true, the action is displayed; if false, it's not displayed. For more about creating predicate format strings, see Predicate Format String Syntax.

See Also

Document Browser Customization

class FPUIActionExtensionViewController

The custom user interface used to perform a selected action.