civicrm/civicrm-core — pull request #1454 by pdelbar (2013-08-17 08:19:39+00:00)
Title: refactored schedule reminders to indtroduce extension hook

# Why

Sometimes, you need to use the handy schedule reminders to send out emails containing additional info, currently not made available in the core code. The idea is to make this open and extendible.

# How

This change introduces a new hook (mod Utils/Hook.php) and refactors the ActionSchedule to allow different types of additional tokens to be added before the email message is composed :

* tokens you can add directly, regardless of the context of the reminder
* tokens depending on data you prefer to include in the original data query
* tokens you may want to add based on data returned by the current query.

Example of a hook which does this:

```
function mymodule_civicrm_getReminderTokens($mapping, $op, &$more) {
$ent = $mapping->entity;
CRM_Core_Session::setStatus('Mymodule's getReminderTokens hook is called !');
if ($mapping->entity == 'civicrm_membership') {
switch ($op) {
case 'pre' :
//
// one way of adding tokens is adding them directly to the tokens array
// mind: use a prefix !
//
$more->tokens = array(
'membership.boo' => 'Boo !',
'mydomain.burp' => 'Scuze me !',
);

//
// it is possible to amend the selection query, for instance to add
// a custom field
// mind: you need to take a look at BAO/ActionSchedule.php to unerstand how to join these !
//
$more->extraJoins[] = 'INNER JOIN civicrm_value_testing_custom_4 cmt ON cmt.entity_id = reminder.entity_id';
$more->extraFields['widgetizement'] = 'cmt.widgetizement_7 as widgetizement';

break;

case 'post' :
//
// in the post hook, we can access the resulting dao, and once again
// add tokens based on any of this info
//
$dao = $more->dao;
$joined = strtotime($dao->join_date);
$more->tokens[ 'membership.mydate' ] = date('d_m_YY',$joined);

break;
}
}
}
```

# Open issues

Currently, you can only work on existing entities. I am working on a fix to ActionSchedule:getSelection* to include that into the hook as well, so the UI automatically picks up the additional action_mappings (to be installed with the module/extension) and drive the UI accordingly. Nonetheless, this extension is useful without the changes to this method.