PDF Form Templating

From FreemedDeveloperWiki, the FreeMED developers' Wiki.

PDF Form Templating is the next-generation templating system which is slated to be released in FreeMED 0.9.0. It allows forms to be generated from PDF forms with composited data pulled from a patient's medical record rendered on top of it, as well as support for custom controls. These custom controls allow custom data to be stored in the patients' medical record, where it can be queried and/or pulled for use in these forms.

This is a current project. Email Jeff if you are interested in working on this.

Contents 1 Creating Templates 1.1 Getting PDF Coordinates 1.2 Testing Templates 2 Template Format 2.1 Data Types 2.2 Data Elements Equivalencies 2.3 Control Types 3 Control Examples

Creating Templates

Creating templates has no GUI for right now, which means that form templates have to be done in raw XML. This should be remedied soon.

Getting PDF Coordinates

This is a bit of a pain, as there is no really good way to do this. The easiest way I have found yet is:

 # Scan in using kooka or something else to create an EPS file
 epstopdf original.eps
 gimp original.png

!! IMPORTANT !! Make sure that you use 72 dpi as the import resolution for the EPS, or else your coordinates will be unbelievably wrong. I'm not kidding about this.

Once in the GIMP, use the selection tool to determine the positions. Dragging can determine the width and height.

Testing Templates

Put this script in your FreeMED root directory as test_template.php:

 <?php
 include_once('lib/freemed.php');
 $t = CreateObject('FreeMED.FormTemplate', 'templatename');
 $t->LoadPatient(1);
 print $t->OutputData();
 ?>

Substitute templatename with the name of the template file without the .xml extension. Make sure you have the CGI/CLI version of PHP installed (run "php -v" to check this). You can then run the following command to generate, render, view and cleanup (from your FreeMED root directory, of course):

 php test_template.php > tmp; ./scripts/composite_form.pl tmp > tmp.pdf; acroread tmp.pdf; rm -f tmp tmp.pdf

If this generates errors, there is a PHP parsing problem. Check this by running:

 php test_template.php | less

kpdf, xpdf, kghostview, etc work just as well as acroread if you don't want to use it for religious reasons.

Template Format

The file is constructed like this:

 <?xml version="1.0"?>
 <formtemplate>
      <information>
           <name>name of template, to appear in FreeMED</name>
           <pdf>name of pdf file to template from</pdf>
           <creator></creator>
      </information>
      <page oid="original page number">
           <element xpos="x position" ypos="y position" xsize="x size" ysize="y size" data="data type">
                <data table="patient or module name" field="field name" type="formatting" />
                <comment>optional comment</comment>
           </element>
 
           <!-- ... repeat elements as necessary ... -->
 
      </page>
 
      <!-- ... repeat pages as necessary ... -->
      
      <controls>
           <control uuid="uuid, as generated by uuidgen"
                    name="Textual name"
                    type="type of control"
                    variable="name_of_variable"
                    limits="limits if necessary"
                    options="options if type=select"
                    default="defaults if there are any"
                    />
 
             <!-- ... repeat controls as necessary ... -->
      </controls>  
 </formtemplate>

It needs to be placed in the data/form/templates directory under the FreeMED root directory. The PDF file referenced in the formtemplate/information/pdf element should be placed in data/form/pdf and should not be referenced with any path name (i.e. "data/form/pdf/test.pdf" would become "test.pdf").

Data Types

This table refers to the "data" attribute of an "element" tag.

"data" Field	Description	Behavior
data	Standard text data	Positions the text that is rendered from the "data" tag. Most elements will use this attribute.
outline	Produce an outline using the area specified by the element area. Useful for "circling" data items.	Any non-null output from the "data" tag will produce the outline. Conditionals are useful to create the option of circling an area. To test, use "static" data elements as you would for "data" fields.

Data Elements Equivalencies

Data element equivalency table

Table Attribute	Description	Field Equivalency
patient	Core patient table attributes from the EMR	Field names of "patient" table, or methods of the patient object if prefaced with 'method:'
module:modulename	Module functions and variables	Regular field name of table associated with module, or method:methodname for output from that modules' method.
object:objectname	Object functions, as accessible through CreateObject()'s FreeMED.* namespace.	In format type:description:method. Type, if "patient", specifies that "description" maps to a patient field. The method field is optional, defaulting to "to_text".
control	Custom controls, defined in the template.	Name of control. This is the variable field of the equivalent control.
static	Static text, which is formatted by the engine. Most useful for positioning and testing.	Text to be displayed (will be subject to the 'type' conversion).

Control Types

Control Type	Description	options Element	limits Element	value Element
conditional	Conditional printing based on a control value; this is not for a control definition, but is used exclusively in data elements.	Control element to examine	-	Value to be printed if conditional succeeds
date	Date selection widget	-	-	-
module	Use a module widget	Name of the module to use	-	-
multiple	Multiple choice picklist	Pipe delimited ("|") options	-	-
phone	Phone selection widget	-	-	-
select	Picklist	Pipe delimited ("|") options	-	-
string	Raw string input	-	Maximum length of input	-

Control Examples

DISCLAIMER  : DO NOT USE THE UUIDS LISTED HERE!! YOU MUST GENERATE YOUR OWN!!

               <control uuid="da27738e-38ae-4183-83fa-fbcf0e20f897"
                       name="Preop Consult Date"
                       type="date"
                       variable="preop_date" />
               <control uuid="8c38cc50-7c2c-4171-b623-68b08f344c72"
                       name="Preop Consultant"
                       variable="preop_provider"
                       type="module"
                       options="providermodule"
                       limits="30" />
               <control uuid="835feff2-413c-44a5-8ed6-5b63c10e018f"
                       name="Anesthesia Consult Date"
                       type="date"
                       variable="anesth_date" />
               <control uuid="ba02316e-4a94-47f8-80bd-e739d4d6cbf2"
                       name="Anesthesia Consultant"
                       variable="anesth_provider"
                       type="module"
                       options="providermodule"
                       limits="30" />
               <control uuid="3b179cd6-a3cb-41c3-9f09-0450763966a1"
                       name="Therapy"
                       type="multiple"
                       variable="therapy"
                       options="Physical Therapy|Physical Therapy (preop)|Occupational Therapy|Social Services" />
               <control uuid="d443c86c-644f-11da-a38a-00110921bf16"
                       name="Location"
                       type="select"
                       variable="location_type"
                       options="Operating Room|Procedure Room|ICC|Radiology" />