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