PDF form is one of the most popular ways of communication within organizations. Thanks to PDF Share Forms businesses are able to integrate PDF forms into SharePoint environment, making collaboration more comfortable and convenient.
It is a clever idea to notify users with more informative and related to the current situation messages directly from the form. For example, a relevant message is displayed if data field has different content format or is empty.
Adobe PDF has a built-in feature that allows creating custom dialog boxes using JavaScript. These scripts can be assigned to any field or control in the form and will provide user with additional information or warning in a familiar system window.

Basic code for simple dialog window
Dynamic form: xfa.host.messageBox("Warning text", "Window title", type);
where “type” can be one of: 0 (Error), 1 (Warning), 2 (Question), 3 (Status).
Static form: app.alert({ cMsg: "Warning text", cTitle: "Window title" });
You can’t format message or customize window layout directly using basic methods. We’ll show how you can modify dialog window content and make it more attractive and interactive.
Creating advanced dialog window

To create a dialog window with the custom layout and text formatting, we need to use JavaScript code and assign it to the corresponding event. For example the following code shows a custom message when user clicks on the button:
var text = xfa.resolveNode('$data..TextField1').value; var HelloDlg = { initialize: function (dialog) { var todayDate = dialog.store()["date"]; todayDate = "Date: " + util.printd("mmmm dd, yyyy", new Date()); dialog.load({ "date": todayDate }); }, description: { elements: [ { type: "view", elements: [ { item_id: "str1", name: "Hello, this is a demo box.", type: "static_text", font: "dialog", bold: true, alignment: "align_center", char_width: 30, height: 20, }, { type: "gap", }, { type: "view", align_children: "align_row", elements: [ { item_id: "str2", name: "Your text:", type: "static_text", }, { item_id: "str3", name: text, type: "static_text", font: "dialog", bold: true, } ] }, { item_id: "date", name: "Date: ", type: "static_text", char_width: 25, } ] }, { type: "ok", ok_name: "Ok!", alignment: "align_right", } ] } }; app.execDialog(HelloDlg);
Some differences can appear while working with static AcroForms and with dynamic XFA-forms. In our case, code is written for dynamic XFA form. If you want to use static AcroForms, then you will need to adjust JavaScript for methods relevant in static forms.
Dynamic form: xfa.resolveNode('$data..TextField1').value;
Static form: this.getField("address").value;
JavaScript code contains different handlers (functions), which are executed while dialog window is being opened on events such as “Mouse Up”, “Mouse Down”, “On Focus”, etc. Handlers are optional yet very helpful. Their results can be used to query or set values in the dialog box.
Each of the handlers can read form field content, create its own objects, like dialogs or warnings with their own properties and controls. It helps to build interactive user dialogs or even workflow-like interface.
The supported handlers are listed in the Table 1.
Dialog box layout properties are listed in the Table 2.
Dialog box element properties are listed in the Table 3.
Some of the elements may have additional attributes, as listed in the Table 4.
Table 1. Dialog box handlers
Dialog box handler | Description |
---|---|
initialize | Called when the dialog box is being initialized. |
validate | Called when a field is modified to determine if the value is acceptable (by returning true) or unacceptable (by returning false). |
commit | Called when the OK button of the dialog box is clicked. |
destroy | Called when the dialog box is being destroyed. |
ItemID | Called when the dialog box element ItemID is modified. For a text box, it is when the text box loses focus. For other controls, it is when the selection changes. If ItemID is not a JavaScript identifier, the name must be enclosed in double quotes when the method is defined, as in the following example. "bt:1": function () { .... } If ItemID is a JavaScript identifier, the double quotes are optional. For example, the following are both correct. "butn": function () { .... } butn: function () { .... } |
Table 2. Description properties
Property | Type | Description |
---|---|---|
name | String | The title bar of the dialog box, which should be localized. |
first_tab | String | An ItemID for the dialog box item that should be first in the tab order. This dialog box item will also be active when the dialog box is created. This property is required for setting up a tabbing order. See the next_tab property defined below. |
width | Numeric | The width of the dialog box in pixels. If no width is specified, the combined width of the contents is used. |
height | Numeric | The height of the dialog box in pixels. If no height is specified, the combined height of the contents is used. |
char_width | Numeric | The width of the dialog box in characters. If no width is specified, the combined width of the contents is used. |
char_height | Numeric | The height of the dialog box in characters. If no height is specified, the combined height of the contents is used. |
align_children | String | The alignment for all descendants. Must be one of the following values: |
align_left: Left aligned | ||
align_center: Center aligned | ||
align_right: Right aligned | ||
align_top: Top aligned | ||
align_fill: Align to fill the parents width; may widen objects. | ||
align_distribute: Distribute the contents over the parents width. | ||
align_row: Distribute the contents over the parents width with a consistent baseline. | ||
align_offscreen: Align items one on top of another. | ||
elements | Array | An array of object literals that describe the dialog box elements contained within this dialog (see elements property). |
Table 3. Elements property
Property | Type | Description |
---|---|---|
name | String | The displayed name of the dialog box element, which should be localized. |
Note:This property is ignored for the edit_text type. | ||
item_id | String | An ItemID for this dialog box, which is a unique 4-character string. |
type | String | The type of this dialog box element. It must be one of the following strings: |
button - A push button. | ||
check_box - A check box. | ||
radio - A radio button. | ||
list_box - A list box. | ||
hier_list_box - A hierarchical list box. | ||
static_text - A static text box. | ||
edit_text - An editable text box. | ||
popup - A pop-up control. | ||
ok - An OK button. | ||
ok_cancel - An OK and Cancel Button. | ||
ok_cancel_other - An OK, Cancel, and Other button. | ||
view - A container for a set controls. | ||
cluster - A frame for a set of controls. | ||
gap - A place holder. | ||
next_tab | String | An ItemID for the next dialog box item in the tab order. |
Note:Tabbing does not stop at any dialog box item that is not the target of the next_tab (or first_tab) property. Tabbing should form a circular linked list. | ||
width | Numeric | Specifies the width of the element in pixels. If no width is specified, the combined width of the contents is used. |
height | Numeric | Specifies the height of the element in pixels. If no height is specified, the combined height of the contents is used. |
char_width | Numeric | Specifies the width of the element in characters. If no width is specified, the combined width of the contents is used. |
char_height | Numeric | Specifies the height of the element in characters. If no height is specified, the combined height of the contents is used. |
font | String | The font to use for this element. Must be one of the following strings: |
default - Default font | ||
dialog - Dialog box font | ||
palette - Palette (small) Font | ||
bold | Boolean | Specify if the font is bold. |
italic | Boolean | Specify if the font is italic. |
alignment | String | Sets the alignment for this element. Must be one of the following values: |
align_left: Left aligned | ||
align_center: Center aligned | ||
align_right: Right aligned | ||
align_top: Top aligned | ||
align_fill: Align to fill the parents width; may widen objects. | ||
align_distribute: Distribute the contents over the parents width. | ||
align_row: Distribute the contents over the parents width with a consistent baseline. | ||
align_offscreen: Align items one on top of another. | ||
align_children | String | Sets the alignment for all descendants. Possible values are the same as for alignment. |
elements | Array | An array of object literals that describe the subelements of this dialog box element. Its properties are the same as those described in this table. |
Table 4. Additional attributes of some dialog box elements
Element type | Property | Type | Description |
---|---|---|---|
static_text | multiline | Boolean | If true, this static text element is multiline. |
edit_text | multiline | Boolean | If true, this edit text element is multiline. |
readonly | Boolean | If true, this text element is read only. | |
Note:This property is ignored when password is set to true. | |||
password | Boolean | If true, this text element is a password field. | |
PopupEdit | Boolean | If true, it is a pop-up edit text element. | |
SpinEdit | Boolean | If true, it is a spin edit text element. | |
radio | group_id | String | The group name to which this radio button belongs. |
ok, ok_cancel, ok_cancel_other | ok_name | String | The name for the OK button. |
cancel_name | String | The name for the cancel button. | |
other_name | String | The name for the other button. |
With all due respect, but I understand that it has to be simple, this does this example really show the power of the Dialog object? It is, for example possible to create a Date Picker (not an issue for XFA forms, but for PDF forms), and I can assure that such a beast works in Acrobat and Reader 7 and higher…
About the forms, and again, with all due respect, it is a bit dangerous to make the differentiation between PDF forms (Acroforms) and XFA by calling one static, and the other one dynamic. Many XFA forms are static, and there are dynamic Acroforms…
Max, thanks for the great comment! Here we refer to AcroForm as static and XFA as dynamic to be explicit to our customers. There are a lot of marketing /sales talk but in the end it all goes to unnecessary assumptions. Of course, there are static XFA forms (also known as XFAF)… Our main point of this blog was to show that nice dialog boxes are possible in PDF forms. Syntax is a little different between AcroForms and XFA forms, but discussion of the differences was not a main purposed of this article.
Hi, I am working on a complex ADM Dialog for my PDF Form…
Right now I’m just trying something really simple.
If you think you can help me, it would be really appreciated… I am trying to get one button to show and app.alert();
It’s just not working.. Do you think you could help me out with this code?
function dialog()
{
var dialogDescriptor =
{
description:
{
name: “Background Dialog”,
elements: [
{
type:”view”,
align_children: “align_row”,
elements: [
{
type: “static_text”,
name: “Create the background with the following choices:”,
},
{
type:”ok”,
}
]
},
{
type:”view”,
align_children: “align_row”,
elements: [
{
type: “button”,
name: “Info?”,
item_id: “cmdObjective”,
},{
type: “check_box”,
name: “Objective”,
item_id: “chkObjective”,
},
]
},
{
type: “view”,
align_children: “align_row”,
elements:[
{
type: “button”,
name: “Info?”,
item_id: “cmdContext”,
},{
type: “check_box”,
name: “Context”,
item_id: “chkContext”,
},
]
},
]
},
initialize: function(dialog)
{
dialog.load(
{
“chkContext”: dialogObject.chkContext,
“chkObjective”: dialogObject.chkObjective,
“cmdObjective”: dialogObject.cmdObjective,
“cmdContext”: dialogObject.cmdContext,
}
);
},
validate : function(dialog)
{
//add validate code here
return true;
},
commit: function(dialog)
{
// Retrieve the values stored in list_box sub1:
var elements = dialog.store();
app.alert(elements.length);
},
“cmdObjective”: function (dialog)
{
app.alert(“You just clicked information for Objectives.”);
},
“cmdContext”: function (dialog)
{
app.alert(“You just clicked information for Context.”);
},
};
var dialogObject =
{
cmdObjective: ({}),
cmdContext: ({}),
execDialog: function() { return app.execDialog(dialogDescriptor); },
};
return dialogObject;
}
var d = dialog();
d.execDialog();
Please reply when you can, I really need this to work as fast as possible! Thank you!
I’ve just notice that the button is not working if I have another name than ‘butn’ or ‘bt:1’
Is the dialog limited to names or what???
HI,
How can be put a calender control to pick the date in pop up dialog? thanks in advance.
To use standard date picker tool you should use PDF XFA, or dynamic form format. It has other pluses and minuses, still there is available really nice date picker. You may also create a JavaScript for the Acroform PDF, but I believe it is not very convenient.
Hello, All
This dialog is great but it is modal, i.e. must be closed before execution continues.
Is there a way to display such dialog, then continue execution and populate the text on the dialog from other parts of code?
Hi Gene
Thanks for your comment. This dialog window is more “Adobe or Windows style”. We just call it using JavaScript. All such dialogs are usually modal.