Difference between revisions of "The Forms API"

From OpenEMR Project Wiki
(simple cap and punctuation hanges.)
 
(56 intermediate revisions by 2 users not shown)
Line 1: Line 1:
=== The Files That Make Up Your Form ===
=== The Files That Make Up Your Form ===


A form using the Forms API of OpenEMR is in reality, a series of files on disk. These files are placed into a subdirectory of the interface/forms/ directory of your OpenEMR install.
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:
Forms written to use the Forms API MUST provide the following files:
{| class="wikitable" border="1" cellpadding="1"
{| class="wikitable" border="1" cellpadding="1"
Line 16: Line 17:
| view.php
| view.php
| Draw a form with data in it, allowing users to edit.
| Draw a form with data in it, allowing users to edit.
| selecting a form in an encounter, show.php
| selecting a form in an encounter, (optionally) show.php
|-
|-
| report.php
| report.php
Line 24: Line 25:
| table.sql  
| table.sql  
| Perform all of the SQL setup of the form (table creation, list insertion, etc)
| 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:
Forms written to use the encounters form API MAY provide the following files:
Line 33: Line 37:
! Function
! Function
! Called by
! 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.php
| Save the passed in form data to the database.
| Save the submitted form data to the database.
| new.php and view.php
| new.php and view.php
|-
|-
Line 43: Line 51:
|-
|-
| show.php
| show.php
| Show a report of the form contents pulled from the database (if applicable).
| Show a the most recent (and optionally signed) form of this type(if applicable).
| left_nav.php
| left_nav.php(with modifications)
|}
|}


=== php files to include ===
=== PHP Files to Include ===
 
==== Core APIs ====
For information about including the core APIs and using their functionality, please see [[The OpenEMR API]].


==== globals.php ====
===== 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.
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:
===== library/api.inc =====
{| class="wikitable" border="1" cellpadding="1"
This is the file defining the OpenEMR core APIs, including access controls, and the third party forms API.  
|-
! Variable
! Used For
! common value(s) or equivalance.
|-
| $GLOBALS['concurrent_layout']
| decide on target of back action.
|-
| $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.
====== Form Functions ======
{| class="wikitable" border="1" cellpadding="1"
{| class="wikitable" border="1" cellpadding="1"
|-
|-
! Variable
! Function
! Use
! 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']
|}
{| class="wikitable" border="1" cellpadding="1"
|-
! Include
! Used For
|-
| $GLOBALS['srcdir']/api.inc
| acl_check()
|-
| $GLOBALS['srcdir']/options.inc.php
| generate_form_field()
|-
| $GLOBALS['srcdir']/patient.inc
|}
=== Functions Available ===
{| class="wikitable" border="1" cellpadding="1"
|-
! Function
! from
! reason
! Returns
! Returns
|-
|-
| formFetch
| formFetch
| library/api.inc
| retrieve encounter based form contents from the sql engine
| retrieve encounter based form contents from the sql engine
| results of mysql_fetch_array
| results of mysql_fetch_array
|-
|-
| formSubmit
| formSubmit
| library/api.inc
| save encounter based form contents to the sql engine
| save encounter based form contents to the sql engine
|-
|-
| formJump
| formJump
| library/api.inc
| redirect the browser to either the top of the current encounter, or an optional URL.
| 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
|}
|}
==== library/options.inc.php ====
This file contains functions for rendering form objects.
===== Functions =====
* generate_form_field()
==== library/forms.inc ====
forms.inc contains the 'addForm' function, for linking a form into an encounter.


=== Files commonly referenced in HTML output ===
=== Files commonly referenced in HTML output ===
Line 215: Line 144:
|-
|-
| formFooter
| formFooter
|
| display a form footer
| 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:
[[Category:Developer Guide]][[Category:Forms]]
 
<?php echo $testvar; ?>
 
== Layout API ==
 
The layout API is usable by forms, who want to have their fields editable through the layouts editor.
 
{| class="wikitable" border="1" cellpadding="1"
|-
! 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.
|}

Latest revision as of 09:25, 8 December 2012

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

Core APIs

For information about including the core APIs and using their functionality, please see The OpenEMR API.

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.

library/api.inc

This is the file defining the OpenEMR core APIs, including access controls, and the third party forms API.

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

library/options.inc.php

This file contains functions for rendering form objects.

Functions
  • generate_form_field()

library/forms.inc

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

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
Retrieved from "https://www.open-emr.org/wiki/index.php?title=The_Forms_API&oldid=13129"