lib/AkActiveRecord/AkActsAsList.php

   1 <?php
   2 /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
   3
   4 // +----------------------------------------------------------------------+
   5 // | Akelos Framework - http://www.akelos.org                             |
   6 // +----------------------------------------------------------------------+
   7 // | Copyright (c) 2002-2006, Akelos Media, S.L.  & Bermi Ferrer Martinez |
   8 // | Released under the GNU Lesser General Public License, see LICENSE.txt|
   9 // +----------------------------------------------------------------------+
  10
  11 /**
  12 * @package ActiveRecord
  13 * @subpackage Behaviours
  14 * @author Bermi Ferrer <bermi a.t akelos c.om>
  15 * @copyright Copyright (c) 2002-2006, Akelos Media, S.L. http://www.akelos.org
  16 * @license GNU Lesser General Public License <http://www.gnu.org/copyleft/lesser.html>
  17 */
  18
  19 require_once(AK_LIB_DIR.DS.'AkActiveRecord'.DS.'AkObserver.php');
  20
  21 /**
  22 * This act provides the capabilities for sorting and reordering a number of objects in list.
  23 * The class that has this specified needs to have a "position" column defined as an integer on
  24 * the mapped database table.
  25 *
  26 * Todo list example:
  27 * <code>
  28 *   class TodoList extends ActiveRecord
  29 *   {
  30 *       var $has_many = array('todo_items', array('order' => "position"));
  31 *   }
  32 *
  33 *   class TodoItem extends ActiveRecord
  34 *   {
  35 *       var $belongs_to = 'todo_list';
  36 *       var $acts_as = array('list' => array('scope' => 'todo_list'));
  37 *   }
  38 *
  39 *   $TodoList =& new TodoList();
  40 *
  41 *   $TodoList->list->moveToBottom();
  42 * </code>
  43 */
  44 class AkActsAsList extends AkObserver
  45 {
  46     var $column = 'position';
  47     var $scope = '';
  48     var $scope_condition;
  49     /**
  50 * Configuration options are:
  51 *
  52 * * +column+ - specifies the column name to use for keeping the position integer (default: position)
  53 * * +scope+ - restricts what is to be considered a list.
  54 *   Example:
  55 *
  56 * class TodoTask extends ActiveRecord
  57 * {
  58 *   var $acts_as = array('list'=> array('scope'=> array('todo_list_id','completed = 0')));
  59 *   var $belongs_to = 'todo_list';
  60 * }
  61 */
  62     var $_ActiveRecordInstance;
  63     function AkActsAsList(&$ActiveRecordInstance)
  64     {
  65         $this->_ActiveRecordInstance =& $ActiveRecordInstance;
  66     }
  67
  68     function init($options = array())
  69     {
  70         $this->column = !empty($options['column']) ? $options['column'] : $this->column;
  71         $this->scope = !empty($options['scope']) ? $options['scope'] : $this->scope;
  72         return $this->_ensureIsActiveRecordInstance($this->_ActiveRecordInstance);
  73     }
  74
  75     function _ensureIsActiveRecordInstance(&$ActiveRecordInstance)
  76     {
  77         if(is_object($ActiveRecordInstance) && method_exists($ActiveRecordInstance,'actsLike')){
  78             $this->_ActiveRecordInstance =& $ActiveRecordInstance;
  79             if(!$this->_ActiveRecordInstance->hasColumn($this->column)){
  80                 trigger_error(Ak::t('Could not find the column "%column" into the table "%table". This column is needed in order to make "%model" act as a list.',array('%column'=>$this->column,'%table'=>$this->_ActiveRecordInstance->getTableName(),'%model'=>$this->_ActiveRecordInstance->getModelName())),E_USER_ERROR);
  81                 unset($this->_ActiveRecordInstance->list);
  82                 return false;
  83             }else {
  84                 $this->observe(&$ActiveRecordInstance);
  85             }
  86         }else{
  87             trigger_error(Ak::t('You are trying to set an object that is not an active record.'), E_USER_ERROR);
  88             return false;
  89         }
  90         return true;
  91     }
  92
  93     function reloadActiveRecordInstance(&$listObject)
  94     {
  95         AK_PHP5 ? null : $listObject->list->setActiveRecordInstance(&$listObject);
  96     }
  97
  98     function getType()
  99     {
 100         return 'list';
 101     }
 102
 103     function beforeDestroy(&$object)
 104     {
 105         $object->list->_ActiveRecordInstance->reload();
 106         return true;
 107     }
 108
 109     function afterSave(&$object)
 110     {
 111         $object->list->_ActiveRecordInstance->reload();
 112         return true;
 113     }
 114
 115     function afterDestroy(&$object)
 116     {
 117         return $object->list->removeFromList();
 118     }
 119
 120     function beforeCreate(&$object)
 121     {
 122         $object->list->_addToBottom();
 123         return true;
 124     }
 125
 126     /**
 127     * All the methods available to a record that has had <tt>acts_as list</tt> specified. Each method works
 128     * by assuming the object to be the item in the list, so <tt>$Chapter->list->moveLower()</tt> would move that chapter
 129     * lower in the list of all chapters. Likewise, <tt>$Chapter->list->isFirst()</tt> would return true if that chapter is
 130     * the first in the list of all chapters.
 131     */
 132
 133
 134     function insertAt($position = 1)
 135     {
 136         return $this->insertAtPosition($position);
 137     }
 138
 139     function moveLower()
 140     {
 141         $this->_ActiveRecordInstance->transactionStart();
 142         if($LowerItem = $this->getLowerItem()){
 143             if($LowerItem->list->decrementPosition() && $this->incrementPosition()){
 144                 $this->_ActiveRecordInstance->transactionComplete();
 145                 return true;
 146             }else{
 147                 $this->_ActiveRecordInstance->transactionFail();
 148             }
 149         }
 150         $this->_ActiveRecordInstance->transactionComplete();
 151         return false;
 152     }
 153
 154     function moveHigher()
 155     {
 156         $this->_ActiveRecordInstance->transactionStart();
 157         if($HigherItem = $this->getHigherItem()){
 158             if($HigherItem->list->incrementPosition() && $this->decrementPosition()){
 159                 $this->_ActiveRecordInstance->transactionComplete();
 160                 return true;
 161             }else{
 162                 $this->_ActiveRecordInstance->transactionFail();
 163             }
 164         }
 165         $this->_ActiveRecordInstance->transactionComplete();
 166         return false;
 167     }
 168
 169
 170     function moveToBottom()
 171     {
 172         if($this->isInList()){
 173             $this->_ActiveRecordInstance->transactionStart();
 174             if($this->decrementPositionsOnLowerItems() && $this->assumeBottomPosition()){
 175                 $this->_ActiveRecordInstance->transactionComplete();
 176                 return true;
 177             }else{
 178                 $this->_ActiveRecordInstance->transactionFail();
 179             }
 180             $this->_ActiveRecordInstance->transactionComplete();
 181         }
 182         return false;
 183     }
 184
 185     /**
 186     * This has the effect of moving all the lower items up one.
 187     */
 188     function decrementPositionsOnLowerItems()
 189     {
 190         if($this->isInList()){
 191             $this->_ActiveRecordInstance->updateAll("{$this->column} = ({$this->column} - 1)", $this->getScopeCondition()." AND {$this->column} > ".$this->_ActiveRecordInstance->getAttribute($this->column));
 192             return true;
 193         }
 194         return false;
 195     }
 196
 197     function assumeBottomPosition()
 198     {
 199         return $this->_ActiveRecordInstance->updateAttribute($this->column, $this->getBottomPosition($this->_ActiveRecordInstance->getId()) + 1);
 200     }
 201
 202     function getBottomPosition($except = null)
 203     {
 204         return ($item = $this->getBottomItem($except)) ? $item->getAttribute($this->column) : 0;
 205     }
 206
 207     /**
 208     * Returns an instance of the item that's on the very bottom of the list. Returns false if there's none
 209     */
 210     function getBottomItem($except = null)
 211     {
 212         $conditions = $this->getScopeCondition();
 213
 214         if(isset($except)){
 215             $conditions .= " AND id != $except";
 216         }
 217         return $this->_ActiveRecordInstance->find('first', array('conditions' => $conditions, 'order' => "{$this->column} DESC"));
 218     }
 219
 220
 221     function isInList()
 222     {
 223         return !empty($this->_ActiveRecordInstance->{$this->column});
 224     }
 225
 226
 227     function moveToTop()
 228     {
 229         if($this->isInList()){
 230             $this->_ActiveRecordInstance->transactionStart();
 231             if($this->incrementPositionsOnHigherItems() && $this->assumeTopPosition()){
 232                 $this->_ActiveRecordInstance->transactionComplete();
 233                 return true;
 234             }else{
 235                 $this->_ActiveRecordInstance->transactionFail();
 236             }
 237             $this->_ActiveRecordInstance->transactionComplete();
 238         }
 239         return false;
 240     }
 241
 242     /**
 243     * This has the effect of moving all the higher items down one.
 244     */
 245     function incrementPositionsOnHigherItems()
 246     {
 247         if($this->isInList()){
 248             $this->_ActiveRecordInstance->updateAll("{$this->column} = ({$this->column} + 1)", $this->getScopeCondition()." AND {$this->column} < ".$this->_ActiveRecordInstance->getAttribute($this->column));
 249             return true;
 250         }
 251         return false;
 252     }
 253
 254     function assumeTopPosition()
 255     {
 256         return $this->_ActiveRecordInstance->updateAttribute($this->column, 1);
 257     }
 258
 259
 260     function removeFromList()
 261     {
 262         if($this->isInList()){
 263             if($this->decrementPositionsOnLowerItems()){
 264                 $this->_ActiveRecordInstance->{$this->column} = null;
 265                 return true;
 266             }
 267         }
 268         return false;
 269     }
 270
 271
 272     function incrementPosition()
 273     {
 274         if($this->isInList()){
 275             return $this->_ActiveRecordInstance->updateAttribute($this->column, $this->_ActiveRecordInstance->getAttribute($this->column) + 1);
 276         }
 277         return false;
 278     }
 279
 280     function decrementPosition()
 281     {
 282         if($this->isInList()){
 283             return $this->_ActiveRecordInstance->updateAttribute($this->column, $this->_ActiveRecordInstance->getAttribute($this->column) - 1);
 284         }
 285         return false;
 286     }
 287
 288     function isFirst()
 289     {
 290         if($this->isInList()){
 291             return $this->_ActiveRecordInstance->getAttribute($this->column) == 1;
 292         }
 293         return false;
 294     }
 295
 296     function isLast()
 297     {
 298         if($this->isInList()){
 299             return $this->_ActiveRecordInstance->getAttribute($this->column) == $this->getBottomPosition();
 300         }
 301         return false;
 302     }
 303
 304     function getHigherItem()
 305     {
 306         if($this->isInList()){
 307             return $this->_ActiveRecordInstance->find('first', array('conditions' => $this->getScopeCondition()." AND {$this->column} = ".($this->_ActiveRecordInstance->getAttribute($this->column) - 1)));
 308         }
 309         return false;
 310     }
 311
 312     function getLowerItem()
 313     {
 314         if($this->isInList()){
 315             return $this->_ActiveRecordInstance->find('first', array('conditions' => $this->getScopeCondition()." AND {$this->column} = ".($this->_ActiveRecordInstance->getAttribute($this->column) + 1)));
 316         }
 317         return false;
 318     }
 319
 320
 321     function addToListTop()
 322     {
 323         $this->incrementPositionsOnAllItems();
 324     }
 325
 326     function _addToBottom()
 327     {
 328         $this->_ActiveRecordInstance->{$this->column} = $this->getBottomPosition() + 1;
 329     }
 330
 331     function getScopeCondition()
 332     {
 333         if (!empty($this->variable_scope_condition)){
 334             return $this->_ActiveRecordInstance->_getVariableSqlCondition($this->variable_scope_condition);
 335
 336         // True condition in case we don't have a scope
 337         }elseif(empty($this->scope_condition) && empty($this->scope)){
 338             $this->scope_condition = (substr($this->_ActiveRecordInstance->_db->databaseType,0,4) == 'post') ? 'true' : '1';
 339         }elseif (!empty($this->scope)){
 340             $this->setScopeCondition(join(' AND ',array_map(array(&$this,'getScopedColumn'),(array)$this->scope)));
 341         }
 342         return  $this->scope_condition;
 343     }
 344
 345
 346     function setScopeCondition($scope_condition)
 347     {
 348         if(!is_array($scope_condition) && strstr($scope_condition, '?')){
 349             $this->variable_scope_condition = $scope_condition;
 350         }else{
 351             $this->scope_condition  = $scope_condition;
 352         }
 353     }
 354
 355     function getScopedColumn($column)
 356     {
 357         if($this->_ActiveRecordInstance->hasColumn($column)){
 358             $value = $this->_ActiveRecordInstance->get($column);
 359             $condition = $this->_ActiveRecordInstance->getAttributeCondition($value);
 360             $value = $this->_ActiveRecordInstance->castAttributeForDatabase($column, $value);
 361             return $column.' '.str_replace('?', $value, $condition);
 362         }else{
 363             return $column;
 364         }
 365     }
 366
 367
 368     /**
 369     * This has the effect of moving all the higher items up one.
 370     */
 371     function decrementPositionsOnHigherItems($position)
 372     {
 373         return $this->_ActiveRecordInstance->updateAll("{$this->column} = ({$this->column} - 1)", $this->getScopeCondition()." AND {$this->column} <= $position");
 374     }
 375
 376     /**
 377     * This has the effect of moving all the lower items down one.
 378     */
 379     function incrementPositionsOnLowerItems($position)
 380     {
 381         return $this->_ActiveRecordInstance->updateAll("{$this->column} = ({$this->column} + 1)", $this->getScopeCondition()." AND {$this->column} >= $position");
 382     }
 383
 384     function incrementPositionsOnAllItems()
 385     {
 386         return $this->_ActiveRecordInstance->updateAll("{$this->column} = ({$this->column} + 1)",  $this->getScopeCondition());
 387     }
 388
 389
 390
 391     /**
 392     * This function saves the object using save() before inserting it into the list
 393     */
 394     function insertAtPosition($position)
 395     {
 396         $this->_ActiveRecordInstance->transactionStart();
 397         if($this->_ActiveRecordInstance->isNewRecord()){
 398             $this->_ActiveRecordInstance->save();
 399         }
 400         $this->removeFromList();
 401         $this->incrementPositionsOnLowerItems($position);
 402
 403         $this->_ActiveRecordInstance->updateAttribute($this->column, $position);
 404         if($this->_ActiveRecordInstance->transactionHasFailed()){
 405             $this->_ActiveRecordInstance->transactionComplete();
 406             return false;
 407         }
 408
 409         $this->_ActiveRecordInstance->transactionComplete();
 410         return true;
 411     }
 412 }
 413
 414 ?>