lib/listlib.php

   1 <?php // $Id$
   2
   3 ///////////////////////////////////////////////////////////////////////////
   4 //                                                                       //
   5 // NOTICE OF COPYRIGHT                                                   //
   6 //                                                                       //
   7 // Moodle - Modular Object-Oriented Dynamic Learning Environment         //
   8 //          http://moodle.com                                            //
   9 //                                                                       //
  10 // Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com     //
  11 //                                                                       //
  12 // This program is free software; you can redistribute it and/or modify  //
  13 // it under the terms of the GNU General Public License as published by  //
  14 // the Free Software Foundation; either version 2 of the License, or     //
  15 // (at your option) any later version.                                   //
  16 //                                                                       //
  17 // This program is distributed in the hope that it will be useful,       //
  18 // but WITHOUT ANY WARRANTY; without even the implied warranty of        //
  19 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         //
  20 // GNU General Public License for more details:                          //
  21 //                                                                       //
  22 //          http://www.gnu.org/copyleft/gpl.html                         //
  23 //                                                                       //
  24 ///////////////////////////////////////////////////////////////////////////
  25
  26 /**
  27  * Classes for displaying and editing a nested list of items.
  28  *
  29  * Handles functionality for :
  30  *
  31  *    Construction of nested list from db records with some key pointing to a parent id.
  32  *    Display of list with or without editing icons with optional pagination.
  33  *    Reordering of items works across pages.
  34  *    Processing of editing actions on list.
  35  *
  36  * @author Jamie Pratt
  37  * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
  38  * @package moodlecore
  39  */
  40
  41 /**
  42  * Clues to reading this code:
  43  *
  44  * The functions that move things around the tree structure just update the
  45  * database - they don't update the in-memory structure, instead they trigger a
  46  * page reload so everything is rebuilt from scratch.
  47  */
  48 class moodle_list {
  49     var $attributes;
  50     var $listitemclassname = 'list_item';
  51     /**
  52      * An array of $listitemclassname objects.
  53      * @var array
  54      */
  55     var $items = array();
  56     /**
  57      * ol / ul
  58      * @var string
  59      */
  60     var $type;
  61     /**
  62      * @var list_item or derived class
  63      */
  64     var $parentitem = null;
  65     var $table;
  66     var $fieldnamesparent = 'parent';
  67     var $sortby = 'parent, sortorder, name';
  68     /**
  69      * Records from db, only used in top level list.
  70      * @var array
  71      */
  72     var $records = array();
  73
  74     var $editable;
  75
  76     /**
  77      * Key is child id, value is parent.
  78      * @var array
  79      */
  80     var $childparent;
  81
  82 //------------------------------------------------------
  83 //vars used for pagination.
  84     var $page = 0;// 0 means no pagination
  85     var $firstitem = 1;
  86     var $lastitem = 999999;
  87     var $pagecount;
  88     var $paged = false;
  89     var $offset = 0;
  90 //------------------------------------------------------
  91     var $pageurl;
  92     var $pageparamname;
  93
  94     /**
  95      * Constructor function
  96      *
  97      * @param string $type
  98      * @param string $attributes
  99      * @param boolean $editable
 100      * @param moodle_url $pageurl url for this page
 101      * @param integer $page if 0 no pagination. (These three params only used in top level list.)
 102      * @param string $pageparamname name of url param that is used for passing page no
 103      * @param integer $itemsperpage no of top level items.
 104      * @return moodle_list
 105      */
 106     function moodle_list($type='ul', $attributes='', $editable = false, $pageurl=null, $page = 0, $pageparamname = 'page', $itemsperpage = 20) {
 107         $this->editable = $editable;
 108         $this->attributes = $attributes;
 109         $this->type = $type;
 110         $this->page = $page;
 111         $this->pageparamname = $pageparamname;
 112         $this->itemsperpage = $itemsperpage;
 113         if ($pageurl === null) {
 114             $this->pageurl = new moodle_url();
 115             $this->pageurl->params(array($this->pageparamname => $this->page));
 116         } else {
 117             $this->pageurl = $pageurl;
 118         }
 119     }
 120
 121     /**
 122      * Returns html string.
 123      *
 124      * @param integer $indent depth of indentation.
 125      */
 126     function to_html($indent=0, $extraargs=array()) {
 127         if (count($this->items)) {
 128             $tabs = str_repeat("\t", $indent);
 129             $first = true;
 130             $itemiter = 1;
 131             $lastitem = '';
 132             $html = '';
 133
 134             foreach ($this->items as $item) {
 135                 $last = (count($this->items) == $itemiter);
 136                 if ($this->editable) {
 137                     $item->set_icon_html($first, $last, $lastitem);
 138                 }
 139                 if ($itemhtml = $item->to_html($indent+1, $extraargs)) {
 140                     $html .= "$tabs\t<li".((!empty($item->attributes))?(' '.$item->attributes):'').">";
 141                     $html .= $itemhtml;
 142                     $html .= "</li>\n";
 143                 }
 144                 $first = false;
 145                 $lastitem = $item;
 146                 $itemiter++;
 147             }
 148         } else {
 149             $html = '';
 150         }
 151         if ($html) { //if there are list items to display then wrap them in ul / ol tag.
 152             $tabs = str_repeat("\t", $indent);
 153             $html = $tabs.'<'.$this->type.((!empty($this->attributes))?(' '.$this->attributes):'').">\n".$html;
 154             $html .= $tabs."</".$this->type.">\n";
 155         } else {
 156             $html ='';
 157         }
 158         return $html;
 159     }
 160
 161     /**
 162      * Recurse down the tree and find an item by it's id.
 163      *
 164      * @param integer $id
 165      * @param boolean $suppresserror error if not item found?
 166      * @return list_item *copy* or null if item is not found
 167      */
 168     function find_item($id, $suppresserror = false) {
 169         if (isset($this->items)) {
 170             foreach ($this->items as $key => $child) {
 171                 if ($child->id == $id) {
 172                     return $this->items[$key];
 173                 }
 174             }
 175             foreach (array_keys($this->items) as $key) {
 176                 $thischild =& $this->items[$key];
 177                 $ref = $thischild->children->find_item($id, true);//error always reported at top level
 178                 if ($ref !== null) {
 179                     return $ref;
 180                 }
 181             }
 182         }
 183
 184         if (!$suppresserror) {
 185             print_error('listnoitem');
 186         }
 187         return null;
 188     }
 189
 190     function add_item(&$item) {
 191         $this->items[] =& $item;
 192     }
 193
 194     function set_parent(&$parent) {
 195         $this->parentitem =& $parent;
 196     }
 197
 198     /**
 199      * Produces a hierarchical tree of list items from a flat array of records.
 200      * 'parent' field is expected to point to a parent record.
 201      * records are already sorted.
 202      * If the parent field doesn't point to another record in the array then this is
 203      * a top level list
 204      *
 205      * @param integer $offset how many list toplevel items are there in lists before this one
 206      * @return array(boolean, integer) whether there is more than one page, $offset + how many toplevel items where there in this list.
 207      *
 208      */
 209     function list_from_records($paged = false, $offset = 0) {
 210         $this->paged = $paged;
 211         $this->offset = $offset;
 212         $this->get_records();
 213         $records = $this->records;
 214         $page = $this->page;
 215         if (!empty($page)) {
 216             $this->firstitem = ($page - 1) * $this->itemsperpage;
 217             $this->lastitem = $this->firstitem + $this->itemsperpage - 1;
 218         }
 219         $itemiter = $offset;
 220         //make a simple array which is easier to search
 221         $this->childparent = array();
 222         foreach ($records as $record) {
 223             $this->childparent[$record->id] = $record->parent;
 224         }
 225         //create top level list items and they're responsible for creating their children
 226         foreach ($records as $record) {
 227             if (!array_key_exists($record->parent, $this->childparent)) {
 228                 //if this record is not a child of another record then
 229
 230                 $inpage = ($itemiter >= $this->firstitem && $itemiter <= $this->lastitem);
 231                 //make list item for top level for all items
 232                 //we need the info about the top level items for reordering peers.
 233                 if ($this->parentitem!==null) {
 234                     $newattributes = $this->parentitem->attributes;
 235                 } else {
 236                     $newattributes = '';
 237
 238                 }
 239                 $this->items[$itemiter] =& new $this->listitemclassname($record, $this, $newattributes, $inpage);
 240                 if ($inpage) {
 241                     $this->items[$itemiter]->create_children($records, $this->childparent, $record->id);
 242                 } else {
 243                     //don't recurse down the tree for items that are not on this page
 244                     $this->paged = true;
 245                 }
 246                 $itemiter++;
 247             }
 248         }
 249         return array($this->paged, $itemiter);
 250     }
 251
 252     /**
 253      * Should be overriden to return an array of records of list items.
 254      *
 255      */
 256     function get_records() {
 257     }
 258
 259     /**
 260      * display list of page numbers for navigation
 261      */
 262     function display_page_numbers() {
 263         $html = '';
 264         $topcount = count($this->items);
 265         $this->pagecount = (integer) ceil(($topcount + $this->offset)/ QUESTION_PAGE_LENGTH );
 266         if (!empty($this->page) && ($this->paged)) {
 267             $html = "<div class=\"paging\">".get_string('page').":\n";
 268             foreach (range(1,$this->pagecount) as $currentpage) {
 269                 if ($this->page == $currentpage) {
 270                     $html .= " $currentpage \n";
 271                 }
 272                 else {
 273                     $html .= "<a href=\"".$this->pageurl->out(false, array($this->pageparamname => $currentpage))."\">";
 274                     $html .= " $currentpage </a>\n";
 275                 }
 276             }
 277             $html .= "</div>";
 278         }
 279         return $html;
 280     }
 281
 282     /**
 283      * Returns an array of ids of peers of an item.
 284      *
 285      * @param    int itemid - if given, restrict records to those with this parent id.
 286      * @return   array peer ids
 287      */
 288     function get_items_peers($itemid) {
 289         $itemref = $this->find_item($itemid);
 290         $peerids = $itemref->parentlist->get_child_ids();
 291         return $peerids;
 292     }
 293
 294     /**
 295      * Returns an array of ids of child items.
 296      *
 297      * @return   array peer ids
 298      */
 299     function get_child_ids() {
 300         $childids = array();
 301         foreach ($this->items as $child) {
 302            $childids[] = $child->id;
 303         }
 304         return $childids;
 305     }
 306
 307     /**
 308      * Move a record up or down
 309      *
 310      * @param string $direction up / down
 311      * @param integer $id
 312      */
 313     function move_item_up_down($direction, $id) {
 314         $peers = $this->get_items_peers($id);
 315         $itemkey = array_search($id, $peers);
 316         switch ($direction) {
 317             case 'down' :
 318                 if (isset($peers[$itemkey+1])) {
 319                     $olditem = $peers[$itemkey+1];
 320                     $peers[$itemkey+1] = $id;
 321                     $peers[$itemkey] = $olditem;
 322                 } else {
 323                     print_error('listcantmoveup');
 324                 }
 325                 break;
 326
 327             case 'up' :
 328                 if (isset($peers[$itemkey-1])) {
 329                     $olditem = $peers[$itemkey-1];
 330                     $peers[$itemkey-1] = $id;
 331                     $peers[$itemkey] = $olditem;
 332                 } else {
 333                     print_error('listcantmovedown');
 334                 }
 335                 break;
 336         }
 337         $this->reorder_peers($peers);
 338     }
 339
 340     function reorder_peers($peers) {
 341         foreach ($peers as $key => $peer) {
 342             if (!set_field("{$this->table}", "sortorder", $key, "id", $peer)) {
 343                 print_error('listupdatefail');
 344             }
 345         }
 346     }
 347
 348     /**
 349      * @param integer $id an item index.
 350      * @return object the item that used to be the parent of the item moved.
 351      */
 352     function move_item_left($id) {
 353         $item = $this->find_item($id);
 354         if (!isset($item->parentlist->parentitem->parentlist)) {
 355             print_error('listcantmoveleft');
 356         } else {
 357             $newpeers = $this->get_items_peers($item->parentlist->parentitem->id);
 358             if (isset($item->parentlist->parentitem->parentlist->parentitem)) {
 359                 $newparent = $item->parentlist->parentitem->parentlist->parentitem->id;
 360             } else {
 361                 $newparent = 0; // top level item
 362             }
 363             if (!set_field("{$this->table}", "parent", $newparent, "id", $item->id)) {
 364                 print_error('listupdatefail');
 365             } else {
 366                 $oldparentkey = array_search($item->parentlist->parentitem->id, $newpeers);
 367                 $neworder = array_merge(array_slice($newpeers, 0, $oldparentkey+1), array($item->id), array_slice($newpeers, $oldparentkey+1));
 368                 $this->reorder_peers($neworder);
 369             }
 370         }
 371         return $item->parentlist->parentitem;
 372     }
 373
 374     /**
 375      * Make item with id $id the child of the peer that is just above it in the sort order.
 376      *
 377      * @param integer $id
 378      */
 379     function move_item_right($id) {
 380         $peers = $this->get_items_peers($id);
 381         $itemkey = array_search($id, $peers);
 382         if (!isset($peers[$itemkey-1])) {
 383             print_error('listcantmoveright');
 384         } else {
 385             if (!set_field("{$this->table}", "parent", $peers[$itemkey-1], "id", $peers[$itemkey])) {
 386                 print_error('listupdatefail');
 387             } else {
 388                 $newparent = $this->find_item($peers[$itemkey-1]);
 389                 if (isset($newparent->children)) {
 390                     $newpeers = $newparent->children->get_child_ids();
 391                 }
 392                 if ($newpeers) {
 393                     $newpeers[] = $peers[$itemkey];
 394                     $this->reorder_peers($newpeers);
 395                 }
 396             }
 397         }
 398     }
 399
 400     /**
 401      * process any actions.
 402      *
 403      * @param integer $left id of item to move left
 404      * @param integer $right id of item to move right
 405      * @param integer $moveup id of item to move up
 406      * @param integer $movedown id of item to move down
 407      * @return unknown
 408      */
 409     function process_actions($left, $right, $moveup, $movedown) {
 410         //should this action be processed by this list object?
 411         if (!(array_key_exists($left, $this->records) || array_key_exists($right, $this->records) || array_key_exists($moveup, $this->records) || array_key_exists($movedown, $this->records))) {
 412             return false;
 413         }
 414         if (!empty($left)) {
 415             $oldparentitem = $this->move_item_left($left);
 416             if ($this->item_is_last_on_page($oldparentitem->id)) {
 417                 // Item has jumped onto the next page, change page when we redirect.
 418                 $this->page ++;
 419                 $this->pageurl->params(array($this->pageparamname => $this->page));
 420             }
 421         } else if (!empty($right)) {
 422             $this->move_item_right($right);
 423             if ($this->item_is_first_on_page($right)) {
 424                 // Item has jumped onto the previous page, change page when we redirect.
 425                 $this->page --;
 426                 $this->pageurl->params(array($this->pageparamname => $this->page));
 427             }
 428         } else if (!empty($moveup)) {
 429             $this->move_item_up_down('up', $moveup);
 430             if ($this->item_is_first_on_page($moveup)) {
 431                 // Item has jumped onto the previous page, change page when we redirect.
 432                 $this->page --;
 433                 $this->pageurl->params(array($this->pageparamname => $this->page));
 434             }
 435         } else if (!empty($movedown)) {
 436             $this->move_item_up_down('down', $movedown);
 437             if ($this->item_is_last_on_page($movedown)) {
 438                 // Item has jumped onto the next page, change page when we redirect.
 439                 $this->page ++;
 440                 $this->pageurl->params(array($this->pageparamname => $this->page));
 441             }
 442         } else {
 443             return false;
 444         }
 445
 446         redirect($this->pageurl->out());
 447     }
 448
 449     /**
 450      * @param integer $itemid an item id.
 451      * @return boolean Is the item with the given id the first top-level item on
 452      * the current page?
 453      */
 454     function item_is_first_on_page($itemid) {
 455         return $this->page && isset($this->items[$this->firstitem]) &&
 456                 $itemid == $this->items[$this->firstitem]->id;
 457     }
 458
 459     /**
 460      * @param integer $itemid an item id.
 461      * @return boolean Is the item with the given id the last top-level item on
 462      * the current page?
 463      */
 464     function item_is_last_on_page($itemid) {
 465         return $this->page && isset($this->items[$this->lastitem]) &&
 466                 $itemid == $this->items[$this->lastitem]->id;
 467     }
 468 }
 469
 470 class list_item {
 471     /**
 472      * id of record, used if list is editable
 473      * @var integer
 474      */
 475     var $id;
 476     /**
 477      * name of this item, used if list is editable
 478      * @var string
 479      */
 480     var $name;
 481     /**
 482      * The object or string representing this item.
 483      * @var mixed
 484      */
 485     var $item;
 486     var $fieldnamesname = 'name';
 487     var $attributes;
 488     var $display;
 489     var $icons = array();
 490     /**
 491      * @var moodle_list
 492      */
 493     var $parentlist;
 494     /**
 495      * Set if there are any children of this listitem.
 496      * @var moodle_list
 497      */
 498     var $children;
 499
 500     /**
 501      * Constructor
 502      * @param mixed $item fragment of html for list item or record
 503      * @param object &$parent reference to parent of this item
 504      * @param string $attributes attributes for li tag
 505      * @param boolean $display whether this item is displayed. Some items may be loaded so we have a complete
 506      *                              structure in memory to work with for actions but are not displayed.
 507      * @return list_item
 508      */
 509     function list_item($item, &$parent, $attributes='', $display = true) {
 510         $this->item = $item;
 511         if (is_object($this->item)) {
 512             $this->id = $this->item->id;
 513             $this->name = $this->item->{$this->fieldnamesname};
 514         }
 515         $this->set_parent($parent);
 516         $this->attributes = $attributes;
 517         $parentlistclass = get_class($parent);
 518         $this->children =& new $parentlistclass($parent->type, $parent->attributes, $parent->editable, $parent->pageurl, 0);
 519         $this->children->set_parent($this);
 520         $this->display = $display;
 521     }
 522
 523     /**
 524      * Output the html just for this item. Called by to_html which adds html for children.
 525      *
 526      */
 527     function item_html($extraargs = array()) {
 528         if (is_string($this->item)) {
 529             $html = $this->item;
 530         } elseif (is_object($this->item)) {
 531             //for debug purposes only. You should create a sub class to
 532             //properly handle the record
 533             $html = join(', ', (array)$this->item);
 534         }
 535         return $html;
 536     }
 537
 538     /**
 539      * Returns html
 540      *
 541      * @param integer $indent
 542      * @param array $extraargs any extra data that is needed to print the list item
 543      *                            may be used by sub class.
 544      * @return string html
 545      */
 546     function to_html($indent=0, $extraargs = array()) {
 547         if (!$this->display) {
 548             return '';
 549         }
 550         $tabs = str_repeat("\t", $indent);
 551
 552         if (isset($this->children)) {
 553             $childrenhtml = $this->children->to_html($indent+1, $extraargs);
 554         } else {
 555             $childrenhtml = '';
 556         }
 557         return $this->item_html($extraargs).'&nbsp;'.(join($this->icons, '')).(($childrenhtml !='')?("\n".$childrenhtml):'');
 558     }
 559
 560     function set_icon_html($first, $last, &$lastitem) {
 561         global $CFG;
 562         $strmoveup = get_string('moveup');
 563         $strmovedown = get_string('movedown');
 564         $strmoveleft = get_string('maketoplevelitem', 'question');
 565         $pixpath = $CFG->pixpath;
 566
 567         if (isset($this->parentlist->parentitem)) {
 568             $parentitem =& $this->parentlist->parentitem;
 569             if (isset($parentitem->parentlist->parentitem)) {
 570                 $action = get_string('makechildof', 'question', $parentitem->parentlist->parentitem->name);
 571             } else {
 572                 $action = $strmoveleft;
 573             }
 574             $this->icons['left'] = $this->image_icon($action, $this->parentlist->pageurl->out_action(array('left'=>$this->id)), 'left');
 575         } else {
 576             $this->icons['left'] =  $this->image_spacer();
 577         }
 578
 579         if (!$first) {
 580             $this->icons['up'] = $this->image_icon($strmoveup, $this->parentlist->pageurl->out_action(array('moveup'=>$this->id)), 'up');
 581         } else {
 582             $this->icons['up'] =  $this->image_spacer();
 583         }
 584
 585         if (!$last) {
 586             $this->icons['down'] = $this->image_icon($strmovedown, $this->parentlist->pageurl->out_action(array('movedown'=>$this->id)), 'down');
 587         } else {
 588             $this->icons['down'] =  $this->image_spacer();
 589         }
 590
 591         if (!empty($lastitem)) {
 592             $makechildof = get_string('makechildof', 'question', $lastitem->name);
 593             $this->icons['right'] = $this->image_icon($makechildof, $this->parentlist->pageurl->out_action(array('right'=>$this->id)), 'right');
 594         } else {
 595             $this->icons['right'] =  $this->image_spacer();
 596         }
 597     }
 598
 599     function image_icon($action, $url, $icon) {
 600         global $CFG;
 601         $pixpath = $CFG->pixpath;
 602         return '<a title="' . $action .'" href="'.$url.'">
 603                 <img src="' . $pixpath . '/t/'.$icon.'.gif" class="iconsmall" alt="' . $action. '" /></a> ';
 604     }
 605
 606     function image_spacer() {
 607         global $CFG;
 608         $pixpath = $CFG->pixpath;
 609         return '<img src="' . $pixpath . '/spacer.gif" class="iconsmall" alt="" />';
 610     }
 611
 612     /**
 613      * Recurse down tree creating list_items, called from moodle_list::list_from_records
 614      *
 615      * @param array $records
 616      * @param array $children
 617      * @param integer $thisrecordid
 618      */
 619     function create_children(&$records, &$children, $thisrecordid) {
 620         //keys where value is $thisrecordid
 621         $thischildren = array_keys($children, $thisrecordid);
 622         if (count($thischildren)) {
 623             foreach ($thischildren as $child) {
 624                 $thisclass = get_class($this);
 625                 $newlistitem =& new $thisclass($records[$child], $this->children, $this->attributes);
 626                 $this->children->add_item($newlistitem);
 627                 $newlistitem->create_children($records, $children, $records[$child]->id);
 628             }
 629         }
 630     }
 631
 632     function set_parent(&$parent) {
 633         $this->parentlist =& $parent;
 634     }
 635 }
 636 ?>