Actions

DynamicPDF Core Suite supports many actions derived from the Action class for achieving many different results. For example, DynamicPDF supports JavaScript actions, URL actions, submit actions, page navigation actions, actions to show/hide fields, actions to open files, and many more actions.

Use these actions to perform tasks in many places, such as outlines, links, buttons, or any Document, Page, or FormField Reader Events.

OutlineAnnotationAction

The OutlineAnnotationAction is parent to the AnnotationShowHideAction, FileOpenAction, GoToAction, JavaScriptAction, ResetAction, SubmitAction, and UrlAction.

The OutlineAnnotationAction has a NextAction property, allowing chaining of multiple actions. An example illustrating chaining is provided below.

AnnotationShowHideAction

The AnnotationShowHideAction shows/hides a specific form field. Specify the form field's name that this action should show or hide in its constructor. By default the class hides a field, but the ShowField boolean property allows modifying its default behavior.

The following example illustrates using two buttons to hide or show a form field.

Button button = new Button("btn", 50, 150, 100, 30);
button.Label = "Hide";
TextField field = new TextField("Text1", 330, 100, 100, 30);
field.DefaultValue = "Text Field Value";
AnnotationShowHideAction action = new AnnotationShowHideAction("Text1");
button.ReaderEvents.MouseDown = action;

Button button2 = new Button("btn", 175, 150, 100, 30);
button2.Label = "Show";
AnnotationShowHideAction action2 = new AnnotationShowHideAction("Text1");
action2.ShowField = true;
button2.ReaderEvents.MouseDown = action2;      

Dim button As New Button("btn", 50, 150, 100, 30)
button.Label = "Hide"
Dim field As New TextField("Text1", 330, 100, 100, 30)
field.DefaultValue = "Text Field Value"
Dim action As New AnnotationShowHideAction("Text1")
button.ReaderEvents.MouseDown = action

Dim button2 As New Button("btn", 175, 150, 100, 30)
button2.Label = "Show"
Dim action2 As New AnnotationShowHideAction("Text1")
action2.ShowField = True
button2.ReaderEvents.MouseDown = action2

FileOpenAction

The FileOpenAction opens a file, provided a native application to open the specific file is already installed.

This class has two constructors, one allowing specifying only the file path of the file to open and the other also allowing specifying a FileLaunchMode. Launch modes include ExistingWindow, NewWindow, and UserPreference (the default launch mode).

The following example demonstrates using a button to open a file in a new window.

Button button = new Button("btn", 50, 150, 100, 30);
button.Label = "Click Here";
FileOpenAction action = new FileOpenAction("Path of the file to open", FileLaunchMode.NewWindow);
button.ReaderEvents.MouseUp = action        

Dim MyButton As Button = New Button("btn", 50, 150, 100, 30)
MyButton.Label = "Click Here"
Dim MyAction As FileOpenAction = New FileOpenAction("Path of the file to open", FileLaunchMode.NewWindow)
MyButton.ReaderEvents.MouseUp = MyAction 

GoToAction

The GoToAction moves to a particular page on a PDF document. The class constructor takes a page number the action should navigate to and a PageZoom. Values include, FitBox, FitHeight, FitPage, FitWidth, None, Percentage, and Retain.

The following example illustrates using a button to navigate to a specific page and ensure the page fits the new page's width after navigation.

Button button = new Button("btn", 50, 150, 100, 30);
button.Label = "Click Here";
GoToAction action = new GoToAction(2, PageZoom.FitWidth);
button.ReaderEvents.MouseUp = action;        

Dim button As New Button("btn", 50, 150, 100, 30)
button.Label = "Click Here"
Dim action As New GoToAction(2, PageZoom.FitWidth)
button.ReaderEvents.MouseUp = action

JavaScriptAction

The JavaScriptAction is implemented differently than the other example actions. Core Suite allows specifying JavaScript code at the document level, page level, and element level for any PDF.

• See the JavaScript topic for more information.

ResetAction

The ResetAction resets all form field values to their default values. The following example illustrates.

ResetAction action = new ResetAction();
Button button = new Button("btn", 50, 300, 100, 50);
button.Label = "Reset";
button.ReaderEvents.MouseEnter = action;        

Dim action As New ResetAction()
Dim button As New Button("btn", 50, 300, 100, 50)
button.Label = "Reset"
button.ReaderEvents.MouseEnter = action

SubmitAction

The SubmitAction sends form field data to a specified URL. Its constructor takes a path to a URL that submits a form's name/value pairs (HTTP POST), query-string values (HTTP GET), or FDF, PDF, or XML. Set the export format for the URL request by providing a FormExportFormat to the SubmitAction constructor. Valid export formats to send to a server are: forms data format (FDF), HTML GET, HTML POST, PDF, and XML. The export format is the format of the data sent to the server.

Adobe Acrobat expects the response to be in Forms Data Format (FDF) and the response's content-type must be Content-Type: application/vnd.fdf. For example, returning the following FDF results in a simple success message displayed as an alert in Adobe Acrobat (Figure 1).

%FDF-1.2
1 0 obj
<<
/FDF << /Status (This form was sucessfully submitted.) >> >>
endobj
trailer
<<
/Root 1 0 R
>>
%%EOF

The following code demonstrates how to use a button to post form field data to a URL as an HTML POST request.

Button button = new Button("Submit", 125, 700, 150, 30);
button.Action = new SubmitAction("http://<url-to-form-handler>", FormExportFormat.HtmlPost);
button.Label = "Submit";

Dim submitAction As New SubmitAction("http://<url-to-form-handler>", FormExportFormat.HtmlPost)
Dim button As New Button("btn", 50, 300, 100, 50)
button.Label = "Submit"
button.Action = submitAction

ImportFormFieldDataAction

The ImportFormDataAction can be used with the Document class (creating PDF documents) or the MergeDocument class (merging/modifying existing PDF documents).

ImportFormDataAction

An FDF file is a text file format used for data exported from PDF form fields that contain only form field data, not a complete form. An AcroForm's fields can be completed using an FDF file through the ImportFormDataAction class.

The following example illustrates using an FDF file. Note that the completed PDF form is the form with the added action to import the FDF data upon the end-user opening the PDF.

The following FDF data is used to fill the form.

%FDF-1.2
%âãÏÓ
1 0 obj
<</FDF<</Fields[<</T(Submit)>><</T(descriptionField)/V(This is a description.)>><</T(nameField)/V(John Doe)>>]/ID[<CA4420574740BBED8326F4582D61BF85><CA4420574740BBED8326F4582D61BF85>]>>/Type/Catalog>>
endobj
trailer
<</Root 1 0 R>>
%%EOF

Document document = new Document();
Page page = new Page();
document.Pages.Add(page);
Label label1 = new Label("Name:", 0, 0, 250, 30);
TextField nameField = new TextField("nameField", 100, 0, 200, 25);
Label label2 = new Label("Description:", 0, 100, 100, 30);
TextField descriptionField = new TextField("descriptionField", 150, 100, 200, 50);
Button button = new Button("btn", 50, 250, 100, 30);
button.Label = "Fill Form";
page.Elements.Add(button);
page.Elements.Add(nameField);
page.Elements.Add(descriptionField);
page.Elements.Add(label1);
page.Elements.Add(label2);
ImportFormDataAction action = new ImportFormDataAction("simple-form-fill_data.fdf");
button.ReaderEvents.MouseUp = action;
document.Draw(outputPath);

Dim document As New Document()

' Create a page and add it to the document
Dim page As New Page()
document.Pages.Add(page)

' Create label and text field
Dim label1 As New Label("Name:", 0, 0, 250, 30)
Dim nameField As New TextField("nameField", 100, 0, 200, 25)
Dim label2 As New Label("Description:", 0, 100, 100, 30)
Dim descriptionField As New TextField("descriptionField", 150, 100, 200, 50)
Dim button As New Button("btn", 50, 250, 100, 30)
button.Label = "Fill Form"

' Add the label and form fields to the page
page.Elements.Add(button)
page.Elements.Add(nameField)
page.Elements.Add(descriptionField)
page.Elements.Add(label1)
page.Elements.Add(label2)

' Create an import form data action and assign it to the button events.
Dim action As New ImportFormDataAction("simple-form-fill_data.fdf")
button.ReaderEvents.MouseUp = action

' Save the PDF
document.Draw(outputPdf)

URLAction

The URLAction supports linking to a URL destination.

Although a URLAction can be used with any element possessing an Action property, note that the Outline class and Link class both allow specifying a URLAction.

• See Outlines and Bookmarks for an example using a bookmark with a URL.

The following example demonstrates creating a link and a button, both of which navigate to each element's specified URL when clicked.

Font font = Font.TimesRoman;
string text = "This is a link to DynamicPDF.com.";
Label label = new Label(text, 50, 20, 215, 80, font, 12, RgbColor.Blue);
label.Underline = true;
Link link = new Link(50, 20, font.GetTextWidth(text, 12), 12 - font.GetDescender(12), new UrlAction("http://www.dynamicpdf.com"));
UrlAction action = new UrlAction("http://www.dynamicpdf.com");
Button button = new Button("btn", 50, 100, 100, 50);
button.Label = "Click";
button.Action = action;

Dim font As Font = Font.TimesRoman
Dim text As String = "This is a link to DynamicPDF.com."

Dim label As New Label(text, 50, 20, 215, 80, font, 12, RgbColor.Blue)
label.Underline = True
Dim link As New Link(50, 20, font.GetTextWidth(text, 12), 12 - font.GetDescender(12), New UrlAction("http://www.dynamicpdf.com"))

Dim action As New UrlAction("http://www.dynamicpdf.com")
Dim button As New Button("btn", 50, 100, 100, 50)
button.Label = "Click"
button.Action = action

XYDestination and ZoomDestination

These two classes are different from the other classes inheriting from the Action class, as they do not also children of the OutlineAnnotationAction class.

The following example illustrates using the UrlAction, XYDestination, and ZoomDestination with an outline.

// Add a top level outline and set properties
Outline outline1 = document.Outlines.Add("Outline1");
outline1.Style = TextStyle.Bold;
outline1.Color = new RgbColor(1.0f, 0.0f, 0.0f);

// Add child outlines
Outline outline1A = outline1.ChildOutlines.Add("Outline1A", new UrlAction("http://www.mydomain.com"));
outline1A.Expanded = false;
Outline outline1A1 = outline1A.ChildOutlines.Add("Outline1A1", new XYDestination(2, 0, 0));
Outline outline1A2 = outline1A.ChildOutlines.Add("Outline1A2", new ZoomDestination(2, PageZoom.FitHeight));
Outline outline1B = outline1.ChildOutlines.Add("Outline1B", new ZoomDestination(2, PageZoom.FitWidth));

// Add a second top level outline
Outline outline2 = document.Outlines.Add("Outline2", new XYDestination(3, 0, 300));

// Add a child outline
Outline outline2A = outline2.ChildOutlines.Add("Outline2A");

Dim outline1 As Outline = document.Outlines.Add("Outline1")
outline1.Style = TextStyle.Bold
outline1.Color = New RgbColor(1.0F, 0.0F, 0.0F)

' Add child outlines
Dim outline1A As Outline = outline1.ChildOutlines.Add("Outline1A", New UrlAction("http://www.mydomain.com"))
outline1A.Expanded = False
Dim outline1A1 As Outline = outline1A.ChildOutlines.Add("Outline1A1", New XYDestination(2, 0, 0))
Dim outline1A2 As Outline = outline1A.ChildOutlines.Add("Outline1A2", New ZoomDestination(2, PageZoom.FitHeight))
Dim outline1B As Outline = outline1.ChildOutlines.Add("Outline1B", New ZoomDestination(2, PageZoom.FitWidth))

' Add a second top-level outline
Dim outline2 As Outline = document.Outlines.Add("Outline2", New XYDestination(3, 0, 300))

' Add a child outline
Dim outline2A As Outline = outline2.ChildOutlines.Add("Outline2A")

Chaining Actions

Recall that most actions are children of the OutlineAnnotationAction class. This class has a NextAction method that allows adding another action to it and can chain multiple actions into a sequence.

The following example illustrates chaining three actions together. When an end use opens the PDF and clicks the button, the PDF hides the two form fields, presents an alert, and then opens another PDF.

AnnotationShowHideAction action = new AnnotationShowHideAction("check_box_nm");
action.NextAction = new AnnotationShowHideAction("text1");
action.NextAction.NextAction = new JavaScriptAction("app.alert(\"Fields Hidden.\")");
action.NextAction.NextAction.NextAction = new FileOpenAction("DocumentA.pdf", FileLaunchMode.NewWindow);
button.ReaderEvents.MouseDown = action;

Dim action As New AnnotationShowHideAction("check_box_nm")
action.NextAction = New AnnotationShowHideAction("text1")
action.NextAction.NextAction = New JavaScriptAction("app.alert(""Fields Hidden."")")
action.NextAction.NextAction.NextAction = New FileOpenAction("DocumentA.pdf", FileLaunchMode.NewWindow)
button.ReaderEvents.MouseDown = action