[Summary view]

Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 401 and 402]

   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      public abstract 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 = array_keys($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  }