Reference for writing HTML for the Html Form Entry Module

Tag Reference

<code>

See <translations>

<completeProgram>

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. If the program has outcomes configured, then if the same concept is used on the form, that concept will be the outcome of that patient's program.

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. The PMTCT program could have the outcome concept, "PMTCT Outcomes" assigned with concept set or coded answer members "Child Died", "Child HIV Positive", "Child HIV Negative". An observation with the coded answer "Child Died" on the form would activate the "Child Died" program outcome.

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

Attributes

WARNING -- Changing the answer to the "outcome" observation will not change the outcome of the program.

<controls>

Conditionally displays a section of html content when an observation is set to a certain value. When a section is hidden, any inputs in it are cleared.

The <controls> tag is only allowed inside an <obs/> tag. It should contain one or more <when/> tags.

It will be triggered when the form is first loaded, as well as when the <obs> field changes value.

Available since 2.1.6.

Attributes

None

Example Usage

<obsgroup groupingConceptId="1">
    <p>
        Disposition:
        <obs id="whatKind" conceptId="2" answerConceptIds="3,4,5">
            <controls>
                <when value="3" thenDisplay="#admit-section"/>
                <when value="4" thenDisplay="#discharge-section"/>
            </controls>
        </obs>
    <p>
    <p id="admit-section">
        Admission diagnosis:
        <obs concept="100"/>
    </p>
    ...
</obsgroup>


<drugOrder>

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.

Attributes

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

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

<encounterDiagnoses> & <encounterDiagnosesByObs>

Data entry widgets bundled within the Core Apps module (and not HTML Form Entry) for recording encounter diagnoses with auto-completion. It can record multiple diagnoses marking them as presumed/confirmed and/or primary/secondary. Either of <encounterDiagnoses>  or <encounterDiagnosesByObs>  tag can be used at-most once in an HTML form.

Attributes

Example Usages

The following examples are identical to using the <encounterDiagnosesByObs/>  tag.

<encounterDiagnoses required="true" selectedDiagnosesTarget="#encounter-diagnoses-target" preferredCodingSource="ICD-10-WHO"/>

<encounterDiagnoses required="true" selectedDiagnosesTarget="#encounter-diagnoses-target" preferredCodingSource="ICD-10-WHO" diagnosisConceptSources="ICD-10-WHO"/>

<encounterDiagnoses required="true" selectedDiagnosesTarget="#encounter-diagnoses-target" preferredCodingSource="ICD-10-WHO" diagnosisConceptClasses="Diagnosis"/>

<encounterDiagnoses required="true" selectedDiagnosesTarget="#encounter-diagnoses-target" preferredCodingSource="ICD-10-WHO" diagnosisConceptClasses="Diagnosis" diagnosisConceptSources="0"/>

<encounterDiagnoses required="true" selectedDiagnosesTarget="#encounter-diagnoses-target" preferredCodingSource="ICD-10-WHO" diagnosisSets="CIEL:160170,CIEL:160169"/>

<encounterDiagnoses required="true" selectedDiagnosesTarget="#encounter-diagnoses-target" preferredCodingSource="ICD-10-WHO" diagnosisSets="CIEL:160170,CIEL:160169"/>

<encounterDiagnoses required="true" selectedDiagnosesTarget="#encounter-diagnoses-target" preferredCodingSource="ICD-10-WHO" diagnosisSets="160170AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,160169AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"/>

<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 default="GlobalProperty:defLoc"/>    <!-- a list of all locations, sorted alphabetically by name, with the location specified in the "defLoc" global property selected by default -->
<encounterLocation default="SessionAttribute:emrContext.sessionLocationId"/> <!-- uses the currently logged in location, per the Reference App --> 
<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 -->
<encounterLocation type="autocomplete"/>                <!-- an autocomplete field for location selection, with prepopulated list of locations -->

<encounterProvider>

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

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 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 -->
<encounterProvider type="autocomplete"/>             <!-- an autocomplete field for provider selection, with pre populated list of providers-->

<encounterProviderAndRole>

(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

Attributes

Example Usage

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

<encounterProviderAndRole encounterRole="2" count="2"/>       <!-- display 2 dropdown of providers, for encounter role 2 -->
<encounterProviderAndRole autocompleteProvider="true" encounterRole="1" /> <!--display an autocomplete search box for provider-->

Notes

Currently, only one encounterProviderAndRole tag is is supported per encounter role, and only a single tag without a encounterRole is supported.  For instance, the following two examples below would be illegal:

<!-- can't have two tags without specifying a role -->
First Provider: <encounterProviderAndRole/> 
Second Provider: <encounterProviderAndRole/>
 
<!-- can't have two tags with the same provider role -->
First Doctor: <encounterProviderAndRole encounterRole="2" />
Second Doctor: <encounterProviderAndRole encounterRole="2"/>
First Nurse: <encounterProviderAndRole encounterRole="3" />
Second Nurser: <encounterProviderAndRole encounterRole="3"/>
 
<!-- proper way to specific multiple providers of different roles -->
Doctors: <encounterProviderAndRole encounterRole="2" count="2"/>   <!-- renders two dropdowns for providers -->
Nurses: <encounterProviderAndRole encounterRole="3" count="2"/>

<encounterType>

Used to specify the Encounter Type while filling out an HTML Form rather than when designing the form. When using this tag, the "Encounter Type" field of the HTML Form design should be left blank.

Attributes

Example Usage

<encounterType types="25,24,9,23,20,14,18,22,19,13,10,17,26,11,12,16,21,15,27" default="CLINIC MOBILE" />

<encounterVoided>

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

<encounterVoided/>

<enrollInProgram>

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:

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>

<exitFromCare>

This tag is used to record the scenario where a patient exits care. It operates in a similar manner to the exit from care functionality on the patient dashboard, providing a date field  and a reason dropdown to the user. To exit a patient from care, the date field should be set to the date of the patient's exit and the reason dropdown set to the reason for the patient's exit. Exiting a patient from care is not mandatory, however once the fields are filled out and submitted for a certain patient, the exit can't be undone, hence the fields can't be set back to empty. However it is possible to edit the date and reason fields.

The possible reasons for exiting care are specified by setting the global property concept.reasonExitedCare. This should point to a question concept; the associated answer concepts will be used to populate the reason dropdown presented to the user.

The tag is also used to mark a patient's death, when 'the death of the patient' is the reason for exiting from care, by providing an additional dropdown to set the cause of death. If the user selects the reason dropdown answer as "Patient Died", a new dropdown will be visible for the user to enter the 'Cause of Death'. The possible causes for patient's death are specified by setting the global property concept.causeOfDeath. This should point to a question concept; the associated answer concepts will be used to populate the cause of death dropdown presented to the user.

If user selects the 'Cause of Death' dropdown answer as "Other Non-coded", there will be another text field visible to manually enter the reason for the death, as the exact cause is not given in the cause dropdown. Here the user can type any of the reason,description etc. which caused the patient's death. 

Once the cause of death and other reason text fields are filled out and submitted for a certain patient, the death obs can't be undone. However it is possible to change the reason for exit field back to an answer other than "Patient Died", so the exit observation can be edited back. Then it will not display the death fields' entries but the death obs still exists. It is also possible to edit the cause of death and other reason fields too.

Example Usage

<exitFromCare/>

<htmlform>

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

<ifMode>

A tag that optionally includes all its content based on whether we are in ENTER, EDIT, or VIEW mode. (Since 2.0.3.)

Attributes

Example Usage

<htmlform>
    <obs conceptId="5089" id="weight"/>
    <ifMode mode="ENTER">
        <script type="text/javascript">
            getField("weight.value").change(function() { window.alert("You entered a weight"); });
        </script>
    </ifMode>


    <ifMode mode="EDIT">
        This will only be displayed in edit mode.
    </ifMode>


    <ifMode mode="EDIT" include="false">
       This is NOT be displayed when in edit mode, but will be displayed in all other modes.
    </ifMode>

</htmlform>

<immunization>

A tag that allows you to record the obs set for vaccinations according to the CIEL concept dictionary; CIEL:1421 - Immunization History. (Since 2.5.)

Example Usage

	<section headerLabel="2. Vaccines">
            <table class="baseline-aligned">
              <tr>
                <td style="text-align:right;">BCG</td>
                <td>
                    <immunization showDate="true" id="bcg" vaccineConceptId="886AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" sequenceNumber="1" label="" />
                </td>
              </tr><tr>
                <td style="text-align:right;">POLIO 0</td>
                <td>
                    <immunization showDate="true" id="polio0" vaccineConceptId="783AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" sequenceNumber="0" label="" />
                </td>
              </tr><tr>
                <td style="text-align:right;">POLIO 1</td>
                <td>
                    <immunization showDate="true" id="polio1" vaccineConceptId="CIEL:783" sequenceNumber="1" label="" />
                </td>
              </tr><tr>
                <td style="text-align:right;">POLIO 2</td>
                <td>
                    <immunization showDate="true" id="polio2" vaccineConceptId="783AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" sequenceNumber="2" label=""/>
                </td>
              </tr><tr>
                <td style="text-align:right;">POLIO 3</td>
                <td>
                    <immunization showDate="true" id="polio3" vaccineConceptId="783AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" sequenceNumber="3" label=""/>
                </td>
              </tr><tr>
                <td style="text-align:right;">POLIO 4</td>
                <td>
                    <immunization showDate="true" id="polio4" vaccineConceptId="783AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" sequenceNumber="4" label=""/>
                </td>
               </tr>
           </table>
	</section>

<includeIf>

See <excludeIf>

<lookup>

Allows 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.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 expression="fn.getConcept('110').description"/> returns description of concept ID 21. Ticket # 478
<lookup expression="fn.getConcept('CIEL:1647').name"/> returns the name of the concept with CIEL mapping of 1647
<lookup complexExpression="#foreach ( $relationship in $relationshipList )
    #if( $relationship.relationshipType.bIsToA == 'Parent' )
          #if( !($relationship.personB.patientId == $patient.patientId ))
             #if( $relationship.personB.gender == 'F' )
                   $relationship.personB.personName
             #end
          #end
    #end
#end "/> this will get the patient's mother's name
<lookup complexExpression="
&#60;img src=&#34;http://www.someserver.com/somepath/barcode.php?string=${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.)
<lookup complexExpression="$fn.latestObs(6527).valueCoded.name"/> this shows the concept name of the latest coded value for concept # 6527.
<lookup expression="visit.startDatetime"/> this shows the start date of the current visit
<lookup complexExpression="#foreach($encounterProvider in $fn.latestEncounter('2549af50-75c8-4aeb-87ca-4bb2cef6c69a').encounterProviders) $encounterProvider.provider.person.personName #end" /> this gets the names of the providers in the latest encounter of the specified type 

<macros>

The macro tag enables one to define a set of constants that can be referred to within the form.  Some of it's more common uses are:

Prior to release 2.6, the only way to define macros was as a properties-style text block within the body of the macros tag.  This is maintained beyond 2.6 for backwards compatibility.  An example of this can be seen below:

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>


As of release 2.6, macros can also be defined using xml tags (see syntax below). The added benefit added here was the ability to supply either a "value" attribute, which simply assigns a constant value to the macro, OR to supply an "expression" attribute, which enables assigning a macro value based on the evaluation of a velocity expression.  This exposes the same capabilities as the lookup tag, with the same syntax as one would use in that tag.  Examples below:

Related Tags

<macro> (from version 2.6)

Used to define a particular macro variable that can be re-used on the form.

Attributes

Example Usage

<htmlform>
    <macros>
        <macro key="backgroundColor" value="#e0e0e0"/>
		<macro key="weight" expression="fn.globalProperty('concept.weight')"/>
    </macros>
    <div style="background-color: $backgroundColor">Weight:  <obs conceptId="$weight"/></div>
</htmlform>


<markPatientDead>

When a form with this tag is submitted (in either Enter or Edit mode) then the patient will be marked as deceased, with a date and cause as specified by tag attributes.

Since 2.4.

Attributes

<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 a dropdown (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 conceptId="5272" 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
answerLocationTags="TAG1, TAG2" limits the locations in the drop-down list to the locations tagged with TAG1 or TAG2
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.
maxlength="50" limits the number of characters that can be entered into the field to 50 (supports any valid integer)
placeholder="Type something" shows placeholder text before the user types

Date

Renders a date picker widget. Note that dates are not allowed to be in the future, unless attribute allowFutureDates="true". If the concept is of type datetime, then both date and time controls will be rendered. However you can override this with allowTime="false" if you want only a date control for a datetime concept.

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, answerConceptId, or answerConceptSetIds 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="1234" answerConceptSetIds="345,789" style="autocomplete" />
Renders an autocomplete textbox which provides coded answers from another concept set.

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

<obs conceptId="1234" answerDrugs="true"/>
Renders as an autocomplete widget that searches the Drug table, and will save the selected value in obs.value_drug
 
<obs conceptId="1234" answerDrugs="true" displayTemplate="{{concept}} ({{doseStrength}} {{units}})"/>
Renders an an autocomplete widget, with items displayed using a custom handlebars template. (Default is "{{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.

Complex

Renders a upload widget, which allows uploading of a file. If the data handler of the concept is an ImageHandler, then only images are allowed for upload, which will be displayed in the form itself when viewing. Otherwise, BinaryDataHandler or BinaryStreamHandler can be used to support any file type.

<obs conceptId="1234" />
Renders as a "Choose File" button. After browsing to choose the tile, the name of the file chosen is beside it. 

Note: The value of conceptId must be a complex obs with a handler, like "ImageHandler" For more info, see the Workflow section at the Complex Obs Support page.

Attributes

Related Tags

<obsgroup>

Used to create an obs group. This is used when you need to link multiple <obs> concepts together. You are required to specify a groupingConceptId, which is of type ConvSet. For example, IMMUNIZATION HISTORY (1421), which has set members IMMUNIZATION SEQUENCE NUMBER (1418), VACCINE LOT NUMBER (1420), VACCINATION DATE (1410), IMMUNIZATIONS (984) and VACCINE MANUFACTURER (1419) which store the details related to the immunization. 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>

<obsreference>

An extension of the standard Obs tag that allows for matching observations outside of the current encounter but collected during the same day as the encounter to be displayed within the form.

If  an encounter datetime is present within the context when the form is rendered (which generally only occurs in VIEW or EDIT mode), this tag will search for all Obs with the same question concept for that patient collected during the current day.  If multiple matching obs are found, it will take the most recent obs. This is the reference obs.

If a reference obs is found and  there is no matching obs on the existing encounter, in view mode the value for this obs will be displayed  where the obs from the encounter would normally be displayed.  Additionally, in edit mode, if a reference obs is found and there is no matching obs on the existing encounter, the reference obs will be displayed view mode, and there will be no widget for entering data.  If allowOverride is set to true, an "Override" button will be present, and clicking it will hide the reference obs and display the standard edit widget for the field.

Note this currently only supports Obs rendered with the following widget types: Numeric Field, Text Input, Date (not Time or Datetime), Dropdown, Radio Button, and Checkbox

All existing Obs attributes are supported, with the following additional attributes added.

Attributes

Related Tags

<obsFromFragment>

Used to record an observation from a given fragment. This is used when you want to use a fragment widget in an htmlform to record an Obs; this works through the associated concept which is specified by: {{conceptId}} that is used to determine the Obs' datatype as its done in 

the <obs/> tag. A number of fragments are supported by the tag, specifically the uicommons field fragments eg. datetimepicker, dropDown, checkbox, radioButtons etc. The tag can also work within or is compatible with the <obsgroup/> tag. 

Attributes

Related Tags

<patient>

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

Attributes

Attribute field

Additional attribute

Is mandatory while enter/create

Description

Example

name


Yes

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

<patient field="name" />

gender


Yes

Display Male / Female option in drop down combo box

<patient field="gender" />

birthDate  


Yes

Display the birth date input text box with calendar widget support

<patient field="birthDate" />

age


Yes

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

<patient field="age" />

birthDateOrAge


Either birth date or age

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

<patient field="birthDateOrAge" />

identifier


Yes

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

<patient field="identifier" />

identifier

identifierTypeId

Yes

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

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

identifierLocation


Yes

Display the available locations in drop down combo box (note that there is an open bug concerning this attribute...see HTML-414

<patient field="identifierLocation" />

address


No

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

<postSubmissionAction>

Since 2.4

Lets you run server-side Java code as part of a form's submission. This action happens after standard form processing (e.g. obs are created) but it happens in the same transaction, so if this processing throws an error, the entire form submission is invalidated.

Attributes

<redirectOnSave>

(Since 2.4)

Lets a form indicate what URL to go to after it is submitted, overriding the default behavior of the web framework.

Attributes

<relationship>

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

Attributes

Example Usage

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

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

<repeat with="">

(Available in HFE 2.0.2 and above)

A less-verbose version of the <repeat> tag.

Attributes

                                  

Example Usage

<repeat with="['664','No Complaints'],['832','Weight Loss'],['777','Nausea']">
<obs conceptId="1069" answerConceptId="{0}" answerLabel="{1}" style="checkbox" /><br/>
</repeat>

would render as:

<obs conceptId="1069" answerConceptId="644" answerLabel="No Complaints" style="checkbox" /><br/>
<obs conceptId="1069" answerConceptId="832" answerLabel="Weight Loss" style="checkbox" /><br/>
<obs conceptId="1069" answerConceptId="777" answerLabel="Nausea" style="checkbox" /><br/>




<restrictByRole>

A user with a particular role can be restricted from either viewing a certain HTML form (or a section in the form) by using the <restrictByRole> tag.

Attributes

<section>

The <section> tag lets you break your form, and corresponding form schema, into sections. Note that we wrote this tag before HTML 5 introduced a real-HTML section tag, so the default behavior of this tag outputs a div.

Attributes

Example Usage

If you want to use HTML 5 section tags, do something like this:

<section headerLabel="Encounter details" sectionTag="section" headerTag="h1"> Your content </section>

<!-- This would be the output -->
<section class="section">
    <h1 class="sectionHeader">Encounter details</h1>
    Your content
</section>

<condition>

This tag lets you record a condition.

Since a condition is not tied to an encounter, you can not edit or view conditions created within a particular visit or encounter using this tag. 

WARNING - In order to use this tag, you must be running openmrs platform 2.2.0 and above.

Attributes

Example Usage


<htmlform>
    ...stuff goes here...
	<!-- For cases were a condition is required -->
    <condition required="true" />
	<!-- For cases were a condition isn't required -->
    <condition required="false" />
</htmlform>

<standardRegimen>

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.

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

Simplest example using defaults

<htmlform>
    ...stuff goes here...
    <submit/>
</htmlform>

Example of applying custom Class to a translated label

<htmlform>
<style>
    .customSubmit { font-weight: bold; }
</style>
<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"/>
    </code>
</translations>
    ...stuff goes here...
    <submit submitStyle="customSubmit" submitCode="submit_text" />
</htmlform>

<template>

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"/>
or
<lookup expression="fn.message('night_sweats')"/>

<uiInclude>

This tag is only available when using the HTML Form Entry UI Framework Integration module and OpenMRS 1.9.3+. It lets you access resources provided by the UI Framework.

Attributes

You are required to specify one of javascript, css, or fragment.

Example Usage

<uiInclude provider="uicommons" javascript="angular.min.js"/>
<uiInclude provider="coreapps" javascript="diagnoses/diagnoses.js"/>


<variant>

See <translations>

<when>

Since: 2.1.6

Must be inside <obs id="..."><controls>...</controls></obs>. See <controls>.

An action that should be taken conditionally based on a chosen value of the <obs> it is in.

Attributes

It is valid to combine more than one of the then* attributes, though in practice you probably want either thenDisplay, or else thenJavascript + elseJavascript.

Example

<obsgroup groupingConceptId="PIH:9722">
    Form signed by role
    <obs id="form-signed-role" conceptId="PIH:TITLE WHO COMPLETED FORM" answerConceptIds="PIH:DOCTOR,PIH:NURSE,PIH:OTHER">
        <controls>
            <when value="PIH:OTHER" thenDisplay="#form-signed-role-other"/>
        </controls>
    </obs>
    <span id="form-signed-role-other">
        Specify:
        <obs conceptId="PIH:GENERAL FREE TEXT"/>
    </span>
</obsgroup>


<obsgroup groupingConceptId="PIH:9722">
    <p>
        <label>Form signed by role</label>
        <obs id="form-signed-role" conceptId="PIH:TITLE WHO COMPLETED FORM" answerConceptIds="PIH:DOCTOR,PIH:NURSE,PIH:OTHER">
            <controls>
                <when value="PIH:OTHER"
                    thenJavaScript="htmlForm.simpleUi.showField('form-signed-role-other')"
                    elseJavaScript="htmlForm.simpleUi.hideField('form-signed-role-other')"/>
            </controls>
        </obs>
    </p>
    <p id="form-signed-role-other">
        <label>Specify:</label>
        <obs conceptId="PIH:GENERAL FREE TEXT"/>
    </p>
</obsgroup>

<workflowState>

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.

Attributes

Example

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

Notes

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:

See HTML-321 for an example of a reported bug that actually is not bug, but, instead obeys the above logic. HTML-321 as been closed as do not fix, but if there is a strong argument that the behaviour should be changed, we can reassess.

Other Examples and Tips

Example HTML Forms

Javascript

You've always been allowed to write Javascript in an HTML form. There is some built-in Javascript helper functionality. The documentation for this has been moved to the HTML Form Entry JavaScript Reference page.

Including HTML character codes in HTML Forms

It is common to include the "non-breaking-space" character code within html:

<td>First&nbsp;Name</td>

However, the non-breaking-space character is, technically, is not valid XML.  Since HTML forms must be valid XML, you will need to use the ASCII-code for a space as a substitution for the non-breaking-space character code:

<td>First&#160;Name</td>

There is currently a ticket about this issue: HTML-325

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.

<obs conceptId="1234" />Renders as a "Choose File" button. After chosen, the name of the file is beside it. 

Reference for writing HTML for the Html Form Entry Module

Tag Reference

<code>

See <translations>

<completeProgram>

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. If the program has outcomes configured, then if the same concept is used on the form, that concept will be the outcome of that patient's program.

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. The PMTCT program could have the outcome concept, "PMTCT Outcomes" assigned with concept set or coded answer members "Child Died", "Child HIV Positive", "Child HIV Negative". An observation with the coded answer "Child Died" on the form would activate the "Child Died" program outcome.

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

Attributes

WARNING -- Changing the answer to the "outcome" observation will not change the outcome of the program.

<controls>

Conditionally displays a section of html content when an observation is set to a certain value. When a section is hidden, any inputs in it are cleared.

The <controls> tag is only allowed inside an <obs/> tag. It should contain one or more <when/> tags.

It will be triggered when the form is first loaded, as well as when the <obs> field changes value.

Available since 2.1.6.

Attributes

None

Example Usage

<obsgroup groupingConceptId="1">
    <p>
        Disposition:
        <obs id="whatKind" conceptId="2" answerConceptIds="3,4,5">
            <controls>
                <when value="3" thenDisplay="#admit-section"/>
                <when value="4" thenDisplay="#discharge-section"/>
            </controls>
        </obs>
    <p>
    <p id="admit-section">
        Admission diagnosis:
        <obs concept="100"/>
    </p>
    ...
</obsgroup>


<drugOrder>

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.

Attributes

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

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

<encounterDiagnoses> & <encounterDiagnosesByObs>

Data entry widgets bundled within the Core Apps module (and not HTML Form Entry) for recording encounter diagnoses with auto-completion. It can record multiple diagnoses marking them as presumed/confirmed and/or primary/secondary. Either of <encounterDiagnoses>  or <encounterDiagnosesByObs>  tag can be used at-most once in an HTML form.

Attributes

Example Usages

The following examples are identical to using the <encounterDiagnosesByObs/>  tag.

<encounterDiagnoses required="true" selectedDiagnosesTarget="#encounter-diagnoses-target" preferredCodingSource="ICD-10-WHO"/>

<encounterDiagnoses required="true" selectedDiagnosesTarget="#encounter-diagnoses-target" preferredCodingSource="ICD-10-WHO" diagnosisConceptSources="ICD-10-WHO"/>

<encounterDiagnoses required="true" selectedDiagnosesTarget="#encounter-diagnoses-target" preferredCodingSource="ICD-10-WHO" diagnosisConceptClasses="Diagnosis"/>

<encounterDiagnoses required="true" selectedDiagnosesTarget="#encounter-diagnoses-target" preferredCodingSource="ICD-10-WHO" diagnosisConceptClasses="Diagnosis" diagnosisConceptSources="0"/>

<encounterDiagnoses required="true" selectedDiagnosesTarget="#encounter-diagnoses-target" preferredCodingSource="ICD-10-WHO" diagnosisSets="CIEL:160170,CIEL:160169"/>

<encounterDiagnoses required="true" selectedDiagnosesTarget="#encounter-diagnoses-target" preferredCodingSource="ICD-10-WHO" diagnosisSets="CIEL:160170,CIEL:160169"/>

<encounterDiagnoses required="true" selectedDiagnosesTarget="#encounter-diagnoses-target" preferredCodingSource="ICD-10-WHO" diagnosisSets="160170AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,160169AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"/>

<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 default="GlobalProperty:defLoc"/>    <!-- a list of all locations, sorted alphabetically by name, with the location specified in the "defLoc" global property selected by default -->
<encounterLocation default="SessionAttribute:emrContext.sessionLocationId"/> <!-- uses the currently logged in location, per the Reference App --> 
<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 -->
<encounterLocation type="autocomplete"/>                <!-- an autocomplete field for location selection, with prepopulated list of locations -->

<encounterProvider>

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

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 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 -->
<encounterProvider type="autocomplete"/>             <!-- an autocomplete field for provider selection, with pre populated list of providers-->

<encounterProviderAndRole>

(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

Attributes

Example Usage

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

<encounterProviderAndRole encounterRole="2" count="2"/>       <!-- display 2 dropdown of providers, for encounter role 2 -->
<encounterProviderAndRole autocompleteProvider="true" encounterRole="1" /> <!--display an autocomplete search box for provider-->

Notes

Currently, only one encounterProviderAndRole tag is is supported per encounter role, and only a single tag without a encounterRole is supported.  For instance, the following two examples below would be illegal:

<!-- can't have two tags without specifying a role -->
First Provider: <encounterProviderAndRole/> 
Second Provider: <encounterProviderAndRole/>
 
<!-- can't have two tags with the same provider role -->
First Doctor: <encounterProviderAndRole encounterRole="2" />
Second Doctor: <encounterProviderAndRole encounterRole="2"/>
First Nurse: <encounterProviderAndRole encounterRole="3" />
Second Nurser: <encounterProviderAndRole encounterRole="3"/>
 
<!-- proper way to specific multiple providers of different roles -->
Doctors: <encounterProviderAndRole encounterRole="2" count="2"/>   <!-- renders two dropdowns for providers -->
Nurses: <encounterProviderAndRole encounterRole="3" count="2"/>

<encounterType>

Used to specify the Encounter Type while filling out an HTML Form rather than when designing the form. When using this tag, the "Encounter Type" field of the HTML Form design should be left blank.

Attributes

Example Usage

<encounterType types="25,24,9,23,20,14,18,22,19,13,10,17,26,11,12,16,21,15,27" default="CLINIC MOBILE" />

<encounterVoided>

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

<encounterVoided/>

<enrollInProgram>

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:

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>

<exitFromCare>

This tag is used to record the scenario where a patient exits care. It operates in a similar manner to the exit from care functionality on the patient dashboard, providing a date field  and a reason dropdown to the user. To exit a patient from care, the date field should be set to the date of the patient's exit and the reason dropdown set to the reason for the patient's exit. Exiting a patient from care is not mandatory, however once the fields are filled out and submitted for a certain patient, the exit can't be undone, hence the fields can't be set back to empty. However it is possible to edit the date and reason fields.

The possible reasons for exiting care are specified by setting the global property concept.reasonExitedCare. This should point to a question concept; the associated answer concepts will be used to populate the reason dropdown presented to the user.

The tag is also used to mark a patient's death, when 'the death of the patient' is the reason for exiting from care, by providing an additional dropdown to set the cause of death. If the user selects the reason dropdown answer as "Patient Died", a new dropdown will be visible for the user to enter the 'Cause of Death'. The possible causes for patient's death are specified by setting the global property concept.causeOfDeath. This should point to a question concept; the associated answer concepts will be used to populate the cause of death dropdown presented to the user.

If user selects the 'Cause of Death' dropdown answer as "Other Non-coded", there will be another text field visible to manually enter the reason for the death, as the exact cause is not given in the cause dropdown. Here the user can type any of the reason,description etc. which caused the patient's death. 

Once the cause of death and other reason text fields are filled out and submitted for a certain patient, the death obs can't be undone. However it is possible to change the reason for exit field back to an answer other than "Patient Died", so the exit observation can be edited back. Then it will not display the death fields' entries but the death obs still exists. It is also possible to edit the cause of death and other reason fields too.

Example Usage

<exitFromCare/>

<htmlform>

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

<ifMode>

A tag that optionally includes all its content based on whether we are in ENTER, EDIT, or VIEW mode. (Since 2.0.3.)

Attributes

Example Usage

<htmlform>
    <obs conceptId="5089" id="weight"/>
    <ifMode mode="ENTER">
        <script type="text/javascript">
            getField("weight.value").change(function() { window.alert("You entered a weight"); });
        </script>
    </ifMode>


    <ifMode mode="EDIT">
        This will only be displayed in edit mode.
    </ifMode>


    <ifMode mode="EDIT" include="false">
       This is NOT be displayed when in edit mode, but will be displayed in all other modes.
    </ifMode>

</htmlform>

<immunization>

A tag that allows you to record the obs set for vaccinations according to the CIEL concept dictionary; CIEL:1421 - Immunization History. (Since 2.5.)

Example Usage

	<section headerLabel="2. Vaccines">
            <table class="baseline-aligned">
              <tr>
                <td style="text-align:right;">BCG</td>
                <td>
                    <immunization showDate="true" id="bcg" vaccineConceptId="886AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" sequenceNumber="1" label="" />
                </td>
              </tr><tr>
                <td style="text-align:right;">POLIO 0</td>
                <td>
                    <immunization showDate="true" id="polio0" vaccineConceptId="783AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" sequenceNumber="0" label="" />
                </td>
              </tr><tr>
                <td style="text-align:right;">POLIO 1</td>
                <td>
                    <immunization showDate="true" id="polio1" vaccineConceptId="CIEL:783" sequenceNumber="1" label="" />
                </td>
              </tr><tr>
                <td style="text-align:right;">POLIO 2</td>
                <td>
                    <immunization showDate="true" id="polio2" vaccineConceptId="783AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" sequenceNumber="2" label=""/>
                </td>
              </tr><tr>
                <td style="text-align:right;">POLIO 3</td>
                <td>
                    <immunization showDate="true" id="polio3" vaccineConceptId="783AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" sequenceNumber="3" label=""/>
                </td>
              </tr><tr>
                <td style="text-align:right;">POLIO 4</td>
                <td>
                    <immunization showDate="true" id="polio4" vaccineConceptId="783AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" sequenceNumber="4" label=""/>
                </td>
               </tr>
           </table>
	</section>

<includeIf>

See <excludeIf>

<lookup>

Allows 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.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 expression="fn.getConcept('110').description"/> returns description of concept ID 21. Ticket # 478
<lookup expression="fn.getConcept('CIEL:1647').name"/> returns the name of the concept with CIEL mapping of 1647
<lookup complexExpression="#foreach ( $relationship in $relationshipList )
    #if( $relationship.relationshipType.bIsToA == 'Parent' )
          #if( !($relationship.personB.patientId == $patient.patientId ))
             #if( $relationship.personB.gender == 'F' )
                   $relationship.personB.personName
             #end
          #end
    #end
#end "/> this will get the patient's mother's name
<lookup complexExpression="
&#60;img src=&#34;http://www.someserver.com/somepath/barcode.php?string=${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.)
<lookup complexExpression="$fn.latestObs(6527).valueCoded.name"/> this shows the concept name of the latest coded value for concept # 6527.
<lookup expression="visit.startDatetime"/> this shows the start date of the current visit
<lookup complexExpression="#foreach($encounterProvider in $fn.latestEncounter('2549af50-75c8-4aeb-87ca-4bb2cef6c69a').encounterProviders) $encounterProvider.provider.person.personName #end" /> this gets the names of the providers in the latest encounter of the specified type 

<macros>

The macro tag enables one to define a set of constants that can be referred to within the form.  Some of it's more common uses are:

Prior to release 2.6, the only way to define macros was as a properties-style text block within the body of the macros tag.  This is maintained beyond 2.6 for backwards compatibility.  An example of this can be seen below:

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>


As of release 2.6, macros can also be defined using xml tags (see syntax below). The added benefit added here was the ability to supply either a "value" attribute, which simply assigns a constant value to the macro, OR to supply an "expression" attribute, which enables assigning a macro value based on the evaluation of a velocity expression.  This exposes the same capabilities as the lookup tag, with the same syntax as one would use in that tag.  Examples below:

Related Tags

<macro> (from version 2.6)

Used to define a particular macro variable that can be re-used on the form.

Attributes

Example Usage

<htmlform>
    <macros>
        <macro key="backgroundColor" value="#e0e0e0"/>
		<macro key="weight" expression="fn.globalProperty('concept.weight')"/>
    </macros>
    <div style="background-color: $backgroundColor">Weight:  <obs conceptId="$weight"/></div>
</htmlform>


<markPatientDead>

When a form with this tag is submitted (in either Enter or Edit mode) then the patient will be marked as deceased, with a date and cause as specified by tag attributes.

Since 2.4.

Attributes

<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 a dropdown (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 conceptId="5272" 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
answerLocationTags="TAG1, TAG2" limits the locations in the drop-down list to the locations tagged with TAG1 or TAG2
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.
maxlength="50" limits the number of characters that can be entered into the field to 50 (supports any valid integer)
placeholder="Type something" shows placeholder text before the user types

Date

Renders a date picker widget. Note that dates are not allowed to be in the future, unless attribute allowFutureDates="true". If the concept is of type datetime, then both date and time controls will be rendered. However you can override this with allowTime="false" if you want only a date control for a datetime concept.

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, answerConceptId, or answerConceptSetIds 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="1234" answerConceptSetIds="345,789" style="autocomplete" />
Renders an autocomplete textbox which provides coded answers from another concept set.

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

<obs conceptId="1234" answerDrugs="true"/>
Renders as an autocomplete widget that searches the Drug table, and will save the selected value in obs.value_drug
 
<obs conceptId="1234" answerDrugs="true" displayTemplate="{{concept}} ({{doseStrength}} {{units}})"/>
Renders an an autocomplete widget, with items displayed using a custom handlebars template. (Default is "{{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.

Complex

Renders a upload widget, which allows uploading of a file. If the data handler of the concept is an ImageHandler, then only images are allowed for upload, which will be displayed in the form itself when viewing. Otherwise, BinaryDataHandler or BinaryStreamHandler can be used to support any file type.

<obs conceptId="1234" />
Renders as a "Choose File" button. After browsing to choose the tile, the name of the file chosen is beside it. 

Note: The value of conceptId must be a complex obs with a handler, like "ImageHandler" For more info, see the Workflow section at the Complex Obs Support page.

Attributes

Related Tags

<obsgroup>

Used to create an obs group. This is used when you need to link multiple <obs> concepts together. You are required to specify a groupingConceptId, which is of type ConvSet. For example, IMMUNIZATION HISTORY (1421), which has set members IMMUNIZATION SEQUENCE NUMBER (1418), VACCINE LOT NUMBER (1420), VACCINATION DATE (1410), IMMUNIZATIONS (984) and VACCINE MANUFACTURER (1419) which store the details related to the immunization. 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>

<obsreference>

An extension of the standard Obs tag that allows for matching observations outside of the current encounter but collected during the same day as the encounter to be displayed within the form.

If  an encounter datetime is present within the context when the form is rendered (which generally only occurs in VIEW or EDIT mode), this tag will search for all Obs with the same question concept for that patient collected during the current day.  If multiple matching obs are found, it will take the most recent obs. This is the reference obs.

If a reference obs is found and  there is no matching obs on the existing encounter, in view mode the value for this obs will be displayed  where the obs from the encounter would normally be displayed.  Additionally, in edit mode, if a reference obs is found and there is no matching obs on the existing encounter, the reference obs will be displayed view mode, and there will be no widget for entering data.  If allowOverride is set to true, an "Override" button will be present, and clicking it will hide the reference obs and display the standard edit widget for the field.

Note this currently only supports Obs rendered with the following widget types: Numeric Field, Text Input, Date (not Time or Datetime), Dropdown, Radio Button, and Checkbox

All existing Obs attributes are supported, with the following additional attributes added.

Attributes

Related Tags

<patient>

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

Attributes

Attribute field

Additional attribute

Is mandatory while enter/create

Description

Example

name


Yes

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

<patient field="name" />

gender


Yes

Display Male / Female option in drop down combo box

<patient field="gender" />

birthDate  


Yes

Display the birth date input text box with calendar widget support

<patient field="birthDate" />

age


Yes

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

<patient field="age" />

birthDateOrAge


Either birth date or age

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

<patient field="birthDateOrAge" />

identifier


Yes

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

<patient field="identifier" />

identifier

identifierTypeId

Yes

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

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

identifierLocation


Yes

Display the available locations in drop down combo box (note that there is an open bug concerning this attribute...see HTML-414

<patient field="identifierLocation" />

address


No

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

<postSubmissionAction>

Since 2.4

Lets you run server-side Java code as part of a form's submission. This action happens after standard form processing (e.g. obs are created) but it happens in the same transaction, so if this processing throws an error, the entire form submission is invalidated.

Attributes

<redirectOnSave>

(Since 2.4)

Lets a form indicate what URL to go to after it is submitted, overriding the default behavior of the web framework.

Attributes

<relationship>

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

Attributes

Example Usage

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

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

<repeat with="">

(Available in HFE 2.0.2 and above)

A less-verbose version of the <repeat> tag.

Attributes

                                  

Example Usage

<repeat with="['664','No Complaints'],['832','Weight Loss'],['777','Nausea']">
<obs conceptId="1069" answerConceptId="{0}" answerLabel="{1}" style="checkbox" /><br/>
</repeat>

would render as:

<obs conceptId="1069" answerConceptId="644" answerLabel="No Complaints" style="checkbox" /><br/>
<obs conceptId="1069" answerConceptId="832" answerLabel="Weight Loss" style="checkbox" /><br/>
<obs conceptId="1069" answerConceptId="777" answerLabel="Nausea" style="checkbox" /><br/>




<restrictByRole>

A user with a particular role can be restricted from either viewing a certain HTML form (or a section in the form) by using the <restrictByRole> tag.

Attributes

<section>

The <section> tag lets you break your form, and corresponding form schema, into sections. Note that we wrote this tag before HTML 5 introduced a real-HTML section tag, so the default behavior of this tag outputs a div.

Attributes

Example Usage

If you want to use HTML 5 section tags, do something like this:

<section headerLabel="Encounter details" sectionTag="section" headerTag="h1"> Your content </section>

<!-- This would be the output -->
<section class="section">
    <h1 class="sectionHeader">Encounter details</h1>
    Your content
</section>

<condition>

This tag lets you record a condition.

Since a condition is not tied to an encounter, you can not edit or view conditions created within a particular visit or encounter using this tag. 

WARNING - In order to use this tag, you must be running openmrs platform 2.2.0 and above.

Attributes

Example Usage


<htmlform>
    ...stuff goes here...
	<!-- For cases were a condition is required -->
    <condition required="true" />
	<!-- For cases were a condition isn't required -->
    <condition required="false" />
</htmlform>

<standardRegimen>

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.

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

Simplest example using defaults

<htmlform>
    ...stuff goes here...
    <submit/>
</htmlform>

Example of applying custom Class to a translated label

<htmlform>
<style>
    .customSubmit { font-weight: bold; }
</style>
<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"/>
    </code>
</translations>
    ...stuff goes here...
    <submit submitStyle="customSubmit" submitCode="submit_text" />
</htmlform>

<template>

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"/>
or
<lookup expression="fn.message('night_sweats')"/>

<uiInclude>

This tag is only available when using the HTML Form Entry UI Framework Integration module and OpenMRS 1.9.3+. It lets you access resources provided by the UI Framework.

Attributes

You are required to specify one of javascript, css, or fragment.

Example Usage

<uiInclude provider="uicommons" javascript="angular.min.js"/>
<uiInclude provider="coreapps" javascript="diagnoses/diagnoses.js"/>


<variant>

See <translations>

<when>

Since: 2.1.6

Must be inside <obs id="..."><controls>...</controls></obs>. See <controls>.

An action that should be taken conditionally based on a chosen value of the <obs> it is in.

Attributes

It is valid to combine more than one of the then* attributes, though in practice you probably want either thenDisplay, or else thenJavascript + elseJavascript.

Example

<obsgroup groupingConceptId="PIH:9722">
    Form signed by role
    <obs id="form-signed-role" conceptId="PIH:TITLE WHO COMPLETED FORM" answerConceptIds="PIH:DOCTOR,PIH:NURSE,PIH:OTHER">
        <controls>
            <when value="PIH:OTHER" thenDisplay="#form-signed-role-other"/>
        </controls>
    </obs>
    <span id="form-signed-role-other">
        Specify:
        <obs conceptId="PIH:GENERAL FREE TEXT"/>
    </span>
</obsgroup>


<obsgroup groupingConceptId="PIH:9722">
    <p>
        <label>Form signed by role</label>
        <obs id="form-signed-role" conceptId="PIH:TITLE WHO COMPLETED FORM" answerConceptIds="PIH:DOCTOR,PIH:NURSE,PIH:OTHER">
            <controls>
                <when value="PIH:OTHER"
                    thenJavaScript="htmlForm.simpleUi.showField('form-signed-role-other')"
                    elseJavaScript="htmlForm.simpleUi.hideField('form-signed-role-other')"/>
            </controls>
        </obs>
    </p>
    <p id="form-signed-role-other">
        <label>Specify:</label>
        <obs conceptId="PIH:GENERAL FREE TEXT"/>
    </p>
</obsgroup>

<workflowState>

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.

Attributes

Example

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

Notes

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:

See HTML-321 for an example of a reported bug that actually is not bug, but, instead obeys the above logic. HTML-321 as been closed as do not fix, but if there is a strong argument that the behaviour should be changed, we can reassess.

Other Examples and Tips

Example HTML Forms

Javascript

You've always been allowed to write Javascript in an HTML form. There is some built-in Javascript helper functionality. The documentation for this has been moved to the HTML Form Entry JavaScript Reference page.

Including HTML character codes in HTML Forms

It is common to include the "non-breaking-space" character code within html:

<td>First&nbsp;Name</td>

However, the non-breaking-space character is, technically, is not valid XML.  Since HTML forms must be valid XML, you will need to use the ASCII-code for a space as a substitution for the non-breaking-space character code:

<td>First&#160;Name</td>

There is currently a ticket about this issue: HTML-325

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.

<obs conceptId="1234" />Renders as a "Choose File" button. After chosen, the name of the file is beside it.