How To Topic

Displaying a HotDocs Interview in a Web Page

A HotDocs interview is a series of dialogs, each containing one or more questions which HotDocs generates from the variables you add to your template. The user must answer the questions in the interview before HotDocs can assemble a custom document. Once the user completes the interview, HotDocs assembles the final customized document from the template by merging the interview answers into the template text. There are two ways to embed a HotDocs interview in a web page using Cloud Services:

• Direct Interview – the interview is displayed as direct part of the page's content, using the GetInterview call in the Web Service Cloud Services API
• Embedded Interview – the interview is displayed within an IFRAME, using the CreateSession web service call in the Embedded API

1. Direct Interview

The Direct Interview is a HotDocs Interview generated by Cloud Services that appears directly in the HTML DOM of a web page, in a DIV element with the ID hdMainDiv.

You can customize the client-side behaviour of the interview using the Direct JavaScript API, which is loaded and initialized by the HotDocs interview runtime as the interview page loads. The direct method offers the most flexibility for integrations, but with that flexibility comes a higher degree of involvement for your application in how the browser interview works and interacts with the end user.

Prerequisites

You must upload a HotDocs Template Package File (.hdpkg) to Cloud Services before you can generate an interview. The package file is used when generating the interview.

Retrieve the Interview Files

To display an interview, you must download the HotDocs Interview Runtime Files and serve the files from your own domain. See HotDocs Interview and JavaScript and Stylesheet Locations for more information.

Generating the Interview

To generate the Interview, the GetInterview method is used. When you call the GetInterview method, it returns three files:

• Interview HTML Fragment – a string of HTML that initializes the interview within the context of your web page
• Collection of Interview Definition Files – the JavaScript files that define the structure and content of the interview, based on the loaded templates
• Collection of Images – any images files used by the interview. For example, in image-type Dialog Elements

These files must be cached somewhere accessible to your host application so the appropriate files can be delivered when requested.

Using the Interview Files

The interview files above (and other files) are used at the following times:

• On first load of the interview
• While the interview is executing

The tables below list files the interview may require and how they may be accessed.

First Load of the Interview

For the initial load of the interview, two files are required:

Name	Optional/Required	Type	Description	Using the File
HotDocs Interview Loader	Required	JavaScript File	The JavaScript file (hdloader.js) that loads all other HotDocs JavaScript files required to display the interview.	When using GetInterview to create the interview, set HotDocsJsUrl to the URL of the HotDocs Server Files JavaScript folder. This is the location of the downloaded Interview Runtime JavaScript files, served from your own domain: https://{servername:portNumber}/{serverFilesFolder}/scripts/ For example: https://exampleserver:80/HDServerFiles/scripts/ The interview will automatically load the hdloader.js file from this location.
Interview HTML Fragment	Required	HTML	The HTML fragment file is returned in the response from the GetInterview method.   A string of HTML that must be added to the body of the page where the interview is displayed. This contains HTML and JavaScript required to render the interview.	Use the GetInterview method to create the interview. The HTML fragment is sent back as part of the multipart stream in the response. Extract the Interview HTML Fragment from the multipart stream and embed it in the web page on which the interview is to be displayed.

 

Files used during Interview execution

When using the Direct Interview, your host application handles all direct communication with the client web browser. When an interview is executing in the browser, it may request specific files or other data related to the template. This means it must provide handlers to handle the following data.

Name	Optional/Required	Type	Description	Using the File
Interview Definition File	Required	JavaScript File	A JavaScript file that defines the content and structure of the interview, based on the requested HotDocs Template. The file is located in the HotDocs Template Package (.hdpkg) file uploaded to Cloud Services. If the template uses inserted templates, the interview may make subsequent calls to retrieve Interview Definition Files for the inserted templates.	Create an endpoint in your host application from which to serve the Interview Definition file. This will use GetInterviewFile to download the Interview Definition File from the Template Package File uploaded to Cloud Services. When using GetInterview to create the interview, set the InterviewDefUrl setting to the URL of your host application endpoint.
Interview Stylesheet	Required	CSS File	The CSS files used to style the interview.	When using GetInterview to create the interview, set the HotDocsCssUrl setting to the Cloud Services Stylesheets URL. This is the location of the hdsuser.css file (in the downloaded Interview Runtime Stylesheets files), served from your own domain: https://{serverName:portNumber}/{serverFilesFolder}/stylesheets/hdsuser.css For example: https://exampleserver/HDServerFiles/stylesheets/hdsuser.css The interview derives the locations of the other required CSS and image files from this URL.
Image Files	Optional	Image File (.png, .jpg, .bmp)	Any image files used by Image-type Dialog Elements in the Interview.	See Displaying Images in the Interview for more information.
Document Preview	Optional	HTML	A Document Preview is an HTML document page that displays a preview of the completed document to the user. Only used if Document Previews are enabled in Interviews.	See Displaying a Document Preview in the Interview for more information.
Answer Data	Optional	XML	Answer Data is a collection of answers retrieved from a HotDocs Interview. The answers are represented in XML. This XML data can then be stored as a HotDocs Answer File (.anx) or in a database. When an interview loads, you can pre-populate the interview by retrieving the XML data from storage and loading it into the interview.	Retrieve the AnswerXML data. Typically, the data is stored in a HotDocs Answer File saved to disk or in a database. When using GetInterview to create the interview, send the Answer XML in the request content.
Save Answers	Optional	XML	An endpoint in your host application that allows users to save answer data without leaving the interview, using the Save Answers button.	See Saving Answers from the Interview for more information.

HotDocs browser interviews, when running in Internet Explorer, require the page in which you embed the interview to be rendered using IE Standards Mode.

For Silverlight interviews, you must ensure that the Silverlight MIME type is appropriately registered in your HTTP server: Extension: .xap and MIME Type: application/x-silverlight-app

Interview Request Sequence

When loading an interview, requests are made in the following order:

1. A user requests an interview from the host application.
2. The host application makes a request to Cloud Service to generate an interview, using GetInterview.
3. Cloud Services retrieves the HotDocs Package File (.hdpkg) for the interview from the Cloud Services cache or HotDocs Hub (if using the RetrieveFromHub parameter).
4. Using the HotDocs Template Package File, Cloud Services generates the interview and sends a response to the host application.
5. The host application retrieves the Interview HTML Fragment from the response and embeds it in a web page, which is displayed to the user.
6. The loading interview makes several callbacks to the host application to retrieve additional interview files:
   1. Interview Definition File
   2. Interview Stylesheets
   3. Image Files
7. Once the additional files are loaded, the interview finishes loading. The user can now interact with the interview.
8. Once the user complete the interview and clicks the Finish button, the interview data is sent back to the host application endpoint specified in the formActionUrl Interview Setting.

Handling Answers Returned from an Interview

When a user finishes an interview, the answers from the interview are posted to a endpoint in your host application. The endpoint URL is specified by the formActionUrl Interview Setting.

When the answers are posted back, answer data can be read from the HDInfo Form value in the response. The answer data is typically then:

• Used to assemble a document
• Saved in a database or a HotDocs Answer File for future use

The string of answers you get from HDInfo is encoded and can only be read by HotDocs Cloud Services. If you want the answers in XML format for archiving or other purposes, you can either call GetAnswers, or else call AssembleDocument and request an answer file as one of the output document formats.

Example Code (C#)

// This method illustrates how you can get the answer string from the HttpRequest

// (C#, ASP.NET)

public string GetInterviewAnswers(HttpRequest request)

{

string ansStr = String.Empty;

string[] hdInfoValues = request.Form.GetValues("HDInfo");

if (hdInfoValues != null && hdInfoValues.Length > 0)

ansStr = string.Join(string.Empty, hdInfoValues);

return ansStr;

}

Further Information

For more information about Direct Interviews, see:

• Cloud Services Direct Interview Tutorial
• Direct Interview Example Code (see the CloudServicesAPIExample3Interview project)

2. Embedded Interview

Embedded Interviews are HotDocs Interviews that are generated by Cloud Services and embedded in a web page using an IFRAME. In comparison with Direct Interviews, Embedded Interviews require less code but are less customizable.

Add the HotDocs Embedded JavaScript to a Web Page

To load an interview in a web page, the page must reference the HotDocs JavaScript files. See HotDocs Interview and JavaScript and Stylesheet Locations for more information.

Using Embedded Interviews

When displaying an embedded interview, your web application:

1. Makes a CreateSession web service call to initiate an Embedded Interview Session.
2. Displays the interview on a web page using an IFRAME.
3. May optionally use the HotDocs Embedded JavaScript API to customize the client-side behaviour of the interview.

Snapshots and Resuming Sessions

Embedded Interview Sessions can be saved and resumed at a later time. The is called a Snapshot. Typically, session data is saved to a database. When a user needs to re-load the session, it is recreated using the Snapshot data and the ResumeSession method.

For more information about snapshots and resuming a session, see:

• Snapshots walkthrough and example code
• HD$GetSnapshot method in the Embedded JavaScript API
• ResumeSession method in the Embedded API

Further Information

For more information about Embedded Interviews, see:

• Embedded API Documentation
• Embedded Interview Tutorial