The Forms API

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.

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, 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.

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

Name	Function	Called by
save.php	Save the passed in 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 report of the form contents pulled from the database (if applicable).	left_nav.php

php files to include

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.

forms written to use the encounters form API MAY use the following variables from 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/
$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']

Include	Used For
$GLOBALS['srcdir']/api.inc	acl_check()
$GLOBALS['srcdir']/options.inc.php	generate_form_field()
$GLOBALS['srcdir']/patient.inc

Functions Available

Function	from	reason	Returns
formFetch	library/api.inc	retrieve encounter based form contents from the sql engine	results of mysql_fetch_array
formSubmit	library/api.inc	save encounter based form contents to the sql engine
formJump	library/api.inc	redirect the browser to either the top of the current encounter, or an optional URL.
acl_check	$GLOBALS['srcdir']/api.inc	check access permissions
addForm	library/forms.inc	add a form to an encounter
sqlInsert	library/sql.inc	perform insert query	the id of the newly inserted row.
sqlStatement	library/sql.inc	perform query	result of mysql_query
sqlQuery	library/sql.inc	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.

The object oriented approach

Forms may also make use of objects OpenEMR provides, in order to utilize the smarty templating system.

Here are some notes for the object oriented case:

Given a form named "Complaint":

• FormComplaint.class.php is an object representing the complaint data and extending ORDataObject. Includes methods persist(), populate() and a bunch of getters and setters.
• C_FormComplaint.class.php extends Controller which extends Smarty. Instantiates FormComplaint as needed to perform its duties. Look at WellChild which does something with CPT codes here.
• templates/Complaint/general_new.html is a Smarty template. Its <form action> invokes save.php.
• new.php instantiates C_FormComplaint and invokes its default_action() which I think displays the Smarty template.
• view.php instantiates C_FormComplaint and invokes its view_action($id) which also seems to display the Smarty template.
• save.php instantiates C_FormComplaint and invokes its default_action_process($_POST) which presumably persists the data.
• report.php displays a report from the persisted form data. This is the ugly stuff in the upper encounter page.
• info.txt is a short 1-liner of the form's title.
• table.sql contains any required CREATE TABLE statements.

Non-object-oriented encounter forms have all the same files except for the .class.php files.