Difference between revisions of "The Forms API"

From OpenEMR Project Wiki
(add how to require controller.)
(move the object oriented approach to the smarty page.)
Line 264: Line 264:
| draw a field in the 'show' view, AKA, the style of the history page.
| draw a field in the 'show' view, AKA, the style of the history page.
|}
|}
== 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.
=== PHP Files to Include ===
==== Controller.class.php ====
This file contains the Controller class. This class is used to generate HTML content from a template, and a series of values to interpolate within that template.
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');'''.
=== Required or Conventional Behaviors ===
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 populate 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.

Revision as of 04:42, 19 February 2011

The Files That Make Up Your Form

In order to implement a form, you provide a series of files. These files are placed into a subdirectory of the interface/forms/ directory of your OpenEMR install.

Required Files

Forms written to use the Forms API MUST provide the following files:

Name Function Called by
new.php Draw a form for users to input data into. dropdown box on right hand of encounters page
view.php Draw a form with data in it, allowing users to edit. selecting a form in an encounter, (optionally) show.php
report.php Draw part of a form displaying a simple 'report' of the form data. encounters.php and the medical records report function
table.sql Perform all of the SQL setup of the form (table creation, list insertion, etc) Executed by library/registry.inc's installSQL function, called when you hit the 'register' link for a form on the 'forms admin' page.

Optional Files

Other files can exist in your form's directory to provide additional funcionality, EG, a printing function, or a non-encounter form, or just to contain common code used by multiple files in your forms. the following is a list of common file names, and their functions (by convention).

Forms written to use the encounters form API MAY provide the following files:

Name Function Called by
info.txt A more user friendly name for your form. if present, displayed in forms admin page, and used as the name when referring to the form. library/registry.inc and interface/forms_admin/forms_admin.php
save.php Save the submitted form data to the database. new.php and view.php
print.php Print the current form, with the contents pulled from the database. view.php
show.php Show a the most recent (and optionally signed) form of this type(if applicable). left_nav.php(with modifications)

PHP Files to Include

interface/globals.php

Including globals.php (which is required) brings in many variables which are useful for finding components of openemr, or for inheriting the look and feel of other openemr code.

The preferred method of including globals.php from your form is to use require_once. for instance: require_once('../../globals.php');.

Variables

forms written to use the encounters form API MAY use the following variables after they have included global.php:

Variable Used For common value(s) or equivalance.
$GLOBALS['concurrent_layout'] decide on target of back action in a form. True or False
$GLOBALS['phone_country_code'] calendar code.
$GLOBALS['athletic_team'] not false if we need to check squads. part of 'sports team' functionality. True or False
$GLOBALS['fileroot'] the path to the top of openemr in the filesystem. /var/www/openemr/
$GLOBALS['webroot'] the path of the top of openemr, when generating URIs. /openemr/
$GLOBALS['srcdir'] find files for inclusion. /var/www/openemr/library/
$GLOBALS['pid'] The unique identifier of the current patient. is_numeric(), or empty.
$css_header include the global css stylesheet.
$tmore the text string that should be the label next to the page name, on a show form page.

The following variables are old, and depreciated.

Variable Use Reason for Depreciation
$top_bg_line colour selection. the same function can be accomplished by editing the global openemr CSS stylesheet.
$srcdir find includes. replaced by $GLOBALS['srcdir']

library/api.inc

This is the file defining the 3rd party forms API.

Functions
Function Use Returns
formFetch retrieve encounter based form contents from the sql engine results of mysql_fetch_array
formSubmit save encounter based form contents to the sql engine
formJump redirect the browser to either the top of the current encounter, or an optional URL.
acl_check check access permissions

library/options.inc.php

This file contains functions for rendering form objects.

Functions
  • generate_form_field()

library/patient.inc

library/forms.inc

forms.inc contains the 'addForm' function, for linking a form into an encounter.

library/sql.inc

Function Use Returns
sqlInsert perform insert query the id of the newly inserted row.
sqlStatement perform query result of mysql_query
sqlQuery perform query result of mysql_fetch_array

Files commonly referenced in HTML output

Referenced Used For
library/dialog.js
library/js/jquery.js jquery
library/textformat.js
$css_header the css theme of the site
../../forms/$form_folder/style.css the css theme of this form
library/dynarch_calendar.css the css theme of calendar objects
library/dynarch_calendar.js calendar base code
library/dynarch_calendar_en.js english calendar code
library/dynarch_calendar_setup.js


Depreciated:

Function From Reason Returns
formHeader display a header for the form.
html_header_show library/translation.inc.php NO-OP; depreciated
formFooter display a form footer

Style

when including a file, use 'require_once', or use 'include_once' and check the return!

all blocks of PHP code should start with '<?php', and end with '; ?>'. for example:

<?php echo $testvar; ?>

Layout API

The layout API is usable by forms, who want to have their fields editable through the layouts editor.

Function Include Source Reason Returns
display_layout_rows() library/api.inc library/options.inc.php display the given record in the view of the given layout
generate_form_field() library/api.inc library/options.inc.php draw a field in the 'view' view, AKA, the view/edit page.
generate_display_field() library/api.inc library/options.inc.php draw a field in the 'show' view, AKA, the style of the history page.
Retrieved from "https://www.open-emr.org/wiki/index.php?title=The_Forms_API&oldid=8691"