Wiki Spaces

Documentation
Projects
Resources

Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack

Documentation

Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 81 Next »

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.

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

Example Usage

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

<encounterDate>

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

Attributes

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

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

<encounterLocation>

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

Attributes

  • default: Sets default value for the widget.
    • OPTIONAL
    • Example: <encounterLocation default="2"/>
    • Value: Location ID, Location UUID, or Location Name
    • 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 locations in alphabetical order

Example Usage

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

<encounterProvider>

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

Attributes

  • 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

Example Usage

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

<encounterVoided>

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

Example Usage

<encounterVoided/>

<enrollInProgram>

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

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

Specifics about this enrollment behavior:

  • If the patient is already in the program on that date, nothing changes
  • If the patient is registered in the program after that date, then the patient's enrollment date will be moved back to the date of this encounter
  • Otherwise, the patient is enrolled as requested

Attributes

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

<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

  • logicTest A logic expression represents a logic test.
    • OPTIONAL
    • Example: <excludeIf logicTest="GENDER = F"/> - A logic test to see if the patient's gender is female
  • velocityTest A 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

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

<htmlform>

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

<includeIf>

See <excludeIf>

<lookup>

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

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

  • patient: the patient object you're entering the form for
  • 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)

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
      Latest BMI: <lookup expression="fn.logic('BMI')"/> <!-- requires that you have a BMI rule registered -->
      
  • fn.allObs(Integer conceptId)
    • returns all the patient's observations for the given concept id, as a List<Obs>
    • since 1.7.0
    • Example
      Past CD4 results: <lookup complexExpression="#foreach($cd4 in $fn.allObs(5497)) $cd4.valueNumeric #end"/>
      
  • 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
      Last Weight: <lookup expression="fn.latestObs(5089)"/>
      
      Last BMI: <lookup complexExpression="#set( $wt = $fn.latestObs(5089) ) #set( $ht = $fn.latestObs(5090) ) #set( $bmi = $wt / ($ht * $ht) ) $!{bmi}"/>
      
  • fn.earliestObs(Integer conceptId)
    • returns the patient's earliest observation for the given concept id
    • since 1.7.0
    • Example
      First Weight: <lookup expression="fn.earliestObs(5089)"/>
      
  • fn.allEncounters()
    • returns all the patient's encounters, as a List<Encounter>
    • since 1.7.4
    • Example
      Past Encounter Dates: <lookup complexExpression="#foreach($encounter in $fn.allEncounters()) $encounter.encounterDatetime #end"/>
      
  • fn.latestEncounter()
    • returns the patient's latest encounter
    • since 1.7.4
    • Example
      Latest MDR-TB Encounter: <lookup expression="fn.latestEncounter(2)"/>
      
  • fn.latestEncounter(EncounterType type)
    • returns the patient's latest encounter for the given encounter type id
    • since 1.7.4
    • Example
      First MDR-TB Encounter: <lookup expression="fn.latestEncounter(2)"/>
      

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

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

<macros>

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

Example Usage

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

<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 (date filed have 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

<patient field="identifierLocation" />

address

 

No

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

<patient field=”address” />

Example Usage

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

<obs>

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

Data Types

Numeric

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

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

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

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

Boolean

Various widget styles can be used to input Boolean values:

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

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

Text

By default, displays a normal text input box.

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

Date

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

Coded

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

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

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

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

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

<obs conceptId="1296" answerClasses="Drug" style="autocomplete"/>
Renders as a autocomplete widget with ConceptClass = "Drug"

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

Attributes

  • allowFutureDates: When set to true allows obsDatetime to be in the future. (Has no effect on valueDatetime.)
    • OPTIONAL
    • Example: <obs conceptId="5096" dateLabel="Date measured:" allowFutureDates="true" />
    • Value: "true" or "false"
    • Default: False - Only past dates are allowed by default.
  • 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" />
    • Value: A valid Concept Integer ID, Concept Mapping, or Concept uuid.
    • 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"/>
    • Value: Quoted, comma separated list of valid Concept Integer IDs, Concept Mappings, or Concept uuid's.
    • 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
  • 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
  • cols: Number of columns in the textarea (implies style="textarea").
    • OPTIONAL
    • Example: <obs conceptId="3221" rows="7" cols="60" />
    • Value: Positive integer.
    • 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
    • Examples:<obs conceptId="6135" /><obs conceptId="XYZ:HT" /><obs conceptId="0cbe2ed3-cd5f-4f46-9459-26127c9265ab" />
    • Value: Valid Concept Integer ID, Concept Mapping, or Concept uuid.
    • Default: None
  • dateLabel: Text to display after the obs.value widget and before the obs.datetime widget. 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: (since version 1.7.4)  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
  • defaultObsDatetime: (since version 1.7.4)  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
  • 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
    • Since 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"
  • 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
  • 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
  • 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.
  • 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"
  • conceptIds:  It is possible to create an obs tag where you're choosing the 'question' for a predefined answerConceptId.  This attribute can't be used in the same obs tag as the usual 'conceptId' attribute, and for the moment requires an answerConceptId.  Here is an example of valid usage of this attribute:
<obs conceptIds="1441,3017,2474" answerConceptId="656" labelText="ISONIAZID"/>
Renders as a dropdown list of drug sensitivity results for the drug isoniazid. 
The resulting obs has, for example,'WEAKLY POSITIVE' for the concept, and Isoniazid as the conceptAnswer.

Related Tags

<obsgroup>

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

Attributes

  • 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

Related Tags

Example Usage

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

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

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

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

<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 relationship_type_id="1" whoAmI="A" changeExistingRelationship="true" />
      • <relationship relationship_type_id="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 relationship_type_id="1" whoAmI="A" changeExistingRelationship="true" />
      • <relationship relationship_type_id="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 relationship_type_id="1" whoAmI="A" changeExistingRelationship="true" />
      • <relationship relationship_type_id="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 relationship_type_id="1" whoAmI="A" changeExistingRelationship="true" required="true" />
      • <relationship relationship_type_id="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.
    • OPTIONAL
    • Examples
      • <relationship relationship_type_id="1" whoAmI="A" changeExistingRelationship="true" requireAttributes="Health Center:Rwinkwavu Health Center" />
      • <relationship relationship_type_id="1" whoAmI="A" changeExistingRelationship="true" requireAttributes="Health Center:${currentPatientAttribute("Health Center")" />
      • <relationship relationship_type_id="1" whoAmI="A" changeExistingRelationship="true" requireAttributes="Health Center" />
      • <relationship relationship_type_id="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.
    • OPTIONAL
    • Examples
      • <relationship relationship_type_id="1" whoAmI="A" changeExistingRelationship="true" programIds="1" />
      • <relationship relationship_type_id="1" whoAmI="A" changeExistingRelationship="true" programIds="1,5" />
      • <relationship relationship_type_id="1" whoAmI="A" changeExistingRelationship="true" programIds="0cbe2ed3-cd5f-4f46-9459-26127c9265ab" />
    • Value: any valid program id or program UUID
    • 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 it is only advisable to use the drop down box option if the number of people returned is being restricted by the use of the requireAttributes and programId fields.
    • OPTIONAL
    • Examples
      • <relationship relationship_type_id="1" whoAmI="A" changeExistingRelationship="true" display="search" />
      • <relationship relationship_type_id="1" whoAmI="A" changeExistingRelationship="true" display="dropDown" />
    • Value: "search" or "dropDown"
    • Default: search

Example Usage

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

<render>

See <repeat>

<repeat>

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

Related Tags

<template>

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

<section>

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

Attributes

  • 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.
    • OPTIONAL
    • Value: Valid CSS style attributes
    • Default: None
  • sectionStyle: Allows you to override the default style for the section.
    • OPTIONAL
    • Value: Valid CSS style attributes
    • 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

  • 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

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

Example of applying custom Class to a translated label

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

<template>

See <repeat>

<translations>

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

Attributes

  • 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

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

And then in the body of the form:

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

<variant>

See <translations>

Javascript function reference

Javascript overview

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

  • Any time you specify an 'id' attribute on an obs tag (for example: <obs id="weight" .../>) you have access to the displayed fields (in this example: weight.value, weight.date, weight.error, and weight.accessionNumber)

getField(idAndProperty)

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

  • argument: idAndProperty the field you want to get (for example "weight.value")
  • returns: a JQuery selector for the field you requested
  • since: 1.6.8
    Example:
    $j(function() {
         getField('weight.value').change(function() {
             window.alert('Weight is now ' + getValue('weight.value'))
        });
    });
    

getValue(idAndProperty)

Gets the value of a field.

  • argument: idAndProperty the field you want to get (for example "weight.value")
  • returns: the value of the specified field
  • since: 1.6.8
    Example:
    $j(function() {
         window.alert('You entered ' + getValue('weight.value') + 'kg as the weight');
    });
    

setValue(idAndProperty)

Sets the value of a field

  • argument: idAndProperty the field you want to set the value of (for example "weight.value")
  • value: the value you want to set
  • since: 1.6.8
    Example:
    $j(function() {
         setValue('weight.value', 74);
         setValue('scheduledVisit.value', true);
         setValue('howTravelClinic.value', 456); // 456 is a concept id that's a legal answer to this question
    });
    

Additional jquery examples

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

Other Examples and Tips

Example HTML Forms

Linking to Pages

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

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

Features in Version 1.7

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

An example for first encounter location using logic:

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

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

Previous BMI:

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

Create your own custom tag and handler

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

  • No labels