Image Based Forms

Documentation

This is documenting MI2's new image-based form API. Its an additional API similar to the 'object oriented' API that has been deprecated.

New Files

MI2's enhancement adds several files to OpenEMR, to allow form developers to write graphically intensive forms, marking a spot on the form, and associating that with a selection from a list AND a note. We're going to call this the 'image based' approach, to contrast it with the object-oriented approach (which this builds on), and the 'normal' approach.

C_AbstractClickmapModel.php

This file contains the C_AbstractClickmap class. This class extends the Controller class, which is used to control the smarty templating engine.

Variables

The C_AbstractClickmap class extends the Controller class by adding the following variables:

Variable	Use
template_dir	the directory the template file is stored in.

Functions

The C_AbstractClickmap class provides the following function members:

Function	Use
C_AbstractClickmap	Called upon object instantiation, to initialize the object. it calls the parent classes initializer, and sets the template_mod to the default. it then sets template_dir, and uses the parent's assign() function to set values for FORM_ACTION, DONT_SAVE_LINK, and STYLE.
createModel	Virtual placeholder for a public function, that returns an AbstractClickmapModel derived object (which we refer to elsewhere as Model). To be supplied later by the class deriving from this one.
getImage	Virtual placeholder for a function returning the path to the image backing the form, relative to the webroot, for use in an <img> tag in the generated html document. To be supplied later by the class deriving from this one.
getOptionsLabel	Virtual placeholder for a function returning the label to use for drop down boxes on this form. To be supplied later by the class deriving from this one.
getOptionsList	Virtual placeholder for a function returning a list of option=>value pairs to be used in dropdown boxes on this form. To be supplied later by the class deriving from this one.
set_context	This function sets up the passed in Model object to model the form. It initializes the passed in Model's saveAction, template_dir, image, optionlist, optionsLabel, data, and hideNav members.
default_action	This function is called in the case that we are creating a new form. It creates a Model, assigns the smarty value for 'form' from the model, calls set_context to set up the model, then returns the result of Controller's fetch() member, called to have smarty generate an html document from the template.
view_action	This function is called in the case that we are viewing/editing an existing form. It creates a Model passing in a form_id, assigns the smarty value for 'form' from the model, calls set_context to set up the model, then returns the result of Controller's fetch() member, called to have smarty generate an html document from the template.
report_action	This function is called in the case that we are rendering a form for a report. It creates a Model, assigns the smarty value for 'form' from the model, calls set_context to set up the model, disables the navigation items, then returns the result of Controller's fetch() member, called to have smarty generate an html document from the template.
default_action_process	This function is called in the case that we have had form contents submitted. It check to make sure there was a 'process' variable submitted with the form, creates a Model, calls this classes parent's populate_object to store all the form data in the Model. It then uses the Model's persist to store the contents to the database, and calls addform if the form isn't already part of this encounter.

AbstractClickmapModel.php

This file contains the AbstractClickmapModel class. This class extends the ORDataObject class, to model the contents of an image-based form.

Variables

The AbstractClickmapModel class extends the ORDataObject by adding the following variables:

Variable	Use
id	The unique identifier of the form to persist data to/from.
date	The date this form is being saved(?). Initialized to today's date.
pid	The unique identifier of the patient this form belongs to. Initialized to $GLOBALS['pid'].
user	Required field in database table. Not used, always defaulted to NULL.
groupname
authorized
activity
data	The contents of this form. Initialized to an empty value.

Functions

The AbstractClickmapModel class provides the following function members:

Function	Use
getTitle	This is a virtual function, provided later by the class extending this class. It's supposed to return the title of this form.
getCode	This is a virtual function, provided later by the class extending this class. It's supposed to return a string thats a 'code' for this form, or lowercase <FORMNAME>.
populate	Fill in this object's members with the contents from the database representing the stored form. This implementation just calls the parent's populate() member.
persist	Store the current structure members representing the form into the database. Again, this implementation just calls the parent's persist() member.

In addition to these, it provides pairs of get/set functions for setting each of the following variables. each of these functions is named either "set_<VARIABLE>" or "get_<VARIABLE>", where <VARIABLE> is the name of the variable being read/written.

Variable	Notes
id	The set function has a filter, and aborts if called with a non-numeric or empty value.
pid	The set function has a filter, and aborts if called with a non-numeric or empty value.
activity	The set function has a filter, and aborts if called with a non-numeric or empty value.
date	The set function has a filter, and aborts if called with an empty value.
user	The set function has a filter, and aborts if called with an empty value.
data	The set function has a filter, and aborts if called with an empty value.

Required or Conventional Behaviors of Form Code

When writing a form utilizing the new 'image based approach', the following is the typical structure and behaviors expected of the form.

C_Form<FORMNAME>.class.php

This file defines the C_Form<FORMNAME> object, where '<FORMNAME>' represents the name of the form. This object extends the C_AbstractClickmap object, from C_AbstractClickmap.php. It is expected to call its parent's initializer, and at a minimum define createModel, getImage, getOptionList and getOptionsLabel functions. This file is expected to include the Form<FORMNAME>.class.php file, so that createModel can instantiate the Form<FORMNAME> object.

createModel

createModel is called by C_AbstractClickmap's members to instantiate a Model object. createModel is expected to instantiate the Form<FORMNAME> class from Form<FORMNAME>.class.php, and return it as a Model.

getImage

getImage is expected to return the path to the backing image relative to the webroot.

getOptionsLabel

getOptionsLabel is supposed to return a label for the optionboxes on the form, as a string.

getOptionList

getOptionList is supposed to return a php array of key:value pairs, to be used as options in dropdown fields on this form.

Form<FORMNAME>.php

This file defines the Form<FORMNAME> class, instantiated to hold the form's data by C_Form<FORMNAME>.php. This class is an extension of the AbstractClickmapModel class. All real work is done in the AbstractClickModel class, with this class only containing variables and functions required for calling add_form. It is required to have a variable member for storing the table name, as well a initializer, a getTitle function, and a getCode function.

TABLE_NAME

The TABLE_NAME variable member stores the name of the table this form persists data in.

getTitle

getTitle is expected to return the FORM_TITLE from C_Form<FORMNAME> as a string, for use when calling add_form.

getCode

getCode is expected to return the FORM_CODE from _Form<FORMNAME> as a string, for use when calling add_form.

info.txt

info.txt is the same as in the normal approach, a file containing just a string naming this form.

new.php

This file is only required to include globals.php, api,inc, and our C_Form<FORMNAME>.php, instantiate the C_Form<FORMNAME> class, and call its default_action.

report.php

This file is only required to include globals.php, api,inc, and our C_Form<FORMNAME>.php, and provide a <FORMNAME>_report function. this function should instantiate the C_Form<FORMNAME> class, and call its report_action.

save.php

This file is only required to include globals.php, api,inc, and our C_Form<FORMNAME>.php, instantiate the C_Form<FORMNAME> class, and call its default_action_process member. Afterward, it should call @formJump() to jump back to the encounter interface.

table.sql

This file contains the SQL code adding the form's backing table to OpenEMR. As the backing tables for image based forms should likely be pretty much identical, i'm just going to quote the sql command below:

CREATE TABLE `form_pain` ( 
 `id` bigint(20) NOT NULL AUTO_INCREMENT,
 `date` datetime DEFAULT NULL,
 `pid` bigint(20) DEFAULT NULL,
 `user` varchar(255) DEFAULT NULL,
 `groupname` varchar(255) DEFAULT NULL,
 `authorized` tinyint(4) DEFAULT NULL,
 `activity` tinyint(4) DEFAULT NULL,
 `data` text DEFAULT '' NULL,
 PRIMARY KEY (`id`) 
) ENGINE=MyISAM DEFAULT CHARSET=utf8

view.php

This file is only required to include globals.php, api,inc, and our C_Form<FORMNAME>.php, instantiate the C_Form<FORMNAME> class, and call its view_action, passing in the id of the form to view.