lib/listlib.php

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