JavaScript API Example 3: Event Handlers

When users load and navigate through the HotDocs Interview, their actions can be used to trigger events. These events can be mapped to a JavaScript function, allowing developers to add custom functionality triggered by users actions. In this example, you will:

  • Register the HotDocs Interview Event Handlers
  • Assign custom functions to the Event Handlers

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.

Using the Browser Developer Tools Console

In these examples, you will write output data to the console in the developer tools of your web browser.

In Mozilla Firefox, Google Chrome, and Microsoft Internet Explorer

To open the Developer Tools Console:

  1. Open the browser and press F12 on your keyboard. The Developer Tools window opens.
  2. Click on the Console tab in the Developer Tools window. Any messages send to the Console will appear in this window.

Types of Events

Each event available in the HotDocs JavaScript API is linked with a user action. This is either loading the interview, movement through the interview – by answering questions, moving between dialogs – or the user finishing the interview. The events available are:

  • OnHDStart – triggered when the interview is fully loaded in the browser but before the user can interact with the interview
  • OnHDNavigated – triggered when the user navigates to a new dialog, including the first dialog displayed in the interview
  • PreHDNavigate – triggered when the user attempts to navigate to a new dialog but before focus has moved away from the current dialog
  • OnHDFinish – triggered when the user clicks the interview's Finish button
  • PreHDSubmit – triggered immediately before answers from the interview are posted back to the server
  • OnHDProgress – triggered every time an variable is answered, cleared, or the interview content otherwise changes

For more information about the different types of events, see HDAPI.RegisterHandler Method.

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 Example4()
{
    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 JavaScript API 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: Example3
  4. Click Add. The new View appears in the Views > Home folder.

You will edit this file later in the example.

3. Registering Events

Before each event in the HotDocs interview can be handled, a specific handler function for that event must be registered. Registration occurs in the HDInterviewOptions object. In the OnInit function, seen in previous examples, you will use the HDAPI.RegisterHandler method to register events. In this example, you will add an OnHDStartEvent

3.1 Create HDInterviewOptions Object

If you have not done so in previous examples, add the HDInterviewOptions object to the page on which the interview is displayed:

HDInterviewOptions = {
    OnInit: function () {}
}

3.2 Register the Handler

To add the handler, use the HDAPI.RegisterHandler method. This method requires two parameters:

  • Event Name – a string. This must be the name of one of the Interview Events listed above.
  • Handler Function – a function. This is the name of the JavaScript function that is called when the event is triggered.

Inside the OnInit function, add a handler for the OnHDStart event. This will trigger a JavaScript function, UpdateLogOnInterviewStart, that you will create in the next step. The HDInterviewOptions looks like this:

HDInterviewOptions = {
    OnInit: function(){
        HDAPI.RegisterHandler( 'OnHDStart', UpdateLogOnInterviewStart);
    }
}

3.3 Create the JavaScript Function used by the Event

Create a new JavaScript function, UpdateLogOnInterviewStart. Inside the body of the function, add a Console.Log with an appropriate logging message. We will use this function whenever a new interview is loaded to write logging data to the brower's developer tools console.

function UpdateLogOnInterviewStart(){
    console.log( "Interview Started");
}

Next, you will create Event Handlers and JavaScript functions for two more events: OnHDNavigated and OnHDProgress.

4. Add the OnHDNavigated Event Handler

The OnHDNavigated event handler is called every time the user navigates between dialogs.

4.1 Add the Event Handler

Add the line below to the OnInit function. This registers the OnHDNavigated event and associates it with the UpdateLogOnInterviewNavigation function created above.

HDAPI.RegisterHandler( 'OnHDNavigated', UpdateLogOnInterviewNavigation);

The OnHDNavigated event has now been registered. Next, you will need to create the JavaScript handler function.

4.2 Add the JavaScript Function

Next, you will create a new JavaScript function that writes to the Developer Tools Console every time the event is triggered. Inside the script tags in the view, add a new function, UpdateLogOnInterviewNavigation, to log a message to the console:

function UpdateLogOnInterviewNavigation(){
    console.log( "Interview Navigated");
}

5. Add the OnHDProgress Handler

The OnHDProgress event handler is called every time the user navigates between dialogs, answers a question or the interview content otherwise changes.  

5.1 Add the Event Handler

Add the line below to the OnInit function. This registers the OnHDProgress event and associates it with the UpdateLogOnInterviewProgress function created below.

HDAPI.RegisterHandler( 'OnHDProgress', UpdateLogOnInterviewProgress);

The OnHDProgress event has now been registered.

5.2 Add the JavaScript Function

Next, you will create a new JavaScript function that writes to the Developer Tools Console every time the event is triggered. Inside the script tags in the view, add a new function, UpdateLogOnInterviewProgress, to log a message to the console:

function UpdateLogOnInterviewProgress(){
    console.log( "Interview Progress Updated");
}

Now that the three event handlers and their JavaScript functions have been created, you can now test the event handlers in the HotDocs Interview.

6. Test

To run the project and test the event handlers:

  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. When the browser opens, add /Home/Example3 to the URL in the Address Bar. The interview loads in the browser.
  4. When the interview has finished loading, enter answer data into the interview fields.
  5. Press F12 to open the Developer Tools.
  6. Select the Console tab. As the interview has started, there is an 'Interview Started' message written to the console.
  7. Click the Next button on the interview page. As you have navigated between dialogs, there are 'Interview Navigated' and 'Interview Progress Updated' messages written to the console.
  8. Enter an answer into a field and press tab. As you have updated a question, there is an 'Interview Progress Updated' message written to the console.

Source Code (C#)

In the HomeController:

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

In the Example3 view:

@model JavaScriptAPIExamples.Models.InterviewModel
@{
    ViewBag.Title = "Example 3";
    ViewBag.SubTitle = "HotDocs Interview Event Handling";
}

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

<script type="text/javascript">
    /* Example 3 Javascript */
    HDInterviewOptions = {
        OnInit: function (){
            HDAPI.RegisterHandler( 'OnHDStart', UpdateLogOnInterviewStart);
            HDAPI.RegisterHandler( 'OnHDNavigated', UpdateLogOnInterviewNavigation);
            HDAPI.RegisterHandler( 'OnHDProgress', UpdateLogOnInterviewProgress);
         }
     }

    function UpdateLogOnInterviewStart(){                 
         console.log( "Interview Started");
     }

     function UpdateLogOnInterviewNavigation(){
         console.log( "Interview Navigated");
     }
     
    function UpdateLogOnInterviewProgress(){         
         console.log( "Interview Progress Updated");
     }
</script>

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