JavaScript API Example 5: Using Language Modules

Language Module Overview

When displaying a HotDocs Interview, you may need to change the language of the user interface to better fit the requirements of end users. When using a language module, user interface elements – for example, Yes/No confirmation buttons, month names in date picker dialogs – are replaced with custom-defined text. The process of creating a custom language pack is outlined below.

In this example, you will:

  • Create a new Browser Language Module definition
  • Select the new Browser Language Module to be used in the interview

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 ActionResult in the Controller

To display the View created above when the project is run, create a new ActionResult in the HomeController for the current project.

Add a new ActionResult method for this example:

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

The contents of the ActionResult are the same as the ActionResult created for example 1. This will create an interview fragment and pass it to the browser. In this example, however, the interview fragment will be passed to a different view, which you will create in the next step.

2. Create a new View

As in JavaScript API Example 1, you need to create a new View for this example.

To create a new View in Visual Studio:

  1. Expand the Views folder in the current project.
  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:
    1. View Name: Example5
  4. Click Add. The new View appears in the Views > Home folder.

You will edit this file later in the example.

3. Create the Language Module JavaScript

When creating a new Browser Language Module, you must register the new language module with the HotDocs locale infrastructure.

3.1 Create a new JavaScript file in the Project

In your project, create a new JavaScript file named LanguageModule.js:

  1. In the current project, right-click the Scripts folder and select Add > JavaScript File. The Specify Name for Item dialog appears.
  2. In the Item Name field, enter LanguageModule and click OK.
  3. In the Solution Explorer, navigate to the Scripts folder and edit the new LanguageModule.js file.

In the JavaScript file, add a new function:

(function ($) { }(typeof HOTDOC$ === "undefined" ? {} : HOTDOC$));

Inside the function, add a new Locales variables:

var Locales = $.Locales = (typeof $.Locales === "undefined") ? {} : $.Locales;

Add a new Language module definition to the Locales array:

Locales["de-DE"] = {};

We will expand this definition in the next step. Finally, either use the existing array or create a new one if it is not yet defined in the global scope:

window.HOTDOC$ = $;

The final content of LanguageModule.js looks like this:

(function ($) {
    var Locales = $.Locales = (typeof $.Locales === "undefined") ? {} : $.Locales; Locales["de-DE"] = {};
    window.HOTDOC$ = $;
}( typeof HOTDOC$ === "undefined" ? {} : HOTDOC$));

Next, you will add the language module definition to Locales["de-DE"].

4. Defining the Language Module

The language module definition has a wide range of options available to customize the interview. For example, the names of the months in the year may be changed by adding the months property to an object in the Locales array:

months: ["Januar", "Februar", "März", "April", "Mai", "Juni", "Juli", "August", "September", "Oktober", "November", "Dezember"]

You can also change the number separator characters in number variables. For example, changing the decimal separator to a comma and the thousands separator to a full stop:

numSeps: [",", "."]

By adding various definitions to the object, a full language definition can be created. A full list can be found in the HotDocs help article, Browser Language Module.

In your JavaScript file, add the language definition to Locales["de-DE"]:

Locales["de-DE"] = {
    name: "German (Germany)",
    dateOrder: "DMY",
    months: ["Januar", "Februar", "März", "April", "Mai", "Juni", "Juli", "August", "September", "Oktober", "November", "Dezember"],     
    monthsShort: ["Jan", "Feb", "Mär", "Apr", "Mai", "Jun", "Jul", "Aug", "Sep", "Okt", "Nov", "Dez"],
    days: ["Sonntag", "Montag", "Dienstag", "Mittwoch", "Donnerstag", "Freitag", "Samstag"],
    daysShort: ["So", "Mo", "Di", "Mi", "Do", "Fr", "Sa"],
    calWeekBegin: 1,
    calWeekend: [0, 6],
    zeroFormats: ["Null"],
    numSeps: [",", "."],
    strings: {
           ui_yes: "Ja",
           ui_no: "Nein"
    },
    SpellNum: function(value, strZero, bOrdinal){}
}

Once the module has been created, you can reference the new module in the InterviewOptions, so it can be used by the interview.

5. Set the Language Module using HDInterviewOptions

The HotDocs JavaScript API uses an associative array named HDInterviewOptions to track all of the options enabled for the interview. When using a Language Module, you need to add two new entries to this array:

  • Locale – the name of the locale used by the interview. This must be the same as the name of the LanguageModule you wish to use in the interview
  • LanguageModule – an object containing the name of the language module and a URL to the JavaScript file containing the language module definition

In the Example5 View, add these options to the HDInterviewOptions object:

HDInterviewOptions = {
    Locale: "de-DE",
    LanguageModule: { "de-DE": "Scripts/LanguageModule.js" }
};

The LanguageModule will now be loaded when the Interview page is accessed.

6. Test

To run the project and test the browser language module:

  1. Set the project as a Startup Project (Right-click the JavaScriptAPIExamples project, select Startup Project from the drop-down menu).
  2. Press F5 to run the Project. The browser opens.
  3. Add /Home/Example5 to the URL in the browser. The interview loads.
  4. When the interview has finished loading, navigate to the second question, NumberExample-n. Enter 1234.56. This number will appear in the field with the number and decimal separators changed to 1.234,56.
  5. Navigate to the third question, DateExample-d. Click on the DatePicker icon. You will see that the month name 'January' has changed to the name specified in the language module, 'Januar'.
  6. Select the date January 18th, 2015 from the date picker. The date appears in the answer field using the Day/Month/Year date format.

  7. Navigate to the fourth question, TrueFalseExample-tf. The 'Yes' and 'No' options for the True/False question have changed to 'Ja' and 'Nein'.

Source Code (C#)

In the HomeController:

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

In the LanguageModule.js file:

(function ($) {
    // Register the new language module with the HotDocs locale infrastructure.
    var Locales = $.Locales = (typeof $.Locales === "undefined") ? {} : $.Locales;

    // Add a new language module definition to the array.
    Locales["de-DE"] = {
        name: "German (Germany)",
        dateOrder: "DMY",
        months: ["Januar", "Februar", "März", "April", "Mai", "Juni", "Juli", "August", "September", "Oktober", "November", "Dezember"],
        monthsShort: ["Jan", "Feb", "Mär", "Apr", "Mai", "Jun", "Jul", "Aug", "Sep", "Okt", "Nov", "Dez"],
        days: ["Sonntag", "Montag", "Dienstag", "Mittwoch", "Donnerstag", "Freitag", "Samstag"],
        daysShort: ["So", "Mo", "Di", "Mi", "Do", "Fr", "Sa"],
        calWeekBegin: 1,
        calWeekend: [0, 6],
        zeroFormats: ["Null"],
        numSeps: [",", "."],
        strings: { ui_yes: "Ja", ui_no: "Nein" },
        SpellNum: function(value, strZero, bOrdinal){}   
    }
    // Either use the existing array or create a new one if it is not yet defined in the global scope.
   window.HOTDOC$ = $; }( typeof HOTDOC$ === "undefined" ? {} : HOTDOC$)
);

In the Example5 view:

@model JavaScriptAPIExamples.Models.InterviewModel
@{
    ViewBag.Title = "Example 5";
    ViewBag.SubTitle = "Using Language Modules in the HotDocs Interview";
}

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

<script type="text/javascript">
    /* Example 5 Javascript */
    HDInterviewOptions = {
        Locale: "de-DE",
        LanguageModule: {
            "de-DE":  "/Scripts/LanguageModule.js"
        }
    };
</script>

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