Create a HotDocs Server answer source

This topic pertains to "HotDocs Server answer sources", a powerful and flexible feature that requires some server- and client-side coding. In addition to this feature, HotDocs Server 11 introduces support for built-in Answer Sources (link) that require no special coding.

Each time a template is used to assemble a document, HotDocs Server presents a browser-based interview to prompt the user for information the template requires. Once the user has answered the questions, the answers are submitted to the server where they are merged into the finished, assembled document.

There are several ways users can provide HotDocs with the information it needs during document assembly. They can use any (or a combination) of these methods:

Enter the information manually.
Retrieve the information from an answer file.
Retrieve the information from an answer source.

The last option, retrieving information from an answer source, allows users to select answers from a separate data source during the interview. That way, information from a company data store or other database-driven program, such as some case managers, can also be used to assemble a HotDocs document.

Before users can retrieve answers from a database or other source, the template developer must first decide which dialogs contain variables that correspond to database fields. Then, a button (hyperlink) must be added to each of these dialogs to allow users to open a URL and retrieve information from the answer source.

To add a hyperlink to a dialog

Edit the dialog to which you want to add the button. The Dialog Editor appears.
At the Properties tab, click the Dialog Element button and drag it to the Contents list. The Dialog Element Editor appears.
Enter a name for the component in the Dialog element name box, or select Generate name automatically, which allows HotDocs to name the component.
In the Style group, select Web link .
In the URL box, enter the complete Web address for the page you want the hyperlink to open.
In the Link text box, enter the text you want to use as the hyperlink.
Click the Options tab and select how you'd like the link to appear on the dialog, based on the following information:
- In the Display as group, select whether the link should be a Button or Hyperlink . (If you select Button, you can specify a custom button size in the Button size group.)
- If you select Hyperlink, select whether the link should include text, an image, or both in the Display using group. (Enter the name of the image file in the Image file box; if you select Image, it must be located in the same folder as the rest of the HotDocs Server images. (See Files Used with HotDocs Server.)
- In the Display in group, select whether the link should appear when the dialog is displayed in Desktop interviews, Server interviews, or both. (At a minimum, you must select Server interviews.)
Optionally, to control the appearance of the browser window when it opens, enter the JavaScript parameters in the window.open features string box. This value corresponds to the third parameter of the JavaScript window.open method (sFeatures). For example, to open the resource in a window that is 200 pixels high, 400 pixels wide, includes the status bar, and does not include the toolbar, menu bar, and location bar, use this string: height=200,width=400,status=yes,toolbar=no,menubar=no,location=no.
Click OK. The Dialog Element Editor is closed.
Drag the component up or down in the Contents list, depending on where you want the hyperlink placed on the dialog.

When the user clicks the button, the URL is processed in another window you (as the site administrator) provide. In this window, you can display information from a database and provide a method for the user to select data and close the window. The following functions are available for implementing a HotDocs Server answer source:

You can use these functions to get or set answers of variables based on the current interview, and refresh the screen once answers have been changed via the answer source.

As these functions are actually called from the child window, they must be referenced correctly from the child. For example: window.opener.HDAPI.SetAnswer("Emp Name", "Bob Smith"). In addition, because of browser security limitations, the page in which these functions are called must use the same domain name as the page in which the interview is presented.

The following example shows an HTML page you can use as a HotDocs Server answer source:

<html>
    <head>
        <script language="javascript">
            // These global arrays contain sample employee names and genders.
            var EmpName = new Array("Will Wilson", "Sally Smith", "Brook Banks", "Hans Henderson");
            var EmpGender = new Array("Male", "Female", "Female", "Male");
     
            // Create the HTML to display the selections.
            // If this were an ASPX page, such data could be read out of a database instead.
            function AddButtons()
                {
                    for (var i=0; i < EmpName.length; i++) {
                        window.document.writeln("<p><input type=button value='" + EmpName[i] + "' name=btn" + i + " onclick='SetVariables("+i+")'></input></p>");
                    }
                }
            // Update the HotDocs answers for the name and gender, then close the window
            function SetVariables(index)
                {
                    window.opener.HDAPI.SetAnswer("Employee Name",EmpName[index]);
                    window.opener.HDAPI.SetAnswer("Employee Gender",EmpGender[index]);
                    window.opener.HDAPI.ScreenRefresh();
                    window.close();
                }
        </script>
    </head>
     
    <body>
        <h1>Please select an employee:</h1>
            <p>(The current employee is <b>
                <script language="javascript"> window.document.write(window.opener.HDAPI.GetAnswer("Employee Name"))
                </script></b>.)
            </p>
        <form ID="Form1">
            <script language="javascript">AddButtons();</script>
        </form>
    </body>
</html>