Smarty

WARNING

The usage of smarty in new openemr code is officially deprecated. This page is only meant to collect smarty resources, so that other developers know what they are doing, when touching smarty code in OpenEMR.

The object oriented approach

Forms may make use of objects OpenEMR provides, which utilize the smarty templating system. This approach is OLD and DEPRECATED, but is documented here for clarity, when maintaining code that uses this approach.

Special Smarty Variables

To use smarty's templating functionality, you set variables in smarty's space to values, that smarty either interpolates on your form, or interprets internally to generate templated content.

Variable	Use	typical value
DONT_SAVE_LINK	URL to link to when the user hits the "don't save" button/link.	/interface/patient_file/encounter/encounter_top.php or patient_encounter.php, depending on $GLOBALS['concurrent_layout']
FORM_ACTION	the 'submit' target in the generated HTML forms.
STYLE	stylesheet to inherit openemr global style settings from.	$GLOBALS['style']

PHP Files to Include

library/classes/Controller.class.php

This file contains the Controller class, deriving from the Smarty class. The Controller class is used to cause smarty to generate HTML content from a template, and a series of values to interpolate within that template.

Classes deriving from this class must call the classes initialization function, and set the classes template_mod member.

The preferred method of including Controller.class.php from your form is to use require_once. for instance: require_once($GLOBALS['srcdir'] . '/classes/Controller.class.php');.

Variables

Variable	Use	typical value
template_mod	Module to generate template from? Used to construct the first part of the template file name.	general

Functions

Function	Use
assign	Used to associate a variable in the smarty template with a string.
fetch	Used to generate the smarty template, interpolating assign()ed values.

library/classes/ORDataObject.class.php

This file contains the ORDataObject class. This class is used to model the data contained in a form, persisting it in a database as needed.

Variables

The OrDataObject has the following variable members:

Variable	Use
_table	The sql table that the form stores its values in.

Required or Conventional Behaviors of Form Code

When writing a form using the old 'object oriented approach', the following is the typical structure 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 Controller object, from Controller.class.php. It is expected to call Controller's initializer, and at a minimum define 'default_action', 'default_action_process', and 'view_action' functions. These three functions represent the three expected 'actions' to be performed against this form.

This file is expected to include the Form<FORMNAME>.class.php file, to instantiate the Form<FORMNAME> object as needed. the three action functions in this file are expected to instantiate and request population the Form<FORMNAME> object as needed.

default_action()

default_action is expected to instantiate a Form<FORMNAME> object, use the assign() function inherited from Controller to assign "data" to the new object, then call the inherited fetch function to request smarty render the given template.

view_action()

This function is responsible for drawing the form, filled in or not. To accomplish this, it is expected to instantiate a Form<FORMNAME> object, passing in a form_id if provided, so that the form will have contents when rendered. it should then call the inherited assign() function and the inherited fetch function to request smarty render the given template. in the case that no form_id was passed into this function, it should perform identically to the default_action().

default_action_process()

This function is responsible for saving the contents of a submitted form. To accomplish this, it is first expected to instantiate a Form<FORMNAME> object, passing in the submitted 'id' form data object. It should then use the parent's populate_object() function to populate the Form<FORMNAME> object with the submitted form data. you should then call the Form<FORMNAME>'s persist() function (FIXME: to save the form if its ID is set?). If $GLOBALS['encounter'] is not set, one should set it to date('Ymd'). If the ID value submitted in the html form is empty, you are set to call AddForm to add the form to the encounter.

Form<FORMNAME>.php

This file defines the Form<FORMNAME> object, instantiated to hold the form's data by C_Form<FORMNAME>.php. This object is an extension of the OrDataObject object. It is required to have variable members named id, date, pid, user, groupname, authorized, and activity, to hold required data for any form. the Form<FORMNAME> object needs to have function members for initialization, populate(), persist, and pairs of set_/get_ functions for setting and getting the values of each form data member, both the required ones, and the ones that are unique to this form. The initializer is required to set sane defaults to the id, date, activity, and pid variables. If the id passed in to the initializer is empty, you should call the populate() function. populate() should probably just call OrDataObject's populate. The form<FORMNAME> object's persist function should likely just call the persist provided by the OrDataObject, as well.

new.php

new.php instantiates C_Form<FORMNAME> and invokes its default_action() which is expected to display the Smarty template.

view.php

view.php instantiates C_Form<FORMNAME> and invokes its view_action(), passing in an id. this requests the display of the Smarty template with form data, if $id is not empty.

save.php

save.php instantiates C_Form<FORMNAME> and invokes its default_action_process($_POST) which saves submitted form data to the form's table.

report.php

report.php displays a report from the saved form data, in the form's SQL table. This report is displayed in the encounter page, as a summary of the form's contents. this file is expected to perform its task the same way as the normal approach.