How to create nice dialog windows in PDF form

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 parent’s width; may widen objects.
		“align_distribute”: Distribute the contents over the parent’s width.
		“align_row”: Distribute the contents over the parent’s 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 parent’s width; may widen objects.
		“align_distribute”: Distribute the contents over the parent’s width.
		“align_row”: Distribute the contents over the parent’s 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.