Reference for writing HTML for the Html Form Entry Module

Tag Reference

<code>

See <translations>

<encounterDate>

Data entry widget for recording encounter date. Along with encounterLocation and encounterProvider, encounterDate should be present on every HTML form.

Attributes

Example Usage

<encounterDate/>                   <!-- an initially-blank date widget -->
<encounterDate default="today"/>   <!-- a date widget pre-filled with today's date -->
<encounterDate showTime="true"/>   <!-- a date and time widget -->
<encounterDate showTime="true" default="now"/>   <!-- a date and time widget defaulting to the time on the server -->

<encounterLocation>

Data entry widget for recording location of the encounter. Along with encounterDate and encounterProvider, encounterLocation should be present on every HTML form.

Attributes

Example Usage

<encounterLocation/>                                    <!-- a list of all locations, sorted alphabetically by name -->
<encounterLocation default="2"/>                        <!-- a list of all locations, sorted alphabetically by name, with location 2 selected by default -->
<encounterLocation order="2,7,4"/>                      <!-- a list of the specified locations, by id -->
<encounterLocation order="Rwinkwavu,Kirehe,Mulindi"/>   <!-- a list of the specified locations, by name -->

<encounterProvider>

Data entry widget for recording provider for the encounter. Along with encounterDate and encounterLocation, encounterProvider should be present on every HTML form.

Attributes

Example Usage

<encounterProvider/>                   <!-- a list of all users -->
<encounterProvider default="djaz"/>    <!-- a list of all users, with the user whose username is djaz selected -->
<encounterProvider default="6"/>       <!-- a list of all users, with the user whose userId is 6 selected -->
<encounterProvider role="Provider"/>   <!-- a list of those users with the Provider role -->
<encounterProvider persons="username1,username2"/>   <!-- a list of those 2 Persons who are users with usernames username1 and username2 -->

<enrollInProgram>

Enrolls a patient in a program when the form is submitted. This only happens when the form is first entered--nothing happens when the form is edited or deleted.

Specifics about this enrollment behavior:

Attributes

<excludeIf>

A tag that optionally exclude all its content based on evaluating a logic token or a velocity expression. This tag has to only contain either a logic test or a velocity test.

Attributes

Example Usage

   <htmlform>
     <table border="0" width="100%">
        <tr><td><includeIf logicTest="GENDER = F">This shows a logic test for a woman</includeIf> </td></tr>
        <tr><td><includeIf velocityTest=""$patient.gender" == "F" ">This shows a velocity test for a woman</includeIf> </td></tr>
        <tr><td><excludeIf logicTest="GENDER = F">This won't show for a logic test for a woman</excludeIf> </td></tr>
        <tr><td><excludeIf velocityTest=""$patient.gender" == "F" ">This won't show for a velocity test for a woman</excludeIf> </td></tr>
     </table>
   </htmlform>

<htmlform>

Top-level tag that defines a form. A form must be wrapped in an htmlform tag.

<includeIf>

See <excludeIf>

<lookup>

Allows you to evaluation of velocity expressions. See the Velocity Users Guide for more documentation.

The variables you have access to in the velocity context are:

Additionally (since 1.7.0) there are some functions available to you that allow you to access existing patient data:

Attributes

Example Usage

<lookup expression="patient.personName"/> this will translate to the velocity expression $\!{patient.personName}
<lookup expression="patient.getPatientIdentifier(5)"/> this will get the patient's first identifier with Identifier Type Id of 5
<lookup complexExpression="#foreach( $addr in $patient.addresses ) $\!addr.cityVillage <br/> #end"/>
<lookup class="value" .../>   this will produce <span>result of expression</span>

<macros>

Define macros at the top of the file (e.g. for things like colors).

Example Usage

<htmlform>
    <macros>
        lightgrey=#e0e0e0
        lightblue=#e0e0ff
        darkblue=#4444ff
    </macros>
    <div style="background-color: $lightblue">This is a pleasant light blue color</div>
</htmlform>

<obs>

Generates an obs data entry widget. Depending on the datatype of the concept you specify, you get different obs.value widgets, and you use different attributes to control them.

Data Types

Numeric

By default, displays a small text box that auto-checks that entries are between absoluteMinimum and absoluteMaximum for the concept, and checks on precise also. You can also specify a constrained list of answers, as radio button or checkboxes. (Since 1.6.1) Example:

<!-- free text box (constrained to legal numbers) -->
<obs conceptId="5497" labelText="Most recent CD4:" dateLabel="Date of test:"/>

<!-- constrained to None, 1-6, and 7-8 -->
<obs conceptId="123" labelText="Education" answers="0,6,8" answerLabels="None,1-6,7-8" style="radio"/>
<obs conceptId="123" labelText="Education" answers="0,6,8" answerLabels="None,1-6,7-8" style="dropdown"/>

You can also specify answerCodes instead of answerLabels to reference answer labels by codes in messages.properties or in the translation mappings in the form itself.

Boolean

Various widget styles can be used to input Boolean values:

style="checkbox"                 A checkbox that when checked creates a TRUE obs, and when unchecked does nothing
style="checkbox" value="false"   A checkbox that when checked creates a FALSE obs, and when unchecked does nothing
style="no_yes"                   Radio buttons for no and yes. You may click on a selected radio button to unselect it.
style="yes_no"                   Like above but reverse order
style="no_yes_dropdown"          Dropdown list with blank, no, and yes options.
style="yes_no_dropdown"          Like above but reverse order

<!-- Localization -->
<obs style="no_yes" noLabel="Non" yesLabel="Oui"/>

Text

By default, displays a normal text input box.

size="5" means a text field with the specified size
style="textarea" means a textarea
rows="10" number of rows in the textarea (implies style="textarea")
cols="80" number of columns in the textarea (implies style="textarea")
answers="comma,separated,legal,answers"
answerLabels="Display,For,Legal,Answers"
answerCodes=Allows you to reference labels by a messages.properties codes or a codes in the translation mappings defined in the form.
style="location" provides a drop-down list of Locations.

Date

Renders a date picker widget. Note that dates are not allowed to be in the future, unless attribute allowFutureDates="true".

Coded

Renders a drop-down with all possible coded answered. Set style="radio" to display a radio set of options in lieu of a drop-down. Set style = "autocomplete" to display a autocomplete widget. Note autocomplete has to work with either an answerClasses attribute or an answerConceptId attribute.

Examples:
<obs conceptId="1234" answerConceptId="123" labelText="The question:" answerLabel="The answer"/>
Renders as: The question: [ ]The answer
If checked creates an obs with conceptId=1234 and valueCoded=123

<obs conceptId="1234"/>
Renders as a dropdown of all possible answer specified for concept 1234 in the dictionary

<obs conceptId="1234" answerConceptIds="123,7,912" answerLabels="Malaria,Tuberculosis,Diabetes"/>
Renders as a dropdown of the specified answers with the specified labels.

<obs conceptId="1296" answerClasses="Drug"/>
Renders as a dropdown all Concepts with ConceptClass = "Drug", ordered by Concept Name

<obs conceptId="1296" answerClasses="Drug" style="autocomplete"/>
Renders as a autocomplete widget with ConceptClass = "Drug", ordered by Concept Name

You can also specify answerCode instead of answerLabel to reference an answer label by a code in messages.properties or in the translation mappings in the form itself.

Attributes

<obs conceptIds="1441,3017,2474" answerConceptId="656" labelText="ISONIAZID"/>
Renders as a dropdown list of drug sensitivity results for the drug isoniazid. 
The resulting obs has, for example,'WEAKLY POSITIVE' for the concept, and Isoniazid as the conceptAnswer.

Related Tags

<obsgroup>

Used to create an obs group. You are required to specify a groupingConceptId. Nested obs groups are now supported.

Attributes

Related Tags

Example Usage

<obsgroup groupingConceptId="1234">
    <obs conceptId="1234" answerConceptId="123" answerLabel="Other"/>
    <obs conceptId="987" labelText="specify:"/>
</obsgroup>

You can wrap an obsgroup tag anywhere in the html, generally speaking, as long as it is still a well-formed xml document.

This is okay:
    <table>
        <tr>
            <obsgroup groupingConceptId="1234">
                <td><obs conceptId="5089" labelText="Weight:"/></td>
                <td><obs conceptId="5090" labelText="Height:"/></td>
            </obsgroup>
        </tr>
    </table>

This will break:
    <obsgroup groupingConceptId="1234">
        <table>
            <tr>
                <td><obs conceptId="5089" labelText="Weight:"/></td>
                <td><obs conceptId="5090" labelText="Height:"/></td>
            </obsgroup>
        </tr>
    </table>

<render>

See <repeat>

<repeat>

Repeatedly renders code that is contained within template tags. Facilitates future code maintenance. Repeats can be nested inside of other tags. A repeat can contain only 2 top level tags: template and render.

Related Tags

<template>

<render>

Example Usage

<repeat>
    <template>
        <obsgroup groupingConceptId="1295">
            <tr>
                <td><obs conceptId="1297" answerConceptId="{concept}" answerLabel="{effect}" labelText=""/></td>
                <td><obs conceptId="3063"/></td>
                <td><obs conceptId="1300"/></td>
                <td><obs conceptId="1643"/></td>
            </tr>
        </obsgroup>
    </template>
    <render concept="6355" effect="Nausées/vomissements"/>
    <render concept="16" effect="Diarrhée"/>
    <render concept="80" effect="Arthralgie"/>
    <render concept="877" effect="Etourdissements et/ou vertiges"/>
</repeat>

<section>

The <section> tag lets you break your form, and corresponding form schema, into sections.

Attributes

<submit>

You need to put a submit tag at the bottom of your form, or else your users will be very disappointed in you. Label/Code/Style attributes analogous to a section tag can be applied.

Attributes

Example

See <repeat>

<translations>

Defines translation mappings at the top of the file which can be accessed by specialized coded attributes in other tags.

Attributes

Related Tags

<code>

Used to define a code to assign variant values to.

Attributes

<variant>

Used to identify the value for a code as determined by the locale.

Attributes

Example Usage

<translations defaultLocale="en">
    <code name="night_sweats">
        <variant locale="en" value="night sweats"/>
        <variant locale="fr" value="sueurs nocturnes"/>
    </code>
</translations>

And then in the body of the form:

<obs conceptId="1234" labelCode="night_sweats"/>

<variant>

See <translations>

Javascript function reference

Javascript overview

You've always been allowed to write Javascript in an HTML form but since version 1.6.8 we provide some built-in Javascript helper functionality.

getField(idAndProperty)

Used to get a JQuery handle to a field, so you can attach event listeners to it.

getValue(idAndProperty)

Gets the value of a field.

setValue(idAndProperty)

Sets the value of a field

Other Examples and Tips

Example HTML Forms

Linking to Pages

To make it seem like your html form has multiple pages, it would be best to put links to allow the user to jump down to the next page:

<a href="#page1">1</a>
Jump to Page: <b>1</b> \| <a href="#page2">2</a> \| <a href="#page3">3</a>
...
...
<hr/>
<a name="page2"></a>
Jump to Page: <a href="#page1">1</a> \| <b>2</b> \| <a href="#page3">3</a>
...
...
<hr/>
<a name="page3"></a>
Jump to Page: <a href="#page1">1</a> \| <a href="#page2">2</a> \| <b>3</b>
...

Features in Version 1.7

New features include access to past observations, as well as the logic service, from the lookup tag.

An example for first encounter location using logic:

<lookup expression="fn.logic('first  encounterLocation')"/>

Or you could calculate the patient's BMI without using logic: (I know this is ugly. Blame the velocity templating language.)

Previous BMI:

<lookup complexExpression="#set( $wt = $fn.latestObs(5089)  ) #set( $ht = $fn.latestObs(5090) ) #set( $bmi = $wt / ($ht * $ht) )  $\!{bmi}" />

Create your own custom tag and handler

It is possible to register your own tag and handler with htmlformentry from another module.  For an example of this, see the htmlformflowsheet module.