Breakpoints and Handlers

From FreemedDeveloperWiki, the FreeMED developers' Wiki.

Contents 1 Handlers 2 Associations 3 Setting Breakpoints 4 Setting Meta-Information 5 List of System Handlers and Breakpoints 5.1 Breakpoints 5.2 Handlers

Handlers

A handler is a case-sensitive, textual name, which allows modules to define dynamic portions of code to execute at a particular moment or event in code. The events are referred to as "breakpoints".

Associations

Associations are like handlers, except that they are for modules, not static code. For example, if you wanted to add a sub-record to episode of care, you would set an association with the episode of care module. When the module runs itself, it checks for associations, and performs the appropriate action(s).

Setting Breakpoints

To set a breakpoint in the system, call:

 freemed::handler_breakpoint( '(name of handler)', array ( [params] ) );

So for example,

 freemed::handler_breakpoint('PatientAdd', array ($pid));

is the statement in patient.php which calls the patient addition handlers. Notice that $pid is passed as a parameter, to allow the handler to be able to get data about its current operation without having to read any dodgy $GLOBAL or $_REQUEST variables.

Setting Meta-Information

Meta information is associated information for each module, usually required by a handler or association, to provide more information about the relationship between the handler or association and the code that will eventually call it.

Example for a module which is providing a Utility menu item (from the modules' constructor):

$this->_SetHandler('Utilities', 'utility');
$this->_SetMetaInformation('UtilityName', __("EMR Attachments"));
$this->_SetMetaInformation('UtilityDescription', __("Move EMR segments from one patient record to another."));

List of System Handlers and Breakpoints

Breakpoints

Handler	Parameters	Action
PatientAdd	patient id	Called whenever a patient has been added to the system, with the record id of the addition.
PatientDelete	patient id	Called before a patient is to be deleted from the system, with the record id of the patient's record.
PatientModify	patient id	Called whenever a patient has been modified in the system, with the record id of the patient's record.
Tickler	array($params)	Called via an external cron job. The hash of parameters passes information like: date - The date that this is running in YYYY-MM-DD, in case it needs to be overridden. interval - The interval of the cron job. Examples are "hourly", "daily", "weekly", et cetera.
UserAdd	user id	Called when a user is added to the system with the user's record id.
UserModify	user id	Called when a user is modified in the system with the user's record id.

Handlers

Handler	Returns	Action
AdminMenu	Textual output from the actual module function.	Adds an item to the Administration menu.
BillingFunctions	Textual output from the actual module function.	Adds an item to the Billing Functions menu. Requires BillingFunctionsName and BillingFunctionsDescription metadata to be set with $this->_SetMetaInformation().
MainMenu	Can return false if nothing, text, array (title, text), or array (title, text, icon path).	Shows main menu notification items in the main menu screen.
MainMenuNotify	Returns false if there is nothing to display (to avoid creating a null entry), or array(text, link) to add to the menu.	Creates the "Notify" menu entries in the menu to allow modules to display events to the user.
Utilities	Textual output from the actual module function.	Adds an item to the Utilities menu. Requires UtilityName and UtilityDescription metadata to be set with $this->_SetMetaInformation().