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.

Simple dialog window message
Simple dialog window message

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

JavaScript dialog box with data from the form field and current date
JavaScript dialog box with data from the form field and current date

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 handlerDescription
initializeCalled when the dialog box is being initialized.
validateCalled when a field is modified to determine if the value is acceptable (by returning true) or unacceptable (by returning false).
commitCalled when the OK button of the dialog box is clicked.
destroyCalled when the dialog box is being destroyed.
ItemIDCalled 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

PropertyTypeDescription
nameStringThe title bar of the dialog box, which should be localized.
first_tabStringAn 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.
widthNumericThe width of the dialog box in pixels. If no width is specified, the combined width of the contents is used.
heightNumericThe height of the dialog box in pixels. If no height is specified, the combined height of the contents is used.
char_widthNumericThe width of the dialog box in characters. If no width is specified, the combined width of the contents is used.
char_heightNumericThe height of the dialog box in characters. If no height is specified, the combined height of the contents is used.
align_childrenStringThe 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.
elementsArrayAn array of object literals that describe the dialog box elements contained within this dialog (see “elements property”).

Table 3. Elements property

PropertyTypeDescription
nameStringThe displayed name of the dialog box element, which should be localized.
Note:This property is ignored for the “edit_text” type.
item_idStringAn ItemID for this dialog box, which is a unique 4-character string.
typeStringThe 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_tabStringAn 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.
widthNumericSpecifies the width of the element in pixels. If no width is specified, the combined width of the contents is used.
heightNumericSpecifies the height of the element in pixels. If no height is specified, the combined height of the contents is used.
char_widthNumericSpecifies the width of the element in characters. If no width is specified, the combined width of the contents is used.
char_heightNumericSpecifies the height of the element in characters. If no height is specified, the combined height of the contents is used.
fontStringThe font to use for this element. Must be one of the following strings:
“default” - Default font
“dialog” - Dialog box font
“palette” - Palette (small) Font
boldBooleanSpecify if the font is bold.
italicBooleanSpecify if the font is italic.
alignmentStringSets 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_childrenStringSets the alignment for all descendants. Possible values are the same as for alignment.
elementsArrayAn 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 typePropertyTypeDescription
static_textmultilineBooleanIf true, this static text element is multiline.
edit_textmultilineBooleanIf true, this edit text element is multiline.
readonlyBooleanIf true, this text element is read only.
Note:This property is ignored when password is set to true.
passwordBooleanIf true, this text element is a password field.
PopupEditBooleanIf true, it is a pop-up edit text element.
SpinEditBooleanIf true, it is a spin edit text element.
radiogroup_idStringThe group name to which this radio button belongs.
ok, ok_cancel, ok_cancel_otherok_nameStringThe name for the OK button.
cancel_nameStringThe name for the cancel button.
other_nameStringThe name for the other button.

8 thoughts on “How to create nice dialog windows in PDF form”

  1. 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…

    1. 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.

  2. 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!

    1. 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???

    1. 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.

      1. 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?

        1. 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.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.