Reference for writing HTML for the Html Form Entry Module

Available since 5.3.0. Requires the Bahmni Appointments module to be installed and running.

This tag fetches all the appointments for the current patient with the status "Scheduled", as well (in edit mode) any appointments linked to the current encounter by the appointment's "fulfilling encounter" property.

Appointments are sorted in reverse chronological order with a check box next to each one.  Upon submit, all checked appointments will have their status set to "CheckedIn" and the current encounter added to the appointment as a fulfilling encounter.

In edit mode, if an appointment is unchecked, the current encounter is removed from the list of fulfilling encounters associated with the appointment.  However, the status is not modified.

In view edit mode, the tag will simply display all the appointments for which the current encounter is a "fulfilling encounter".

• class: will apply the specified class to each span that wraps each individual appointment checkbox and label 

  •  OPTIONAL

  • Default: none

See <translations>

This tag lets you record a condition linked to the form's submitted encounter.

WARNING - This tag is supported from OpenMRS 2.3.3. The tag may work to a certain extent from Core 2.2.2 as some support for it was introduced too soon, however we strongly discourage this and suggest to upgrade Core appropriately.

• required: this is used for validation, and if true the form will not be able to be submitted without the required condition otherwise the form would be submitted.

  • OPTIONAL

  • Value: "true" or "false"

  • Default: false

• controlId:

  • REQUIRED

  • Value: a unique string (within the form) to identify the condition control within the form.

• showAdditionalDetail: this toggles the visibility of the additional detail text box.

  • OPTIONAL

  • Value: "true" or "false"

  • Default: false

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.

• programId:  ID or UUID of the program, or name of the associated concept, in which the patient is to be enrolled.

  • REQUIRED

  • Examples: 

    • <completeProgram programId="1"/> 

    • <completeProgram programId="9b45541a-e8f0-41ff-a55a-445b08a8d8b5"/> 

    • <completeProgram programId="Rehab program"/>

  • Value: Any valid program ID, program UUID or underlying concept name

  • Default: None.

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

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

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

None

NOTE - This tag is deprecated.

Documentation on the drugOrder tag for versions prior to 4.0.0 can be found at the bottom of this page, under "Legacy Version of Tags".

In htmlformentry 4.0.0, the drugOrder tag was rewritten from the ground up as a more generic "order" tag.  See the "order" tag section below for full documentation.

The "drugOrder" tag is simply a wrapper class that delegates to the order tag and allows for the "orderType" attribute to be excluded as long as their is only a single Order Type configured of class "org.openmrs.DrugOrder"

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

• default: Specifies default value for encounterDate widget.

  • OPTIONAL

  • Example: <encounterDate default="today"/>

  • Value: "today", "now", or ?????

  • Default: None

• showTime: The showTime attribute determines if the encounterDate widget is date-only or date and time.

  • OPTIONAL

  • Example: <encounterDate showTime="true"/>

  • Value: "true" or "false"

  • Default: False - Widget is date-only

• disallowMultipleEncountersOnDate: This will warn the user that this Form type has been entered for this Patient on this Encounter date.  This will prevent duplicate paper entries of the same form.  The mechanism for this is an ajax popup that is presented to the user after selecting an encounter date (only if there is already a form submitted of the same type for that date for that patient).

  • OPTIONAL

  • As of version 1.8.0

  • Example: <encounterDate disallowMultipleEncountersOnDate ="warn"/>

  • Value: "warn" or "block":  'warn' will only warn the user that they may be entering a duplicate form.  'block' will give the warning, and will then clear the encounterDate field, thus making the form un-submittable.

  • Default: there is no default.  You must choose one of the above.

• widget: preliminary support for having different widgets (in enter/edit mode).

  • OPTIONAL

  • As of version 2.5

  • Example: <encounterDate widget="hidden"/>

  • Value: "hidden" (or no value)

    • (no value): Standard widgets (jQuery UI datepicker, optional dropdowns for hour, minute, second)

    • hidden: In enter/edit mode, there will be no visible widgets, but just <input type="hidden" .../> (one for date, and optionally 3 for hour, minute, second); This is for the advanced use case where you want to provide custom widgets that will set the values of the hidden inputs via javascript.

  • Default: none standard widgets

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.

• required: Specifies that the diagnoses field must be completed/filled.

  • OPTIONAL

  • Example: <encounterDiagnoses required="true"/> 

  • Value: "true", "false"

  • Default: false

• selectedDiagnosesTarget: Specifies the id of the <div>  container where the selected diagnoses are displayed. 
  
  

  • REQUIRED

  • Example:
    <encounterDiagnoses selectedDiagnosesTarget="encounter-diagnoses-target"/> 
<div id="encounter-diagnoses-target"></div> 

  • Value: can be any valid HTML safe id

  • Default: There is no default for this and therefore should be provided as illustrated in the above example.

• preferredCodingSource: This is used to notify the user that choices that are presented to him through the autocomplete don't pertain to a preferred source.
  
  

  • OPTIONAL

  • As of version Core Apps 1.23.0

  • Example:
    <encounterDiagnoses preferredCodingSource="ICD-10-WHO"/> 

  • Value: A valid concept source name, e.g "ICD-10-WHO", "CIEL", "ICPC2", ... etc.

  • Default: "ICD-10-WHO"

• diagnosisConceptClasses: Specifies one or more concept classes in a form of a comma separated string to search in. Can be used together with diagnosisConceptSources. 

  • OPTIONAL

  • As of version 1.23.0

  • Examples: 
    <encounterDiagnoses diagnosisConceptClasses="Diagnosis"/> 
<encounterDiagnoses diagnosisConceptClasses="Diagnosis,Finding"/> 

  • Value: A valid concept class e.g "Diagnosis", list of classes "Diagnosis,Finding"

• diagnosisConceptSources: Specifies one or more concept sources in a form of a comma separated string to search in. Can be used together and works well with diagnosisConceptClasses. 

  • OPTIONAL

  • As of version 1.23.0

  • Examples: 
    <encounterDiagnoses diagnosisConceptSources="CIEL"/> 
<encounterDiagnoses diagnosisConceptSources="CIEL,ICPC2"/> 
<encounterDiagnoses diagnosisConceptSources="0"/>
    NOTE: pointing to a null concept source ensures that no default will be used, it will remove the concept sources as a space for the search. 
    <encounterDiagnoses diagnosisConceptSources=""/>
    NOTE: pointing to an empty concept source will lead to using the defaults.
    
    

  • Value: A valid concept sources e.g "ICD-10-WHO", list of sources "CIEL,ICPC2" or "0" (zero)

  • Default: "ICD-10-WHO"

• diagnosisSets: Specifies the concept sets of diagnoses to search from. Can be one or more comma separated string of UUIDs, concept mappings (e.g CIEL:160170) or combination of both representing the sets. This when provided, overrides the default globally configured set of sets of diagnoses to search from.

  • OPTIONAL

  • As of version 1.23.0

  • Examples:
    <encounterDiagnoses diagnosisSets="160170AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,160169AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"/> 
<encounterDiagnoses diagnosisSets="CIEL:160170,CIEL:160169"/> 
<encounterDiagnoses diagnosisSets="CIEL:160170,160170AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"/> 
<encounterDiagnoses diagnosisSets="0"/> 
    NOTE: pointing to a null concept set ensures that no default will be used, it will remove the concept sets as a space for the search.
    <encounterDiagnoses diagnosisSets=""/> 
    NOTE: pointing to a empty concept set will lead to using the defaults.

  • Value: comma separated string of UUID or Concept Mappings or both or "0". When "0" (zero) is used, this means that the default globally defined concept sets are not used to search in.

  • Default: concepts contained in the sets globally defined by a set of sets concept (CIEL:160167 or 160167AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA).

  • IMPORTANT NOTE: When the diagnosisSets  is specified either through global defaults or provided in this HFE tag, the name search for diagnoses within classes and/or sources is bypassed. This means that the name search only operates within those sets, such that the classes and/or sources are ignored. To globally define diagnosis concepts sets and/or diagnosis concept sources, edit the emr.concept.diagnosisSetOfSets and emrapi.conceptSourcesForDiagnosisSearch global properties respectively.

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

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

• default: Sets default value for the widget.

  • OPTIONAL

  • Example: <encounterLocation default="2"/>

  • Example: <encounterLocation default="SessionAttribute:emrContext.sessionLocationId"/>

  • Example: <encounterLocation default="SystemDefault"/>

  • Value: Location ID, Location UUID, Location Name. Since 1.9.5 we also support "GlobalProperty:xyz" and "UserProperty:xyz" where xyz is the name of a global property or user property, whose value must be equal to a legal location value using one of the supported formats. Since 2.0.3 we also support "SessionAttribute:xyz" where xyz is the name of an HttpSession attribute, whose value must be a location, or a String using one of the supported formats. Since 2.3 we support "SystemDefault" to set the default to the configured system default.

  • Default: None

• order: Determines which locations appear in the list, and specifies the order in which they appear.

  • OPTIONAL

  • Example: <encounterLocation order="2,7,4"/>

  • Value: Comma separated list of Location IDs, Location UUIDs, or Location Names

  • Default: All non-retired locations in alphabetical order

• tags: Limits the locations that appear in the list to locations tags with one or more the specified tags

  • Since 2.1.3

  • OPTIONAL

  • Example: <encounterLocation tags="Admission Location, 1" />

  • Value: Comma separated list of Location Tags IDs or Location tag Names

  • Cannot be used in conjunction with the order attribute

• required: Defaults to true when not specified. When false the form can be submitted without specifying a location 
  
  

• restrictToCurrentVisitLocation: when set to true and in a context of a visit, restricts the list of locations to the visit location and children/grandchildren/etc of that location

  • Since 4.0.0

  • OPTIONAL

  • Example: <encounterLocation restrictToCurrentVisitLocation="true"/>

  • Value: true/false

  • Default: false

  • Can be used with the order or tags attribute... "tags" or "order" will be used to get the base list of potential locations, and then that list will be filtered by the criteria described above

  • Can be globally enabled by setting a the global property "htmlformentry.restrictEncounterLocationToCurrentVisitLocation" to "true"

• restrictToSupportedVisitLocations: when set to true, restricts the list of locations to those tagged as "Visit Locations" and their children

  • Since 3.12.0

  • OPTIONAL

  • Example: <encounterLocation restrictToSupportedVisitLocations="true"/>

  • Value: true/false

  • Default: false

  • Cannot be used in conjunction with the order or tags attribute

• type: Specifies the input element to display (i.e a dropdown vs autocomplete); shows a dropdown by default if type is not specified

  • Since 1.11

  • OPTIONAL

  • Example: <encounterLocation type="autocomplete"/>

  • Value:  "autocomplete"

  • Default: dropdown

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

• default: Sets default value for the widget.

  • OPTIONAL

  • Example: <encounterProvider default="djaz"/>

  • Value: username, currentUser, Person IDs, or Person UUID

  • Default: None

• role: Filters the list of persons to only those users with the specified role

  • OPTIONAL

  • Example: <encounterProvider role="Provider"/>

  • Value: Any valid role

  • Default: Provider

• persons:  Determines which persons appear in the list, and specifies the order in which they appear.

  • OPTIONAL

  • As of version 1.6.8

  • Example: <encounterLocation persons="1,2,4"/>

  • Value: Comma separated list of usernames, Person IDs, or Person UUIDs

• required: Defaults to true when not specified. When false the form can be submitted without specifying a provider 

• type: Specifies the input element to display (i.e a dropdown vs autocomplete); shows a dropdown by default if type is not specified

  • Since 1.11

  • OPTIONAL

  • Example: <encounterProvider type="autocomplete"/>

  • Value:  "autocomplete"

  • Default: dropdown

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

Note that "provider roles" and "encounter roles" are different things. Providers have provider roles, e.g. "Yemi is a surgeon." A provider may have an encounter role within an encounter, e.g. "Yemi was the lead surgeon for this encounter."

If the encounterRole  attribute is not provided, the widget renders as a pair of dropdowns. The first allows selecting from a list of providers; the second allows selecting from a list of encounter roles. If the encounterRole  attribute is provided, the encounter role dropdown is omitted.

Note that this tag cannot be repeated in the usual fashion; see the "Note" below. Instead, use the count  and providerWidgetSeparator  attributes.

All attributes are optional

• default: Sets default provider for the widget (id or uuid of a Provider, or "currentUser"). 

  • If you specify "currentUser" but the currently-logged-in user does not have a Provider record associated with their Person record, nothing happens. (If that user has more than one Provider record, one is chosen arbitrarily.)

• encounterRole: Use the given encounterRole  instead of rendering a dropdown.
  
  

  • If the encounterRole  attribute is not provided, the widget renders as a pair of dropdowns. The first allows selecting from a list of providers; the second allows selecting from a list of encounter roles. If the encounterRole  attribute is provided, the encounter role dropdown is omitted; the provider is added to the encounter with the encounter role given as the value of this attribute.

  • Value:  id or uuid of an encounterRole 

• providerRoles:  Limit the list of possible providers to those with any of the specified providerRoles 
  
  

  • Example:  <encounterProviderAndRole providerRoles="8" />

  • Value:  Comma separated list of provider role id or uuid

  • Requires that the Provider Management module be installed

  • since HFE 1.9 Extensions 1.2
    
    

• required: when true, the form cannot be submitted unless you have chosen a provider

• autocompleteProvider: When true, the provider widget is rendered in autocomplete search box in which user is expected to type the few characters used to search for a particular provider (s).
  
  

  • Value: true or false

  • Default: false

  • Example: <encounterProviderAndRole autocompleteProvider="true"/>

  • since HFE 1.9 Extensions 1.6

• providerMatchMode: Used in conjunction with autocompleteProvider attribute to specify the position to match search text in provider identifier/names.
  
  

  • Values: START, END, ANYWHERE (Default is START)

  • Example: <encounterProviderAndRole autocompleteProvider="true" providerMatchMode="ANYWHERE" />

  • Since HFE 1.9 Extensions 1.6

• count: Repeat this widget count  times. See the "Note" below.
  
  

  • Default: 1

• providerWidgetSeparator: If using count , this HTML is inserted in between each widget.
  
  

  • Default:  ", "

  • Since:  htmlformentry version 3.10.0

  • Example:  

    <div class="provider-grid"> <div> <encounterProviderAndRole encounterRole="98bf2792-3f0a-4388-81bb-c78b29c0df92" count="2" providerWidgetSeparator="&lt;/div&gt;&lt;div&gt;"/> </div> </div>

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:

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.

• types: comma-separated list of encounterTypes to display in the select list, referenced by id, uuid, or name

• default: the default encounterType, referenced by id, uuid or name

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

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:

• If the patient is already in the program on the selected date, nothing changes

• If the patient is registered in the program after the selected date, then the patient's enrollment date will be moved back to the selected date, otherwise, patient is enrolled on selected date

• Otherwise, the patient is enrolled as requested

• If state ids are specified, these patient states are set upon program enrollment

• If the patient is already enrolled in the program when this form is submitted, the patient states are NOT automatically set; however, if the enrollment date is changed (via the logic above) all the states that have a start date equal to the enrollment date are changed to the new enrollment date

• This tag is invalid if any of the states listed are not initial states, or if two or more of the states are from the same workflow

• If the showDate parameter is not used, the encounterDate tag must appear above the enrollInProgram tag. See

  Error rendering macro 'jira' : Unable to locate Jira server for this macro. It may be due to Application Link configuration.

• locationTag: if specified, the enrollment location of the patient program is set to the encounter location if  the encounter location is tagged with the specified tag; otherwise it searches up through the parent locations of the location and uses the first location found with that tag. If no matching location found with that tag, enrollment location is not set.  Note that this only sets  the location on initial enrollment, it does not edit the enrollment location if the encounter location is later edited.  Also, note that if this tag is not  present, no enrollment location is set (which was default behavior before introduction of this tag).

  • OPTIONAL

  • Example:

    • <enrollInProgram programId="Rehab program" locationTag="Program Location"/>

  • Since version 3.12.0

• programId: ID or UUID of the program, or name of the associated concept, in which the patient is to be enrolled.

  • REQUIRED

  • Examples: 

    • <enrollInProgram programId="1"/> 

    • <enrollInProgram programId="9b45541a-e8f0-41ff-a55a-445b08a8d8b5"/>