OpenEMR Xml Form Generator

From OpenEMR Project Wiki
Revision as of 01:54, 17 August 2011 by Julia Longtin (talk | contribs) (correct formatting.)

The XML Form Generator is still in development.

Its goal is to allow you to write a single .XML file, and use the XML Form Generator to generate a form complying to The Forms API. This should allow you to write encounter and non-encounter forms as short (but very specific) .xml files, and interchange them 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 has been integrated into the OpenEMR 4.0 development tree at openemr/contrib/forms/xmlformgen.

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

Filesystem access is required to install a generated form into an OpenEMR installation. Specifically, the installation process for a form requires administrator privileges, and write access to the interface/forms/ directory of the target OpenEMR install.

Ubuntu

dependency package : xsltproc

On 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.
  • cd into the openemr directory where xml formgen is. ( for example: cd c:/xampp/htdocs/openemr/contrib/forms/xmlformgen). Please mind the backslashes. They are important.
  • After moving to the xml formgen directory, please type the following command:
make INFILE=communication_log.xml

communication_log.xml is the default xml form attached with the xml formgen module, so it is used as an example. Please replace "communication_log.xml" with your custom form name in case you have your xml form code ready.

  • Thats it...all the php files are ready for your form along with the sql tables. You will find your new form in a folder in xml formgen directory.
  • Cut/copy the above newly made form folder and paste it into the interface/forms directory.
  • Login to openemr as an administrator and go to Administration-->others-->Forms.
  • In the unregistered section, you will find your new form. Please click "Register" and then "Install DB" to install the form into the database.
  • Do not forget to enable the form and give it a category name.
  • you will find your form in the encounter sheet for a patient.

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

Usage

Generating an Example Form

To generate a form from an .XML file, open up a terminal, cd into the directory where you have extracted the xml form generator, 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. 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->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. 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 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.

Field Types, and Type Specific Attributes

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"/>
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 common ones required for all fields.

Example
<field name="test_textbox" label="TextBox" type="textbox" fieldlength="20" hoverover="Test Field" 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 reference the listid from the list_options table)
    • maxlength: dictates the varchar length of the field 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.
Retrieved from "https://www.open-emr.org/wiki/index.php?title=OpenEMR_Xml_Form_Generator&oldid=7828"