function RegisterHandler(eventName, handlerFunc);

Parameters

eventName

Type: SystemString
A string representing the name of an interview event. You can specify any string, but only those listed below (see Remarks) are supported and will cause your event handler to be called.

handlerFunc

Type: function
A JavaScript function that will be called any time the event for which it is registered occurs. It should accept a single parameter, EventArgs, the contents of which vary depending on the event as described below.

• "OnHDStart" - This event fires when an interview is fully loaded and initialized in the browser, but before the user has a chance to interact with the interview. For example, if you want to dictate that the user should begin the interview at any dialog besides the first one, you could register for this event and call the HDGotoInterviewBookmark function to set an alternate starting point for the user's interview.

  The EventArgs object passed to your event handler does not have any properties.

• "OnHDNavigated" - This event fires when the user navigates to a new dialog, including the dialog first displayed when starting the interview. It is fired after the dialog script has run for the new dialog, and after the display has been updated. (In the case of the first dialog, it is fired after the OnHDStart event.)

  If you make changes to answers in your handler, you should call HDScreenRefresh as usual to make sure the screen gets refreshed afterwards.

  The EventArgs object passed to your event handler has the following properties:

  Property	Description
  DialogName	The name of the dialog to which the user has navigated.

• "PreHDNavigate" - This event fires at the time the user attempts to navigate away from a dialog. It fires after any pending answer changes have been saved, but before focus has actually moved away from the current dialog.

  The EventArgs object passed to your event handler has the following properties:

  Property	Description
  DialogName	This is the name of the dialog the user is attempting to leave.
  TargetName	This is the name of the dialog to which the user is attempting to navigate.
  Cancel	If you set this Boolean property to true, the user's attempt to navigate away from the dialog will be cancelled.   Caution: If you cancel the user’s navigation, it is strongly recommended that you supply a CancelMessage. If you do not, you should undertake some other means of communicating to the user why they are not being allowed to navigate away from the current dialog.
  CancelMessage	If navigation was cancelled and this property is a non-empty string, a message box is displayed to the user to indicate why navigation was cancelled.

• "OnHDFinish" - This event fires when the user clicks the Finish button, after HotDocs first ensures that all required variables have been answered. You can use this function to perform custom answer validation and potentially cancel the user's action if needed.

  The EventArgs object when this event is called has the following properties:

  Property	Description
  Cancel	If you set this Boolean property to true, the user's attempt to finish the interview will be cancelled, leaving them at the current dialog.   Caution: If you cancel the user’s navigation, it is strongly recommended that you supply a CancelMessage. If you do not, you should undertake some other means of communicating to the user why they are not being allowed to finish their interview.
  CancelMessage	If navigation was cancelled and this property is a non-empty string, a message box is displayed to the user to indicate why navigation was cancelled.

• "PreHDSubmit" - This event fires immediately before interview answers are submitted to the host application on the server. This could happen when the user clicks the Finish, Save Answers, or Document Preview buttons, or any other time the HDPostAnswersToServer API is invoked. You should subscribe to this event if you need to add fields, such as the ASP.NET view state, to the form submission.

  The EventArgs object when this event is called has the following properties:

  Property	Description
  FieldArray	An associative array containing all the form fields that are about to be submitted to the host application on the server.
  Context	A string indicating the context in which the event handler was called. It can be one of the following values: "InterviewComplete": The user clicked either the Finish button or the Next button at the last dialog. "SaveAnswers": The user clicked the Save Answers button. "DocumentPreview": The user clicked the Document Preview button. "APICall": The HDPostAnswersToServer function has been invoked programmatically (via the API) or by some other means.

  Caution: The Legacy API also allows you to register for this handler by declaring a global function named PreHDSubmit. If you declare such a function, and also register for the PreHDSubmit handler using RegisterHandler, both handlers will be called. To avoid this error, do not declare a global function named PreHDSubmit.

• "OnHDProgress" - This event fires every time a variable is answered (or cleared) or the interview content otherwise changes, such that information about the user's progress towards completion of the interview has changed. You might use this event if you have suppressed display of the built-in interview progress bar (using the HDInterviewOptions.ProgressBar option) and wish to track user progress through some alternate means.

  The EventArgs object when this event is called has the following properties:

  Property	Description
  Answered	The number of answered questions, not counting answers to optional questions
  Total	The total number of questions in the interview (not counting optional questions)
  State	A number indicating the state of the interview as a whole. 0: Interview is complete. If the interview progress bar were visible and had the default styling applied, this would correspond to a green, fully complete progress bar. 1: Interview is incomplete. If the interview progress bar were visible and had the default styling applied, this would correspond to a blue progress bar in an empty or partially-complete state. 2: Interview is incomplete, and one or more of the unanswered questions are required before the user is allowed to progress further. If the interview progress bar were visible and had the default styling applied, this is one of two states that would display a red progress bar. 3: The interview contains a dialog with an error message, which prevents the user from progressing. If the interview progress bar were visible and had the default styling applied, this is one of two states that would display a red progress bar. 4: The interview is incomplete, there is one or more required unanswered question, and a dialog contains an error message. Because of this state, the user cannot progress further in the interview. If the interview progress bar were visible and had the default styling applied, this is one of two states that would display a red progress bar.

Reference