Reference for writing HTML for the Html Form Entry Module

Tag Reference


See <translations>


Automatically completes a PatientProgram on the encounterDate when the form is submitted. This only happens if there is a valid PatientProgram for the patient on the encounterDate.  An example usage would be for a transfer form, when a patient is being transferred permanently out of the district, or if you have finite programs like maybe for PMTCT, for example.

This is a complementary tag to the enrollInProgram tag.   Available in htmlformentry 1.7.4.



WARNING -- using this tag in a one-form per encounter workflow may cause duplicate drugOrders to be created.  For example, if a monthly rendez-vous form has a field for current regimen, broken down by specific drugs (like a chronic care form might, for example), it is tempting to include this tag in an htmlform replicating the paper encounter form.  However, if the patient hasn't changed regimens, but the paper form has the regimen re-entered, you're going to end up with duplicate drugOrders, or worse, contradictory drugOrders if a regimen change has taken place, but the old drugOrders haven't been closed which has to be done currently outside of the htmlform (you'd have to open the original encounter during which the drugOrder was originally entered) .  The 'best' and currently recommended use of this tag is in conjunction with the htmlformflowsheet module, which allows you to use htmlforms in a flowsheet-type patient chart.  In this model of using the tag, all patient drugOrders across all relevant encounters (for example, all encounters with formId = 61, or even all encounters with encounterTypeId = 5) are loaded everytime you open the htmlform for the patient chart.  With this method, you can use this tag to build the exact patient regimen that you want reflected on the patient dashboard, and in your database.

Data entry widget for recording drug order. The widget displays input fields for drug names (drop-down), dose, frequency, start date (calendar), end date (calendar), instructions, discontinueReason.

Note: regimens are currently not considered in this tag, just the basic DrugOrder object.  Most of the design around this tag has been done within ticket HTML-120.


Example Usage

<drugOrder drugNames='d80af3ef-ca9f-11de-ac93-672ba0a04471, 17, kaletra' />        <!-- list of drugs is generated using UUID, ID and drug name -->
<drugOrder drugNames='d80af3ef-ca9f-11de-ac93-672ba0a04471' validateDose='true'/>  <!-- dose value will be validated (min, max value) -->


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


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 -->


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


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 -->


Data entry widget for recording provider for the encounter. Along with encounterDate and encounterLocation, encounterProvider should be present on every HTML form. (In 1.9+ you should use the <encounterProviderAndRole> tag instead.)


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 default="currentUser"/> <!-- a list of all users, with the current user 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 -->


(since 1.9; requires htmlformentry19ext module)

Data entry widget for recording one or more providers for the encounter, along with the roles those providers played in the encounter


Example Usage

<encounterProvider/>                                   <!-- dropdown of encounter roles : dropdown of providers -->
<encounterProvider default="currentUser"/>             <!-- dropdown of encounter roles : dropdown of providers with one chosen by default -->
<encounterProvider encounterRole="1" required="true"/> <!-- dropdown of providers, required for submission -->
<encounterProvider encounterRole="2" default="3"/>     <!-- dropdown of providers, with one chosen by default -->


In edit mode only, for an existing encounter, renders a voided checkbox that allows you to void the encounter.  There are no tag arguments.  Available in htmlformentry1.7.4.  This tag does not render anything when entering a new form, or when viewing an existing encounter (viewing the encounter implies already implies that the encounter is not voided).

Example Usage



Enrolls a patient in a program when the form is submitted.

To automatically un-enroll a patient, see the completeProgram tag.

Specifics about this enrollment behavior:



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.


Example Usage

     <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>


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


See <excludeIf>


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:


Example Usage

<lookup expression="patient.personName"/> this will translate to the velocity expression $\!{patient.personName}
<lookup expression="patient.personName.givenName"/>
<lookup expression="patient.personName.familyName"/>
<lookup expression="patient.getPatientIdentifier(5)"/> this will get the patient's first identifier with Identifier Type Id of 5
<lookup expression="patient.birthdate"/>
<lookup expression="patient.age"/>
<lookup expression="patient.gender" codePrefix="gender_"/>
<lookup complexExpression="#foreach( $addr in $patient.addresses ) $\!addr.cityVillage <br/> #end"/>
<lookup class="value" .../>   this will produce <span>result of expression</span>
<lookup expression="personAttributes.get('Tribe')"/> this will get the patient's 'Tribe' person attribute
<lookup expression="patient.personAddress.address1"/> this will get the address1 field of the patient's preferred address
<lookup expression="patient.personAddress.cityVillage"/> this will get the city field of the patient's preferred address
<lookup complexExpression="#foreach ( $relationship in $relationshipList )
    #if( $relationship.relationshipType.bIsToA == 'Parent' )
          #if( !($relationship.personB.patientId == $patient.patientId ))
             #if( $relationship.personB.gender == 'F' )
#end "/> this will get the patient's mother's name
<lookup complexExpression="
&#60;img src=&#34;${patient.getPatientIdentifier(1)}&#34;/&#62;
" /> this loads a dynamic image (This requires the us of ASCII character codes because the quote and less-than symbols are illegal.)


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

Example Usage

    <div style="background-color: $lightblue">This is a pleasant light blue color</div>


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


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 or in the translation mappings in the form itself.


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"/>


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")
answerCodes=Allows you to reference labels by a codes or a codes in the translation mappings defined in the form.
style="location" provides a drop-down list of Locations
style="person" provides a drop-down list of persons.  Used with role, it limits the list to a subset of persons who have an associated User account with the specified Role.


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


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.

<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"

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


Related Tags


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


Related Tags

Example Usage

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

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:
            <obsgroup groupingConceptId="1234">
                <td><obs conceptId="5089" labelText="Weight:"/></td>
                <td><obs conceptId="5090" labelText="Height:"/></td>

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


The patient tag can be used to create a new patient or edit an existing patient within an HTML Form. The tag allows to reference age/birthdate, gender, name, address, identifier.

(Note that there is no way in the current UI to access a form without already being in the context of specific patient, so, in the current UI you can only edit, not create, a patient using this tag. In custom code, if you intend to load a form without specifying a patientId or personId as a parameter, make sure set mode=enter when calling the html form entry controller.)


Attribute field

Additional attribute

Is mandatory while enter/create






Display the name fields (first name, family name, title, etc) based on the global variable layout value  

<patient field="name" />




Display Male / Female option in drop down combo box

<patient field="gender" />




Display the birth date input text box with calendar widget support

<patient field="birthDate" />




Display the age input text box with the validation of  0 <= age <= 200

<patient field="age" />



Either birth date or age

Display both birthday and age input text boxes (birthdate field has the high priority)

<patient field="birthDateOrAge" />




Display identifier input text box and identifier types in drop down combo box

<patient field="identifier" />




If you pass identifierTypeId attribute along with Identifier tag, only identifier input text box will display

<patient field="identifier" identifierTypeId="xxx"/>




Display the available locations in drop down combo box

<patient field="identifierLocation" />




Display the address fields (add1, add2, zipcode, etc) based on the global variable layout value

<patient field=”address” />

Example Usage

<patient field="name"/> <!-- displays the name fields -->
<patient field="identifier" identifierTypeId="2"/>  <!-- displays identifier field for identifier type 2 - input is validated accordingly  -->


(Since 1.7.4.)

Used to add relationships for a patient. The tag allows you to replace existing relationships or add new relationships, it does not currently support editing and deleting existing relationships.


Example Usage

<relationship type="21" whoAmI="A" required="true" changeExistingRelationship="false" 
	requireAttributes="HealthCenter:${currentPatientAttribute("Health Center")" programIds="3"display="search" labelText=”label” />


See <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



Example Usage

        <obsgroup groupingConceptId="1295">
                <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>
    <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"/>


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



This tag lets you create/edit/discontinue standard regimens, which are managed in the xml file in the global property 'dashboard.regimen.standardRegimens'.  In the htmlform, by just selecting a standard regimen and a start date, all the DrugOrders in the regimen will be created upon form submission.  For EDIT/VIEW mode, htmlformentry will compare all DrugOrders in an Encounter and will choose the 'best matching' standard regimen if there are any.  If any of the DrugOrders in an existing standard regimen have been modified outside of the tag, the standard regimen matching may fail  (for example if one of the drugs in a regimen has a modified start or discontinue date than the other DrugOrders, the tag will NOT assume that these DrugOrders are part of the same standard regimen).  In other words, all DrugOrders in a standard regimen are never really expected to be modifed outside of the htmlformentry context.

WARNING -- using this tag in a one-form per encounter workflow may cause duplicate drugOrders to be created.  See the WARNING for DrugOrder.  The same idea applies here too.



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.



Simplest example using defaults

    ...stuff goes here...

Example of applying custom Class to a translated label

    .customSubmit { font-weight: bold; }
<translations defaultLocale="en">
    <code name="submit_text">
        <variant locale="en" value="Close Flowsheet"/>
        <variant locale="fr" value="Not sure how to say it in French"/>
    ...stuff goes here...
    <submit submitStyle="customSubmit" submitCode="submit_text" />


See <repeat>


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


Related Tags


Used to define a code to assign variant values to.



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


Example Usage

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

And then in the body of the form:

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


See <translations>


Used to transfer a patient into a certain program workflow state.

*Since 1.9*

Note: Due to the way the encounterDate tag works, it should always be placed BEFORE any workflowState tags on a form, to insure that the proper date is used when processing state changes

Note: This tag is intended to be used with encounter dates that have only a date component (not a date and time component).  The tag may not always work in a logical manner when using encounter dates with a time component.



<workflowState workflowId="12" labelText="Lunch" stateIds="0,6,8" stateLabels="The Pig,Au Bon Pain" style="dropdown" />


Since programs, workflows, and states are not tied to encounters, and forms and still (generally) modeled around encounters, it is not always obvious exactly how this tag should modify an existing workflow, especially when editing a form.

When submitting a new form, the patient is transferred into the selected state on the encounter date entered on the form. Also:

When editing an existing form, the logic is more complex:

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.

Also note that attempting to use a less than (<) symbol within javascript will result in an error when saving the form, because the < symbol will be interpreted as the beginning of a tag. Use:


to represent a less than symbol within your javascript.


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


Gets the value of a field.


Sets the value of a field

Defining javascript functions to call before form validation and submission

Since version 1.8.0, it is possible to define javascript functions within a form that will be called before form validation and form submission. Two new array variables have been added to an HTML form: beforeValidation and beforeSubmit. These arrays are empty by default, but form developers can define functions within a form and add them to these arrays. All functions added to the beforeValidation array will be called before form validation, and all functions added to beforeSubmit will be called before form submission. These functions should return a boolean result: if a function returns false, no further functions are called, and the validation or submission is cancelled. 


<includeIf velocityTest="$patient.gender == 'M'">
<BR>This patient is a male.</BR>
<obs conceptId="5090" id="height" labelText="Height:"/>
<script type="text/javascript">
beforeSubmit.push(function() {
    var val = getValue('height.value');
    if (val == null || val == '') {
        getField('height.error').html('Required for males').show();
        return false;
    return true;

Additional jquery examples

If you want areas to "grey out" based on checking a radio button or checkbox, review this additional documentation for explanation and examples.

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>
<a name="page2"></a>
Jump to Page: <a href="#page1">1</a> \| <b>2</b> \| <a href="#page3">3</a>
<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

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