All OpenMRS ID accounts have been reset.

Read more and change your password before signing in.
Icon

EXTENDED: OMRS14 Proposals due 30 April! Read more and submit a proposal at OpenMRS Talk.

Skip to end of metadata
Go to start of metadata

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.  An example usage would be for a transfer form, when a patient is being transferred permanently out of the district, or if you have finite programs like maybe for PMTCT, for example.

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

Attributes

  • programId: ID of the program in which the patient is to be enrolled.
    • REQUIRED
    • Example: <completeProgram programId="1"/>
    • Value: Any valid program ID or program UUID.
    • Default: None.

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

Available since 2.1.6.

Attributes

None

Example Usage

 

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

  • since: 1.7.2
  • attributes below starting with instructionsLabel will be available in 1.7.3

Attributes

  • drugNames: Determines which drug names appear in the list
    • REQUIRED
    • Example: <drugOrder drugNames='kaletra' />
    • Value: Comma separated list of drug id, drug name, drug UUID
    • Default: None
  • validateDose: Sets whether or not to validate the dose value (min, max of the dose)
    • OPTIONAL
    • Example: <drugOrder drugNames='kaletra' validateDose='true' />
    • Value: true or false
    • Default: false
  • instructionsLabel: Renders a text box for entering instructions for the drug order.
    • OPTIONAL
    • Example: <drugOrder drugNames="d4T 30,d4T 40" validateDose="true" instructionsLabel="Drug Order Instructions: "/>
    • Value: any text label for the instructions field
    • Default:none
  • drugLabels: This allows you to change the drug names that are displayed in the drop-down drug list. There have to be an equal number of drugLabels as drugNames to use this attribute, although validation will catch this if you forget.  
    • OPTIONAL
    • Example: <drugOrder drugNames="RIF 300,RHEZ,PZA 500,NVP Susp" drugLabels="RIF,RZ, PZ, NVP Syrup" />
    • Value: a comma-delimited set of drug names.  Names will be applied to the drugs in the drugName attribute, in order.
    • Default: none
    • NOTE: Adding Drug Type Headers to the dropdown list:  Also, I added a hacky syntax to the drugName attribute what can allow you to put drug type headers in the drugName dropdown widget. To insert a drug type header into the drug list, in the drugName list, you just insert the header with the forward-slash '/' character at the beginning and end of the drugName. For example, this is a valid tag: <drugOrder drugNames="RIF 300,RHEZ,PZA 500,/Syrups/,NVP Susp" drugLabels="RIF,RZ, PZ, NVP Syrup" hideDoseAndFrequency="true"/>. You'll notice that the drugNames attribue has 5 entries and the drugLabels attribute has only four labels. This works because the /Syrups/ isn't a real drug, so it isn't considered during validation. Finally, I've added validation that doesn't allow you to select a drug type header as a drug.
  • hideDoseAndFrequency:  Allows you to hide the dose and frequency text boxes that are rendered by the tag by default
    • OPTIONAL
    • Example: <drugOrder drugNames="RIF 300,RHEZ,PZA 500,/Syrups/,NVP Susp" drugLabels="RIF,RZ, PZ, NVP Syrup"  hideDoseAndFrequency="true"/>
    • Value: true/false
    • Default: false
    • NOTE: If this tag is used the drug order will be submitted using the drug strength from the concept drug definition. 
  • checkbox: This renders a checkbox for choosing to create a drugOrder for a single drug listed in the drugName attribute. Works nicely with the "hideDoseAndFrequency" tag above.  This tag will only be applied if there is EXACTLY one drug listed in drugName, and the select attribute is set to "true".
    • OPTIONAL
    • Example: <drugOrder drugNames="Terizidone (Trd)" drugLabels="TRD" checkbox="true" hideDoseAndFrequency="true"/>
    • Value:true/false
    • Default: false
  • discontinuedReasonConceptId: This creates a drop-down of coded reasons for discontinuing a regimen. This covers the valueCoded reason for discontinuing a regimen, and I'm currently waiting on a bug fix to 1.6+ to be able to support a text field for 'other' for discontinueReasonText.
    • OPTIONAL
    • Example: <drugOrder drugNames="d4T 30,d4T 40" validateDose="true" instructionsLabel="INSTRUCTIONS:" discontinuedReasonConceptId="1252"/>
    • Value:  a valid conceptId or uuid for the concept representing the reason for discontinuing drug question.  This concept must have conceptAnswers.
    • Default: none
  • showOrderDuration: This creates a text field that allows you to say what the duration of the order should be.  This, then, is applied as an autoExpireDate.
    • OPTIONAL
    • Example <drugOrder drugNames="Nelfinavir,Tenofovir (TDF)" showOrderDuration="true" /> 
    • Value:  true/false
    • Default: false
  • defaultDose:This sets a default dose that will be pre-entered in the drug order entry widget
    • OPTIONAL
    • Example <drugOrder drugNames="Ibuprofen" defaultDose="250"/>
    • Value: empty string or a string that can be converted to a Double
    • Default: none
  • toggle: For checkbox style fields only, specify the id of a div or span that you wish to hide or disable depending on whether the checkbox is checked or not.
    • OPTIONAL
    • The toggle attribute accepts two syntaxes (see below).
      • Basic: The basic syntax simply accepts the DOM id of the target div or span:
      • Advanced: The more advanced syntax accepts a JSON structure with the attributes: id and style. The "id" attribute is the DOM id of target div/span that you wish to hide or disable. The "style" attribute accepts either "hide" (default) or "dim". The "hide" style completely hides the target div/span until the checkbox is checked. The "dim" style greys-out and disables the child components of the target div/span until the checkbox is checked.
    • Version: Available since version 1.11.0

Example Usage

<encounterDate>

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

Attributes

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

Example Usage

<encounterLocation>

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

Attributes

  • default: Sets default value for the widget.
    • OPTIONAL
    • Example: <encounterLocation default="2"/>
    • Example: <encounterLocation default="SessionAttribute:emr.sessionLocation"/>
    • 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
  • 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

Example Usage

<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

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

Example Usage

<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

  • 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.)
  • count: number of potential providers for the specified role 
    • Example:  the number of dropdown widgets to render) 
    • Default is 1
  • encounterRole:
    • When specified, this tag displays a widget for choosing a provider, and assigns it to the role indicated by this parameter. 
    • If you do not specify this attribute, then the tag will also display a widget to choose an encounter role for the provider.
    • Value:  id or uuid of an encounterRole 
  • providerRoles:  Specify the role assigned to the provider
    • OPTIONAL
    • Example:  <encounterProvider 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

Example Usage

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:

 

<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

  • 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

Example Usage

<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

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

  • 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

Attributes

  • programId: ID of the program in which the patient is to be enrolled.
    • REQUIRED
    • Examples: 
      • <enrollInProgram programId="1"/> 
      • <enrollInProgram programId="Rehab program"/>
    • Value: Any valid program ID, program UUID or underlying concept name
    • Default: None.
  • showDate: If true, a date widget is displayed and the patient is enrolled on the selected date; if false, or if no date selected, the patient is enrolled on the encounter date
    • OPTIONAL
    • Example: <enrollInProgram programId="1" showDate="true"/>
    • Value: true or false
    • Default: False.
  • stateIds: A comma-separated list of program work flow states ids
    • OPTIONAL
    • Example: <enrollInProgram programId="1" stateIds="3, 444ce6ba-551d-11e1-8cb6-00248140a5eb, PIH:356789"/>
    • Value: Any valid program workflow state id, program workflow state uuid, or concept mapping of the underlying concept for the state
    • Default: None
    • If you reference states by concept mappings, be careful that you don't have two states in the same program with the same underlying concept, or unpredictable results will occur!

<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

  • logicTestA logic expression represents a logic test.
    • OPTIONAL
    • Example: <excludeIf logicTest="GENDER = F"/> - A logic test to see if the patient's gender is female
  • velocityTestA velocity expression represents a velocity test.
    • OPTIONAL
    • Example: <excludeIf velocityTest="$patient.gender == 'F' "/> - A velocity test to see if the patient's gender is female.

Example Usage

<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

<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

  • modein which mode to include the content
    • REQUIRED
    • allowed values: "ENTER", "EDIT", "VIEW" (not case-sensitive)
    • Example: <ifMode mode="ENTER">...</ifMode>
  • includewhether to include or exclude the content based on the mode
    • allowed values: true or false
    • default: true

Example Usage

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

  • patient: the patient object you're entering the form for
  • user: the current authenticated user (added in HFE 1.9)
  • locale: the authenticated user's locale
  • patientIdentifiers: Map<String, List<String>> of identifierType.name -> all identifiers of that type
  • personAttributes: Map<String, Object> of personAttributeType.name -> the (hydrated) current attribute value
    • since HTML Form Entry 1.7 the name has any single quotes removed, so "Mother's Name" will become "Mothers Name"
  • relationshipList: List<Relationship> of all relationships that the subject of the form belongs to
  • relationshipMap: Map<String, List<Person>> of either RelationshipType.aIsToB or RelationshipType.bIsToA -> all persons with that relationship to the subject
  • form: the HtmlForm currently in use
  • encounter: the Encounter currently being viewed/edited. (only set in view/edit mode)
  • concept: the Concept object of given concept ID passed as parameter

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

  • fn.logic(String logicExpression)
    • evaluates a logic expression, and returns an org.openmrs.logic.Result
    • since 1.7.0
    • Example

  • fn.allObs(Integer conceptId)
    • returns all the patient's observations for the given concept id, as a List<Obs>
    • since 1.7.0
    • Example

  • fn.latestObs(Integer conceptId)
    • returns the patient's most recent observation for the given concept id (most recent ever and not in relation to this encounter's date)
    • since 1.7.0
    • Example

  • fn.earliestObs(Integer conceptId)
    • returns the patient's earliest observation for the given concept id
    • since 1.7.0
    • Example

  • fn.allEncounters(EncounterType type)
    • returns all the patient's encounters for the given encounter type ( or all the patient's encounters if given a null parameter), as a List<Encounter>
    • since 1.7.4
    • Example

  • fn.latestEncounter()
    • returns the patient's latest encounter
    • since 1.7.4
    • Example

  • fn.latestEncounter(EncounterType type)
    • returns the patient's latest encounter for the given encounter type id
    • since 1.7.4
    • Example

  • fn.patientAgeInDays()
    • returns the patient's age in days, that is the number of days between patient's birthdate and current date (not the encounter date)
    • since 1.10.0
    • Example

  • fn.patientAgeInMonths()
    • returns the patient's age in months, that is the number of months between patient's birth month and current date (not the encounter date)
    • since 1.10.0
    • Example

  • fn.getConcept(String conceptId)
    • returns the concept object for given concept Id, UUID or mapping type Id
    • since 2.2.0
    • Example

Attributes

  • complexExpression
    • OPTIONAL
    • Example: <lookup complexExpression="#foreach( $addr in $patient.addresses ) $!addr.cityVillage <br/> #end"/>
    • Value: Valid complex velocity expression
    • Default: None
  • class
    • OPTIONAL
    • Example: <lookup class="value" ... />
    • Value: Valid velocity class
    • Default: None
  • expression
    • OPTIONAL
    • Example: <lookup expression="patient.personName"/>
    • Value: Valid velocity expression
    • Default: None

Example Usage

<macros>

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

Example Usage

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

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:

Text

By default, displays a normal text input box.

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 or an answerConceptId attribute.

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.

Attributes

  • accessionNumberLabel: Text to display before the obs.accession_number widget (which is a TextField Widget) for this obs. Specifying this implies showAccessionNumber="true".
    • OPTIONAL
    • Example: <obs conceptId="5497" labelText="Most recent CD4:" accessionNumberLabel="Accession Number:"/>
    • Value: Any quoted string
    • Default: None
  • allowFutureDates: When set to true allows obsDatetime to be in the future. (Has no effect on valueDatetime.)
    • OPTIONAL
    • Example: <obs conceptId="5096" allowFutureDates="true" />
    • Value: "true" or "false"
    • Default: False - Only past dates are allowed by default.
  • allowTime: When set to false, disables the time control for a datetime concept
    • OPTIONAL
    • Example: <obs conceptId="5096" allowTime="false" />
    • Value: "true" or "false"
    • Default: True - Datetime concepts are rendered with date and time controls
    • Version: Available since version 2.1
  • answerCodes: Allows you to reference labels by a messages.properties codes or a codes in the translation mappings defined in the form.
    • OPTIONAL
    • Example: ???
    • Value ??
    • Default: ?????
  • answerClasses: Renders as a dropdown all Concepts with specified ConceptClass, ordered by Concept Name
    • OPTIONAL
    • Example: <obs conceptId="1296" answerClasses="Drug"/>
    • Value: Valid ConceptClass
    • Default: None
  • answerConceptId: Concept reference corresponding to the coded answer for the question. Frequently used with checkboxes.
    • OPTIONAL
    • Examples:
      • <obs conceptId="3509" answerConceptId="2070" answerLabel="l'hôpital" style="checkbox" />
      • <obs conceptId="3509" answerConceptId="XYZ:HT" answerLabel="l'hôpital" style="checkbox" />
      • <obs conceptId="3509" answerConceptId="0cbe2ed3-cd5f-4f46-9459-26127c9265ab" answerLabel="l'hôpital" style="checkbox" />
      • <obs conceptId="3509" answerConceptId="org.openmrs.module.mymod.Dictionary.YES" answerLabel="Yes" style="checkbox" />
    • Value: A valid Concept Integer ID, Concept Mapping, Concept UUID or fully qualified constant name.
    • Default: None
  • answerConceptIds: Concept references corresponding to the coded answers for the question. Used with radio buttons and dropdowns.
    • OPTIONAL
    • Examples:
      • <obs conceptId="1319" labelText="Toiture/Roofing: " answerConceptIds="1320,1321,1316" answerLabels="tole,tache,beton"/>
      • <obs conceptId="1319" labelText="Toiture/Roofing: " answerConceptIds="XYZ:HT,ABC:QQ,QWE:TR" answerLabels="tole,tache,beton"/>
      • <obs conceptId="1319" labelText="Toiture/Roofing: " answerConceptIds="5ecb88f3-cd5f-4f46-9459-26127c9265ab,74e3ded1-cd4f-4f4b-9459-26127c9265ab,0cbe2ed3-cd5f-4f46-9459-26127c9265ab" answerLabels="tole,tache,beton"/>
      • <obs conceptId="1319" labelText="Toiture/Roofing: " answerConceptIds="1320,ABC:QQ,0cbe2ed3-cd5f-4f46-9459-26127c9265ab" answerLabels="tole,tache,beton"/>
      • <obs conceptId="3509" answerConceptIds="org.openmrs.module.mymod.Dictionary.YES,org.openmrs.module.mymod.Dictionary.NO" answerLabels="Yes,No" />
    • Value: Quoted, comma separated list of valid Concept Integer IDs, Concept Mappings, Concept UUIDs or fully qualified constant names.
    • Default: None
  • answerLabel: Sets the text to display after the object. Used with checkboxes.
    • OPTIONAL
    • Example: <obs conceptId="3509" answerConceptId="2070" answerLabel="l'hôpital" style="checkbox" />
    • Value: Any quoted string
    • Default: None
  • answerLabels: Sets the text to display after the objects. Used with radio buttons or dropdowns.
    • OPTIONAL
    • Example: <obs conceptId="3201" labelText="" answerConceptIds="1065,1066" style="radio" answerLabels="oui,non" />
    • Value: Comma separated list.
    • Default: None
  • answerLocationTags: Filters the locations based on location tags. Used with dropdowns only when style="location".
    • OPTIONAL
    • Example: <obs conceptId="6" style="location" answerLocationTags="Admission, Login" />
    • Value: Comma separated list.
    • Default: None
  • answers: Values to be stored as the answer for a radio button or dropdown. NOT used when answers are concepts - see answerConceptIds in that case
    • OPTIONAL
    • Example: <obs conceptId="123" labelText="Education" answers="0,6,8" answerLabels="None,1-6,7-8" style="radio"/>
    • Value: Comma-separated list
    • Default: None
  • answerSeparator: Defines the string or character to be used to separate answers in case of radio buttons, one use case for this would be to set the layout of the radio buttons i.e horizontal Vs vertical orientation by setting the value to an html line break(<br />) as shown in the example below
    • OPTIONAL
    • Example: <obs conceptId="1054" labelText="Question Label<br/>" answerSeparator="<br />" answerConceptIds="1056,1057,1058" answerLabels="Label 1,Label 2,Label 3" style="radio"/>
    • Value: Any quoted string.
    • Default: None
  • class: adds the specified class or classes to a span that wraps the obs element on the rendered HTML page
    • OPTIONAL
    • Example: <obs conceptId="5089" class="input-element large"/>
    • Value: string
    • Default: None
    • Version: Available since version 2.0.9
  • cols: Number of columns in the textarea (implies style="textarea").
    • OPTIONAL
    • Example: <obs conceptId="3221" rows="7" cols="60" />
    • Value: Positive integer.
    • Default: None
  • commentFieldLabel: Text to display before the obs.comments widget (which is a TextField Widget) in the <obs> tag. Specifying this implies showCommentField="true".
    • OPTIONAL
    • Example: <obs conceptId="5497" labelText="Most recent CD4:" commentFieldLabel="Add any comments:"/>
    • Value: Any quoted string
    • Default: None
  • conceptId: Integer ID, Concept Mapping, or Concept uuid of the concept to which the obs widget is linked. The datatype of this concept drives the behavior of the widget.
    • REQUIRED (unless using conceptIds)
    • Examples:
      • <obs conceptId="6135" />
      • <obs conceptId="XYZ:HT" />
      • <obs conceptId="0cbe2ed3-cd5f-4f46-9459-26127c9265ab" />
      • <obs conceptId="org.openmrs.module.mymod.Dictionary.HT" />
    • Value: Valid Concept Integer ID, Concept Mapping, Concept UUID or fully qualified constant name.
    • Default: None
  • conceptIds: It is possible to create an obs tag where you're choosing the 'question' for a predefined answerConceptId.This attribute can'tbe used in the same obs tag as the usual 'conceptId' attribute, and for the moment requires an answerConceptId.
    • OPTIONAL
    • Example: <obs conceptIds="1441,3017,2474" answerConceptId="656" labelText="ISONIAZID"/> (Renders as a dropdown list of drug sensitivity results for the drug isoniazid. Concepts 1441, 3017, and 2474-SUSCEPTIBLE TO TUBERCULOSIS DRUG, INTERMEDIATE TO TUBERCULOSIS DRUG, RESISTANT TO TUBERCULOSIS DRUG-would be the concepts listed in the dropdown list). The resulting obs may, for example,'WEAKLY POSITIVE' for the concept, and Isoniazid (concept 656( as the conceptAnswer.)
    • Default: None
  • conceptLabels: Sets the display text to use for a concept. Used with the "conceptIds" tag.
    • OPTIONAL
    • Example: <obs conceptIds="1441,3017,2474" answerConceptId="656" labelText="ISONIAZID" conceptLabels="Susceptible, Intermediate, Resistant"/>
    • Default: None
  • dateLabel: Text to display after the obs.value widget and before the obs.datetime widget (obs.obs_datetime). Specifying this implies showDate="true".
    • OPTIONAL
    • Example: <obs conceptId="5497" labelText="Most recent CD4:" dateLabel="Date of test:"/>
    • Value: Any quoted string
    • Default: None
  • defaultDatetime: Specify a default value for an Obs of type date, time, or datetime.
    • OPTIONAL
    • Values: "now" to use the current date and time; "today" to use the current date with time 00:00;  a specific date in the format yyyy-MM-dd-HH-mm
    • Examples: <obs conceptId="5497" labelText="Sample test time:" defaultDatetime="now"/> <obs conceptId="5498" labelText="Request date:" defaultDatetime="today"/> <obs conceptId="5499" labelText="Last updated:" defaultDatetime="2011-04-18-23-05"/>
    • Default: None
    • Version: Available since version 1.9.0
  • defaultObsDatetime: Every Obs has a datetime attribute to record when the Obs was made. This tag specifies a default datetime for an Obs of any type. If you also specify showDate="true" to display a datepicker for the obs.datetime , the datepicker will show this default. 
    • OPTIONAL
    • Values: "now" to use the current date and time; "today" to use the current date with time 00:00;  a specific date in the format yyyy-MM-dd-HH-mm
    • Examples: <obs conceptId="6000" labelText="Appearance:" defaultObsDatetime="now"/> <obs conceptId="6001" labelText="Appearance:" defaultObsDatetime="today"/> <obs conceptId="6002" labelText="Appearance:" defaultObsDatetime="2011-04-18-23-05"/>
    • Default: None
    • Version: Available since version 1.9.0
  • defaultValue: Specify a default value for Obs of any datatype
    • OPTIONAL
    • Values:
      • For numeric: Any numeric value
      • For boolean: "true" or "false"
      • For text: Any string
      • For date: "now" to use the current date and time; "today" to use the current date with time 00:00; a specific date in the format yyyy-MM-dd-HH-mm Note: For obs with a date datatype, defaultValue and defaultDateTime achieve the same result.
      • For coded: Valid Concept Integer ID, Concept Mapping, or Concept uuid
    • Examples:
      • <obs conceptId="3401" defaultValue="Hello World" />
      • <obs conceptId="3509" answerConceptId="2070" answerLabel="l'hôpital" style="checkbox" defaultValue="PIH: 2070" />
      • <obs conceptId="3201" labelText="" answerConceptIds="1175,1065,1066" style="radio" answerLabels="N/A,oui,non" defaultValue="PIH: 1065"/>
      • <obs conceptId="7417" defaultValue="2011-02-17-00-00"/>
      • <obs conceptId="1837" defaultValue="now"/> <obs conceptId="1271" answerConceptIds="678,729,653,654,849,1624" answerLabels="GB,Plaquettes,ALT/SGOT,AST/SGPT,Proteinuria,TSH" defaultValue="653"/>
    • Default: None
    • Version: Available since version 1.9.0
  • displayTemplate: how to format an autocomplete result
    • OPTIONAL
    • Only used when answerDrugs="true"
    • Example: <obs concept="1234 answerDrugs="true" displayTemplate="{{concept}} {{doseStrength}} {{units}}" />
    • Default: "{{name}}"
    • Version: since 2.1.6
  • id: label that you can use to refer to this obs in javascript on the page
    • OPTIONAL
    • Example: <obs conceptId="5089" id="weight"/><obs conceptId="5090" id="height"/> <script>var bmi = getValue('weight.value') / Math.pow(getValue('height.value'), 2);</script>
    • Value: string
    • Default: None
    • Version: Available since version 1.6.8
  • labelCode: Allows you to reference a label by a messages.properties code or a code in the translation mappings defined in the form.
    • OPTIONAL
    • Example: <obs conceptId="1234" labelCode="night_sweats"/>
    • Value: If referencing a translation mapping, the value for the labelCode attribute must be a valid name as defined within the <code> tag.
    • Default: None
  • labelNameTag: "default" will delegate to Concept.getBestName(Context.getLocale()). Currently that's the only legal tag.
    • OPTIONAL
    • Example: ?????
    • Value: "default"
    • Default: None
  • labelText: Sets the label that goes before the widget.
    • OPTIONAL
    • Example: <obs conceptId="3355" labelText="cause de décès:" />
    • Value: Any quoted string
    • Default: None
  • noLabel: Defines the label for the "no" option for all styles with a "no" parameter. Commonly used to change label from "No" to "non"
    • OPTIONAL
    • Example: <obs conceptId="6689" style="yes_no" noLabel="non" yesLabel="oui" />
    • Value: Any quoted string.
    • Default: "No"
  • placeholder: Placeholder text (for text obs displayed as text fields and textareas)
    • OPTIONAL
    • Example: <obs conceptId="1234" placeholder="e.g. bid, tid, twice per week"/>
    • Value: text
    • Default: none
    • Version: since 2.1.6
  • required: Sets this field as a required field
    • OPTIONAL
    • Example: <obs conceptId="3453" required="true" />
    • Value: True or false
  • role: Limits the person drop-down list to only include persons who have an associated User account with specified Role
    • OPTIONAL
    • Only affects when style="person"
    • Example: <obs concept="PIH: Name of Rehabilitation educator" style="person" role="Rehab educator" />
    • Default: Provider 
  • rows: Number of rows in the textarea (implies style="textarea")
    • OPTIONAL
    • Example: <obs conceptId="3221" rows="7" cols="60" />
    • Value: Positive Integer
    • Default: None
  • answerDrugs: for coded concepts, if true, displays an autocomplete widget to pick a drug as the obs value
    • OPTIONAL
    • Example: <obs conceptId="1234" answerDrugs="true" />
    • Value: true or false
    • Default: false
    • Version: since 2.1.6
  • showAccessionNumber: Sets whether or not to show a field to set the obs.accession_number for this obs
    • OPTIONAL
    • Example: <obs conceptId="3232" showAccessionNumber="true" />
    • Value: True or false
    • Default: None
  • showCommentField: Sets whether or not to show a text field to set the obs.comments for this obs. If set to 'true' a label string will be displayed as "Comment:".
    • OPTIONAL
    • Example: <obs conceptId="3232" showCommentField="true" />
    • Value: True or false
    • Default: None
  • showDate: Sets whether or not to show a date widget to set the obs.datetime for this obs
    • OPTIONAL
    • Example: <obs conceptId="3232" showDate="true" />
    • Value: True or false
    • Default: False
  • showUnits: Sets whether to display a numeric concept's units after its data widget
    • OPTIONAL
    • Example: <obs conceptId="5089" showUnits="true" />
    • Example: <obs conceptId="5089" showUnits="units.kg" />
    • Value: true, false, or a message code
    • Default: false
    • since: 1.11.0 (supports true/false)
    • since: 2.0.5 (supports message code)
  • size: Specifies the size of a text field.
    • OPTIONAL
    • Example: <obs conceptId="2216" labelText="Résultats: " size="80" />
    • Value: Positive integer
    • Default:?
  • style: Specifies the type of input element (radio, checkbox, dropdown, yes/no, etc.) that displays on the form.
    • OPTIONAL
    • Example: <obs conceptId="6689" style="yes_no" noLabel="non" yesLabel="oui" />
    • Value: "radio", "checkbox", "dropdown", "yes_no", "no_yes", "yes_no_dropdown", "no_yes_dropdown", "textarea", "autocomplete", "location", "person"
    • Default: Driven by datatype of associated concept.
  • unitsCssClass: What CSS class to apply to the span around the units (if shown)
    • OPTIONAL
    • Default: units
    • Example: <obs ... showUnits="true" unitsCssClass="units big"/>
    • since: 2.0.5
  • value:When set to "false", a checked checkbox signifies a value of false for the concept. It inverts the normal relationship where a checked checkbox signifies "true".
    • OPTIONAL
    • Example: <obs conceptId="2146" style="checkbox" value="false" />
    • Value: True or false
    • Default: True
  • yesLabel: Defines the label for the "yes" option for all styles with a "yes" parameter. Commonly used to change label from "Yes" to "Oui"
    • OPTIONAL
    • Example: <obs conceptId="6689" style="yes_no" noLabel="non" yesLabel="oui" />
    • Value: Any quoted string.
    • Default: "Yes"
  • toggle: For checkbox style fields only, specify the id of a div or span that you wish to hide or disable depending on whether the checkbox is checked or not.
    • OPTIONAL
    • The toggle attribute accepts two syntaxes (see below).
      • Basic: The basic syntax simply accepts the DOM id of the target div or span:
      • Advanced: The more advanced syntax accepts a JSON structure with the attributes: id and style. The "id" attribute is the DOM id of target div/span that you wish to hide or disable. The "style" attribute accepts either "hide" (default) or "dim". The "hide" style completely hides the target div/span until the checkbox is checked. The "dim" style greys-out and disables the child components of the target div/span until the checkbox is checked.
    • Version: Available since version 1.11.0

Related Tags

<obsgroup>

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

Attributes

  • groupingConceptId: ID of the associated concept
    • REQUIRED
    • Examples:
      • <obsgroup groupingConceptId="2214">
      • <obsgroup groupingConceptId="XYZ:HT">
      • <obsgroup groupingConceptId="0cbe2ed3-cd5f-4f46-9459-26127c9265ab">
    • Value: Any valid concept integer ID, concept mapping pair, or concept uuid.
    • Default: None
  • label: an optional display label for the ObsGroup; This will not show up in the form itself, but can be used to customize column headers in data exports, for example.
    • OPTIONAL
    • Default: None
    • Example
      • <obsgroup groupingConceptId="0cbe2ed3-cd5f-4f46-9459-26127c9265ab" label="Primary Diagnosis">
  • showIfEmpty: when set to false, when viewing a form, the obsgroup tag and its contents will produce no output if the encounter you are viewing contains no matching obs group
    • OPTIONAL
    • Default: true
    • Example
      • <repeat ...> <obsgroup groupingConceptId="123" showIfEmpty="false">...</obsgroup></repeat> 

Related Tags

Example Usage

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

  • since: 1.7.2

Attributes

  • field:
    • Example: <patient field="name" />
    • Value: see table
    • Default:

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

 

  • required: (currently only applies to patient identifier fields)
    • Example: <patient field="identifier" identifierType="2" required="false" />
    • Default: true 

Example Usage

<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

  • type: this is the relationship_type_id (or UUID) for the relationship that should be created for the selected person.
    • REQUIRED
    • Examples
      • <relationship type="1" whoAmI="A" changeExistingRelationship="true" />
      • <relationship type="0cbe2ed3-cd5f-4f46-9459-26127c9265ab" whoAmI="A" changeExistingRelationship="true" />
    • Value: Any valid relationship type ID or UUID for a relationship type
    • Default: NONE
  • whoAmI:this is the side of the relationship the patient the form is being entered on is. For example in a Parent to Child relationship, if the form is being filled out for the child then the whoAmI value should be set to "B" whereas if the form is being filled out for the parent then the whoAmI value should be set to "A"
    • REQUIRED
    • Examples
      • <relationship type="1" whoAmI="A" changeExistingRelationship="true" />
      • <relationship type="1" whoAmI="B" changeExistingRelationship="true" />
    • Value: "A" or "B"
    • Default: NONE
  • changeExistingRelationship: this attribute determines if new relationships should be added in addition to existing relationships or should replace the existing relationships of that type. So if this value is set to true, any existing relationships of that type will be replaced. If the attribute is set to false then a new relationship will be added in addition to any existing relationships.
    • REQUIRED
    • Examples
      • <relationship type="1" whoAmI="A" changeExistingRelationship="true" />
      • <relationship type="1" whoAmI="A" changeExistingRelationship="false" />
    • Value: "true" or "false"
    • Default: NONE
  • required: this is used for validation, and if true the form will not be able to be submitted without the required relationships existing for the patient. The code checks to see if the patient already has relationships existing, so validation will not fail if the required relationship types were set up prior to entering the form (in this situation the data entry clerk can edit or add new relationships or just ignore the question). The relationship widget displays to the user all existing relationships (for the types we care about in the tag), so the data entry clerk should be able to decide if entry on this question is needed.
    • OPTIONAL
    • Examples
      • <relationship type="1" whoAmI="A" changeExistingRelationship="true" required="true" />
      • <relationship type="1" whoAmI="A" changeExistingRelationship="true" required="false" />
    • Value: "true" or "false"
    • Default: false
  • requireAttributes: this attribute restricts the search results based on person_attributes. This attribute takes in a comma separated list of attributes. Each attribute can be entered as a name value pair (separated by a ',' for example Health Center:Rwinkwavu Health Center. Alternatively the attribute value can be entered in the format of ${currentPatientAttribute("Health Center")}, in this case the relationship tag will retrieve the value of Health Center attribute for the patient of the form and use this value as the valueto match. The value for the attribute is optional, and if left out then the search will return any people that possess the specified person_attribute.  If multiple attributes are specified, only persons that match allof the specified attributes are displayed.
    • OPTIONAL
    • Examples
      • <relationship type="1" whoAmI="A" changeExistingRelationship="true" requireAttributes="Health Center:Rwinkwavu Health Center" />
      • <relationship type="1" whoAmI="A" changeExistingRelationship="true" requireAttributes="Health Center:${currentPatientAttribute("Health Center")}" />
      • <relationship type="1" whoAmI="A" changeExistingRelationship="true" requireAttributes="Health Center" />
      • <relationship type="1" whoAmI="A" changeExistingRelationship="true" requireAttributes="Health Center:Florida,Citizenship:USA" />
    • Value: any valid person attribute type and optionally the value the person attribute should have.
    • Default: NONE
  • programIds: this attribute allows the search results to be filtered based on program enrollment. So this takes in a comma separated list of the program ids (or UUIDs). This can be used in conjunction with the personAttributes if necessary. If multiple programs are specified, only patients in allof the specified programs are displayed.
    • OPTIONAL
    • Examples
      • <relationship type="1" whoAmI="A" changeExistingRelationship="true" programIds="1" />
      • <relationship type="1" whoAmI="A" changeExistingRelationship="true" programIds="1,5" />
      • <relationship type="1" whoAmI="A" changeExistingRelationship="true" programIds="0cbe2ed3-cd5f-4f46-9459-26127c9265ab" />
    • Value: Any valid program ID, program UUID or underlying concept name
    • Default: NONE
  • display: This attribute determines which widget is displayed to the user to pick the person for the relationship. A value of “search” will present the user with a popup search box, allow them to enter a search term then select from the returned list. All searches in the tag search are based on person not patient, however you can search on patient identifiers and it will work. A value of “dropDown” presents the people in a simple drop down. If the drop down list is used when a large number of people are returned then this slows down the loading of the form, so drop down box option can only be used in conjunction with the requireAttributes and/or programId fields.
    • OPTIONAL
    • Examples
      • <relationship type="1" ="1" whoAmI="A" changeExistingRelationship="true" display="search" />
      • <relationship type="1" ="1" whoAmI="A" changeExistingRelationship="true" display="dropDown" />
    • Value: "search" or "dropDown"
    • Default: search

Example Usage

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

  • The code contained in the <template> tags is repeated for each <render> tag.

<render>

  • Used within a repeat tag to render code. Within the render tag you can also specify attributes that can be used as keys during substitution.

Example Usage

<repeat with="">

(Available in HFE 2.0.2 and above)

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

Attributes

  • with: Defines all the item
    •     REQUIRED
    •     Value: All the items that should be rendered with tag element, defined within single quotes. Supports 1 to n sets, and 1 to n items in each set.
    •     Example:<repeat with="['664','No Complaints'],['832','Weight Loss']">

                                  

Example Usage

<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

  • include: Defines all the user roles for whom the tag content should be included       
    •     REQUIRED (Either include or exclude field)
    •     Value: A comma seperated list of user roles
    •     Example:<restrictByRole include="System Developer,Provider"/>
    •     Default: None
    •     Since: 1.11
          
  • exclude: Defines all the user roles for whom the tag content should be excluded     
    •     REQUIRED (Either include or exclude field)
    •     Value: A comma seperated list of user roles
    •     Example:<restrictByRole exclude="Data Manager"/>
    •     Default: None
    •     Since: 1.11
       

<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

  • headerCode: Allows you specify the header label using a code that references message.properties or the translation mappings in the form itself.
    • OPTIONAL
    • Example: ???
    • Value: ????
    • Default: None.
  • headerLabel: The label to use in the section header.
    • OPTIONAL
    • Example: <section headerLabel="1. Information démographique">
    • Value: Any quoted string
    • Default: None.
  • headerStyle: Allows you to override the default style for the section header. (Treated as a CSS class.)
    • OPTIONAL
    • Value: Valid CSS class names
    • Default: sectionHeader
  • sectionStyle: Allows you to override the default style for the section. (Treated as a CSS class.)
    • OPTIONAL
    • Value: Valid CSS class names
    • Default: section
  • sectionTag: Lets you specify what tag should be used for the section
    • OPTIONAL
    • Value: Valid HTML tag name
    • Default: div
    • Since: 2.0.3
  • headerTag: Lets you specify what tag should be used for the section header
    • OPTIONAL
    • Value: Valid HTML tag name
    • Default: span
    • Since: 2.0.3

Example Usage

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

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

  • since: 1.9.0

Attributes

  • regimenCodes: Determines which regimens appear in the list
    • REQUIRED
    • Example: <standardRegimen regimenCodes="standardTri30,standardTri40" />
    • Value: Comma separated list of regimenCodes from the standard regimen xml in the global property 'dashboard.regimen.standardRegimens'
    • Default: None
  • discontinuedReasonConceptId: This creates a drop-down of coded reasons for discontinuing a regimen. This covers the valueCoded reason for discontinuing a regimen, and I'm currently waiting on a bug fix to 1.6+ to be able to support a text field for 'other' for discontinueReasonText.
    • OPTIONAL
    • Example: <standardRegimenregimenCodes="standardTri30,standardTri40" discontinuedReasonConceptId="1252"/>
    • Value:  a valid conceptId or uuid for the concept representing the reason for discontinuing.  This concept must have conceptAnswers.
    • Default: none
  • discontinueReasonAnswers: Allows you to explicitly set the possible list of discontinue reason answers.  If not used, all ConceptAnswers for discontinueReasonConceptId will be used.
    • OPTIONAL
    • Example: <standardRegimen regimenCodes="standardTri30,standardTri40" discontinuedReasonConceptId="1252" discontinueReasonAnswers="102,105"/>
    • Value:  valid reasons for discontinuing.  These concept should be a subset or all of the ConceptAnswers associated with the discontinuedReasonConceptId concept.
    • Default: none
  • discontinueReasonAnswerLabels: Allows you to specify labels for your discontinue reason answers
    • OPTIONAL
    • Example: <standardRegimen regimenCodes="standardTri30,standardTri40" discontinuedReasonConceptId="1252" discontinueReasonAnswers="102,105" discontinueReasonAnswerLabels="toxicity,defaulted"/>
    • Value: text strings equal in number to the number of ConceptAnswers specified in discontinueReasonAnswers.
    • Default: none

<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

  • class: adds the specified class or classes the generated submit element in rendered HTML
    • OPTIONAL
    • Example: <submit class="input-element large"/>
    • Value: string
    • Default: None
    • Version: Available since version 2.0.9
  • submitLabel: Allows you to set the text of the submit button.
    • OPTIONAL
    • Value: Any String
    • Default: Messages from message.properties for htmlformentry.enterFormButton or htmlformentry.saveChangesButton depending on if form new form is being saved or existing form is being edited, respectively.
    • Since: 1.7.2
  • submitCode: Allows you to set the text of the submit button using an htmlformentry translation code
    • OPTIONAL
    • Value: reference to a translation code
    • Default: None
    • Since: 1.7.2
  • submitStyle: Allows you to set the style class for the submit button.  This attribute gets written into the rendered submit tag as class="<<submitStyle Value>>".
    • OPTIONAL
    • Value: Valid CSS style attributes
    • Default: submitButton CSS style is referenced by default; if none is defined in the style section, no style will be applied 
    • since: 1.7.2

Example

Simplest example using defaults

Example of applying custom Class to a translated label

<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

  • defaultLocale: Allows you to specify the default variant value.
    • OPTIONAL
    • Example: <translations defaultLocale="en">
    • Value: Any quoted string.
    • Default: None.

Related Tags

<code>

Used to define a code to assign variant values to.

Attributes
  • name: Name of the variant
    • REQUIRED
    • Example: <code name="night_sweats">
    • Value: Any quoted string.
    • Default: None

<variant>

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

Attributes
  • locale: ????
    • REQUIRED
    • Example: <variant locale="en" value="night sweats"/>
    • Value: A valid two letter locale value. E.g. "ar", "en", "es", "fr"
    • Default: None
  • value: The value to be assigned to the code.
    • REQUIRED
    • Example: <variant locale="en" value="night sweats"/>
    • Value: Any quoted string.
    • Default: None

Example Usage

<variant>

See <translations>

<when>

See <controls>

Since: 2.1.6

<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

  • workflowId:
    • REQUIRED
    • Value: id or uuid of the workflow, or concept map reference to a concept associated with a workflow
  • type
    • Value: "radio", "dropdown", "checkbox", "hidden"
    • Defaults to dropdown. Tells how to render the widget to select a state.
    • In "radio" or "dropdown" mode the widget renders a list of the states in the workflow for selection by radio or dropdown respectively.
      • If the patient is not currently in a state for that workflow, only states flagged as "initial" will appear, otherwise all states will appear
      • (States that appear can be customized by the using the stateIds & stateLabels attributes)
      • If the patient is currently in a state for that workflow, that state will be selected on form load
      • Note that selecting a blank entry from a dropdown will do nothing--it will not take the patient out of his/her current state
    • In "checkbox" mode, upon form submittal, if the checkbox is checked, the patient is transitioned into the state specified by the by "stateId" parameter
      • If the patient is currently in the state specified by "stateId", the checkbox should appear checked
      • Note that unchecking a checkbox will do nothing--it will NOT take the patient out of the state
    • In "hidden" mode, the patient is automatically transitioned into the state specified by the "stateId" parameter (assuming they aren't already in that state)
  • stateIds
    • Only allowed if type="radio" or type="dropdown"
    • List of ids, uuids, or concept maps for the states. There could be one or a comma-separated list. This is the list of states to be displayed as options.
    • Only states within the specified workflow are allowed. Note that non-initial states will be suppressed from the display list if the patient is not currently in a state for the specified workflow. 
  • stateLabels
    • Only allowed if type="radio" or type="dropdown"
    • Matching text for the list of stateIDs. There could be one or a comma-separated list. If no labels are set, defaults to the preferred name of the concept backing the specified state
  • stateId
    • Mandatory if type="checkbox" or type="hidden", disallowed if type="radio" or type="dropdown"
    • State to transitional the patient into, referenced by id, uuid or concept mapping
  • stateLabel
    • Only allowed if type="checkbox" or type="hidden"
  • labelText: Sets the label that goes before the widget.
  • labelCode: Allows you to reference a label by a messages.properties code or a code in the translation mappings defined in the form.

Example

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:

  • If the patient is not enrolled in the program associated with the state, she is enrolled in the program on the encounter date.
  • If the patient is currently in another state in the workflow on the encounter date, that state is ended on the encounter date.
  • If the patient enters another state in the workflow after the encounter date, the new state added is ended on the date that this existing state starts. 
  • If the patient is already in the selected state on encounter date, no change is made

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

  • If there is no existing state for the selected workflow for the patient on the original encounter date, the same logic is followed as when entering a new form.
  • Otherwise, the state selected on the form is compared to the current patient state at the time of the original encounter date. If these two states differ, change the existing patient state on the original encounter date is changed to the selected state.
  • Regardless of whether or not the states differ:
    • If the new encounter date is earlier than the original encounter date:
      • The start date of the patient state on the original encounter date is moved to the new encounter date
      • If there is an active patient state on the new encounter date, it is ended on the new encounter date
      • If there are any other patient states between the new date and the original date, they are deleted
      • The program enrollment date is moved earlier (to the new encounter date) if necessary
    • If the new encounter date is after the original encounter date:
      • The start date of the patient state on the original encounter date is moved to the new encounter date
      • If there was a patient state just prior to the state we just shifted, it's end date is set to the new encounter date
      • Exception: if the patient state on the original encounter date had an end date, and the new encounter date is after that end date, an exception is thrown

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:

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:

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

Previous BMI:

Create your own custom tag and handler

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

7 Comments

  1. When looking up Observations based on Concepts that have a data type of Date/DateTime, use the getValueDatetime():

    For other Concepts use getValueAsString(null) or passing the locale as an argument:

  2. When calling a logic rule from an HTML form, if the name has a space in it, (for example <lookup expression="fn.logic('S N')"/>)  it doesn't work. As a work-around, simply remove the space(s) in the logic rule name.  For more information see HTML-210.

    1. Tokens that have spaces need to be enclosed with quotes like this:

  3. To pre-populate a field in an HTML form with the next consecutive number (not patient specific) for that observation type you can do the following.

    1. Create a numeric concept. In this example is it concept_id 6407.
    2. Create a Logic Rule, under Administration, Rule Definitions, Add a Rule.
    • In this example, its named SN.
    • It's in the Groovy language.
    • It has the following rule content. (Note: it has a parameter to set the count to blank for the first entry of every year. If this is not desired, remove the "def jan1" line and replace jan1 with null in the call to getObservations.)

         3. Put the following code at the top of your html form.

    Note: The field that gets the value would look something like this (notice the id for the field is used above)...

    Special thanks to Darius for all the help to come up with this solution!

    1. FWIW, I don't actually agree with doing this. The "next sequential number" is fetched from the database when you open the form, rather then when you submit this. And I'd fear that you're too likely to run into issues where two people open the form simultaneously, etc.

      But if you have human processes in place to make it work, go ahead...

  4. I have two questions about HTML forms:

    - fn.latestObs only returns the patient's most recent observation for the given concept id, but I want to return a list of the most recent answers of a Coded concept in a form and then show this list on another form. Is there anyway to do that ?

    - I need to retrieve the regimen name in HTML form when viewing a form. However, as I know, I cannot do that because OpenMRS just saves drug ID(s) of the selected regimen at Regimen tab, not the regimen name. I think about <standardRegimen> tag but it cannot categorize the regimen for what treatment I want, e.g the regimen for tuberculosis or the regimen for ARV. Does the OpenMRS support to get the regimen name of a patient?

    1. Tri--

      People don't normally monitor comments on wiki pages, so to get your questions answered, I would recommend writing to the implementer list instead:

      implementers@openmrs.org