HTML Form Entry UI Module

The HTML Form Entry UI module provides integration between HTML Form Entry and the UI Framework, allowing forms to be rendered in with the OpenMRS 2.0 style.

Unfortunately, this functionality have been woefully under-documented, but I hope to add some documentation here.

Serving Up Forms as Resources

In the initial design of OpenMRS 1.0 and HTML Form Entry, HTML Forms were stored in the database and edited via a simplistic editor built-in to the OpenMRS 1.0 administrative interface.

Storing forms directly in the DB made it almost impossible to collaborate on them and to maintain a version control system.

In OpenMRS 2.0, forms can be bundled up in custom modules, or even stored in the application data directory, and served up by the UI Framework as a resource. It's important to note that the form is still stored behind-the-scenes in the database, but forms referenced by resource will be loaded from the file system on demand and them updated in the DB before being rendered to the user. This allows developers to "hot reload" forms when working on them.

Serving Up a Form from the File System

Let's say you have a form "myForm.xml" that you'd like to load directly from the file system. The first step it to put the form in the "configuration" directory (or one of it's subdirectories) found within the application data directory.

For instance, in a type Tomcat instance on Ubuntu this might be as follows:

^{/home/tomcat7/.OpenMRS/configuration/pih/htmlforms/myForm.xml}

Then, you can reference this form by setting up an app or extension that renders the following link:

^{https://[serverUrll]/openmrs/htmlformentryui/htmlform/enterHtmlFormWithStandardUi.page?patientId={{patient-uuid}}&definitionUiResource=file:pih/htmlforms/myForm.xml}

Note the "definitionUiResource" parameter. "File" indicates that this is a "file" resource, and then after the colon a path relative to the "configuration" directory is provided. (Note that an absolute path could be provided instead, but relative is preferred).

Form Versioning

HFE-UI provides basic support for maintaining multiple versions of a single form and loading the correct version of the form based on the version used to create the initial encounter.

To do this, forms should be named in the format myForm_v[versionNumber].xml, where version number matches the version number defined in the form schema.

For instance, say you have three versions of "myForm", versions 1.0, 2.0, and 3.0, where 3.0 is the "current" version of the form. You could name them like this:

^{myform_v1.0.xml}

^{<htmlform formUuid="9c180d22-7ef6-49e4-8e52-ff314e218451"}
^{formEncounterType="c31d3312-40c4-11e7-a919-92ebcb67fe33"}
^{formName="My Form V1.0" formVersion="1.0">}

^{myform_v2.0.xml}

^{<htmlform formUuid="60efebcc-a4ff-4459-9754-1eaeafc4dc24"}
^{formEncounterType="c31d3312-40c4-11e7-a919-92ebcb67fe33"}
^{formName="M Form V2.0" formVersion="2.0">}

^myform.xml

^{<htmlform formUuid="d2cee145-0b53-4588-9836-dadafa122a8e"}
^{formEncounterType="c31d3312-40c4-11e7-a919-92ebcb67fe33"}
^{formName="My Form V3.0" formVersion="3.0">}

Then if you load a form via "file:pih/htmlforms/myForm.xml" and there's a encounter within the context, HFE will look to see if the encounter has a certain form version associated with it, and then will look for a file appended with that version. If no matching file is found, the default filename, "myform.xml", will be used.

Note that we call the most recent version of the form just "myform.xml" because that is the default version we want served up if no encounter is present (ie when creating a new form).

In the future, for example, if you were going to create a new "4.0" version of the form, you'd rename myform.xml → myform_v.3.0.xml and create a new myform.xml (setting a new random formUuid) with the new version 4.0 of the form.