Creating_Help modified by Alessandro Vernet

Alessandro Vernet — Tue, 20 May 2014 18:43:59 -0000

Creating the Help HTML Document
Support for Multiple Bookmarks Per Field
- Different Bookmark
- Different Help Descriptions

Creating the Help HTML Document

The HTML help is created from the Word document by exporting it to HTML from Microsoft Word:

In Microsoft Word, open the file WEB-INF/resources/apps/exist/ibd/standard-rfp/bookmarks.doc. This file is not used by the application but stored in that directory for convenience. Update the file as needed.
Insert bookmarks for all the form fields you wish to have a help for.
- When there is a field in the Word document that corresponds to the form field, use for the bookmark the same name used for the form field. If the name is too long to be used as a bookmark name, pick a shorter name and rename accordingly the field in the Word document. The Word document is stored in the same directory as word.doc. If you change the name of a Word field, also change in word-fields.xml (always in the same directory) the name attribute for that field.
- When there is no field in the Word document for the form field, pick a name for the bookmark. This name will need to be declared in an XML file yet to be specified. For now please send those names with a description of the corresponding form fields to Alex.
Go to Save As, in the Save as type choose Web page (.htm, .html). Save the document as help.html in the same directory.
Edit the file with a text editor, look for <object

classid="clsid:38481807-CA0E-42D2-BF39-B33AF135CC4D" id=ieooui></object> and remove it. This is to prevent a warning on IE.

Support for Multiple Bookmarks Per Field

The help for some fields sometimes need too point to a different bookmark depending on some condition. For instance, there is a field that corresponds to the country of which laws have jurisdiction over the contract. The help for this field differs depending on the type of contract.

In the UI (XForms), we want to have just one field (i.e. one XForms control). The XForms control is mapped to a field name in the Word document through word-fields.xml. If there are multiple fields with the same name in the Word document, they will be all replaced by the value entered in the XForms control.

The help for this field, depending on the currently selected type of contract, needs to:

Point to a different bookmark in help-xy.html.
Have a different help description (e.g. "See paragraph 5.4" vs. "See paragraph 6.2").

Different Bookmark

Let's first see how to do point number 1. For most controls, the help bookmark name is the same as the field name. But it can be different. Here is an example of the markup that you can have in word-fields.xml:

&lt;mergefield name="Contract_Signature_Day" xref="Contract/Signature/Day"&gt;
    &lt;help if="ContractType = '1'" bookmark="Contract_Signature_Day_1"/&gt;
    &lt;help if="ContractType = '2'" bookmark="Contract_Signature_Day_2"/&gt;
&lt;/mergefield&gt;

If those help elements are present, when users click on the help icon each one of the if expression will be evaluated, and the bookmark for the first one that succeeds will be used.

Different Help Descriptions

In the resource files (form-resources-en.xml and form-resources-es.xml) instead of having just one <help>, you create a second one and add an attribute on the <help> elements to differentiate them. In the example that follows, the attribute contract-type has been added.

&lt;estimate-foreign-currency&gt;
    &lt;label&gt;Consultant's remuneration ceiling in foreign currency&lt;/label&gt;
    &lt;hint&gt;Insert amount and currency [Example: one hundred thousand pacific dollars (100.000)]&lt;/hint&gt;
    &lt;help contract-type="1"&gt;See paragraph 6.1 (b)&lt;/help&gt;
    &lt;help contract-type="2"&gt;See paragraph 6.2&lt;/help&gt;
&lt;/estimate-foreign-currency&gt;

Then edit the corresponding XForms control. In that control, the help would normally read:

&lt;xforms:help ref="$form-resources/estimate-foreign-currency/help"/&gt;

Since there are now multiple <help>, you need to indicate which one to choose. To select the one that has an attribute contract-type equal to the currently selected contract, write (if you wish, you can put the two lines that follow on just one line):

&lt;xforms:help ref="$form-resources/estimate-foreign-currency/help
    [@contract-type = instance('fr-form-instance')/ContractType]"/&gt;

Recent changes to Creating_Help

Creating_Help modified by Alessandro Vernet

Creating the Help HTML Document

Support for Multiple Bookmarks Per Field

Different Bookmark

Different Help Descriptions