JavaScript API Example 2: Custom Interview Options

The HotDocs Interview Options object provides a variety of options to customise the Interview. By editing the properties of the object, you can change the interview appearance and behaviour. In this example, you will:

  • Create a HotDocs Interview Options object
  • Alter the width and height of the interview
  • Disable the 'Confirmation before leaving the interview' dialog.
  • Use the Interview Options object to add a custom button

Full source code for this example is available at the bottom of the page.

Example Source Code on GitHub

The JavaScriptAPIExamples example project is available on GitHub, in the HotDocs-Samples repository.

Prerequisites

For this example, you should have already created the MVC project in example 1. In this example, you will add new files and code to the existing project.

1. Create a new ActionResult in the Controller

To display the View created above when the project is run, create a new ActionResult in the HomeController for the current project.

Add a new ActionResult method for this example:

public ActionResult Example2()
{
    Util.SetPersistentEncryptionKey( "ExampleKey");
     var interviewFragment = GetInterviewFragment();
     var model = new InterviewModel { InterviewFragment = interviewFragment };
     return View( model);
}

The contents of the ActionResult are the same as the ActionResult created for example 1. This will create an interview fragment and pass it to the browser. In this example, however, the interview fragment will be passed to a different view, which you will create in the next step.

2. Create a new View

As in example 1, you need to create a new View for this example. To create a new View in Visual Studio:

  1. Expand the Views folder in the current project.
  2. Right-click the Views > Home folder and select Add > View from the drop-down list. The Add View dialog appears.
  3. In the Add View dialog, enter the following data:
    1. View Name: Example2
  4. Click Add. The new View appears in the Views > Home folder.

You will edit this file later in the example.

3. Create a HotDocs Interview Options Object

First, initialize the HDInterviewOptions object:

<script>
    HDInterviewOptions = {}
</script>

The properties of this object can be changed from their default values, allowing you to customize the interview. In this example, you will only examine a few of these. A full list is available in the HDInterviewOptions article in the HotDocs JavaScript API help.

4. Alter the Width and Height of the Interview

By default, the HotDocs Interview spans the entire width of the container div. To specify an exact width and height for the interview, you can set pixel values for the HotDocs Interview Options by adding the Width and Height properties to the HDInterviewOptions object, and giving them specific pixel values:

HDInterviewOptions = { Width: 800, Height: 500}

When the interview is displayed, the dimensions of the interview will be restricted to those specified.

5. Disable the 'Confirmation on leaving the Interview' dialog

By default, HotDocs displays a dialog asking for user confirmation when closing the interview page. You can disable the confirmation so that a user can close or navigate away from the page without being prompted. To do this, add a new LeaveWarning property to HDInterviewOptions and give it a value of false:

HDInterviewOptions = {
    ...
    LeaveWarning: false
}

LeaveWarning must be set to a bool value. A value of True displays the warning; False disables the warning.

6. Add a Custom Button to the Interview

Next, you will add a new custom button to the interview. This will appear at the top of the interview, on the same toolbar as the Answer Summary, Document Preview, and Interview Outline buttons.

6.1 Add the OnInit Property to HDInterviewOptions

The function contained within the OnInit property is immediately executed as the interview loads. This function always contains code that must be executed before a user can interact with the interview, such as Event Handlers, Language Modules, and Custom Buttons.

HDInterviewOptions = { 
    ...
    OnInit: function(){}
}

6.2 Add a Test Function for the Custom Button

To test the button, create a simple function, CustomButtonTest, that displays an alert:

function CustomButtonTest(){
    alert( "Hello World");
}

This function should be placed inside the Script tags from  Step 3. You will use this in the next step, when adding the custom button to the toolbar. When the button is pressed, the test function will be called and the alert message displayed.

6.3 Add the Custom Button to the Toolbar

Finally, you can add the custom button to the toolbar at the top of the page using the AddCustomToolbarButton method in the JavaScript API:

HDInterviewOptions = {
    ...
    OnInit: function(){
        HDAPI.AddCustomToolbarButton( CustomButtonTest, '@Url.Content("~/add.png")');
    }
}

This function requires two parameters:

  • The Function Name (funcClick) – the name of the custom function that is triggered when a user clicks the button. In this example, the parameter is the name of the function created in step 6.2.

  • The Button Image (imageNormal) – the URL for the image to be used as the background of the button.

The AddCustomToolbarButton API method has several other parameters available, which change the behavior of the button. For example,

  • imageHot – the image used when the user hovers the mouse over the button
  • tooltip – the hint text displayed when the user hovers the mouse over the button
  • funcActive – a function that determines if the button is in an active state or not. Return a boolean value

For more details, see the AddCustomToolbarButton article in the JavaScript API help file.

Now that the custom button has been added to the OnInit property for HDInterviewOptions, the interview is ready to test.

7. Test

To run the project and test the custom interview options:

  1. Make sure the project is set as a Startup Project (Right-click the JavaScriptAPIExamples project, select Startup Project from the drop-down menu)
  2. Press F5 to run the Project. The browser opens.
  3. Add /Home/Example2 to the URL in the browser. The interview loads.
  4. When the interview has finished loading, you should see that the interview width and height matches the specified values.
  5. An additional button now appears in the toolbar. Click the button. An alert dialog with the message "Hello World" is displayed.
  6. Close the tab containing the Interview. Notice that an "Exit Interview" confirmation dialog is not displayed.

Source Code (C#)

In the HomeController:

public ActionResult Example2()
{
     Util.SetPersistentEncryptionKey( "ExampleKey");
     var interviewFragment = GetInterviewFragment();
     var model = new InterviewModel { InterviewFragment = interviewFragment };
     return View( model);
}

In the Example 2 view:

@model JavaScriptAPIExamples.Models.InterviewModel
@{
    ViewBag.Title = "Example 2";
    ViewBag.SubTitle = "Custom interview options and buttons";
}

<h2>@ViewBag.Title</h2>
<h3>@ViewBag.SubTitle</h3>

<script type="text/javascript">
    /* Example 2 Interview Options*/
    HDInterviewOptions = {
        Width : 800,
        Height : 500,
        LeaveWarning : false,
        OnInit: function () {
            HDAPI.AddCustomToolbarButton( CustomButtonTest, '@Url.Content("~/add.png")');
        }
    }

    function CustomButtonTest() {
        alert( "Hello World");
    }
</script>

<div>
    @Html.Raw( Model.InterviewFragment)
</div>