* @package etemplate * @subpackage api * @copyright (c) 2007-12 by Ralf Becker * @license http://opensource.org/licenses/gpl-license.php GPL - GNU General Public License * @version $Id$ */ /** * Abstract base class for trackering: * - logging all modifications of an entry * - notifying users about changes in an entry * * You need to extend these class in your application: * 1. set the required class-vars: app, id_field * 2. optional set class-vars: creator_field, assigned_field, check2prefs * 3. implement the required methods: get_config, get_details * 4. optionally re-implement: get_title, get_subject, get_body, get_attachments, get_link, get_notification_link, get_message * They are all documented in this file via phpDocumentor comments. * * Translate field-name to history status field: * As history status was only char(2) prior to EGroupware 1.6, a mapping was necessary. * Now it's varchar(64) and a mapping makes no sense for new applications, just list * all fields to log as key AND value! * * History login supports now 1:N relations on a base record. To use that you need: * - to have the 1:N relation as array of arrays with the values of that releation, eg: * $data = array( * 'id' => 123, * 'title' => 'Something', * 'date' => '2009-08-21 14:42:00', * 'participants' => array( * array('account_id' => 15, 'name' => 'User Hugo', 'status' => 'A', 'quantity' => 1), * array('account_id' => 17, 'name' => 'User Bert', 'status' => 'U', 'quantity' => 3), * ), * ); * - set field2history as follows * $field2history = array( * 'id' => 'id', * 'title' => 'title', * 'participants' => array('uid','status','quantity'), * ); * - set content for history log widget: * $content['history'] = array( * 'id' => 123, * 'app' => 'calendar', * 'status-widgets' => array( * 'title' => 'label', // no need to set, as default is label * 'date' => 'datetime', * 'participants' = array( * 'select-account', * array('U' => 'Unknown', 'A' => 'Accepted', 'R' => 'Rejected'), * 'integer', * ), * ), * ); * - set lables for history: * $sel_options['status'] = array( * 'title' => 'Title', * 'date' => 'Starttime', * 'participants' => 'Participants: User, Status, Quantity', // a single label! * ); * * The above is also an example for using regular history login in EGroupware (by skipping the 'participants' key). */ abstract class bo_tracking { /** * Application we are tracking * * @var string */ var $app; /** * Name of the id-field, used as id in the history log (required!) * * @var string */ var $id_field; /** * Name of the field with the creator id, if the creator of an entry should be notified * * @var string */ var $creator_field; /** * Name of the field with the id(s) of assinged users, if they should be notified * * @var string */ var $assigned_field; /** * Can be used to map the following prefs to different names: * - notify_creator - user wants to be notified for items he created * - notify_assigned - user wants to be notified for items assigned to him * @var array */ var $check2pref; /** * Translate field-name to history status field (see comment in class header) * * @var array */ var $field2history = array(); /** * Should the user (passed to the track method or current user if not passed) be used as sender or get_config('sender') * * @var boolean */ var $prefer_user_as_sender = true; /** * Should the current user be email-notified (about change he made himself) * * Popup notifications are never send to the current user! * * @var boolean */ var $notify_current_user = false; /** * Array with error-messages if track($data,$old) returns false * * @var array */ var $errors = array(); /** * instance of the historylog object for the app we are tracking * * @access private * @var historylog */ var $historylog; /** * Current user, can be set via bo_tracking::track(,,$user) * * @access private * @var int; */ var $user; /** * Saved user preferences, if send_notifications need to set an other language * * @access private * @var array */ var $save_prefs; /** * Datetime format of the currently notified user (send_notificaton) * * @var string */ var $datetime_format; /** * Should the class allow html content (for notifications) * * @var boolean */ var $html_content_allow = false; /** * Custom fields of type link entry or application * * Used to automatic create or update a link * * @var array field => application name pairs (or empty for link entry) */ var $cf_link_fields = array(); /** * Separator for 1:N relations * */ const ONE2N_SEPERATOR = '~|~'; /** * Config name for custom notification message */ const CUSTOM_NOTIFICATION = 'custom_notification'; /** * Constructor * * @param string $cf_app=null if set, custom field names get added to $field2history * @return bo_tracking */ function __construct($cf_app = null) { if ($cf_app) { $linkable_cf_types = array('link-entry')+array_keys(egw_link::app_list()); foreach(config::get_customfields($cf_app, true) as $cf_name => $cf_data) { $this->field2history['#'.$cf_name] = '#'.$cf_name; if (in_array($cf_data['type'],$linkable_cf_types)) { $this->cf_link_fields['#'.$cf_name] = $cf_data['type'] == 'link-entry' ? '' : $cf_data['type']; } } } } function bo_tracking() { self::__construct(); } /** * Get the details of an entry * * You can/should call $this->get_customfields() to add custom fields. * * @param array|object $data * @param int|string $receiver nummeric account_id or email address * @return array of details as array with values for keys 'label','value','type' */ function get_details($data,$receiver=null) { return array(); } /** * Get custom fields of an entry of an entry * * @param array|object $data * @param string $only_type2=null if given only return fields of type2 == $only_type2 * @return array of details as array with values for keys 'label','value','type' */ function get_customfields($data, $only_type2=null) { $details = array(); if (($cfs = config::get_customfields($this->app, $all_private_too=false, $only_type2))) { $header_done = false; foreach($cfs as $name => $field) { if (in_array($field['type'], customfields_widget::$non_printable_fields)) continue; if (!$header_done) { $details['custom'] = array( 'value' => lang('Custom fields').':', 'type' => 'reply', ); $header_done = true; } //error_log(__METHOD__."() $name: data['#$name']=".array2string($data['#'.$name]).", field[values]=".array2string($field['values'])); $details['#'.$name] = array( 'label' => $field['label'], 'value' => customfields_widget::format_customfield($field, $data['#'.$name]), ); //error_log("--> details['#$name']=".array2string($details['#'.$name])); } } return $details; } /** * Get a config value, which can depend on $data and $old * * Need to be implemented in your extended tracking class! * * @param string $what possible values are: * - 'copy' array of email addresses notifications should be copied too, can depend on $data * - 'lang' string lang code for copy mail * - 'subject' string subject line for the notification of $data,$old, defaults to link-title * - 'link' string of link to view $data * - 'sender' sender of email * - 'skip_notify' array of email addresses that should _not_ be notified * - CUSTOM_NOTIFICATION string notification body message. Merge print placeholders are allowed. * @param array $data current entry * @param array $old=null old/last state of the entry or null for a new entry * @return mixed */ protected function get_config($name,$data,$old=null) { return null; } /** * Tracks the changes in one entry $data, by comparing it with the last version in $old * * @param array $data current entry * @param array $old=null old/last state of the entry or null for a new entry * @param int $user=null user who made the changes, default to current user * @param boolean $deleted=null can be set to true to let the tracking know the item got deleted or undeleted * @param array $changed_fields=null changed fields from ealier call to $this->changed_fields($data,$old), to not compute it again * @param boolean $skip_notification=false do NOT send any notification * @return int|boolean false on error, integer number of changes logged or true for new entries ($old == null) */ public function track(array $data,array $old=null,$user=null,$deleted=null,array $changed_fields=null,$skip_notification=false) { $this->user = !is_null($user) ? $user : $GLOBALS['egw_info']['user']['account_id']; $changes = true; //error_log(__METHOD__.__LINE__); if ($old && $this->field2history) { //error_log(__METHOD__.__LINE__.' Changedfields:'.print_r($changed_fields,true)); $changes = $this->save_history($data,$old,$deleted,$changed_fields); //error_log(__METHOD__.__LINE__.' Changedfields:'.print_r($changed_fields,true)); //error_log(__METHOD__.__LINE__.' Changes:'.print_r($changes,true)); } //error_log(__METHOD__.__LINE__.' LinkFields:'.array2string($this->cf_link_fields)); if ($changes && $this->cf_link_fields) { $this->update_links($data,(array)$old); } // do not run do_notifications if we have no changes if ($changes && !$skip_notification && !$this->do_notifications($data,$old,$deleted)) { $changes = false; } return $changes; } /** * Store a link for each custom field linking to an other application and update them * * @param array $data * @param array $old */ protected function update_links(array $data, array $old) { //error_log(__METHOD__.__LINE__.array2string($data).function_backtrace()); //error_log(__METHOD__.__LINE__.array2string($this->cf_link_fields)); foreach((array)$this->cf_link_fields as $name => $val) { //error_log(__METHOD__.__LINE__.' Field:'.$name. ' Value (new):'.array2string($data[$name])); //error_log(__METHOD__.__LINE__.' Field:'.$name. ' Value (old):'.array2string($old[$name])); if (is_array($data[$name]) && array_key_exists('id',$data[$name])) $data[$name] = $data[$name]['id']; if (is_array($old[$name]) && array_key_exists('id',$old[$name])) $old[$name] = $old[$name]['id']; //error_log(__METHOD__.__LINE__.'(After processing) Field:'.$name. ' Value (new):'.array2string($data[$name])); //error_log(__METHOD__.__LINE__.'(After processing) Field:'.$name. ' Value (old):'.array2string($old[$name])); } $current_ids = array_unique(array_diff(array_intersect_key($data,$this->cf_link_fields),array('',0,NULL))); $old_ids = $old ? array_unique(array_diff(array_intersect_key($old,$this->cf_link_fields),array('',0,NULL))) : array(); //error_log(__METHOD__.__LINE__.array2string($current_ids)); //error_log(__METHOD__.__LINE__.array2string($old_ids)); // create links for added application entry foreach(array_diff($current_ids,$old_ids) as $name => $id) { if (!($app = $this->cf_link_fields[$name])) { list($app,$id) = explode(':',$id); if (!$id) continue; // can be eg. 'addressbook:', if no contact selected } $source_id = $data[$this->id_field]; //error_log(__METHOD__.__LINE__.array2string($source_id)); if ($source_id) egw_link::link($this->app,$source_id,$app,$id); //error_log(__METHOD__.__LINE__."egw_link::link('$this->app',".array2string($source_id).",'$app',$id);"); //echo "

egw_link::link('$this->app',{$data[$this->id_field]},'$app',$id);

\n"; } // unlink removed application entries foreach(array_diff($old_ids,$current_ids) as $name => $id) { if (!isset($data[$name])) continue; // ignore not set link cf's, eg. from sync clients if (!($app = $this->cf_link_fields[$name])) { list($app,$id) = explode(':',$id); if (!$id) continue; } $source_id = $data[$this->id_field]; if ($source_id) egw_link::unlink(null,$this->app,$source_id,0,$app,$id); //echo "

egw_link::unlink(NULL,'$this->app',{$data[$this->id_field]},0,'$app',$id);

\n"; } } /** * Save changes to the history log * * @internal use only track($data,$old) * @param array $data current entry * @param array $old=null old/last state of the entry or null for a new entry * @param boolean $deleted=null can be set to true to let the tracking know the item got deleted or undelted * @param array $changed_fields=null changed fields from ealier call to $this->changed_fields($data,$old), to not compute it again * @return int number of log-entries made */ protected function save_history(array $data,array $old=null,$deleted=null,array $changed_fields=null) { //error_log(__METHOD__.__LINE__.' Changedfields:'.array2string($changed_fields)); if (is_null($changed_fields)) { $changed_fields = self::changed_fields($data,$old); //error_log(__METHOD__.__LINE__.' Changedfields:'.array2string($changed_fields)); } if (!$changed_fields) return 0; if (!is_object($this->historylog) || $this->historylog->user != $this->user) { $this->historylog = new historylog($this->app,$this->user); } foreach($changed_fields as $name) { $status = isset($this->field2history[$name]) ? $this->field2history[$name] : $name; //error_log(__METHOD__.__LINE__." Name $name,".' Status:'.array2string($status)); if (is_array($status)) // 1:N relation --> remove common rows { //error_log(__METHOD__.__LINE__.' is Array'); self::compact_1_N_relation($data[$name],$status); self::compact_1_N_relation($old[$name],$status); $added = array_values(array_diff($data[$name],$old[$name])); $removed = array_values(array_diff($old[$name],$data[$name])); $n = max(array(count($added),count($removed))); for($i = 0; $i < $n; ++$i) { //error_log(__METHOD__."() $i: historylog->add('$name',data['$this->id_field']={$data[$this->id_field]},".array2string($added[$i]).','.array2string($removed[$i])); $this->historylog->add($name,$data[$this->id_field],$added[$i],$removed[$i]); } } else { //error_log(__METHOD__.__LINE__.' IDField:'.array2string($this->id_field).' ->'.$data[$this->id_field].' New:'.$data[$name].' Old:'.$old[$name]); $this->historylog->add($status,$data[$this->id_field], is_array($data[$name]) ? implode(',',$data[$name]) : $data[$name], is_array($old[$name]) ? implode(',',$old[$name]) : $old[$name]); } } //error_log(__METHOD__.__LINE__.' return:'.count($changed_fields)); return count($changed_fields); } /** * Compute changes between new and old data * * Can be used to check if saving the data is really necessary or user just pressed save * * @param array $data * @param array $old=null * @return array of keys with different values in $data and $old */ public function changed_fields(array $data,array $old=null) { if (is_null($old)) return array_keys($data); $changed_fields = array(); foreach($this->field2history as $name => $status) { if (!$old[$name] && !$data[$name]) continue; // treat all sorts of empty equally if ($name[0] == '#' && !isset($data[$name])) continue; // no set customfields are not stored, therefore not changed if (is_array($status)) // 1:N relation { self::compact_1_N_relation($data[$name],$status); self::compact_1_N_relation($old[$name],$status); } if ($old[$name] != $data[$name]) { // normalize arrays, we do NOT care for the order of multiselections if (is_array($data[$name]) || is_array($old[$name])) { if (!is_array($data[$name])) $data[$name] = explode(',',$data[$name]); if (!is_array($old[$name])) $old[$name] = explode(',',$old[$name]); if (count($data[$name]) == count($old[$name])) { sort($data[$name]); sort($old[$name]); if ($data[$name] == $old[$name]) continue; } } $changed_fields[] = $name; //echo "

$name: ".array2string($data[$name]).' != '.array2string($old[$name])."

\n"; } } foreach($data as $name => $value) { if ($name[0] == '#' && $name[1] == '#' && $value !== $old[$name]) { $changed_fields[] = $name; } } //error_log(__METHOD__."() changed_fields=".array2string($changed_fields)); return $changed_fields; } /** * Compact (spezified) fields of a 1:N relation into an array of strings * * @param array &$rows rows of the 1:N relation * @param array $cols field names as values */ private static function compact_1_N_relation(&$rows,array $cols) { if (is_array($rows)) { foreach($rows as $key => &$row) { $values = array(); foreach($cols as $col) { $values[] = $row[$col]; } $row = implode(self::ONE2N_SEPERATOR,$values); } } else { $rows = array(); } } /** * sending all notifications for the changed entry * * @internal use only track($data,$old,$user) * @param array $data current entry * @param array $old=null old/last state of the entry or null for a new entry * @param boolean $deleted=null can be set to true to let the tracking know the item got deleted or undelted * @param array $email_notified=null if present will return the emails notified, if given emails in that list will not be notified * @return boolean true on success, false on error (error messages are in $this->errors) */ public function do_notifications($data,$old,$deleted=null,&$email_notified=null) { $this->errors = $email_sent = array(); if (!empty($email_notified) && is_array($email_notified)) $email_sent = $email_notified; if (!$this->notify_current_user && $this->user) // do we have a current user and should we notify the current user about his own changes { //error_log("do_notificaton() adding user=$this->user to email_sent, to not notify him"); $email_sent[] = $GLOBALS['egw']->accounts->id2name($this->user,'account_email'); } $skip_notify = $this->get_config('skip_notify',$data,$old); if($skip_notify && is_array($skip_notify)) { $email_sent = array_merge($email_sent, $skip_notify); } // entry creator if ($this->creator_field && ($email = $GLOBALS['egw']->accounts->id2name($data[$this->creator_field],'account_email')) && !in_array($email, $email_sent)) { if ($this->send_notification($data,$old,$email,$data[$this->creator_field],'notify_creator')) { $email_sent[] = $email; } } // members of group when entry owned by group if ($this->creator_field && $GLOBALS['egw']->accounts->get_type($data[$this->creator_field]) == 'g') { foreach($GLOBALS['egw']->accounts->members($data[$this->creator_field],true) as $u) { if (($email = $GLOBALS['egw']->accounts->id2name($u,'account_email')) && !in_array($email, $email_sent)) { if ($this->send_notification($data,$old,$email,$u,'notify_owner_group_member')) { $email_sent[] = $email; } } } } // assigned / responsible users if ($this->assigned_field) { //error_log("bo_tracking::do_notifications() data[$this->assigned_field]=".print_r($data[$this->assigned_field],true).", old[$this->assigned_field]=".print_r($old[$this->assigned_field],true)); $assignees = $old_assignees = array(); if ($data[$this->assigned_field]) // current assignments { $assignees = is_array($data[$this->assigned_field]) ? $data[$this->assigned_field] : explode(',',$data[$this->assigned_field]); } if ($old && $old[$this->assigned_field]) { $old_assignees = is_array($old[$this->assigned_field]) ? $old[$this->assigned_field] : explode(',',$old[$this->assigned_field]); } foreach(array_unique(array_merge($assignees,$old_assignees)) as $assignee) { //error_log("bo_tracking::do_notifications() assignee=$assignee, type=".$GLOBALS['egw']->accounts->get_type($assignee).", email=".$GLOBALS['egw']->accounts->id2name($assignee,'account_email')); if (!$assignee) continue; // item assignee is a user if ($GLOBALS['egw']->accounts->get_type($assignee) == 'u') { if (($email = $GLOBALS['egw']->accounts->id2name($assignee,'account_email')) && !in_array($email, $email_sent)) { if ($this->send_notification($data,$old,$email,$assignee,'notify_assigned', in_array($assignee,$assignees) !== in_array($assignee,$old_assignees) || $deleted)) // assignment changed { $email_sent[] = $email; } } } else // item assignee is a group { foreach($GLOBALS['egw']->accounts->members($assignee,true) as $u) { if (($email = $GLOBALS['egw']->accounts->id2name($u,'account_email')) && !in_array($email, $email_sent)) { if ($this->send_notification($data,$old,$email,$u,'notify_assigned', in_array($u,$assignees) !== in_array($u,$old_assignees) || $deleted)) // assignment changed { $email_sent[] = $email; } } } } } } // notification copies if (($copies = $this->get_config('copy',$data,$old))) { $lang = $this->get_config('lang',$data,$old); foreach($copies as $email) { if (strchr($email,'@') !== false && !in_array($email, $email_sent)) { if ($this->send_notification($data,$old,$email,$lang,'notify_copy')) { $email_sent[] = $email; } } } } // restore the user enviroment if ($this->save_prefs) { $GLOBALS['egw_info']['user'] = $this->save_prefs; // need to call preferences constructor and read_repository, to set user timezone again $GLOBALS['egw']->preferences->__construct($GLOBALS['egw_info']['user']['account_id']); $GLOBALS['egw_info']['user']['preferences'] = $GLOBALS['egw']->preferences->read_repository(false); // no session prefs! unset($this->save_prefs); } if ($GLOBALS['egw_info']['user']['preferences']['common']['lang'] != translation::$userlang) { translation::init(); } $email_notified = $email_sent; return !count($this->errors); } /** * Sending a notification to the given email-address * * Called by track() or externally for sending async notifications * * @param array $data current entry * @param array $old=null old/last state of the entry or null for a new entry * @param string $email address to send the notification to * @param string $user_or_lang='en' user-id or 2 char lang-code for a non-system user * @param string $check=null pref. to check if a notification is wanted * @param boolean $assignment_changed=true the assignment of the user $user_or_lang changed * @param boolean $deleted=null can be set to true to let the tracking know the item got deleted or undelted * @return boolean true on success or false if notification not requested or error (error-message is in $this->errors) */ public function send_notification($data,$old,$email,$user_or_lang,$check=null,$assignment_changed=true,$deleted=null) { //error_log(__METHOD__."(,,'$email',$user_or_lang,$check,$assignment_changed,$deleted)"); if (!$email) return false; if (!$this->save_prefs) $this->save_prefs = $GLOBALS['egw_info']['user']; if (is_numeric($user_or_lang)) // user --> read everything from his prefs { $GLOBALS['egw']->preferences->__construct($user_or_lang); $GLOBALS['egw_info']['user']['preferences'] = $GLOBALS['egw']->preferences->read_repository(false); // no session prefs! if ($check && $this->check2pref) $check = $this->check2pref[$check]; if ($check && !$GLOBALS['egw_info']['user']['preferences'][$this->app][$check]) { return false; // no notification requested } if ($check && $GLOBALS['egw_info']['user']['preferences'][$this->app][$check] === 'assignment' && !$assignment_changed) { return false; // only notification about changed assignment requested } if($this->user == $user_or_lang && !$this->notify_current_user) { return false; // no popup for own actions } } else { // for the notification copy, we use default (and forced) prefs plus the language from the the tracker config $GLOBALS['egw_info']['user']['preferences'] = $GLOBALS['egw']->preferences->default_prefs(); $GLOBALS['egw_info']['user']['preferences']['common']['lang'] = $user_or_lang; } if ($GLOBALS['egw_info']['user']['preferences']['common']['lang'] != translation::$userlang) // load the right language if needed { translation::init(); } // send over notification_app if ($GLOBALS['egw_info']['apps']['notifications']['enabled']) { // send via notification_app $receiver = is_numeric($user_or_lang) ? $user_or_lang : $email; try { $notification = new notifications(); $notification->set_receivers(array($receiver)); $notification->set_message($this->get_body(false,$data,$old,false,$receiver)); // set message as plaintext $notification->set_message($this->get_body(true,$data,$old,false,$receiver)); // and html $notification->set_sender($this->get_sender($data,$old,true,$receiver)); $notification->set_subject($this->get_subject($data,$old,$deleted,$receiver)); $notification->set_links(array($this->get_notification_link($data,$old,$receiver))); if (($attachments = $this->get_attachments($data,$old,$receiver)) && is_array($attachments)) { $notification->set_attachments($attachments); } $notification->send(); } catch (Exception $exception) { $this->errors[] = $exception->getMessage(); return false; } } else { error_log('tracking: cannot send any notifications because notifications is not installed'); } return true; } /** * Return date+time formatted for the currently notified user (prefs in $GLOBALS['egw_info']['user']['preferences']) * * @param int|string|DateTime $timestamp in server-time * @param boolean $do_time=true true=allways (default), false=never print the time, null=print time if != 00:00 * * @return string */ public function datetime($timestamp,$do_time=true) { if (!is_a($timestamp,'DateTime')) { $timestamp = new egw_time($timestamp,egw_time::$server_timezone); } $timestamp->setTimezone(egw_time::$user_timezone); if (is_null($do_time)) { $do_time = ($timestamp->format('Hi') != '0000'); } $format = $GLOBALS['egw_info']['user']['preferences']['common']['dateformat']; if ($do_time) $format .= ' '.($GLOBALS['egw_info']['user']['preferences']['common']['timeformat'] != 12 ? 'H:i' : 'h:i a'); return $timestamp->format($format); } /** * Get sender address * * The default implementation prefers depending on the prefer_user_as_sender class-var the user over * what is returned by get_config('sender'). * * @param int $user account_lid of user * @param array $data * @param array $old * @param bool $prefer_id returns the userid rather than email * @param int|string $receiver nummeric account_id or email address * @return string or userid */ protected function get_sender($data,$old,$prefer_id=false,$receiver=null) { $sender = $this->get_config('sender',$data,$old); //echo "

bo_tracking::get_sender() get_config('sender',...)='".htmlspecialchars($sender)."'

\n"; if (($this->prefer_user_as_sender || !$sender) && $this->user && ($email = $GLOBALS['egw']->accounts->id2name($this->user,'account_email'))) { $name = $GLOBALS['egw']->accounts->id2name($this->user,'account_fullname'); if($prefer_id) { $sender = $this->user; } else { $sender = $name ? $name.' <'.$email.'>' : $email; } } elseif(!$sender) { $sender = 'eGroupWare '.lang($this->app).' '; } //echo "

bo_tracking::get_sender()='".htmlspecialchars($sender)."'

\n"; return $sender; } /** * Get the title for a given entry, can be reimplemented * * @param array $data * @param array $old * @return string */ protected function get_title($data,$old) { return egw_link::title($this->app,$data[$this->id_field]); } /** * Get the subject for a given entry, can be reimplemented * * Default implementation uses the link-title * * @param array $data * @param array $old * @param boolean $deleted=null can be set to true to let the tracking know the item got deleted or undelted * @param int|string $receiver nummeric account_id or email address * @return string */ protected function get_subject($data,$old,$deleted=null,$receiver=null) { return egw_link::title($this->app,$data[$this->id_field]); } /** * Get the modified / new message (1. line of mail body) for a given entry, can be reimplemented * * Default implementation does nothing * * @param array $data * @param array $old * @param int|string $receiver nummeric account_id or email address * @return string */ protected function get_message($data,$old,$receiver=null) { return ''; } /** * Get a link to view the entry, can be reimplemented * * Default implementation checks get_config('link') (appending the id) or link::view($this->app,$id) * * @param array $data * @param array $old * @param string $allow_popup=false if true return array(link,popup-size) incl. session info an evtl. partial url (no host-part) * @param int|string $receiver nummeric account_id or email address * @return string|array string with link (!$allow_popup) or array(link,popup-size), popup size is something like '640x480' */ protected function get_link($data,$old,$allow_popup=false,$receiver=null) { if (($link = $this->get_config('link',$data,$old))) { if (strpos($link,$this->id_field.'=') === false && isset($data[$this->id_field])) { $link .= strpos($link,'?') === false ? '?' : '&'; $link .= $this->id_field.'='.$data[$this->id_field]; } } else { if (($view = egw_link::view($this->app,$data[$this->id_field]))) { $link = $GLOBALS['egw']->link('/index.php',$view); $popup = egw_link::is_popup($this->app,'view'); } } if ($link[0] == '/') { $link = ($_SERVER['HTTPS'] || $GLOBALS['egw_info']['server']['enforce_ssl'] ? 'https://' : 'http://'). ($GLOBALS['egw_info']['server']['hostname'] ? $GLOBALS['egw_info']['server']['hostname'] : $_SERVER['HTTP_HOST']).$link; } if (!$allow_popup) { // remove the session-id in the notification mail! $link = preg_replace('/(sessionid|kp3|domain)=[^&]+&?/','',$link); if ($popup) $link .= '&nopopup=1'; } //error_log(__METHOD__."(..., $allow_popup, $receiver) returning ".array2string($allow_popup ? array($link,$popup) : $link)); return $allow_popup ? array($link,$popup) : $link; } /** * Get a link for notifications to view the entry, can be reimplemented * * @param array $data * @param array $old * @param int|string $receiver nummeric account_id or email address * @return array with link */ protected function get_notification_link($data,$old,$receiver=null) { if (($view = egw_link::view($this->app,$data[$this->id_field]))) { return array( 'text' => $this->get_title($data,$old), 'view' => $view, 'popup' => egw_link::is_popup($this->app,'view'), ); } return false; } /** * Get the body of the notification message, can be reimplemented * * @param boolean $html_email * @param array $data * @param array $old * @param boolean $integrate_link to have links embedded inside the body * @param int|string $receiver nummeric account_id or email address * @return string */ public function get_body($html_email,$data,$old,$integrate_link = true,$receiver=null) { $body = ''; if($this->get_config(self::CUSTOM_NOTIFICATION, $data, $old)) { $body = $this->get_custom_message($data,$old); if($html_email) { $body = nl2br($body); } if($sig = $this->get_signature($data,$old,$receiver)) { $body .= ($html_email ? '
':'') . "\n$sig"; } return $body; } if ($html_email) { $body = ''."\n"; } // new or modified message if (($message = $this->get_message($data,$old,$receiver))) { $body .= $this->format_line($html_email,'message',false,$message); } if ($integrate_link && ($link = $this->get_link($data,$old,false,$receiver))) { $body .= $this->format_line($html_email,'link',false,$integrate_link === true ? lang('You can respond by visiting:') : $integrate_link,$link); } foreach($this->get_details($data,$receiver) as $name => $detail) { // if there's no old entry, the entry is not modified by definition // if both values are '', 0 or null, we count them as equal too $modified = $old && $data[$name] != $old[$name] && !(!$data[$name] && !$old[$name]); //if ($modified) error_log("data[$name]=".print_r($data[$name],true).", old[$name]=".print_r($old[$name],true)." --> modified=".(int)$modified); if (empty($detail['value']) && !$modified) continue; // skip unchanged, empty values $body .= $this->format_line($html_email,$detail['type'],$modified, $detail['label'] ? $detail['label'] : '', $detail['value']); } if ($html_email) { $body .= "
\n"; } if($sig = $this->get_signature($data,$old,$receiver)) { $body .= ($html_email ? '
':'') . "\n$sig"; } return $body; } /** * Format one line to the mail body * * @internal * @param boolean $html_mail * @param string $type 'link', 'message', 'summary', 'multiline', 'reply' and ''=regular content * @param boolean $modified mark field as modified * @param string $line whole line or just label * @param string $data=null data or null to display just $line over 2 columns * @return string */ protected function format_line($html_mail,$type,$modified,$line,$data=null) { //error_log(__METHOD__.'('.array2string($html_mail).",'$type',".array2string($modified).",'$line',".array2string($data).')'); $content = ''; if ($html_mail) { if (!$this->html_content_allow) $line = html::htmlspecialchars($line); // XSS $color = $modified ? 'red' : false; $size = '110%'; $bold = false; $background = '#FFFFF1'; switch($type) { case 'message': $background = '#D3DCE3;'; $bold = true; break; case 'link': $background = '#F1F1F1'; break; case 'summary': $background = '#F1F1F1'; $bold = true; break; case 'multiline': // Only Convert nl2br on non-html content if (strpos($data, 'html_content_allow ? $data : html::htmlspecialchars($data)); $this->html_content_allow = true; // to NOT do htmlspecialchars again } break; case 'reply': $background = '#F1F1F1'; break; default: $size = false; } $style = ($bold ? 'font-weight:bold;' : '').($size ? 'font-size:'.$size.';' : '').($color?'color:'.$color:''); $content = ''; } else // text-mail { if ($type == 'reply') $content = str_repeat('-',64)."\n"; if ($modified) $content .= '> '; } $content .= $line; if ($html_mail) { if ($line && $data) $content .= ''; if ($type == 'link') { // the link is often too long for html boxes chunk-split allows to break lines if needed $content .= html::a_href(chunk_split(rawurldecode($data),40,'​'),$data,'','target="_blank"'); } elseif ($this->html_content_allow) { $content .= html::activate_links($data); } else { $content .= html::htmlspecialchars($data); } } else { $content .= ($content?': ':'').$data; } if ($html_mail) $content .= ''; $content .= "\n"; return $content; } /** * Get the attachments for a notification * * @param array $data * @param array $old * @param int|string $receiver nummeric account_id or email address * @return array or array with values for either 'string' or 'path' and optionally (mime-)'type', 'filename' and 'encoding' */ protected function get_attachments($data,$old,$receiver=null) { return array(); } /** * Get a (global) signature to append to the change notificaiton */ protected function get_signature($data, $old, $receiver) { $config = config::read('notifications'); if(!isset($data[$this->id_field])) { error_log($this->app . ' did not properly implement bo_tracking->id_field. Merge skipped.'); } elseif(class_exists($this->app. '_merge')) { $merge_class = $this->app.'_merge'; $merge = new $merge_class(); $sig = $merge->merge_string($config['signature'], array($data[$this->id_field]), $error, 'text/html'); if($error) { error_log($error); return $config['signature']; } return $sig; } return $config['signature']; } /** * Get a custom notification message to be used instead of the standard one. * It can use merge print placeholders to include data. */ protected function get_custom_message($data, $old, $merge_class = null) { $message = $this->get_config(self::CUSTOM_NOTIFICATION, $data, $old); if(!$message) { return ''; } // Automatically set merge class from naming conventions if($merge_class == null) { $merge_class = $this->app.'_merge'; } if(!isset($data[$this->id_field])) { error_log($this->app . ' did not properly implement bo_tracking->id_field. Merge skipped.'); return $message; } elseif(class_exists($merge_class)) { $merge = new $merge_class(); $merged_message = $merge->merge_string($message, array($data[$this->id_field]), $error, 'text/html'); if($error) { error_log($error); return $message; } return $merged_message; } else { throw new egw_exception_wrong_parameter("Invalid merge class '$merge_class' for {$this->app} custom notification"); } } }