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-2004  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  * @version  $Id$
  38  * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
  39  * @package moodlecore
  40  */
  41
  42
  43 class moodle_list{
  44     var $attributes;
  45     var $listitemclassname = 'list_item';
  46     /**
  47      * An array of $listitemclassname objects.
  48      *
  49      * @var array
  50      */
  51     var $items = array();
  52     /**
  53      * ol / ul
  54      *
  55      * @var string
  56      */
  57     var $type;
  58     /**
  59      *
  60      * @var list_item or derived class
  61      */
  62     var $parentitem = null;
  63     var $table;
  64     var $fieldnamesparent = 'parent';
  65     var $sortby = 'parent, sortorder, name';
  66     /**
  67      * Records from db, only used in top level list.
  68      *
  69      * @var array
  70      */
  71     var $records = array();
  72
  73     var $editable;
  74
  75     /**
  76      * Key is child id, value is parent.
  77      *
  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     /**
 123      * Returns html string.
 124      *
 125      * @param integer $indent depth of indentation.
 126      */
 127     function to_html($indent=0, $extraargs=array()){
 128         if (count($this->items)){
 129             $tabs = str_repeat("\t", $indent);
 130             $first = true;
 131             $itemiter = 1;
 132             $lastitem = '';
 133             $html = '';
 134
 135             foreach ($this->items as $item){
 136                 $last = (count($this->items) == $itemiter);
 137                 if ($this->editable){
 138                     $item->set_icon_html($first, $last, $lastitem);
 139                 }
 140                 if ($itemhtml = $item->to_html($indent+1, $extraargs)){
 141                     $html .= "$tabs\t<li".((!empty($item->attributes))?(' '.$item->attributes):'').">";
 142                     $html .= $itemhtml;
 143                     $html .= "</li>\n";
 144                 }
 145                 $first = false;
 146                 $lastitem = $item;
 147                 $itemiter++;
 148             }
 149         } else {
 150             $html = '';
 151         }
 152         if ($html){ //if there are list items to display then wrap them in ul / ol tag.
 153             $tabs = str_repeat("\t", $indent);
 154             $html = $tabs.'<'.$this->type.((!empty($this->attributes))?(' '.$this->attributes):'').">\n".$html;
 155             $html .= $tabs."</".$this->type.">\n";
 156         } else {
 157             $html ='';
 158         }
 159         return $html;
 160     }
 161
 162     /**
 163      * Recurse down the tree and find an item by it's id.
 164      *
 165      * @param integer $id
 166      * @param boolean $suppresserror error if not item found?
 167      * @return list_item *copy* or null if item is not found
 168      */
 169     function find_item($id, $suppresserror = false){
 170         if (isset($this->items)){
 171             foreach ($this->items as $key => $child){
 172                 if ($child->id == $id){
 173                     return $this->items[$key];
 174                 }
 175             }
 176             foreach (array_keys($this->items) as $key){
 177                 $thischild =& $this->items[$key];
 178                 $ref = $thischild->children->find_item($id, true);//error always reported at top level
 179                 if ($ref !== null){
 180                     return $ref;
 181                 }
 182             }
 183         }
 184
 185         if (!$suppresserror){
 186             print_error('listnoitem');
 187         }
 188         return null;
 189     }
 190
 191
 192
 193     function add_item(&$item){
 194         $this->items[] =& $item;
 195     }
 196
 197     function set_parent(&$parent){
 198         $this->parentitem =& $parent;
 199     }
 200
 201
 202     /**
 203      * Produces a hierarchical tree of list items from a flat array of records.
 204      * 'parent' field is expected to point to a parent record.
 205      * records are already sorted.
 206      * If the parent field doesn't point to another record in the array then this is
 207      * a top level list
 208      *
 209      * @param integer $offset how many list toplevel items are there in lists before this one
 210      * @return integer $offset + how many toplevel items where there in this list.
 211      *
 212      */
 213     function list_from_records($paged = false, $offset =1){
 214         $this->paged = $paged;
 215         $this->offset = $offset;
 216         $this->get_records();
 217         $records = $this->records;
 218         $page = $this->page;
 219         if (!empty($page)) {
 220
 221             $this->firstitem = ($page-1) * $this->itemsperpage + 1;
 222             $this->lastitem = $this->firstitem + $this->itemsperpage - 1;
 223         }
 224         $itemiter = $offset;
 225         //make a simple array which is easier to search
 226         $this->childparent = array();
 227         foreach ($records as $record){
 228             $this->childparent[$record->id] = $record->parent;
 229         }
 230         //create top level list items and they're responsible for creating their children
 231         foreach ($records as $record){
 232             if (!array_key_exists($record->parent, $this->childparent)){
 233                 //if this record is not a child of another record then
 234
 235                 $inpage = ($itemiter >= $this->firstitem && $itemiter <= $this->lastitem);
 236                 //make list item for top level for all items
 237                 //we need the info about the top level items for reordering peers.
 238                 if ($this->parentitem!==null){
 239                     $newattributes = $this->parentitem->attributes;
 240                 } else {
 241                     $newattributes = '';
 242
 243                 }
 244                 $newlistitem =& new $this->listitemclassname($record, $this, $newattributes, $inpage);
 245                 if ($inpage){
 246                     //but don't recurse down the tree for items that are not on this page
 247                     $newlistitem->create_children($records, $this->childparent, $record->id);
 248                 } else {
 249                     $this->paged = true;
 250                 }
 251                 $itemiter++;
 252             }
 253         }
 254         return array($this->paged, $itemiter);
 255     }
 256
 257     /**
 258      * Should be overriden to return an array of records of list items.
 259      *
 260      */
 261     function get_records() {
 262     }
 263
 264     /**
 265      * display list of page numbers for navigation
 266      */
 267     function display_page_numbers() {
 268         $html = '';
 269         $topcount = count($this->items);
 270         $this->pagecount = (integer) ceil(($topcount + $this->offset)/ QUESTION_PAGE_LENGTH );
 271         if (!empty($this->page) && ($this->paged)){
 272             $html = "<div class=\"paging\">".get_string('page').":\n";
 273             foreach (range(1,$this->pagecount) as $currentpage) {
 274                 if ($this->page == $currentpage) {
 275                     $html .= " $currentpage \n";
 276                 }
 277                 else {
 278                     $html .= "<a href=\"".$this->pageurl->out(false, array($this->pageparamname => $currentpage))."\">";
 279                     $html .= " $currentpage </a>\n";
 280                 }
 281             }
 282             $html .= "</div>";
 283         }
 284         return $html;
 285     }
 286
 287     /**
 288      * Returns an array of ids of peers of an item.
 289      *
 290      * @param    int itemid - if given, restrict records to those with this parent id.
 291      * @return   array peer ids
 292      */
 293     function get_items_peers($itemid) {
 294         $itemref = $this->find_item($itemid);
 295         $peerids = $itemref->parentlist->get_child_ids();
 296         return $peerids;
 297     }
 298
 299     /**
 300      * Returns an array of ids of child items.
 301      *
 302      * @return   array peer ids
 303      */
 304     function get_child_ids() {
 305         $childids = array();
 306         foreach ($this->items as $child){
 307            $childids[] = $child->id;
 308         }
 309         return $childids;
 310     }
 311
 312     /**
 313      * Move a record up or down
 314      *
 315      * @param string $direction up / down
 316      * @param integer $id
 317      */
 318     function move_item_up_down($direction, $id) {
 319         $peers = $this->get_items_peers($id);
 320         $itemkey = array_search($id, $peers);
 321         switch ($direction) {
 322             case 'down' :
 323                 if (isset($peers[$itemkey+1])){
 324                     $olditem = $peers[$itemkey+1];
 325                     $peers[$itemkey+1] = $id;
 326                     $peers[$itemkey] = $olditem;
 327                 } else {
 328                     print_error('listcantmoveup');
 329
 330                 }
 331                 break;
 332
 333             case 'up' :
 334                 if (isset($peers[$itemkey-1])){
 335                     $olditem = $peers[$itemkey-1];
 336                     $peers[$itemkey-1] = $id;
 337                     $peers[$itemkey] = $olditem;
 338                 } else {
 339                     print_error('listcantmovedown');
 340                 }
 341                 break;
 342         }
 343         $this->reorder_peers($peers);
 344     }
 345     function reorder_peers($peers){
 346         foreach ($peers as $key => $peer) {
 347             if (! set_field("{$this->table}", "sortorder", $key, "id", $peer)) {
 348                 print_error('listupdatefail');
 349             }
 350         }
 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     }
 372     /**
 373      * Make item with id $id the child of the peer that is just above it in the sort order.
 374      *
 375      * @param integer $id
 376      */
 377     function move_item_right($id) {
 378         $peers = $this->get_items_peers($id);
 379         $itemkey = array_search($id, $peers);
 380         if (!isset($peers[$itemkey-1])){
 381             print_error('listcantmoveright');
 382         } else {
 383             if (!set_field("{$this->table}", "parent", $peers[$itemkey-1], "id", $peers[$itemkey])) {
 384                 print_error('listupdatefail');
 385             } else {
 386                 $newparent = $this->find_item($peers[$itemkey-1]);
 387                 if (isset($newparent->children)){
 388                     $newpeers = $newparent->children->get_child_ids();
 389                 }
 390                 if ($newpeers){
 391                     $newpeers[] = $peers[$itemkey];
 392                     $this->reorder_peers($newpeers);
 393                 }
 394             }
 395         }
 396     }
 397
 398     /**
 399      * process any actions.
 400      *
 401      * @param integer $left id of item to move left
 402      * @param integer $right id of item to move right
 403      * @param integer $moveup id of item to move up
 404      * @param integer $movedown id of item to move down
 405      * @return unknown
 406      */
 407     function process_actions($left, $right, $moveup, $movedown){
 408         //should this action be processed by this list object?
 409         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))){
 410             return false;
 411         }
 412         if (!empty($left)) {
 413             $this->move_item_left($left);
 414         } else if (!empty($right)) {
 415             $this->move_item_right($right);
 416         } else if (!empty($moveup)) {
 417             $this->move_item_up_down('up', $moveup);
 418             if ($moveup == $this->items[$this->firstitem -1]->id){//redirect to page that item has been moved to.
 419                 $this->page --;
 420                 $this->pageurl->params(array($this->pageparamname => $this->page));
 421             }
 422         } else if (!empty($movedown)) {
 423             $this->move_item_up_down('down', $movedown);
 424             if ($movedown == $this->items[$this->lastitem -1]->id){//redirect to page that item has been moved to.
 425                 $this->page ++;
 426                 $this->pageurl->params(array($this->pageparamname => $this->page));
 427             }
 428         } else {
 429             return false;
 430         }
 431
 432         redirect($this->pageurl->out());
 433     }
 434 }
 435
 436 class list_item{
 437     /**
 438      * id of record, used if list is editable
 439      *
 440      * @var integer
 441      */
 442     var $id;
 443     /**
 444      * name of this item, used if list is editable
 445      *
 446      * @var string
 447      */
 448     var $name;
 449     /**
 450      * The object or string representing this item.
 451      *
 452      * @var mixed
 453      */
 454     var $item;
 455     var $fieldnamesname = 'name';
 456     var $attributes;
 457     var $display;
 458     var $icons = array();
 459     /**
 460      *
 461      * @var moodle_list
 462      */
 463     var $parentlist;
 464     /**
 465      * Set if there are any children of this listitem.
 466      *
 467      * @var moodle_list
 468      */
 469     var $children;
 470     /**
 471      * Constructor
 472      *
 473      * @param mixed $item fragment of html for list item or record
 474      * @param object &$parent reference to parent of this item
 475      * @param string $attributes attributes for li tag
 476      * @param boolean $display whether this item is displayed. Some items may be loaded so we have a complete
 477      *                              structure in memory to work with for actions but are not displayed.
 478      * @return list_item
 479      */
 480     function list_item($item, &$parent, $attributes='', $display = true){
 481         $this->item = $item;
 482         if (is_object($this->item)) {
 483             $this->id = $this->item->id;
 484             $this->name = $this->item->{$this->fieldnamesname};
 485         }
 486         $this->set_parent($parent);
 487         $this->attributes = $attributes;
 488         $parentlistclass = get_class($parent);
 489         $this->children =& new $parentlistclass($parent->type, $parent->attributes, $parent->editable, $parent->pageurl, 0);
 490         $this->children->set_parent($this);
 491         $this->display = $display;
 492     }
 493     /**
 494      * Output the html just for this item. Called by to_html which adds html for children.
 495      *
 496      */
 497     function item_html($extraargs = array()){
 498         if (is_string($this->item)){
 499             $html = $this->item;
 500         } elseif (is_object($this->item)) {
 501             //for debug purposes only. You should create a sub class to
 502             //properly handle the record
 503             $html = join(', ', (array)$this->item);
 504         }
 505         return $html;
 506     }
 507     /**
 508      * Returns html
 509      *
 510      * @param integer $indent
 511      * @param array $extraargs any extra data that is needed to print the list item
 512      *                            may be used by sub class.
 513      * @return string html
 514      */
 515     function to_html($indent=0, $extraargs = array()){
 516         if (!$this->display){
 517             return '';
 518         }
 519         $tabs = str_repeat("\t", $indent);
 520
 521         if (isset($this->children)){
 522             $childrenhtml = $this->children->to_html($indent+1, $extraargs);
 523         } else {
 524             $childrenhtml = '';
 525         }
 526         return $this->item_html($extraargs).'&nbsp;'.(join($this->icons, '')).(($childrenhtml !='')?("\n".$childrenhtml):'');
 527     }
 528
 529     function set_icon_html($first, $last, &$lastitem){
 530         global $CFG;
 531         $strmoveup = get_string('moveup');
 532         $strmovedown = get_string('movedown');
 533         $strmoveleft = get_string('maketoplevelitem', 'question');
 534         $pixpath = $CFG->pixpath;
 535
 536         if (isset($this->parentlist->parentitem)) {
 537             $parentitem =& $this->parentlist->parentitem;
 538             if (isset($parentitem->parentlist->parentitem)){
 539                 $action = get_string('makechildof', 'question', $parentitem->parentlist->parentitem->name);
 540             } else {
 541                 $action = $strmoveleft;
 542             }
 543             $this->icons['left'] = $this->image_icon($action, $this->parentlist->pageurl->out_action(array('left'=>$this->id)), 'left');
 544         } else {
 545             $this->icons['left'] =  $this->image_spacer();
 546         }
 547
 548         if (!$first) {
 549             $this->icons['up'] = $this->image_icon($strmoveup, $this->parentlist->pageurl->out_action(array('moveup'=>$this->id)), 'up');
 550         } else {
 551             $this->icons['up'] =  $this->image_spacer();
 552         }
 553
 554         if (!$last) {
 555             $this->icons['down'] = $this->image_icon($strmovedown, $this->parentlist->pageurl->out_action(array('movedown'=>$this->id)), 'down');
 556         } else {
 557             $this->icons['down'] =  $this->image_spacer();
 558         }
 559
 560         if (!empty($lastitem)) {
 561             $makechildof = get_string('makechildof', 'question', $lastitem->name);
 562             $this->icons['right'] = $this->image_icon($makechildof, $this->parentlist->pageurl->out_action(array('right'=>$this->id)), 'right');
 563         } else {
 564             $this->icons['right'] =  $this->image_spacer();
 565         }
 566
 567     }
 568     function image_icon($action, $url, $icon){
 569         global $CFG;
 570         $pixpath = $CFG->pixpath;
 571         return '<a title="' . $action .'" href="'.$url.'">
 572                 <img src="' . $pixpath . '/t/'.$icon.'.gif" class="iconsmall" alt="' . $action. '" /></a> ';
 573     }
 574     function image_spacer(){
 575         global $CFG;
 576         $pixpath = $CFG->pixpath;
 577         return '<img src="' . $pixpath . '/spacer.gif" class="iconsmall" alt="" />';
 578     }
 579     /**
 580      * Recurse down tree creating list_items, called from moodle_list::list_from_records
 581      *
 582      * @param array $records
 583      * @param array $children
 584      * @param integer $thisrecordid
 585      */
 586     function create_children(&$records, &$children, $thisrecordid){
 587         //keys where value is $thisrecordid
 588         $thischildren = array_keys($children, $thisrecordid);
 589         if (count($thischildren)){
 590             foreach ($thischildren as $child){
 591                 $thisclass = get_class($this);
 592                 $newlistitem =& new $thisclass($records[$child], $this->children, $this->attributes);
 593                 $newlistitem->create_children($records, $children, $records[$child]->id);
 594             }
 595         }
 596     }
 597     function set_parent(&$parent){
 598         $this->parentlist =& $parent;
 599         $parent->add_item($this);
 600     }
 601
 602 }
 603 ?>