include/reminder.inc.php

   1 <?php
   2 /***************************************************************************
   3  *  Copyright (C) 2003-2011 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($uid, $type_id, $status, $next_ask)
  73     {
  74         XDB::execute('INSERT INTO  reminder (uid, type_id, status, remind_last, remind_next)
  75                            VALUES  ({?}, {?}, {?}, NOW(), FROM_UNIXTIME({?}))
  76           ON DUPLICATE KEY UPDATE  status = VALUES(status), remind_last = VALUES(remind_last), remind_next = VALUES(remind_next)',
  77                      $uid, $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         pl_content_headers("text/html");
 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         pl_content_headers("text/html");
 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     // Returns the url for the information page.
 152     public function info() { return ''; }
 153
 154     // Static status update methods -------------------------------------------
 155
 156     // Marks the candidate reminder as having been accepted for user |uid|.
 157     // It is intended to be used when a reminder box has been bypassed, and when
 158     // it should behave as if the user had clicked on 'yes'.
 159     protected static function MarkCandidateAsAccepted($uid, $candidate)
 160     {
 161         Reminder::UpdateStatus($uid, $candidate['type_id'],
 162                                'yes', $candidate['remind_delay_yes']);
 163     }
 164
 165     // Static factories -------------------------------------------------------
 166
 167     // Returns a chosen class using the user data from |user|, and from the database.
 168     public static function GetCandidateReminder(User $user)
 169     {
 170         $res = XDB::query('SELECT  rt.*, r.status, r.remind_last
 171                              FROM  reminder_type AS rt
 172                         LEFT JOIN  reminder      AS r ON (rt.type_id = r.type_id AND r.uid = {?})
 173                             WHERE  r.uid IS NULL OR r.remind_next < NOW()',
 174                           $user->id());
 175         $candidates  = $res->fetchAllAssoc();
 176
 177         $weight_map = create_function('$a', 'return $a["weight"];');
 178         while (count($candidates) > 0) {
 179             $position = rand(1, array_sum(array_map($weight_map, $candidates)));
 180             foreach ($candidates as $key => $candidate) {
 181                 $position -= $candidate['weight'];
 182                 if ($position <= 0) {
 183                     $class = self::GetClassName($candidate['name']);
 184                     if ($class && call_user_func(array($class, 'IsCandidate'), $user, $candidate)) {
 185                         return new $class($user, $candidate);
 186                     }
 187                     unset($candidates[$key]);
 188                 }
 189             }
 190         }
 191
 192         return null;
 193     }
 194
 195     // Returns an instantiation of the reminder class which name is |name|, using
 196     // user data from |user|, and from the database.
 197     public static function GetByName(User $user, $name)
 198     {
 199         if (!($class = self::GetClassName($name))) {
 200             return null;
 201         }
 202
 203         $res = XDB::query('SELECT  rt.*, r.status, r.remind_last
 204                              FROM  reminder_type AS rt
 205                         LEFT JOIN  reminder      AS r ON (rt.type_id = r.type_id AND r.uid = {?})
 206                             WHERE  rt.name = {?}',
 207                           $user->id(), $name);
 208         if ($res->numRows() > 0) {
 209             return new $class($user, $res->fetchOneAssoc());
 210         }
 211
 212         return null;
 213     }
 214
 215     // Computes the name of the class for reminder named |name|, and preloads
 216     // the class.
 217     private static function GetClassName($name)
 218     {
 219         include_once "reminder/$name.inc.php";
 220         $class = 'Reminder' . str_replace(' ', '', ucwords(str_replace('_', ' ', $name)));
 221         return (class_exists($class) ? $class : null);
 222     }
 223 }
 224
 225
 226 // vim:set et sw=4 sts=4 sws=4 foldmethod=marker enc=utf-8:
 227 ?>