Difference between revisions of "OpenEMR Xml Form Generator"

From OpenEMR Project Wiki
 
(54 intermediate revisions by 3 users not shown)
Line 1: Line 1:
The XML based form generator (xmlformgen) is available at the following link:
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.


[http://sourceforge.net/tracker/download.php?group_id=60081&atid=1245239&file_id=380615&aid=3004080 XML Form Generator]
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 - [https://sourceforge.net/projects/mingw/files/MinGW/make/mingw32-make-3.80-3/mingw32-make-3.80.0-3.exe/download]
:* Install the make package (The downloaded file is an .exe file)
:* Install cygwin for windows - [http://www.cygwin.com]
:* 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- [http://www.sagehill.net/docbookxsl/InstallingAProcessor]-- Thank you bradymiller for the link.
 
= <center><span style="color:red;font-size:100%;">'''Important - For fixing E-sign Issues'''</span></center> =
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 [http://sourceforge.net/p/openemr/discussion/202506/thread/79625634/ 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.
 
<pre>
<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- Example form -->
<form>
<table type="form">form_history</table>
<!-- Form contents go here. -->
</form>
</pre>
:* 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


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.
<pre>
<?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>
</pre>
:* Now for the most important part and the root cause of problem for e-sign, the safename part. <span style="color:red;">'''The safename of the form should match the table type name'''</span> 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 -


It contains a series of stylesheets(written in XSLT), a Makefile, and some example forms in .xml files.
<pre>
<?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>
</pre>


= Dependencies =
<pre>
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.
<?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>
</pre>


Filesystem access is required to install a generated form into an OpenEMR installation.
<pre>
<?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>
</pre>


(Ubuntu dependency package : xsltproc )
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 =
= Usage =


== Generating an Example Form ==
== 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]].
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 ==
== 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!
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 ==
== Example Forms ==
Line 28: Line 111:
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.
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.
:* 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.
 
:* 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.


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 =
= Format of an XML Input File =
Line 73: Line 157:


===== Attributes =====
===== Attributes =====
The 'type' option indicates the table type.
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)
* '''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.
* '''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).


<pre>
<pre>
Line 101: Line 185:


==== The safename Entity ====
==== 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.
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.


<pre>
<pre>
Line 186: Line 270:


==== Common Attributes ====
==== 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.
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.


* '''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)
===== 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)
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.
* '''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()".
* '''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.
* '''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.
* '''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 ====
==== Field Types, and Type Specific Attributes ====


===== textfield =====
===== CheckBox_List =====
fields with a type of 'textfield' are useful for containing a field with a hard limit on text contents.
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 ======
====== Required Attributes ======
** '''maxlength''': dictates the varchar length of the table column where the list data will be stored
* '''list''': this references the 'listid' of a list in a <nowiki><list></nowiki> tag. (Which itself should reference or create a listid in the list_options table...)


====== Optional Attributes ======
====== Limits ======
** '''length''': dictates the size of the html field used for input - defaults to 10 characters
* Backed in the database by a varchar(255). Be careful not to specify TOO many options at once...


====== Example ======
====== Example ======
<pre>
<pre>
<field name="test_textfield" label="Textfield" type="textfield" hoverover="A Text Field" length="50" maxlength="255" labelcols="1" cols="3"/>
<field name="test_checkbox" label="CheckBox" type="checkbox_list" labelcols="1" cols="1" list="yesno" />
</pre>
</pre>


===== TextBox =====
===== DropDown_List =====
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.
Fields with the 'dropdown_list' type create a dropdown box, allowing for a single selection from a list of values to be saved.
====== Attributes ======
 
TextBoxes have no attributes other than the ones required for all fields.
====== Required Attributes ======
* '''list''': This references the 'listid' of a list in a <nowiki><list></nowiki> 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 ======
====== Example ======
<pre>
<pre>
<field name="test_textarea" label="Textarea" type="textarea" rows="10" columns="80" labelcols="1" cols="1"/>
<field name="test_dropdown" label="DropDown" type="dropdown_list" maxlength="30" labelcols="1" cols="1" list="status"/>
</pre>
</pre>


===== The textarea Type =====
===== Date =====
Fields with the textarea type are capable of containing 64k of text in a box.
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.


====== Optional Attributes ======
====== Additional 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


====== Example ======
<pre>
<pre>
<field name="test_textarea" label="Textarea" type="textarea" rows="10" columns="80" labelcols="1" cols="1"/>
<field name="test_date" label="Date" type="date" labelcols="1" cols="3"/>
</pre>
</pre>


===== The checkbox_list Type =====
===== Exams =====
The checkbox_list field type creates a set of checkboxes, which allows for multiple checkboxes to be selected.
A type specific to the history form.


====== Required Attributes ======
===== Provider =====
** '''list''': this references the 'listid' of a list in a <nowiki><list></nowiki> tag (which, itself, should refrence the listid from the list_options table)
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 ======
====== Example ======
<pre>
<pre>
<field name="test_checkbox" label="Checkbox" type="checkbox_list" list="yesno" hoverover="" labelcols="1" cols="1"/>
<field name="test_provider" label="Provider" type="provider" hoverover="" labelcols="1" cols="1"/>
</pre>
</pre>


===== The dropdown_list type =====
===== TextArea =====
The dropdown_list field type creates a dropdown list which allows for individual selections to be saved.
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.


====== Required Attributes ======
====== Optional Attributes ======
** '''list''': this references the 'listid' of a list in a <nowiki><list></nowiki> tag (which, itself, should refrence the listid from the list_options table)
* '''rows''': the number of rows visible in the textarea. Defaults to 4.
** '''maxlength''': dictates the varchar length of the table column where the list data will be stored
* '''columns''': the number of columns visible in the textarea. Defaults to 40.


====== Example ======
====== Example ======
<pre>
<pre>
<field name="test_dropdown" label="Dropdown" type="dropdown_list" list="status" maxlength="30" hoverover="" labelcols="1" cols="1"/>
<field name="test_textarea" label="Textarea" type="textarea" rows="10" columns="80" labelcols="1" cols="1"/>
</pre>
</pre>


===== The date Type =====
===== TextBox =====
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.
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 ======
<pre>
<pre>
<field name="test_date" label="Date" type="date" hoverover="" labelcols="1" cols="3"/>
<field name="test_textbox" label="TextBox" type="textbox" fieldlength="20" hoverover="Test Field" labelcols="1" cols="1"/>
</pre>
</pre>


===== The provider Type =====
===== 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.


'''provider''': creates an int(11) field that references the "providers" from the `users` table. The provider type has no additional attributes required.
====== Optional Attributes ======
* '''size''': dictates the size of the html field used for input. Defaults to 10 characters.


====== Example ======
<pre>
<pre>
<field name="test_provider" label="Provider" type="provider" hoverover="" labelcols="1" cols="1"/>
<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"/>
</pre>
</pre>


Line 295: Line 400:
:* To find the list id for a list already in openemr, I recommend viewing the source of the 'edit list' administration page.
:* To find the list id for a list already in openemr, I recommend viewing the source of the 'edit list' administration page.


== formscript.pl ==
[[Category:Configuration Guide]][[Category:Developer Guide]][[Category:Forms]]
 
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.

Latest revision as of 08:25, 25 October 2014

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.

Additional Attributes
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.