SDK Example 3 - Retrieve the Interview HTML Fragment

A core function of HotDocs is the Interview, a series of questions displayed to users in order to gather answer data that HotDocs can use to assemble a completed document. You can use the SDK to provide a fragment of HTML that allows you to embed the HotDocs Interview in a web page, where users can interact with it.

This example takes you through the process of creating an interview and retrieving the HTML fragment used to display the interview to users. In this example you will:

  • Create a new Visual Studio project
  • Create an InterviewSettings object
  • Create an interview using the HotDocs Service
  • Retrieve the Interview HTML Fragment

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

Example Source Code on GitHub

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

1. Create a Visual Studio Project for Example 3

Before you start, create a new Console Application project for this example, named SdkExample3InterviewFragment. You will gradually add code to this project until you have a working example. Remember to reference the HotDocs SDK DLLs at the beginning of the class.

2. Create the Interview Settings

2.1 CreateInterviewSettings method

The first step is to create a new method, CreateInterviewSettings, that returns an InterviewSettings object:

private static InterviewSettings CreateInterviewSettings() {   }

The InterviewSettings object defines:

  • The location of the HotDocs JavaScript and Stylesheet files
  • How the Interview should behave

You will use the InterviewSettings later when retrieving the interview HTML. You will expand CreateInterviewSettings in the following step.

2.2 The HotDocs File URLs

Next, you need to supply several parameters to create a new InterviewSettings object. These are:

  • Post-Interview URL – the URL to which data from the interview is sent. This will usually be a controller in your web application. Handling post-interview processing is covered in Example 4. For now, you canuse an empty string value.
  • Interview Runtime URL – the URL from which the browser interview will request the script files used by the interview.
  • Stylesheet URL – the URL where the CSS stylesheets for the interview are stored.
  • Interview File URL – the URL from which the browser interview will request template-specific files required by the interview at runtime.

For more information about these parameters, see InterviewSettings Constructor(String, String, String, String).

In this example, you will use URLs for a typical HotDocs Server installation, where the interviewRuntimeUrl and interviewStylesheetUrl use the default HDServerFiles IIS application. This is set up by default when installing HotDocs Server. By default, the files are located at the following URLs on a local machine:

  • Runtime files – http://localhost/HDServerFiles/js
  • Stylesheet files – http://localhost/HDServerFiles/stylesheets

The final method looks like this:

private static InterviewSettings GetInterviewSettings(){     string postInterviewUrl = "";     string interviewRuntimeUrl = "http://localhost/HDServerFiles/js";     string interviewStylesheetUrl = "http://localhost/HDServerFiles/stylesheets";     string interviewFileUrl = "";       var interviewSettings = new InterviewSettings(postInterviewUrl, interviewRuntimeUrl, interviewStylesheetUrl, interviewFileUrl);     return interviewSettings; }

2.3 Change the interview behaviour (Optional)

The InterviewSettings object also allows you to change the default behaviour of the interview. For example, you can set InterviewSettings properties to define:

  • DisableAnswerSummary – disable the answer summary page.
  • UnansweredFormat – specify the text to merge into a document when an answer is missing.
  • TemplateTitleOverride – change the title of the template displayed in the interview.

For a full list of interview settings options, see InterviewSettings Members.

3. Get the Interview HTML Fragment

In this step, you will use the InterviewSettings to retrieve the InterviewResult, an object that allows you to interact with a HotDocs interview.

First, create a new method, CreateInterviewFragment, that returns a string:

private static string CreateInterviewFragment() {   }

Next, retrieve the interview settings using the GetInterviewSettings method created above:

var interviewSettings = GetInterviewSettings();

Retrieve the template using the CreateTemplate method, created in previous examples:

var template = CreateTemplate();

Retrieve the HotDocs Service using the CreateHotDocsService method, created in previous examples:

var service = CreateHotDocsService();

Using the HotDocs Service, use the GetInterview method to retrieve the InterviewResult:

var interview = service.GetInterview(template, null, interviewSettings, null, "Logging Identifier Text");

In this example, you are not passing answers or marked variables to GetInterview, as these are not necessary to assemble a completed document. If you wish, you can use the GetAnswers method from Example 2 to retrieve answers that can then be passed to GetInterview.

The InterviewResult has a property, HtmlFragment. Accessing this property gives us the HTML definition for the HotDocs Interview. Return the interview HTML fragment, so it can be used later in the class.

return interview.HtmlFragment;

The final CreateInterviewFragment method looks like this:

private static string CreateInterviewFragment(){

var interviewSettings = GetInterviewSettings();

var template = CreateTemplate();

var service = CreateHotDocsService();

 

var interview = service.GetInterview(template, null, interviewSettings, null, "Logging Identifier Text");

return interview.HtmlFragment;

}

4. Retrieve the Interview HTML Fragment

 In the Main method of the class, retrieve the InterviewResult using the GetInterviewFragment method created above.

var interviewFragment = CreateInterviewFragment();

The Interview HTML fragment contains all of the information required to display an interview to users, including links to the JavaScript files required for rendering the interview and answer definitions. Typically, this fragment would then be passed to another method to be rendered as part of a web page. In Example 4, you will use a simple MVC application to demonstrate how this is accomplished.

To see how the HTML fragment looks, write it out to a file:

File.WriteAllText(@"C:\temp\InterviewExample.html", interviewFragment);

5. Test

To test retrieving the Interview HTML Fragment:

  1. Set the current project as the Startup Project (Right-click the SdkExample3InterviewFragment project, select Startup Project from the drop-down menu)
  2. Press F5 to run the Project. The console opens and closes.
  3. Open the newly created HTML file (C:\temp\InterviewExample.html). The HotDocs Interview HTML fragment has been written to the file.

Example Source Code (C#)

using System; using System.IO; using HotDocs.Sdk; using HotDocs.Sdk.Server.Local;   namespace SdkExample3InterviewFragment {     /// <summary>     /// This demonstrates how to retrieve the HTML fragment for an interview     /// </summary>     internal class Example3     {         private static void Main(string[] args)         {                                  var interviewFragment = GetInterviewFragment();                         File.WriteAllText(@"C:\temp\InterviewExample.html", interviewFragment);         }           private static Template CreateTemplate()         {             const string packagePath = @"C:\temp\HelloWorld.hdpkg";             string packageId = Guid.NewGuid().ToString();             var templateLocation = new PackagePathTemplateLocation(packageId, packagePath);             var template = new Template(templateLocation);             return template;         }           private static Services CreateHotDocsService()         {             const string tempDirectoryPath = @"C:\temp\";             var service = new Services(tempDirectoryPath);             return service;         }           private static string GetInterviewFragment()         {             var interviewSettings = GetInterviewSettings();             var template = CreateTemplate();                                     var service = CreateHotDocsService();             var interview = service.GetInterview(template, null, interviewSettings, null, "Logging Identifier Text");             return interview.HtmlFragment;         }           private static InterviewSettings GetInterviewSettings()         {             string postInterviewUrl = "";             string interviewRuntimeUrl = "http://localhost/HDServerFiles/js";             string interviewStylesheetUrl = "http://localhost/HDServerFiles/stylesheets";             string interviewFileUrl = "";             var interviewSettings = new InterviewSettings(postInterviewUrl, interviewRuntimeUrl, interviewStylesheetUrl, interviewFileUrl);             return interviewSettings;         }     } }