Explore flexible PDF annotation actions on iOS

A PDF action is similar to a web hyperlink, but it’s much more flexible. Nutrient supports most common actions defined in Adobe’s PDF Reference (page 417ff).

The most common types are GoTo and URI. However, many documents also use GoToR, Launch, Named, or JavaScript for page changes.

Every Action subclass can either be parsed from a PDF or created in code. It can also be serialized via NSKeyedArchiver (supporting NSSecureCoding):

ActionNutrient classUse case
GoToGoToActionGo to a destination (page) in the current document.
GoToRRemoteGoToActionGo to a destination in another document.
GoToEEmbeddedGoToActionGo to a destination in an embedded file.
LaunchRemoteGoToActionLaunch an application, usually to open a file.
URIURLActionResolve a uniform resource identifier (web link).
HideHideActionSet an annotation’s hidden flag.
JavaScriptJavaScriptActionExecute a JavaScript script.
RenditionRenditionActionControl the playing of multimedia content.
SubmitFormSubmitFormActionSend data to a uniform resource locator.
ResetFormResetFormActionSet fields to their default values.
NamedNamedActionExecute an action predefined by the conforming reader.

Unsupported actions include Thread, Sound, Movie, ImportData, SetOCGState, Trans, and GoTo3DView.

Actions are chainable via the subActions property. Certain annotations, such as LinkAnnotation and WidgetAnnotation, can contain an action. Furthermore, every annotation can contain additionalActions that are executed on certain trigger events. You can use the additionalActions property to add actions to annotation types that don’t have an action handler by default, such as stamp annotations. In most cases, the Annotation.TriggerEvent.mouseUp event is what you want.

Bookmark and OutlineElement also contain an action, thereby supporting the same types of actions as an annotation. (A PDF outline can open a web link or even play a video.)

Trigger events

See Annotation.TriggerEvent for available trigger events. Nutrient supports a subset of these events.

Executing actions

You can use PDFViewController’s execute(_:targetRect:pageIndex:animated:actionContainer:) to execute PDF actions, such as the action property of LinkAnnotation:

pdfController.execute(linkAnnotation.action, targetRect: linkAnnotation.boundingBox, pageIndex: linkAnnotation.absolutePageIndex, animated: true, actionContainer: linkAnnotation)

The file structure for the action has to be correctly specified for it to work, and the files in question should be in a local folder.