OpenEMR Xml Form Generator

The XML Form Generator allows you to write a single .XML file, and use the XML Form Generator to generate a form complying to The Forms API. This allows you to write encounter and non-encounter forms as short (but very specific) .xml files, which can be interchanged easily with other OpenEMR users.

It contains a series of stylesheets(written in XSLT), a Makefile, and some example forms in .xml files.

Availability

The XML Form Generator can be found in OpenEMR 4.0 and later under the contrib/forms/xmlformgen direcory.

Dependencies

This form generator uses xalan-c++ or xsltproc to interpret style sheets written in the XSLT language. It also uses a simple Makefile, so requires (likely) GNU Make, and a posix compatible shell environment(linux,MacOSX,windows(with add-ons)...).

Write access to an Openemr Instance is required to install a generated form into an OpenEMR installation. Specifically, the installation process for a form requires write access to the interface/forms/ directory of the target OpenEMR install.

Linux

Most versions of Linux just need to have a posix compliant shell, GNU make, and xsltproc available.

Debian

All Debian installs come with some sort of posix compliant shell, so the only things to worry about are make and xsltproc.

apt-get install make xsltproc

Windows

To run xml form generator on windows, the following steps are to be followed:

• First install the "make" package from sourceforge - [1]
• Install the make package (The downloaded file is an .exe file)
• Install cygwin for windows - [2]
• While installing cygwin, first install it with the default packages available.
• After completion of installation, run the cygwin setup again and install the "make" files from the "devel" category and "util" category.
• Also install the "libxml2" and "libxslt" packages from the "lib" category during setup.
• Let the cygwin install on its own.
• After complete installation of cygwin, run cygwin by double clicking the desktop icon.
• A command prompt like window appears. This window is running bash, a shell engine sufficient for running xmlformgen.
• CD into the directory where xmlformgen is. ( for example: cd c:/xampp/htdocs/openemr/contrib/forms/xmlformgen). Please mind the backslashes. They are important.
• From this directory, you should be able to follow the below directions.

For further information on installing xsltproc on windows and cygwin, please follow the link- [3]-- Thank you bradymiller for the link.

Important - For fixing E-sign Issues

The E-signing of encounters and individual forms gets broken if xmlformgen forms or any other forms have a mismatch in the table_name of the form and the safe_name of the form in the database. For this, while making xml forms, we need to take care of certain things which can avoid the issue and make e-sign go well with the forms and encounters.The issue has been discussed here

• Lets take an example of making a History form for the encounter. While preparing the xmlformgen xml file, write a table_name of your choice for the form like form_history.This is your table type which gets the table name of the form in the database.

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- Example form -->
<form>
 <table type="form">form_history</table>
 <!-- Form contents go here. -->
</form>

• Next, enter the real name of the form which will appear nice in the OpenEMR encounter. Suppose we want the real name to be History Form. We will do it as shown below

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- Example form -->
<form>
 <table type="form">form_history</table>
 <RealName>History Form</RealName>
 <!-- Form contents go here. -->
</form>

• Now for the most important part and the root cause of problem for e-sign, the safename part. The safename of the form should match the table type name i.e for our History Form as the table type was form_history, the safename should be history only. If the table type name is form_generalsurvey, then the safename should be generalsurvey. Three examples of different types are given below -

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- Example form -->
<form>
 <table type="form">form_history</table>
 <RealName>History Form</RealName>
 <safename>history</safename>
 <!-- Form contents go here. -->
</form>

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- Example form -->
<form>
 <table type="form">form_generalsurvey</table>
 <RealName>General Survey</RealName>
 <safename>generalsurvey</safename>
 <!-- Form contents go here. -->
</form>

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- Example form -->
<form>
 <table type="form">form_resp_exam</table>
 <RealName>Respiratory Examination</RealName>
 <safename>resp_exam</safename>
 <!-- Form contents go here. -->
</form>

Developers are working on the issue to make it a permanent fix so that the safename and tablename without matching can work with e-sign. For the time being we can make our forms by following the above steps so that the issue can be avoided.

Usage

Generating an Example Form

To generate a form from an .XML file, open up a terminal, cd into the directory containing the xml form generator, and type "make INFILE=communication_log.xml", where communication_log.xml is the name of a xml document you've created, or one of the example .xml files. This will create a form contained in a directory (named after the form). In the newly created directory, you should see 6 .php files, one .css file, and one .sql file. These files are your newly created form, hopefully conforming to The Forms API.

Importing a Form

To import one of these forms, copy the folder containing the generated files to the interface/forms location in your openemr install. Login to your OpenEMR install as the 'administrator', to the administration->others->forms page. Your new form should be shown at the bottom of the page in the 'unregistered' section. click 'Register', and then 'Install DB' to add your form the the database. Make sure you enable the form, and give it an appropriate category name, indicating what category you will find it under in a patient's encounter sheet.

Example Forms

communication_log.xml

The Communication Log form is a form for logging a phone call (incoming or outgoing) relating to a client. Its table type is set to 'extended', mainly so that it saves its revision history.

• Its laid out four cells wide, and contains a pretty generic contact form's fields.

• It makes use of the 'yesno' list, that is part of OpenEMR. As the 'yesno' list is already there, we mark the list in the xml file 'import="no"', so that we do not import it into the internal list system. We also define no members of the list.

• It is a 'signable' form, indicating that it criteria that mark it as 'completed'. The most recent signed form of a given type for a given client can be made visible by adding a special link to left_nav.php.

Format of an XML Input File

The following is a definition of each field you can/must have in a form contained in an xml file.

Comments

XML style comments can be applied anywhere an element would be placed. they should be formatted like the following:

  <!-- MHP Progress Note -->
  <!-- this OpenEMR form has not yet been approved by CRRT -->

Required Parts of a Form

XML Header

Input files must start with a header, defining the file as an XML document.

<?xml version="1.0" encoding="ISO-8859-1"?>

Open the form tag

The form tag contains the contents of your form. there should only be one form tag per document, at the top opening the document, and a closing tag at the bottom of the file.

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- Example form -->
<form>
<!-- Form contents go here. -->
</form>

The Table Entity

Content

This entity's contents indicate the sql-safe name of the table where the data for this form will be stored.

Attributes

The 'type' option indicates the table type. This attribute is required. You MUST pick one type or the other, otherwise your form's table.sql will be malformed, and fail to import.

• form indicates that this form happens in an encounter, and it will not have a revision history. (this is the normal behavior of forms in OpenEMR)
• extended indicates that this form can fall outside of the encounter system (like the 'history' page), but it doesn't prevent it from being part of the encounter system. Mainly, it gives us a form that saves edit history. For a signed form, the form's show.php will show the most recent form for the given client that was 'signed' via the signatures method(described below).

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- Example form -->
<form>
 <table type="form">form_example</table>
 <!-- Form contents go here. -->
</form>

The RealName Entity

This entity contains the name of the form as it will show up in OpenEMR. Single ticks should be escaped PHP style.

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- Example form -->
<form>
 <table type="form">form_example</table>
 <RealName>Example Form</RealName>
 <!-- Form contents go here. -->
</form>

The safename Entity

This entity contains the html-safe directory-name-safe name of the form. this will be the name of the directory created, along with the name used for internal variables within the form.

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- Example form -->
<form>
 <table type="form">form_example</table>
 <RealName>Example Form</RealName>
 <safename>example</safename>
 <!-- Form contents go here. -->
</form>

The style Entity

The style entity indicates what 'style' to use when drawing the form, and the number of columns wide to make the form.

Content

• layouts: visual style similar to the layout engine (non-encounter forms)
• paper: visual style is more similar to the encounter system forms style

Attributes

• cells_per_row: indicates how many columns you want to lay out your fields in. (i.e., how many <td>s per <tr>)

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- Example form -->
<form>
 <table type="form">form_example</table>
 <RealName>Example Form</RealName>
 <safename>example</safename>
 <style cells_per_row="4">paper</style>
 <!-- Form contents go here. -->
</form>

Notes about RealName, and safename

Both of these names will show up in the `registry` table of the mysql database. 'RealName' will be in `registry`.`name` and 'safename' will be in `registry`.`directory`

Optional Form Components

The Acl Entity

We don't know exactly how to configure this, but the code is templated from openemr code, and its reported to work by a user. It is not required.

Content

The content of the acl entity is the name of the 'type of information' we require the user have permissions to.

Attributes

• table:

<acl table="patients">med</acl>

Describing Your Form

Forms generated by the XML form generator are broken into sections, which are collapsable. each of these sections contains a series of fields, laid out on a 'grid'. Structurally, this means that all of your fields MUST be contained inside of sections, and all of your sections MUST be inside of a manual or layout entity(described next).

Manual and Layout Entities

The <manual> tag and the <layout> tag both enclose a section of the XML document that contains sections and fields the form generator will generate. The difference between the tags is that layout will create a php page that honors the layout engine (this functionality is not commonly tested), whereas manual uses xmlformgen's internal engine to generate the form contents (and is recommended). you MUST place all your fields within sections, and all your sections inside of either a manual or a layout section.

Section Entities

The <section> tag begins a named, collapsible section of the form.

Content

The contents of this tag should consists only of field entities, as described below.

Required Attributes

• name: indicates the name used for the div in the html.
• label: indicates the visible name of the secton that will show up in the GUI and (I assume in the <layout> mode will be the name of the section that goes into the `layout_options`.`group_name` field.

Example

<section name="client_info" label="Client Info">
 <!--- field entities go here -->
</section>

Field Entities

Each field on your form is represented by a field entity. a field entity describes the fields at every level: sql table structure, look, behaviors, etc. fields have no content, only attributes, and therefore can be self-closed as shown below:

<field [put some attributes here] />

Common Attributes

The most important attribute of a field is the 'type' attribute. This attribute specifies the 'type' of the field (and is an violation of XML philosophy, IMO). It dictates the field's presentation, behaviors, and any of the field's other functions.

Required Attributes

• type: dictates the data type both for the html form field and the sql table. (More on this below, as each type dictates further required and optional attributes)
• name: dictates both the field's column name in the sql table and the name of the html object representing the field. The contents of this attribute need to be safe for both html field names and mysql column table names.
• label: dictates the label will be visible to the user. This attribute's contents must be escaped PHP style, and is passed to ".xl_layout_label()".
• labelcols: dictates the number of columns that will be reserved for displaying the label in the form.
• cols : dictates the number of columns that will be reserved for displaying the field in the form.

Optional attributes

• hoverover: dictates the title attribute of the html form field. In effect, this becomes the text that pops up when you hover your mouse over the field. This attribute's contents must be escaped PHP style for inclusion within singlequotes.

Please note that hoverover attributes do not function, on checkbox_list fields.

Field Types, and Type Specific Attributes

CheckBox_List

Fields with the 'checkbox_list' type create a set of check boxes, which allow for multiple check boxes representing multiple values to be selected.

Required Attributes

• list: this references the 'listid' of a list in a <list> tag. (Which itself should reference or create a listid in the list_options table...)

Limits

• Backed in the database by a varchar(255). Be careful not to specify TOO many options at once...

Example

<field name="test_checkbox" label="CheckBox" type="checkbox_list" labelcols="1" cols="1" list="yesno" />

DropDown_List

Fields with the 'dropdown_list' type create a dropdown box, allowing for a single selection from a list of values to be saved.

Required Attributes

• list: This references the 'listid' of a list in a <list> tag. (which itself should reference or create a listid in the list_options able)
• maxlength: The length of the varchar() field in the database table where a selection from the list will be stored.

Optional Attributes

There are no optional attributes unique to the dropdown_list type.

Example

<field name="test_dropdown" label="DropDown" type="dropdown_list" maxlength="30" labelcols="1" cols="1" list="status"/>

Date

Fields with a 'date' type are meant for storing a date in. On input forms, this draws a calendar widget retrievable by clicking the button next to the field. This widget makes finding dates easier.

Required Attributes

This type has no additional attributes required.

Example

<field name="test_date" label="Date" type="date" labelcols="1" cols="3"/>

Exams

A type specific to the history form.

Provider

Fields with the 'provider' type create an int(11) field that references the "providers" from the `users` table. This is to store a reference to a selected provider. The provider type has no additional attributes required.

Example

<field name="test_provider" label="Provider" type="provider" hoverover="" labelcols="1" cols="1"/>

TextArea

Fields with a type of 'textarea' are useful for up to ten long narratives on a form, and can contain 64k of text in a box.

Optional Attributes

• rows: the number of rows visible in the textarea. Defaults to 4.
• columns: the number of columns visible in the textarea. Defaults to 40.

Example

<field name="test_textarea" label="Textarea" type="textarea" rows="10" columns="80" labelcols="1" cols="1"/>

TextBox

Fields with a type of 'textbox' are useful for containing narrative contents, EG, paragraphs of text. TextBoxes are capable of containing up to 64K of text.

Attributes

TextBoxes have no attributes other than those required for all fields.

Example

<field name="test_textbox" label="TextBox" type="textbox" fieldlength="20" hoverover="Test Field" labelcols="1" cols="1"/>

TextField

Fields with a type of 'textfield' are useful for containing text with a hard limit on contents.

Required Attributes

• maxlength: dictates the length of the SQL varchar field where the list data will be stored.

Optional Attributes

• size: dictates the size of the html field used for input. Defaults to 10 characters.

Example

<field name="test_textfield" label="TextField" type="textfield" hoverover="A Text Field" size="50" maxlength="255" labelcols="1" cols="3"/>
<field name="test_normaltextfield" label="NormalTextField" type="textfield" hoverover="A Normal Text Field" maxlength="255" labelcols="1" cols="1"/>

Lists

Every list used in the field entities above should have a list entity representing it. Lists can be either lists that are already in openemr (internal lists), or can be created as part of importing the form. In cases where you're not having the form import the lists(by setting the import attribute ="no") there is no need to have content for these entities, and the list tag can close itself.

Example List

<list name="yesno" label="Yes/No" type="standard" id="yesno" import="yes">
 <listitem id="NO" label="NO" order="1">NO</listitem>
 <listitem id="YES" label="YES" order="2">YES</listitem>
</list>

Example Internal List

<list name="marital_status" label="Marital Status" type="standard" id="marital" import="no"/>

Notes

• Please keep in mind, that OpenEMR's lists system has a 31 character limit for list ids and listitem ids.
• If you don't have the list created in openemr already and/or your list id attribute isn't referencing a list, then the field won't show up in the GUI.
• To find the list id for a list already in openemr, I recommend viewing the source of the 'edit list' administration page.