OpenEMR Xml Form Generator

The XML based form generator (xmlformgen) is available at the following link:

XML Form Generator

It contains a series of XSLT stylesheets, a Makefile, and a pile of .xml files.

The XML files contain example form definitions. this is a series of xml files containing forms, for you to draw from when writing your own forms.

Dependencies

This form generator uses xalan-c++ to interpret the contents of XSLT files. it also uses a simple Makefile, so requires (likely) GNU Make.

Filesystem access is required to install a generated form into an OpenEMR installation.

Using

Compiling an Example Form

To 'compile' a form, open up a terminal, go to the directory you have extracted xmlformgen into, and type "make INFILE=filename.xml", where filename.xml is the name of a xml document you've created, or one of the .xml files that comes with xmlformgen. This will create a directory with 7 .php files, and one .sql file, 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->forms page, and the form should be shown at the bottom of the page as a form ready-to-install. Register it, run its sql, enable it, and you're done!

Format of a XML Input 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 should 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.

• 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. the 'history style' link for the page will show the most recent form for the given client that was 'signed' via the signatures method 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 xmlformgen creates, and populates with files, along with the name used for internal variables in 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 is the 'type' attribute. this attribute specifies the 'type' of the field (and is an abuse of xml, IMO). this dictates its display properties, behaviors, and other attributes required.

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

Some other attributes are required for most fields:

• 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 in the GUI. This attribute's contents must be escaped PHP style.
• 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. It is believed that this attribute's contents must be escaped PHP style.
• 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.

Field Types, and Type Specific Attributes

textfield

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

Required Attributes

• • maxlength: dictates the varchar length of the table column where the list data will be stored

Optional Attributes

• • length: 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" length="50" maxlength="255" labelcols="1" cols="3"/>

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 the ones required for all fields.

Example

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

The textarea Type

Fields with the textarea type are capable of containing 64k of text in a box.

Optional Attributes

• • rows: indicates the number of rows in the visible textarea - defaults to 4
  • columns indicates the number of columns in the visible textarea - defaults to 40

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

The checkbox_list Type

The checkbox_list field type creates a set of checkboxes, which allows for multiple checkboxes to be selected.

Required Attributes

• • list: this references the 'listid' of a list in a <list> tag (which, itself, should refrence the listid from the list_options table)

Example

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

The dropdown_list type

The dropdown_list field type creates a dropdown list which allows for individual selections to be saved.

Required Attributes

• • list: this references the 'listid' of a list in a <list> tag (which, itself, should refrence the listid from the list_options table)
  • maxlength: dictates the varchar length of the table column where the list data will be stored

Example

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

The date Type

Fields with a date type are meant for storing a date in. on input forms, this draws a calendar widget next to the field. This type has no additional attributes required.

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

The provider Type

provider: creates an int(11) field that references the "providers" from the `users` table. The provider type has no additional attributes required.

<field name="test_provider" label="Provider" type="provider" hoverover="" 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.

formscript.pl

Q: hey, Out of curiosity is this using the formscript.pl script? Just noted it in the 'make' file?

A: Not at all. its meerly there because i was using it for comparison purposes.