JavaScript API Example 1: Setting and Retrieving Answers

The HotDocs JavaScript API allows you to customise the client-side experience of the HotDocs Interview, including manipulating the answer data in the interview. In this example, you will look at:

  • Retrieving an answer value from the interview
  • Setting an answer value in the interview
  • Refreshing the interview after setting an answer value

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.

1. Create a new MVC Project in Visual Studio

Before you start, create a new MVC Application project for this example named JavaScriptAPIExamples. You will gradually add code to this project until you have a working example.

2. Create a new Interview Model

As you saw in HotDocs Open SDK example 4, you must create a ViewModel to pass the HotDocs Interview HTML Fragment to the browser. To create a ViewModel in Visual Studio:

  1. Right-click the Models folder in the current project and select Add > Class from the drop-down menu. The Add New Item dialog appears.
  2. In the Add New Item dialog, select Class from the centre list and enter InterviewModel in the Name field.
  3. Click Add. A new model appears in the Models folder.

Next, you need to edit the InterviewModel and add the InterviewFragment string. The entire model looks as below:

namespace JavaScriptAPIExamples.Models
{     
    public class InterviewModel     
    {
        public string InterviewFragment
        {
             get; set;
        }
    }
}

3. Create a new ActionResult in the Controller

If it does not already exist, create a new HomeController:

  1. Right-click the Controllers folder in the current project and select Add > Controller from the drop-down menu. The Add Controller dialog appears.
  2. In the Add Controller dialog, enter the following information:
  3. Controller name: HomeController
  4. Click Add. The new controller is added to the Controllers folder in the current project.

When the HomeController has been added to your project, add a new ActionResult method for this example, as follows:

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

This retrieves the information required to return a HotDocs Interview.

4. Create a new View

To display the HotDocs Interview in a web-page that is accessible by an end-user, you must create a View.

4.1 Create the View

To create the new View in Visual Studio:

  1. Expand the Views folder in the current project. If it does not already exist, add a new Home folder:
    1. Right-click the Views folder and select Add > New Folder. A new folder is added to Views.
    2. Rename the new folder to Home.
  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:
    • View Name: Example1
  4. Click Add. The new View appears in the Views > Home folder.

4.2 Add the Model Reference

Edit the View created in the previous step. At the top of the file, add the following line:

@model JavaScriptAPIExamples.Models.InterviewModel

Where JavaScriptAPIExamples is the namespace of the current project. If your project has a different name, replace JavaScriptAPIExamples in the line above with the namespace appropriate to your project. This line is Razor markup syntax, a markup language that is part of ASP.Net. It is used to embed C# code into web-pages. Any line in the View preceded by an @ symbol is using Razor syntax.

4.3 Add the Script tags

After the model reference, add Script tags:

<script></script>

You will add JavaScript inside these tags in later steps.

4.4 Add the Interview

At the bottom of the View, add the Interview HTML fragment:

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

As in step 4.2. above, this step uses Razor syntax to embed C# code in the web-page. In this case, you are using Html.Raw to render raw, unencoded HTML in the View.

You will add additional content to this file in the next step.

5. Retrieve an Answer Value

To interact with the HotDocs JavaScript API, you need to add JavaScript on the page where the interview appears. To do this, edit the View created in step 3.

The first step is to create a new function, GetAnswerValue, to retrieve the answer value from a HotDocs variable.

function GetAnswerValue(){ }

To get the value from an answer, use a GetAnswer method call:

HDAPI.GetAnswer( 'TextExample-t','-1:-1:-1:-1','TX');

The three parameters for GetAnswer are:

  • Variable Name – the name of the HotDocs variable from which you will retrieve the value. In this example, the variable named TextExample-t.
  • Repeat Index – the Repeat Index of the variable. See Repeat Indexes for more information.
  • Variable Type – the type of the variable being retrieved. The different variable types are:
    • TX – a Text variable
    • NU – a Number variable
    • DA – a Date variable
    • TF – a True/False variable
    • MC – a Multiple Choice variable

6. Set an Answer Value

Create a new function, SetAnswerValue, in which you will set the answer for a HotDocs variable.

function SetAnswerValue(){ }

To set the answer for a variable, use the SetAnswer method call:

HDAPI.SetAnswer( 'TextExample-t',,'Hello World','-1:-1:-1:-1','TX');

Like the GetAnswer method call above, you need to set the variable name, repeat index. However, there is an additional parameter, Value. This is the data to be added to the selected answer.

7. Refreshing the Interview

After an answer value has been set (using the SetAnswer method, as above), you must refresh the interview using the ScreenRefresh method. Add the ScreenRefresh method call to the SetAnswerValue function above, after HDAPI.SetAnswer:

HDAPI.SetAnswer( 'TextExample-t','Hello World','-1:-1:-1:-1','TX'); HDAPI.ScreenRefresh();

This redraws the interview in its entirety. A Screen Refresh is required after setting a value as the fields in the interview must be refreshed before they display new values. Without a refresh, the fields appear as if they have not been updated.

8. Add Buttons to the View

Finally, you need to update the view so the GetAnswerValue and SetAnswerValue JavaScript functions can be tested. Above the InterviewFragment, add the following buttons to the view:

<input type="button" onclick="GetHotDocsAnswer()" value="Get Answer Value" />
<input type="button" onclick="SetHotDocsAnswer()" value="Set Answer Value" />

9. Test

To run the project, and test retrieving and setting answers:

  1. Make sure the project is set as a Startup Project (Right-click the Example7 project, select Startup Project from the drop-down menu)
  2. Press F5 to run the Project. The browser opens.
  3. Add /Home/Example1 to the URL in the browser. The interview loads.
  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.
  7. Click the Get Answer Value button on the interview page. The Answer value for the TextExample-t variable appears in the console.
  8. Click the Set Answer Value button and navigate to the TextExample-t field in the interview. The value for the field is set to 'Hello World'.

Source Code (C#)

In the HomeController:

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

In the Example 1 view:

@model JavaScriptAPIExamples.Models.InterviewModel
@{
    ViewBag.Title = "Example 1";
    ViewBag.SubTitle = "Retrieving and modifying HotDocs interview answers";
}

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

<script type="text/javascript">
    /* Example 1 Javascript functions */
    function GetHotDocsAnswer() {
        var answerValue = HDAPI.GetAnswer( 'TextExample-t', '-1:-1:-1:-1', 'TX');
        console.log( "Answer value: " + answerValue);
    }     

    function SetHotDocsAnswer() {
         HDAPI.SetAnswer( 'TextExample-t', "Hello World", '-1:-1:-1:-1', 'TX');
         HDAPI.ScreenRefresh();
    }
</script>

<div>
    <!-- Example 1 Buttons -->
    <input type="button" onclick="GetHotDocsAnswer()" value="Get Answer Value" />
    <input type="button" onclick="SetHotDocsAnswer()" value="Set Answer Value" />

    <!-- HotDocs Interview -->
    @Html.Raw( Model.InterviewFragment)
</div>