[Sommaire] [Imprimer]

   1  <?php
   2  /**
   3   * TPager class file.
   4   *
   5   * @author Qiang Xue <qiang.xue@gmail.com>
   6   * @link http://www.pradosoft.com/
   7   * @copyright Copyright &copy; 2005 PradoSoft
   8   * @license http://www.pradosoft.com/license/
   9   * @version $Id: TPager.php 1515 2006-11-26 20:09:44Z xue $
  10   * @package System.Web.UI.WebControls
  11   */
  12  
  13  /**
  14   * TPager class.
  15   *
  16   * TPager creates a pager that provides UI for end-users to interactively
  17   * specify which page of data to be rendered in a {@link TDataBoundControl}-derived control,
  18   * such as {@link TDataList}, {@link TRepeater}, {@link TCheckBoxList}, etc.
  19   * The target data-bound control is specified by {@link setControlToPaginate ControlToPaginate},
  20   * which must be the ID path of the target control reaching from the pager's
  21   * naming container. Note, the target control must have its {@link TDataBoundControl::setAllowPaging AllowPaging}
  22   * set to true.
  23   *
  24   * TPager can display three different UIs, specified via {@link setMode Mode}:
  25   * - NextPrev: a next page and a previous page button are rendered.
  26   * - Numeric: a list of page index buttons are rendered.
  27   * - List: a dropdown list of page indices are rendered.
  28   *
  29   * TPager raises an {@link onPageIndexChanged OnPageIndexChanged} event when
  30   * the end-user interacts with it and specifies a new page (e.g. clicking
  31   * on a page button that leads to a new page.) The new page index may be obtained
  32   * from the event parameter's property {@link TPagerPageChangedEventParameter::getNewPageIndex NewPageIndex}.
  33   * Normally, in the event handler, one can set the {@link TDataBoundControl::getCurrentPageIndex CurrentPageIndex}
  34   * to this new page index so that the new page of data is rendered.
  35   *
  36   * Multiple pagers can be associated with the same data-bound control.
  37   *
  38   * @author Qiang Xue <qiang.xue@gmail.com>
  39   * @version $Id: TPager.php 1515 2006-11-26 20:09:44Z xue $
  40   * @package System.Web.UI.WebControls
  41   * @since 3.0.2
  42   */
  43  class TPager extends TWebControl implements INamingContainer
  44  {
  45      /**
  46       * Command name that TPager understands.
  47       */
  48      const CMD_PAGE='Page';
  49      const CMD_PAGE_NEXT='Next';
  50      const CMD_PAGE_PREV='Previous';
  51      const CMD_PAGE_FIRST='First';
  52      const CMD_PAGE_LAST='Last';
  53  
  54      private $_pageCount=0;
  55  
  56      /**
  57       * Restores the pager state.
  58       * This method overrides the parent implementation and is invoked when
  59       * the control is loading persistent state.
  60       */
  61  	public function loadState()
  62      {
  63          parent::loadState();
  64          if($this->getEnableViewState(true))
  65          {
  66              $this->getControls()->clear();
  67              $this->buildPager();
  68          }
  69      }
  70  
  71      /**
  72       * @return string the ID path of the control whose content would be paginated.
  73       */
  74  	public function getControlToPaginate()
  75      {
  76          return $this->getViewState('ControlToPaginate','');
  77      }
  78  
  79      /**
  80       * Sets the ID path of the control whose content would be paginated.
  81       * The ID path is the dot-connected IDs of the controls reaching from
  82       * the pager's naming container to the target control.
  83       * @param string the ID path
  84       */
  85  	public function setControlToPaginate($value)
  86      {
  87          $this->setViewState('ControlToPaginate',$value,'');
  88      }
  89  
  90      /**
  91       * @return TPagerMode pager mode. Defaults to TPagerMode::NextPrev.
  92       */
  93  	public function getMode()
  94      {
  95          return $this->getViewState('Mode',TPagerMode::NextPrev);
  96      }
  97  
  98      /**
  99       * @param TPagerMode pager mode.
 100       */
 101  	public function setMode($value)
 102      {
 103          $this->setViewState('Mode',TPropertyValue::ensureEnum($value,'TPagerMode'),TPagerMode::NextPrev);
 104      }
 105  
 106      /**
 107       * @return TPagerButtonType the type of command button for paging. Defaults to TPagerButtonType::LinkButton.
 108       */
 109  	public function getButtonType()
 110      {
 111          return $this->getViewState('ButtonType',TPagerButtonType::LinkButton);
 112      }
 113  
 114      /**
 115       * @param TPagerButtonType the type of command button for paging.
 116       */
 117  	public function setButtonType($value)
 118      {
 119          $this->setViewState('ButtonType',TPropertyValue::ensureEnum($value,'TPagerButtonType'),TPagerButtonType::LinkButton);
 120      }
 121  
 122      /**
 123       * @return string text for the next page button. Defaults to '>'.
 124       */
 125  	public function getNextPageText()
 126      {
 127          return $this->getViewState('NextPageText','>');
 128      }
 129  
 130      /**
 131       * @param string text for the next page button.
 132       */
 133  	public function setNextPageText($value)
 134      {
 135          $this->setViewState('NextPageText',$value,'>');
 136      }
 137  
 138      /**
 139       * @return string text for the previous page button. Defaults to '<'.
 140       */
 141  	public function getPrevPageText()
 142      {
 143          return $this->getViewState('PrevPageText','<');
 144      }
 145  
 146      /**
 147       * @param string text for the next page button.
 148       */
 149  	public function setPrevPageText($value)
 150      {
 151          $this->setViewState('PrevPageText',$value,'<');
 152      }
 153  
 154      /**
 155       * @return string text for the first page button. Defaults to '<<'.
 156       */
 157  	public function getFirstPageText()
 158      {
 159          return $this->getViewState('FirstPageText','<<');
 160      }
 161  
 162      /**
 163       * @param string text for the first page button. If empty, the first page button will not be rendered.
 164       */
 165  	public function setFirstPageText($value)
 166      {
 167          $this->setViewState('FirstPageText',$value,'<<');
 168      }
 169  
 170      /**
 171       * @return string text for the last page button. Defaults to '>>'.
 172       */
 173  	public function getLastPageText()
 174      {
 175          return $this->getViewState('LastPageText','>>');
 176      }
 177  
 178      /**
 179       * @param string text for the last page button. If empty, the last page button will not be rendered.
 180       */
 181  	public function setLastPageText($value)
 182      {
 183          $this->setViewState('LastPageText',$value,'>>');
 184      }
 185  
 186      /**
 187       * @return integer maximum number of pager buttons to be displayed. Defaults to 10.
 188       */
 189  	public function getPageButtonCount()
 190      {
 191          return $this->getViewState('PageButtonCount',10);
 192      }
 193  
 194      /**
 195       * @param integer maximum number of pager buttons to be displayed
 196       * @throws TInvalidDataValueException if the value is less than 1.
 197       */
 198  	public function setPageButtonCount($value)
 199      {
 200          if(($value=TPropertyValue::ensureInteger($value))<1)
 201              throw new TInvalidDataValueException('pager_pagebuttoncount_invalid');
 202          $this->setViewState('PageButtonCount',$value,10);
 203      }
 204  
 205      /**
 206       * @return integer the zero-based index of the current page. Defaults to 0.
 207       */
 208  	public function getCurrentPageIndex()
 209      {
 210          return $this->getViewState('CurrentPageIndex',0);
 211      }
 212  
 213      /**
 214       * @param integer the zero-based index of the current page
 215       * @throws TInvalidDataValueException if the value is less than 0
 216       */
 217  	protected function setCurrentPageIndex($value)
 218      {
 219          if(($value=TPropertyValue::ensureInteger($value))<0)
 220              throw new TInvalidDataValueException('pager_currentpageindex_invalid');
 221          $this->setViewState('CurrentPageIndex',$value,0);
 222      }
 223  
 224      /**
 225       * @return integer number of pages of data items available
 226       */
 227  	public function getPageCount()
 228      {
 229          return $this->getViewState('PageCount',0);
 230      }
 231  
 232      /**
 233       * @param integer number of pages of data items available
 234       * @throws TInvalidDataValueException if the value is less than 0
 235       */
 236  	protected function setPageCount($value)
 237      {
 238          if(($value=TPropertyValue::ensureInteger($value))<0)
 239              throw new TInvalidDataValueException('pager_pagecount_invalid');
 240          $this->setViewState('PageCount',$value,0);
 241      }
 242  
 243      /**
 244       * @return boolean whether the current page is the first page Defaults to false.
 245       */
 246  	public function getIsFirstPage()
 247      {
 248          return $this->getCurrentPageIndex()===0;
 249      }
 250  
 251      /**
 252       * @return boolean whether the current page is the last page
 253       */
 254  	public function getIsLastPage()
 255      {
 256          return $this->getCurrentPageIndex()===$this->getPageCount()-1;
 257      }
 258  
 259      /**
 260       * Performs databinding to populate data items from data source.
 261       * This method is invoked by {@link dataBind()}.
 262       * You may override this function to provide your own way of data population.
 263       * @param Traversable the bound data
 264       */
 265  	public function onPreRender($param)
 266      {
 267          parent::onPreRender($param);
 268  
 269          $controlID=$this->getControlToPaginate();
 270          if(($targetControl=$this->getNamingContainer()->findControl($controlID))===null || !($targetControl instanceof TDataBoundControl))
 271              throw new TConfigurationException('pager_controltopaginate_invalid',$controlID);
 272  
 273          if($targetControl->getAllowPaging())
 274          {
 275               $this->_pageCount=$targetControl->getPageCount();
 276              $this->getControls()->clear();
 277              $this->setPageCount($targetControl->getPageCount());
 278              $this->setCurrentPageIndex($targetControl->getCurrentPageIndex());
 279              $this->buildPager();
 280          }
 281          else
 282              $this->_pageCount=0;
 283      }
 284  
 285      /**
 286       * Renders the control.
 287       * The method overrides the parent implementation by rendering
 288       * the pager only when there are two or more pages.
 289       * @param THtmlWriter the writer
 290       */
 291  	public function render($writer)
 292      {
 293          if($this->_pageCount>1)
 294              parent::render($writer);
 295      }
 296  
 297      /**
 298       * Builds the pager content based on the pager mode.
 299       * Current implementation includes building 'NextPrev', 'Numeric' and 'DropDownList' pagers.
 300       * Derived classes may override this method to provide additional pagers.
 301       */
 302  	protected function buildPager()
 303      {
 304          switch($this->getMode())
 305          {
 306              case TPagerMode::NextPrev:
 307                  $this->buildNextPrevPager();
 308                  break;
 309              case TPagerMode::Numeric:
 310                  $this->buildNumericPager();
 311                  break;
 312              case TPagerMode::DropDownList:
 313                  $this->buildListPager();
 314                  break;
 315          }
 316      }
 317  
 318      /**
 319       * Creates a pager button.
 320       * Depending on the button type, a TLinkButton or a TButton may be created.
 321       * If it is enabled (clickable), its command name and parameter will also be set.
 322       * Derived classes may override this method to create additional types of buttons, such as TImageButton.
 323       * @param string button type, either LinkButton or PushButton
 324       * @param boolean whether the button should be enabled
 325       * @param string caption of the button
 326       * @param string CommandName corresponding to the OnCommand event of the button
 327       * @param string CommandParameter corresponding to the OnCommand event of the button
 328       * @return mixed the button instance
 329       */
 330  	protected function createPagerButton($buttonType,$enabled,$text,$commandName,$commandParameter)
 331      {
 332          if($buttonType===TPagerButtonType::LinkButton)
 333          {
 334              if($enabled)
 335                  $button=new TLinkButton;
 336              else
 337              {
 338                  $button=new TLabel;
 339                  $button->setText($text);
 340                  return $button;
 341              }
 342          }
 343          else
 344          {
 345              $button=new TButton;
 346              if(!$enabled)
 347                  $button->setEnabled(false);
 348          }
 349          $button->setText($text);
 350          $button->setCommandName($commandName);
 351          $button->setCommandParameter($commandParameter);
 352          $button->setCausesValidation(false);
 353          return $button;
 354      }
 355  
 356      /**
 357       * Builds a next-prev pager
 358       */
 359  	protected function buildNextPrevPager()
 360      {
 361          $buttonType=$this->getButtonType();
 362          $controls=$this->getControls();
 363          if($this->getIsFirstPage())
 364          {
 365              if(($text=$this->getFirstPageText())!=='')
 366              {
 367                  $label=$this->createPagerButton($buttonType,false,$text,'','');
 368                  $controls->add($label);
 369                  $controls->add("\n");
 370              }
 371              $label=$this->createPagerButton($buttonType,false,$this->getPrevPageText(),'','');
 372              $controls->add($label);
 373          }
 374          else
 375          {
 376              if(($text=$this->getFirstPageText())!=='')
 377              {
 378                  $button=$this->createPagerButton($buttonType,true,$text,self::CMD_PAGE_FIRST,'');
 379                  $controls->add($button);
 380                  $controls->add("\n");
 381              }
 382              $button=$this->createPagerButton($buttonType,true,$this->getPrevPageText(),self::CMD_PAGE_PREV,'');
 383              $controls->add($button);
 384          }
 385          $controls->add("\n");
 386          if($this->getIsLastPage())
 387          {
 388              $label=$this->createPagerButton($buttonType,false,$this->getNextPageText(),'','');
 389              $controls->add($label);
 390              if(($text=$this->getLastPageText())!=='')
 391              {
 392                  $controls->add("\n");
 393                  $label=$this->createPagerButton($buttonType,false,$text,'','');
 394                  $controls->add($label);
 395              }
 396          }
 397          else
 398          {
 399              $button=$this->createPagerButton($buttonType,true,$this->getNextPageText(),self::CMD_PAGE_NEXT,'');
 400              $controls->add($button);
 401              if(($text=$this->getLastPageText())!=='')
 402              {
 403                  $controls->add("\n");
 404                  $button=$this->createPagerButton($buttonType,true,$text,self::CMD_PAGE_LAST,'');
 405                  $controls->add($button);
 406              }
 407          }
 408      }
 409  
 410      /**
 411       * Builds a numeric pager
 412       */
 413  	protected function buildNumericPager()
 414      {
 415          $buttonType=$this->getButtonType();
 416          $controls=$this->getControls();
 417          $pageCount=$this->getPageCount();
 418          $pageIndex=$this->getCurrentPageIndex()+1;
 419          $maxButtonCount=$this->getPageButtonCount();
 420          $buttonCount=$maxButtonCount>$pageCount?$pageCount:$maxButtonCount;
 421          $startPageIndex=1;
 422          $endPageIndex=$buttonCount;
 423          if($pageIndex>$endPageIndex)
 424          {
 425              $startPageIndex=((int)(($pageIndex-1)/$maxButtonCount))*$maxButtonCount+1;
 426              if(($endPageIndex=$startPageIndex+$maxButtonCount-1)>$pageCount)
 427                  $endPageIndex=$pageCount;
 428              if($endPageIndex-$startPageIndex+1<$maxButtonCount)
 429              {
 430                  if(($startPageIndex=$endPageIndex-$maxButtonCount+1)<1)
 431                      $startPageIndex=1;
 432              }
 433          }
 434  
 435          if($startPageIndex>1)
 436          {
 437              if(($text=$this->getFirstPageText())!=='')
 438              {
 439                  $button=$this->createPagerButton($buttonType,true,$text,self::CMD_PAGE_FIRST,'');
 440                  $controls->add($button);
 441                  $controls->add("\n");
 442              }
 443              $prevPageIndex=$startPageIndex-1;
 444              $button=$this->createPagerButton($buttonType,true,$this->getPrevPageText(),self::CMD_PAGE,"$prevPageIndex");
 445              $controls->add($button);
 446              $controls->add("\n");
 447          }
 448  
 449          for($i=$startPageIndex;$i<=$endPageIndex;++$i)
 450          {
 451              if($i===$pageIndex)
 452              {
 453                  $label=$this->createPagerButton($buttonType,false,"$i",'','');
 454                  $controls->add($label);
 455              }
 456              else
 457              {
 458                  $button=$this->createPagerButton($buttonType,true,"$i",self::CMD_PAGE,"$i");
 459                  $controls->add($button);
 460              }
 461              if($i<$endPageIndex)
 462                  $controls->add("\n");
 463          }
 464  
 465          if($pageCount>$endPageIndex)
 466          {
 467              $controls->add("\n");
 468              $nextPageIndex=$endPageIndex+1;
 469              $button=$this->createPagerButton($buttonType,true,$this->getNextPageText(),self::CMD_PAGE,"$nextPageIndex");
 470              $controls->add($button);
 471              if(($text=$this->getLastPageText())!=='')
 472              {
 473                  $controls->add("\n");
 474                  $button=$this->createPagerButton($buttonType,true,$text,self::CMD_PAGE_LAST,'');
 475                  $controls->add($button);
 476              }
 477          }
 478      }
 479  
 480      /**
 481       * Builds a dropdown list pager
 482       */
 483  	protected function buildListPager()
 484      {
 485          $list=new TDropDownList;
 486          $this->getControls()->add($list);
 487          $list->setDataSource(range(1,$this->getPageCount()));
 488          $list->dataBind();
 489          $list->setSelectedIndex($this->getCurrentPageIndex());
 490          $list->setAutoPostBack(true);
 491          $list->attachEventHandler('OnSelectedIndexChanged',array($this,'listIndexChanged'));
 492      }
 493  
 494      /**
 495       * Event handler to the OnSelectedIndexChanged event of the dropdown list.
 496       * This handler will raise {@link onPageIndexChanged OnPageIndexChanged} event.
 497       * @param TDropDownList the dropdown list control raising the event
 498       * @param TEventParameter event parameter
 499       */
 500  	public function listIndexChanged($sender,$param)
 501      {
 502          $pageIndex=$sender->getSelectedIndex();
 503          $this->onPageIndexChanged(new TPagerPageChangedEventParameter($sender,$pageIndex));
 504      }
 505  
 506      /**
 507       * This event is raised when page index is changed due to a page button click.
 508       * @param TPagerPageChangedEventParameter event parameter
 509       */
 510  	public function onPageIndexChanged($param)
 511      {
 512          $this->raiseEvent('OnPageIndexChanged',$this,$param);
 513      }
 514  
 515      /**
 516       * Processes a bubbled event.
 517       * This method overrides parent's implementation by wrapping event parameter
 518       * for <b>OnCommand</b> event with item information.
 519       * @param TControl the sender of the event
 520       * @param TEventParameter event parameter
 521       * @return boolean whether the event bubbling should stop here.
 522       */
 523  	public function bubbleEvent($sender,$param)
 524      {
 525          if($param instanceof TCommandEventParameter)
 526          {
 527              $command=$param->getCommandName();
 528              if(strcasecmp($command,self::CMD_PAGE)===0)
 529              {
 530                  $pageIndex=TPropertyValue::ensureInteger($param->getCommandParameter())-1;
 531                  $this->onPageIndexChanged(new TPagerPageChangedEventParameter($sender,$pageIndex));
 532                  return true;
 533              }
 534              else if(strcasecmp($command,self::CMD_PAGE_NEXT)===0)
 535              {
 536                  $pageIndex=$this->getCurrentPageIndex()+1;
 537                  $this->onPageIndexChanged(new TPagerPageChangedEventParameter($sender,$pageIndex));
 538                  return true;
 539              }
 540              else if(strcasecmp($command,self::CMD_PAGE_PREV)===0)
 541              {
 542                  $pageIndex=$this->getCurrentPageIndex()-1;
 543                  $this->onPageIndexChanged(new TPagerPageChangedEventParameter($sender,$pageIndex));
 544                  return true;
 545              }
 546              else if(strcasecmp($command,self::CMD_PAGE_FIRST)===0)
 547              {
 548                  $this->onPageIndexChanged(new TPagerPageChangedEventParameter($sender,0));
 549                  return true;
 550              }
 551              else if(strcasecmp($command,self::CMD_PAGE_LAST)===0)
 552              {
 553                  $this->onPageIndexChanged(new TPagerPageChangedEventParameter($sender,$this->getPageCount()-1));
 554                  return true;
 555              }
 556              return false;
 557          }
 558          else
 559              return false;
 560      }
 561  }
 562  
 563  /**
 564   * TPagerPageChangedEventParameter class
 565   *
 566   * TPagerPageChangedEventParameter encapsulates the parameter data for
 567   * {@link TPager::onPageIndexChanged PageIndexChanged} event of {@link TPager} controls.
 568   *
 569   * The {@link getCommandSource CommandSource} property refers to the control
 570   * that originally raises the OnCommand event, while {@link getNewPageIndex NewPageIndex}
 571   * returns the new page index carried with the page command.
 572   *
 573   * @author Qiang Xue <qiang.xue@gmail.com>
 574   * @version $Id: TPager.php 1515 2006-11-26 20:09:44Z xue $
 575   * @package System.Web.UI.WebControls
 576   * @since 3.0.2
 577   */
 578  class TPagerPageChangedEventParameter extends TEventParameter
 579  {
 580      /**
 581       * @var integer new page index
 582       */
 583      private $_newIndex;
 584      /**
 585       * @var TControl original event sender
 586       */
 587      private $_source=null;
 588  
 589      /**
 590       * Constructor.
 591       * @param TControl the control originally raises the <b>OnCommand</b> event.
 592       * @param integer new page index
 593       */
 594  	public function __construct($source,$newPageIndex)
 595      {
 596          $this->_source=$source;
 597          $this->_newIndex=$newPageIndex;
 598      }
 599  
 600      /**
 601       * @return TControl the control originally raises the <b>OnCommand</b> event.
 602       */
 603  	public function getCommandSource()
 604      {
 605          return $this->_source;
 606      }
 607  
 608      /**
 609       * @return integer new page index
 610       */
 611  	public function getNewPageIndex()
 612      {
 613          return $this->_newIndex;
 614      }
 615  }
 616  
 617  
 618  /**
 619   * TPagerMode class.
 620   * TPagerMode defines the enumerable type for the possible modes that a {@link TPager} control can take.
 621   *
 622   * The following enumerable values are defined:
 623   * - NextPrev: pager buttons are displayed as next and previous pages
 624   * - Numeric: pager buttons are displayed as numeric page numbers
 625   * - DropDownList: a dropdown list is used to select pages
 626   *
 627   * @author Qiang Xue <qiang.xue@gmail.com>
 628   * @version $Id: TPager.php 1515 2006-11-26 20:09:44Z xue $
 629   * @package System.Web.UI.WebControls
 630   * @since 3.0.4
 631   */
 632  class TPagerMode extends TEnumerable
 633  {
 634      const NextPrev='NextPrev';
 635      const Numeric='Numeric';
 636      const DropDownList='DropDownList';
 637  }
 638  
 639  
 640  /**
 641   * TPagerButtonType class.
 642   * TPagerButtonType defines the enumerable type for the possible types of pager buttons.
 643   *
 644   * The following enumerable values are defined:
 645   * - LinkButton: link buttons
 646   * - PushButton: form submit buttons
 647   *
 648   * @author Qiang Xue <qiang.xue@gmail.com>
 649   * @version $Id: TPager.php 1515 2006-11-26 20:09:44Z xue $
 650   * @package System.Web.UI.WebControls
 651   * @since 3.0.4
 652   */
 653  class TPagerButtonType extends TEnumerable
 654  {
 655      const LinkButton='LinkButton';
 656      const PushButton='PushButton';
 657  }
 658  
 659  ?>