Difference between revisions of "The OpenEMR API"

From OpenEMR Project Wiki
(begin documenting proper escaping.)
m (fileroot, not webroot.)
 
(12 intermediate revisions by the same user not shown)
Line 19: Line 19:
! Variable
! Variable
! Used For
! Used For
! Default Value.
! Default Value
|-
|-
| $GLOBALS['athletic_team']
| $GLOBALS['athletic_team']
Line 36: Line 36:
| the path to the top of openemr in the filesystem.
| the path to the top of openemr in the filesystem.
| /var/www/openemr/
| /var/www/openemr/
|-
| $GLOBALS['OE_SITE_DIR']
| a per-site directory
|
|-
|-
| $GLOBALS['phone_country_code']
| $GLOBALS['phone_country_code']
Line 46: Line 50:
| $GLOBALS['srcdir']
| $GLOBALS['srcdir']
| find files for inclusion.
| find files for inclusion.
| $webserver_root/library/
| $GLOBALS['fileroot']/library/
|-
|-
| $GLOBALS['style']
| $GLOBALS['style']
|  
|  
|
|
|-
| $GLOBALS['temporary_files_dir']
| A directory on the server for storing temporary files outside of the web-visible space.
| /tmp (on *nix), or C:/windows/temp (on windows)
|-
|-
| $GLOBALS['webroot']
| $GLOBALS['webroot']
Line 69: Line 77:
! Use
! Use
! Reason for Depreciation
! Reason for Depreciation
! Replaced By
|-
|-
| $top_bg_line  
| $top_bg_line  
| colour selection.
| colour selection.
| the same function can be accomplished by editing the global openemr CSS stylesheet.
| The same function can be accomplished by editing the global openemr CSS stylesheet.
|-
|-
| $srcdir
| $srcdir
| find includes.
| find includes.
| replaced by $GLOBALS['srcdir']
| Globals in the lowercase namespace are deprecated.
| $GLOBALS['srcdir']
|-
| $incdir
| find interface.
| Globals in the lowercase namespace are deprecated.
| $GLOBALS['fileroot']/interface
|}
|}


Line 83: Line 98:


The following functions are common to use everywhere in OpenEMR:
The following functions are common to use everywhere in OpenEMR:
=== acl_check() ===
This function is used to check if a user has a given type or types of access to an ACO(access control object).
==== Parameters ====
A category/subcategory describing a the ACO to which permission is being requested, and optionally the type or types of permissions being requested.
==== Returns ====
TRUE or FALSE if a single permission is being checked, or an array of TRUE/FALSE values coresponding to the types of permission requested.
== auth.inc ==
auth.inc handles various functions, such as verification of the user's password, and implementing a timeout if the user has not been active in the interface.
It has a block of code starting at the begining of the file, that parses variables from the form submitted, and reacts accordingly. Important variables to note are:
=== skip_timeout_reset ===
Submit this item with your form to prevent the automatic timeout function from seeing your form as activity.
== formdata.inc.php ==
formdata.inc.php includes functionality for safely handling form data from the web browser, either via POST, GET, or from a cookie.
The preferred method of including formdata.inc.php is to use require_once. for instance: '''require_once($GLOBALS['srcdir'].'/formdata.inc.php');'''.
The following functions should be used in OpenEMR, in leiu using the _POST[], _GET[], and _REQUEST[] variables:


{| class="wikitable" border="1" cellpadding="1"
{| class="wikitable" border="1" cellpadding="1"
Line 91: Line 130:
! Returns
! Returns
|-
|-
| acl_check
| formData
| Check if a user has a given type or types of access to an access control object
| retrieve a variable from post, get, or cookie data submitted by the browser.
| A category/subcategory describing a specific ACO, and optionally, a username to check, and type or types of access being requested
| The name of the variable requested, the type of data stream to look for it in (post, get, or request), and whether to use trim() against the data.
| TRUE or FALSE if a single type of access is being checked, or an array of TRUE/FALSE values coresponding to the types of access requested
| A string containing the requested data, put through strip_escape_custom(), add_escape_custom() and (optionally) trim().
|}
|}


Line 165: Line 204:


= Notes API =
= Notes API =
The Notes API manages non-medical notes, attached to a client's medical record. see [[The Notes API]] for more information.
The Notes API manages non-medical notes, attached to a client's medical record. See [[The Notes API]] for more information.
 
= Reminders API =
The Reminders API manages reminders, which can be sent to ones self or others, and may have a patient associated with them. See [[The Reminders API]] for more information.

Latest revision as of 00:48, 6 January 2013

Overview

The OpenEMR API is divided into many modules, few of which have been documented.

There is presently a documentation project underway. please see OpenEMR API for an overview.

Core API

globals.php

globals.php defines a series of global variables, most of which are editable via the 'Administration->Globals' page.

The prefered method of including globals.php is to use require_once, providing a relative path from where your file is located, to interface/globals.php. for instance: require_once('../../globals.php');.

The following variables are common to use everywhere in OpenEMR:

Variable Used For Default Value
$GLOBALS['athletic_team'] True if we need to check squads. part of 'sports team' functionality. False
$GLOBALS['concurrent_layout'] decide on target of back action in a form. True or False
$GLOBALS['encounter'] the ID of the current encounter, or empty for none. is_numeric() or ""
$GLOBALS['fileroot'] the path to the top of openemr in the filesystem. /var/www/openemr/
$GLOBALS['OE_SITE_DIR'] a per-site directory
$GLOBALS['phone_country_code'] calendar code.
$GLOBALS['pid'] The unique identifier of the current patient. is_numeric(), or empty.
$GLOBALS['srcdir'] find files for inclusion. $GLOBALS['fileroot']/library/
$GLOBALS['style']
$GLOBALS['temporary_files_dir'] A directory on the server for storing temporary files outside of the web-visible space. /tmp (on *nix), or C:/windows/temp (on windows)
$GLOBALS['webroot'] the path of the top of openemr, when generating URIs. /openemr/
$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 Replaced By
$top_bg_line colour selection. The same function can be accomplished by editing the global openemr CSS stylesheet.
$srcdir find includes. Globals in the lowercase namespace are deprecated. $GLOBALS['srcdir']
$incdir find interface. Globals in the lowercase namespace are deprecated. $GLOBALS['fileroot']/interface

api.inc

The prefered method of including api.inc is to use require_once. for instance: require_once($GLOBALS['srcdir'].'/api.inc');.

The following functions are common to use everywhere in OpenEMR:

acl_check()

This function is used to check if a user has a given type or types of access to an ACO(access control object).

Parameters

A category/subcategory describing a the ACO to which permission is being requested, and optionally the type or types of permissions being requested.

Returns

TRUE or FALSE if a single permission is being checked, or an array of TRUE/FALSE values coresponding to the types of permission requested.

auth.inc

auth.inc handles various functions, such as verification of the user's password, and implementing a timeout if the user has not been active in the interface.

It has a block of code starting at the begining of the file, that parses variables from the form submitted, and reacts accordingly. Important variables to note are:

skip_timeout_reset

Submit this item with your form to prevent the automatic timeout function from seeing your form as activity.

formdata.inc.php

formdata.inc.php includes functionality for safely handling form data from the web browser, either via POST, GET, or from a cookie.

The preferred method of including formdata.inc.php is to use require_once. for instance: require_once($GLOBALS['srcdir'].'/formdata.inc.php');.

The following functions should be used in OpenEMR, in leiu using the _POST[], _GET[], and _REQUEST[] variables:

Function Use Accepts Returns
formData retrieve a variable from post, get, or cookie data submitted by the browser. The name of the variable requested, the type of data stream to look for it in (post, get, or request), and whether to use trim() against the data. A string containing the requested data, put through strip_escape_custom(), add_escape_custom() and (optionally) trim().

htmlspecialchars.inc.php

htmlspecialchars.inc.php includes functionality for handling escaping of characters in html received from the client, and stored in the database.

The preferred method of including htmlspecialchars.inc.php is to use require_once. for instance: require_once($GLOBALS['srcdir'].'/htmlspecialchars.inc.php');.

The following functions should be used in OpenEMR, in leiu of calling htmlspecialchars:

Function Use Accepts Returns
text Escape a PHP string for use as (part of) an HTML / XML text node. The string to escape, possibly including "&", "<", or ">". The string, with "&", "<", and ">" escaped.

patient.inc

patient.inc includes functions for manipulating patient information.

The preferred method of including patient.inc is to use require_once. for instance: require_once($GLOBALS['srcdir'].'/patient.inc');.

The following functions are common to use everywhere in OpenEMR:

Function Use Accepts Returns
getPatientData Get a patient's demographic data. A patient ID, and optionally a subsection of the patient's demographic data to retrieve. The requested subsection of a patient's demographic data. If no subsection was given, returns everything, with the date of birth as the last field.

sql.inc

sql.inc includes functions for manipulating the database directly. Please try to use one of the APIs and the built in functions for manipulating/retrieving your data, rather than always reaching for a SQL statement.

The preferred method of including sql.inc is to use require_once. for instance: require_once($GLOBALS['srcdir'].'/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

Forms API

The Forms API includes all of the functions required to create both per-encounter and non-encounter forms in the OpenEMR system. see The Forms API for more information.

Notes API

The Notes API manages non-medical notes, attached to a client's medical record. See The Notes API for more information.

Reminders API

The Reminders API manages reminders, which can be sent to ones self or others, and may have a patient associated with them. See The Reminders API for more information.