OpenEMR Xml Form Generator
The XML based form generator (xmlformgen) is available at the following link:
Its goal is to allow you to write a single .XML file, and use the XML Form Generator to generate a form complying to openemr's form standard.
It contains a series of stylesheets(written in XSLT), a Makefile, and some example forms in .xml files.
Dependencies
This form generator uses xalan-c++ 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.
Filesystem access is required to install a generated form into an OpenEMR installation.
(Ubuntu dependency package : xsltproc )
Usage
Generating an Example Form
To generate a form from an .XML file, 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 example .xml files that comes with xmlformgen. This will create a form contained in a directory (named after the form). In the newly created directory, you should see 7 .php files, 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->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!
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 is a signable form. The most recent signed form of a given type for a given client can be made visible by adding a link to left_nav.php.
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.
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.
- 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.
