SetaPDF-Core Manual

Actions Create Actions of Various Types

Introduction

PDF includes a wide variety of standard action types. Such actions can be executed by different triggers, such as annotations, document or page related events. 

Available Action Classes

The SetaPDF-Core component comes with native support for following action types:

SetaPDF_Core_Document_Action_GoTo

Go to a destination in the current document.

SetaPDF_Core_Document_Action_GoToR

Go to a destination in an external document.

SetaPDF_Core_Document_Action_ImportData

Import field values from a file.

SetaPDF_Core_Document_Action_JavaScript

Execute a JavaScript script.

SetaPDF_Core_Document_Action_Launch

Launch an application, usually to open a file.

SetaPDF_Core_Document_Action_Named

Execute an action predefined by the conforming reader.

SetaPDF_Core_Document_Action_ResetForm

Set fields to their default values.

SetaPDF_Core_Document_Action_SubmitForm

Send data to a uniform resource locator.

SetaPDF_Core_Document_Action_Uri

Resolve a uniform resource identifier.

SetaPDF_Core_Document_Action

A base class for all other action classes and a fallback that will be used for actions that are not implemented especially in SetaPDF.

Some examples of common action types:

// The URI action, that allows you to link to resources on the Internet.
$uriAction = new \SetaPDF_Core_Document_Action_Uri('http://www.setasign.com');

// A JavaScript action, that allows you to execute JavaScript when an action is executed
$javaScript = 'app.alert("SetaPDF is here!")';
$javaScriptAction = new \SetaPDF_Core_Document_Action_JavaScript($javaScript);

// A Named action, that goes to the next page of the document.
$nextPage = new \SetaPDF_Core_Document_Action_Named(
    \SetaPDF_Core_Document_Action_Named::NEXT_PAGE
);

Chaining Actions

The PDF specification allows to chain up actions so that several actions are executed in a specific order. This functionallity is build into the base class SetaPDF_Core_Document_Action: 

// Define the first action
$actionOne = new \SetaPDF_Core_Document_Action_JavaScript('app.alert("Action One executed!");');

// Define the second action
$actionTwo = new \SetaPDF_Core_Document_Action_JavaScript('app.alert("Action Two executed!");');

// Chain up the actions
$actionOne->addNext($actionTwo);

// Chain an additional action up the the second action
$actionThree = new \SetaPDF_Core_Document_Action_JavaScript('app.alert("Action Three executed!");');
$actionTwo->addNext($actionThree);

Using Actions

Actions are commonly used in outline items or in annotations such as through their additional actions entry or if they offer a direct action entry such as the link annotation. 

Furthermore actions can be attached to an individual page or to document specific events.

Document Actions

Document related actions shall be accessed through the SetaPDF_Core_Document_Catalog class. It grants access to the OpenAction entry in the catalog dictionary:

getOpenAction()

Get the open action.

setOpenAction()

Set the open action.

Furthermore a helper method offers access to the SetaPDF_Core_Document_Catalog_AdditionalActions instance that allows you to access the document's additional actions dictionary.

$additionalActions = $document->getCatalog()->getAdditionalActions();

The class will offer following methods to define actions for specifc events. All actions have to be JavaScript actions:

getDidPrint()

Get the JavaScript action that shall be performed after printing the document.

getDidSave()

Get the JavaScript action that shall be performed after saving the document.

getWillClose()

Get the JavaScript action that shall be performed before closing the document.

getWillPrint()

Get the JavaScript action that shall be performed before printing the document.

getWillSave()

Get the JavaScript action that shall be performed before saving the document.

setDidPrint()

Set the JavaScript action that shall be performed after printing the document.

setDidSave()

Set the JavaScript action that shall be performed after saving the document.

setWillClose()

Set the JavaScript action that shall be performed before closing the document.

setWillPrint()

Set the JavaScript action that shall be performed before printing the document.

setWillSave()

Set the JavaScript action that shall be performed before saving the document.

Page Actions

It is possible to define actions to be executed when a page is opened or closed by the SetaPDF_Core_Document_Page_AdditionalActions class, which can be accessed by a helper method on the page instance:  

$additionalActions = $page->getAdditionalActions();

getClose()

Get the action that shall be performed when the page is closed.

getOpen()

Get the action that shall be performed when the page is opened.

setClose()

Set the action that shall be performed when the page is closed.

setOpen()

Set the action that shall be performed when the page is opened.