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, with selections from an optionlist in random locations. 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. |
| template_mod | the name of the module, for the purposes of finding the template file. |
Functions
The C_AbstractClickmap class provides the following function members:
| Function | Use |
|---|---|
| createModel | Virtual placeholder for a public function, that creates a AbstractClickmapModel derived object (which we refer to 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 template. 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 makes 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 makes 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 makes 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's 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 this form. |
| 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 | |
| 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. its supposed to return the title of this form. |
| getCode | This is a virtual function, provided later by the class extending this class. |
| populate | Fill in the structure's members with the contents from the database representing the stored form. This implementatio just calls the parent's populate() member. |
| persist | Store the current structure members representing the form into the database. |
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 alling 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.
