include/reminder.inc.php

   1 <?php
   2 /***************************************************************************
   3  *  Copyright (C) 2003-2009 Polytechnique.org                              *
   4  *  http://opensource.polytechnique.org/                                   *
   5  *                                                                         *
   6  *  This program is free software; you can redistribute it and/or modify   *
   7  *  it under the terms of the GNU General Public License as published by   *
   8  *  the Free Software Foundation; either version 2 of the License, or      *
   9  *  (at your option) any later version.                                    *
  10  *                                                                         *
  11  *  This program is distributed in the hope that it will be useful,        *
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of         *
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          *
  14  *  GNU General Public License for more details.                           *
  15  *                                                                         *
  16  *  You should have received a copy of the GNU General Public License      *
  17  *  along with this program; if not, write to the Free Software            *
  18  *  Foundation, Inc.,                                                      *
  19  *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA                *
  20  ***************************************************************************/
  21
  22 // Base class for a reminder; it offers the factory for creating valid reminders
  23 // tailored for a given user, as well as base methods for reminder impls.
  24 // Sub-classes should define at least the abstract methods, and the static
  25 // IsCandidate method (prototype: (User &$user)).
  26 //
  27 // Usage:
  28 //   // Instantiates and returns a valid Reminder object for the user.
  29 //   $reminder = Reminder::GetCandidateReminder($user);
  30 //
  31 //   // Returns the named Reminder object.
  32 //   $reminder = Reminder::GetByName($user, 'ax_letter');
  33 abstract class Reminder
  34 {
  35     // Details about the reminder.
  36     public $name;
  37     protected $type_id;
  38     protected $weight;
  39     protected $remind_delay_yes;
  40     protected $remind_delay_no;
  41     protected $remind_delay_dismiss;
  42
  43     // Details about the user.
  44     protected $user;
  45     protected $current_status;
  46     protected $last_ask;
  47
  48     // Constructs the Reminder object from a mandatory User instance, a list of
  49     // key-value pairs from the `reminder_type` and `reminder` tables.
  50     function __construct(User &$user, array $type)
  51     {
  52         $this->user = &$user;
  53
  54         $this->type_id              = $type['type_id'];
  55         $this->name                 = $type['name'];
  56         $this->weight               = $type['weight'];
  57         $this->remind_delay_yes     = $type['remind_delay_yes'];
  58         $this->remind_delay_no      = $type['remind_delay_no'];
  59         $this->remind_delay_dismiss = $type['remind_delay_dismiss'];
  60
  61         if (isset($type['status'])) {
  62             $this->current_status = $type['status'];
  63         }
  64         if (isset($type['remind_last'])) {
  65             $this->last_ask = $type['remind_last'];
  66         }
  67     }
  68
  69     // Updates (or creates) the reminder line for the pair (|user|, |reminder_id|)
  70     // using the |status| as status, and the |next_ask| as the delay between now
  71     // and the next ask (if any).
  72     private static function UpdateStatus($user_id, $type_id, $status, $next_ask)
  73     {
  74         XDB::execute('REPLACE INTO  reminder
  75                                SET  uid = {?}, type_id = {?}, status = {?},
  76                                     remind_last = NOW(), remind_next = FROM_UNIXTIME({?})',
  77                      $user_id, $type_id, $status,
  78                      ($next_ask > 0 ? time() + $next_ask * 24 * 60 * 60 : null));
  79     }
  80
  81     // Updates the status of the reminder for the current user.
  82     protected function UpdateOnYes()
  83     {
  84         $this->UpdateStatus($this->user->id(), $this->type_id,
  85                             'yes', $this->remind_delay_yes);
  86     }
  87     protected function UpdateOnNo()
  88     {
  89         $this->UpdateStatus($this->user->id(), $this->type_id,
  90                             'no', $this->remind_delay_no);
  91     }
  92     protected function UpdateOnDismiss()
  93     {
  94         $this->UpdateStatus($this->user->id(), $this->type_id,
  95                             'dismiss', $this->remind_delay_dismiss);
  96     }
  97
  98     // Display and http handling helpers --------------------------------------
  99
 100     // Handles a hit on the reminder onebox (for links made using the GetBaseUrl
 101     // method below).
 102     abstract public function HandleAction($action);
 103
 104     // Displays a reduced version of the reminder and notifies that the action
 105     // has been taken into account.
 106     public function NotifiesAction(&$page)
 107     {
 108         header('Content-Type: text/html; charset=utf-8');
 109         $page->changeTpl('reminder/notification.tpl', NO_SKIN);
 110         $page->assign('previous_reminder', $this->title());
 111     }
 112
 113     // Displays the reminder as a standalone html snippet. It should be used
 114     // when the reminder is the only output of a page.
 115     public function DisplayStandalone(&$page, $previous_reminder = null)
 116     {
 117         header('Content-Type: text/html; charset=utf-8');
 118         $page->changeTpl('reminder/base.tpl', NO_SKIN);
 119         $this->Prepare($page);
 120         if ($previous_reminder) {
 121             $page->assign('previous_reminder', $previous_reminder);
 122         }
 123     }
 124
 125     // Prepares the display by assigning template variables.
 126     public function Prepare(&$page)
 127     {
 128         $page->assign_by_ref('reminder', $this);
 129     }
 130
 131     // Returns the name of the inner template, or null if a simple text obtained
 132     // from GetText should be printed.
 133     public function template() { return null; }
 134
 135     // Returns the text to display in the onebox, or null if a
 136     public function text() { return ''; }
 137
 138     // Returns the title of the onebox.
 139     public function title() { return ''; }
 140
 141     // Should return true if this onebox needs to be considered as a warning and
 142     // not just as a subscription offer.
 143     public function warning() { return false; }
 144
 145     // Returns the base url for the reminder module.
 146     public function baseurl()
 147     {
 148         return 'ajax/reminder/' . $this->name;
 149     }
 150
 151     // Static status update methods -------------------------------------------
 152
 153     // Marks the candidate reminder as having been accepted for user |user_id|.
 154     // It is intended to be used when a reminder box has been bypassed, and when
 155     // it should behave as if the user had clicked on 'yes'.
 156     protected static function MarkCandidateAsAccepted($user_id, $candidate)
 157     {
 158         Reminder::UpdateStatus($user_id, $candidate['type_id'],
 159                                'yes', $candidate['remind_delay_yes']);
 160     }
 161
 162     // Static factories -------------------------------------------------------
 163
 164     // Returns a chosen class using the user data from |user|, and from the database.
 165     public static function GetCandidateReminder(User &$user)
 166     {
 167         $res = XDB::query('SELECT  rt.*, r.status, r.remind_last
 168                              FROM  reminder_type AS rt
 169                         LEFT JOIN  reminder      AS r ON (rt.type_id = r.type_id AND r.uid = {?})
 170                             WHERE  r.uid IS NULL OR r.remind_next < NOW()',
 171                           $user->id());
 172         $candidates  = $res->fetchAllAssoc();
 173
 174         $weight_map = create_function('$a', 'return $a["weight"];');
 175         while (count($candidates) > 0) {
 176             $position = rand(1, array_sum(array_map($weight_map, $candidates)));
 177             foreach ($candidates as $key => $candidate) {
 178                 $position -= $candidate['weight'];
 179                 if ($position <= 0) {
 180                     $class = self::GetClassName($candidate['name']);
 181                     if ($class && call_user_func(array($class, 'IsCandidate'), $user, $candidate)) {
 182                         return new $class($user, $candidate);
 183                     }
 184                     unset($candidates[$key]);
 185                 }
 186             }
 187         }
 188
 189         return null;
 190     }
 191
 192     // Returns an instantiation of the reminder class which name is |name|, using
 193     // user data from |user|, and from the database.
 194     public static function GetByName(User &$user, $name)
 195     {
 196         if (!($class = self::GetClassName($name))) {
 197             return null;
 198         }
 199
 200         $res = XDB::query('SELECT  rt.*, r.status, r.remind_last
 201                              FROM  reminder_type AS rt
 202                         LEFT JOIN  reminder      AS r ON (rt.type_id = r.type_id AND r.uid = {?})
 203                             WHERE  rt.name = {?}',
 204                           $user->id(), $name);
 205         if ($res->numRows() > 0) {
 206             return new $class($user, $res->fetchOneAssoc());
 207         }
 208
 209         return null;
 210     }
 211
 212     // Computes the name of the class for reminder named |name|, and preloads
 213     // the class.
 214     private static function GetClassName($name)
 215     {
 216         include_once "reminder/$name.inc.php";
 217         $class = 'Reminder' . str_replace(' ', '', ucwords(str_replace('_', ' ', $name)));
 218         return (class_exists($class) ? $class : null);
 219     }
 220 }
 221
 222
 223 // vim:set et sw=4 sts=4 sws=4 foldmethod=marker enc=utf-8:
 224 ?>