Get Interview

One of the key services that HotDocs Cloud Services provides is the ability to display an answer-gathering interview in a browser.

Most of the behavior of this interview, such as which dialogs are asked and in which order, and how questions are arranged on each dialog, is defined by the author of the template prior to publishing it as a package for use with HotDocs Cloud Services.

When your host application has determined that it needs to present an interview to the end user, it can call the GetInterview method of the HDCS service. The response consists of an array of files:

  • A string of HTML code that must be embedded on the page in your Web application where you want the interview to appear.
  • If applicable, each of the images that are used on dialogs in the interview.
  • If applicable, each of the compiled Silverlight DLLs that contain the template-specific logic for the interview.

Embed an Interview in a Web Page

After calling GetInterview, you should take the interview HTML code (the first file in the response) and insert it in your page where the interview is to be displayed. Since the interview is designed to expand to the height of the browser window, you should not place anything below the interview as that would force users to scroll in order to see any text below the interview.

For JavaScript interviews, the page in which you embed the interview must use the HTML Transitional document type:

!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"

Embedding a JavaScript interview in an XHTML page is not supported. This limitation does not apply to Silverlight interviews, however.

Serve Template-Specific Interview Files

After the HTML code, the rest of the files returned by GetInterview fit into one of the following two categories:

  • Dialog Element Images — images the template author has placed on dialogs in the interview.
  • Interview Definitions (Silverlight DLLs) — compiled Silverlight DLLs that contain the interview logic for a template. Every template (whether it is a main template or an inserted template) has its own interview definition.

Your application should save each of these files (if any exist) in an appropriate location from which they can be served if requested as the user interacts with the interview. For example, if there are image files, the interview will request them when the user navigates to the dialog on which the image should appear. Likewise, if you requested a Silverlight interview, the Silverlight DLLs for the interview will be requested during interview intialization or whenever the user answers a question in a way that causes another DLL to be required.

The URLs from which the interview will request these images and Silverlight files are configured when you call GetInterview:

The URL for template-specific (dialog element) image files is set in the tempImageUrl parameter.

The URL for interview definitions is defined by the InterviewDefUrl setting in the settings parameter.

For Silverlight interviews, you must ensure that the Silverlight MIME type is registered in the IIS virtual directory from which the interview files will be served:
Extension: .xap
MIME Type: application/x-silverlight-app

Seeding (Pre-Populating) an Interview with Answers

One of the core features of HotDocs is the ability to save answers entered during one interview and re-use those answers when assembling other documents from the same or different template. As part of the call to GetInterview, you can specify one or more answer files containing answers you wish to use with the interview. When the user sees the interview, any relevant answers contained in those answer files will be pre-populated in the interview.

Another way in which you can pre-populate an interview with answers is by inspecting a template to determine which variables it requires.

You can then query a database to get answers for those variables and create your own answer file based on the information from the database.

Handling Answers Returned from an Interview

When a user finishes an interview, the answers entered during the interview (along with any answers in the original answer file sent to the interview) are posted to a page provided by your host application. You can then read those answers from the HDInfo Form value and use them to assemble a document or archive them 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 call AssembleDocument and request an answer file as one of the output document formats.

<![CDATA[

// This method illustrates how you can get the answer string from the HttpRequest 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;

}]]>

Interview Appearance

When you call GetInterview, you can choose which stylesheet, or theme, to use for the interview when you specify the stylesheet URL. The stylesheets dictate fonts, colors, and other visual elements of the interview. HotDocs Cloud Services has a few themes to choose from, or you can create your own.