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 function UpdateStatus($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                      $this->user->id(), $this->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('yes', $this->remind_delay_yes);
  85     }
  86     protected function UpdateOnNo()
  87     {
  88         $this->UpdateStatus('no', $this->remind_delay_no);
  89     }
  90     protected function UpdateOnDismiss()
  91     {
  92         $this->UpdateStatus('dismiss', $this->remind_delay_dismiss);
  93     }
  94
  95     // Display and http handling helpers --------------------------------------
  96
  97     // Handles a hit on the reminder onebox (for links made using the GetBaseUrl
  98     // method below).
  99     abstract public function HandleAction($action);
 100
 101     // Returns the content of the onebox reminder. Default implementation displays
 102     // a text and three links (yes, no, dismiss); it uses the text from method
 103     // GetDisplayText.
 104     public function Display(&$page)
 105     {
 106         header('Content-Type: text/html; charset=utf-8');
 107         $page->changeTpl('reminder/default.tpl', NO_SKIN);
 108         $page->assign('text', $this->GetDisplayText());
 109         $page->assign('baseurl', $this->GetBaseUrl());
 110     }
 111
 112     // Helper for returning the content as a string, instead of using the existing
 113     // globale XorgPage instance.
 114     public function GetDisplayAsString()
 115     {
 116         $page = new XorgPage();
 117         $this->Display($page);
 118         return $page->raw();
 119     }
 120
 121     // Returns the text to display in the onebox.
 122     abstract protected function GetDisplayText();
 123
 124     // Returns the base url for the reminder module.
 125     protected function GetBaseUrl()
 126     {
 127         return 'ajax/reminder/' . $this->name;
 128     }
 129
 130     // Static factories -------------------------------------------------------
 131
 132     // Returns a chosen class using the user data from |user|, and from the database.
 133     public static function GetCandidateReminder(User &$user)
 134     {
 135         $res = XDB::query('SELECT  rt.*, r.status, r.remind_last
 136                              FROM  reminder_type AS rt
 137                         LEFT JOIN  reminder      AS r ON (rt.type_id = r.type_id AND r.uid = {?})
 138                             WHERE  r.uid IS NULL OR r.remind_next < NOW()',
 139                           $user->id());
 140         $candidates  = $res->fetchAllAssoc();
 141
 142         $weight_map = create_function('$a', 'return $a["weight"];');
 143         while (count($candidates) > 0) {
 144             $position = rand(1, array_sum(array_map($weight_map, $candidates)));
 145             foreach ($candidates as $key => $candidate) {
 146                 $position -= $candidate['weight'];
 147                 if ($position <= 0) {
 148                     $class = self::GetClassName($candidate['name']);
 149                     if ($class && call_user_func(array($class, 'IsCandidate'), $user)) {
 150                         return new $class($user, $candidate);
 151                     }
 152                     unset($candidates[$key]);
 153                 }
 154             }
 155         }
 156
 157         return null;
 158     }
 159
 160     // Returns an instantiation of the reminder class which name is |name|, using
 161     // user data from |user|, and from the database.
 162     public static function GetByName(User &$user, $name)
 163     {
 164         if (!($class = self::GetClassName($name))) {
 165             return null;
 166         }
 167
 168         $res = XDB::query('SELECT  rt.*, r.status, r.remind_last
 169                              FROM  reminder_type AS rt
 170                         LEFT JOIN  reminder      AS r ON (rt.type_id = r.type_id AND r.uid = {?})
 171                             WHERE  rt.name = {?}',
 172                           $user->id(), $name);
 173         if ($res->numRows() > 0) {
 174             return new $class($user, $res->fetchOneAssoc());
 175         }
 176
 177         return null;
 178     }
 179
 180     // Computes the name of the class for reminder named |name|, and preloads
 181     // the class.
 182     private static function GetClassName($name)
 183     {
 184         @include_once "reminder/$name.inc.php";
 185         $class = 'Reminder' . str_replace(' ', '', ucwords(str_replace('_', ' ', $name)));
 186         return (class_exists($class) ? $class : null);
 187     }
 188 }
 189
 190
 191 // vim:set et sw=4 sts=4 sws=4 foldmethod=marker enc=utf-8:
 192 ?>