## Class TPager

Description

Implements interfaces:

- INamingContainer

TPager class.

TPager creates a pager that provides UI for end-users to interactively specify which page of data to be rendered in a TDataBoundControl-derived control, such as TDataList, TRepeater, TCheckBoxList, etc. The target data-bound control is specified by ControlToPaginate, which must be the ID path of the target control reaching from the pager's naming container. Note, the target control must have its TDataBoundControl::setAllowPaging set to true.

TPager can display three different UIs, specified via Mode:

- NextPrev: a next page and a previous page button are rendered.
- Numeric: a list of page index buttons are rendered.
- List: a dropdown list of page indices are rendered.

When the pager mode is either NextPrev or Numeric, the paging buttons may be displayed in three types by setting ButtonType:

- LinkButton: a hyperlink button
- PushButton: a normal button
- ImageButton: an image button (please set XXXPageImageUrl properties accordingly to specify the button images.)

TPager raises an OnPageIndexChanged event when the end-user interacts with it and specifies a new page (e.g. clicking on a page button that leads to a new page.) The new page index may be obtained from the event parameter's property TPagerPageChangedEventParameter::getNewPageIndex. Normally, in the event handler, one can set the TDataBoundControl::getCurrentPageIndex to this new page index so that the new page of data is rendered.

Multiple pagers can be associated with the same data-bound control.

- since: 3.0.2
- version: $Id: TPager.php 2541 2008-10-21 15:05:13Z qiang.xue $
- author: Qiang Xue <qiang.xue@gmail.com>

Located in /Web/UI/WebControls/TPager.php (line 49)

    TComponent
       |
       --TApplicationComponent
          |
          --TControl
             |
             --TWebControl
                |
                --TPager

Direct descendents

Class | Description
--- | ---
TActivePager | TActivePager is the active control counter part of TPager.

Class Constant Summary
CMD_PAGE = 'Page'
CMD_PAGE_FIRST = 'First'
CMD_PAGE_LAST = 'Last'
CMD_PAGE_NEXT = 'Next'
CMD_PAGE_PREV = 'Previous'
Method Summary
boolean bubbleEvent (TControl $sender, TEventParameter $param)
void buildListPager ()
void buildNextPrevPager ()
void buildNumericPager ()
void buildPager ()
mixed createPagerButton (string $buttonType, boolean $enabled, string $text, string $commandName, string $commandParameter)
TPagerButtonType getButtonType ()
string getControlToPaginate ()
integer getCurrentPageIndex ()
string getFirstPageImageUrl ()
string getFirstPageText ()
boolean getIsFirstPage ()
boolean getIsLastPage ()
string getLastPageImageUrl ()
string getLastPageText ()
TPagerMode getMode ()
string getNextPageImageUrl ()
string getNextPageText ()
string getNumericPageImageUrl ()
integer getPageButtonCount ()
integer getPageCount ()
void getPageImageUrl (string $text, string $commandName)
string getPrevPageImageUrl ()
string getPrevPageText ()
void listIndexChanged (TDropDownList $sender, TEventParameter $param)
void loadState ()
void onPageIndexChanged (TPagerPageChangedEventParameter $param)
void onPreRender (Traversable $param)
void render (THtmlWriter $writer)
void setButtonType (TPagerButtonType $value)
void setControlToPaginate (string $value)
void setCurrentPageIndex (integer $value)
void setFirstPageImageUrl (string $value)
void setFirstPageText (string $value)
void setLastPageImageUrl (string $value)
void setLastPageText (string $value)
void setMode (TPagerMode $value)
void setNextPageImageUrl (string $value)
void setNextPageText (string $value)
void setNumericPageImageUrl (string $value)
void setPageButtonCount (integer $value)
void setPageCount (integer $value)
void setPrevPageImageUrl (string $value)
void setPrevPageText (string $value)
Methods
bubbleEvent (line 656)

Processes a bubbled event.

This method overrides parent's implementation by wrapping event parameter for OnCommand event with item information.

- return: whether the event bubbling should stop here.
- access: public

boolean bubbleEvent (TControl $sender, TEventParameter $param)

- TControl $sender: the sender of the event
- TEventParameter $param: event parameter

Redefinition of:

TControl::bubbleEvent()
  This method responds to a bubbled event.

buildListPager (line 616)

Builds a dropdown list pager

- access: protected

void buildListPager ()

Redefined in descendants as:

- TActivePager::buildListPager() : Builds a dropdown list pager Override parent implementation to build Active dropdown lists.

buildNextPrevPager (line 492)

Builds a next-prev pager

- access: protected

void buildNextPrevPager ()
buildNumericPager (line 546)

Builds a numeric pager

- access: protected

void buildNumericPager ()
buildPager (line 404)

Builds the pager content based on the pager mode.

Current implementation includes building 'NextPrev', 'Numeric' and 'DropDownList' pagers. Derived classes may override this method to provide additional pagers.

- access: protected

void buildPager ()
createPagerButton (line 432)

Creates a pager button.

Depending on the button type, a TLinkButton or a TButton may be created. If it is enabled (clickable), its command name and parameter will also be set. Derived classes may override this method to create additional types of buttons, such as TImageButton.

- return: the button instance
- access: protected

mixed createPagerButton (string $buttonType, boolean $enabled, string $text, string $commandName, string $commandParameter)

- string $buttonType: button type, either LinkButton or PushButton
- boolean $enabled: whether the button should be enabled
- string $text: caption of the button.
- string $commandName: CommandName corresponding to the OnCommand event of the button.
- string $commandParameter: CommandParameter corresponding to the OnCommand event of the button

Redefined in descendants as:

- TActivePager::createPagerButton() : Creates a pager button.

getButtonType (line 115)

- return: the type of command button for paging. Defaults to TPagerButtonType::LinkButton.
- access: public

TPagerButtonType getButtonType ()
getControlToPaginate (line 80)

- return: the ID path of the control whose content would be paginated.
- access: public

string getControlToPaginate ()
getCurrentPageIndex (line 310)

- return: the zero-based index of the current page. Defaults to 0.
- access: public

integer getCurrentPageIndex ()
getFirstPageImageUrl (line 196)

- return: the image URL for the first page button. This is only used when ButtonType is 'ImageButton'.
- access: public
- since: 3.1.1

string getFirstPageImageUrl ()
getFirstPageText (line 163)

- return: text for the first page button. Defaults to ''.
- access: public

string getFirstPageText ()
getIsFirstPage (line 348)

- return: whether the current page is the first page Defaults to false.
- access: public

boolean getIsFirstPage ()
getIsLastPage (line 356)

- return: whether the current page is the last page
- access: public

boolean getIsLastPage ()
getLastPageImageUrl (line 214)

- return: the image URL for the last page button. This is only used when ButtonType is 'ImageButton'.
- access: public
- since: 3.1.1

string getLastPageImageUrl ()
getLastPageText (line 179)

- return: text for the last page button. Defaults to '>>'.
- access: public

string getLastPageText ()
getMode (line 99)

- return: pager mode. Defaults to TPagerMode::NextPrev.
- access: public

TPagerMode getMode ()
getNextPageImageUrl (line 232)

- return: the image URL for the next page button. This is only used when ButtonType is 'ImageButton'.
- access: public
- since: 3.1.1

string getNextPageImageUrl ()
getNextPageText (line 131)

- return: text for the next page button. Defaults to '>'.
- access: public

string getNextPageText ()
getNumericPageImageUrl (line 269)

- return: the image URL for the numeric page buttons. This is only used when ButtonType is 'ImageButton' and Mode is 'Numeric'.
- access: public
- since: 3.1.1
- see: TPager::setNumericPageImageUrl()

string getNumericPageImageUrl ()
getPageButtonCount (line 291)

- return: maximum number of pager buttons to be displayed. Defaults to 10.
- access: public

integer getPageButtonCount ()
getPageCount (line 329)

- return: number of pages of data items available
- access: public

integer getPageCount ()
getPageImageUrl (line 469)

- access: protected
- since: 3.1.1

void getPageImageUrl (string $text, string $commandName)

- string $text: the caption of the image button
- string $commandName: the command name associated with the image button

getPrevPageImageUrl (line 250)

- return: the image URL for the previous page button. This is only used when ButtonType is 'ImageButton'.
- access: public
- since: 3.1.1

string getPrevPageImageUrl ()
getPrevPageText (line 147)

- return: text for the previous page button. Defaults to '<'.
- access: public

string getPrevPageText ()
listIndexChanged (line 633)

Event handler to the OnSelectedIndexChanged event of the dropdown list.

This handler will raise OnPageIndexChanged event.

- access: public

void listIndexChanged (TDropDownList $sender, TEventParameter $param)

- TDropDownList $sender: the dropdown list control raising the event
- TEventParameter $param: event parameter

loadState (line 67)

Restores the pager state.

This method overrides the parent implementation and is invoked when the control is loading persistent state.

- access: public

void loadState ()

Redefinition of:

TControl::loadState()
  This method is invoked right after the control has loaded its state.

onPageIndexChanged (line 643)

This event is raised when page index is changed due to a page button click.

- access: public

void onPageIndexChanged (TPagerPageChangedEventParameter $param)

- TPagerPageChangedEventParameter $param: event parameter

onPreRender (line 367)

Performs databinding to populate data items from data source.

This method is invoked by dataBind(). You may override this function to provide your own way of data population.

- access: public

void onPreRender (Traversable $param)

- Traversable $param: the bound data

Redefinition of:

TControl::onPreRender()
  This method is invoked when the control enters 'OnPreRender' stage.

render (line 393)

Renders the control.

The method overrides the parent implementation by rendering the pager only when there are two or more pages.

- access: public

void render (THtmlWriter $writer)

- THtmlWriter $writer: the writer

Redefinition of:

TWebControl::render()
  Renders the control.

Redefined in descendants as:

- TActivePager::render()

setButtonType (line 123)

- access: public

void setButtonType (TPagerButtonType $value)

- TPagerButtonType $value: the type of command button for paging.

setControlToPaginate (line 91)

Sets the ID path of the control whose content would be paginated.

The ID path is the dot-connected IDs of the controls reaching from the pager's naming container to the target control.

- access: public

void setControlToPaginate (string $value)

- string $value: the ID path

setCurrentPageIndex (line 319)

- access: protected
- throws: TInvalidDataValueException if the value is less than 0

void setCurrentPageIndex (integer $value)

- integer $value: the zero-based index of the current page

setFirstPageImageUrl (line 205)

- access: public
- since: 3.1.1

void setFirstPageImageUrl (string $value)

- string $value: the image URL for the first page button. This is only used when ButtonType is 'ImageButton'.

setFirstPageText (line 171)

- access: public

void setFirstPageText (string $value)

- string $value: text for the first page button. If empty, the first page button will not be rendered.

setLastPageImageUrl (line 223)

- access: public
- since: 3.1.1

void setLastPageImageUrl (string $value)

- string $value: the image URL for the last page button. This is only used when ButtonType is 'ImageButton'.

setLastPageText (line 187)

- access: public

void setLastPageText (string $value)

- string $value: text for the last page button. If empty, the last page button will not be rendered.

setMode (line 107)

- access: public

void setMode (TPagerMode $value)

- TPagerMode $value: pager mode.

setNextPageImageUrl (line 241)

- access: public
- since: 3.1.1

void setNextPageImageUrl (string $value)

- string $value: the image URL for the next page button. This is only used when ButtonType is 'ImageButton'.

setNextPageText (line 139)

- access: public

void setNextPageText (string $value)

- string $value: text for the next page button.

setNumericPageImageUrl (line 283)

Sets the image URL for the numeric page buttons.

This is actually a template for generating a set of URLs corresponding to numeric button 1, 2, 3, .., etc. Use {0} as the placeholder for the numbers. For example, the image URL http://example.com/images/button{0}.gif will be replaced as http://example.com/images/button1.gif, http://example.com/images/button2.gif, etc.

- access: public
- since: 3.1.1

void setNumericPageImageUrl (string $value)

- string $value: the image URL for the numeric page buttons. This is only used when ButtonType is 'ImageButton' and Mode is 'Numeric'.

setPageButtonCount (line 300)

- access: public
- throws: TInvalidDataValueException if the value is less than 1.

void setPageButtonCount (integer $value)

- integer $value: maximum number of pager buttons to be displayed

setPageCount (line 338)

- access: protected
- throws: TInvalidDataValueException if the value is less than 0

void setPageCount (integer $value)

- integer $value: number of pages of data items available

setPrevPageImageUrl (line 259)

- access: public
- since: 3.1.1

void setPrevPageImageUrl (string $value)

- string $value: the image URL for the previous page button. This is only used when ButtonType is 'ImageButton'.

setPrevPageText (line 155)

- access: public

void setPrevPageText (string $value)

- string $value: text for the next page button.

#### Inherited Methods

Inherited From TWebControl

> TWebControl::addAttributesToRender()
> TWebControl::clearStyle()
> TWebControl::copyBaseAttributes()
> TWebControl::createStyle()
> TWebControl::getAccessKey()
> TWebControl::getBackColor()
> TWebControl::getBorderColor()
> TWebControl::getBorderStyle()
> TWebControl::getBorderWidth()
> TWebControl::getCssClass()
> TWebControl::getDisplay()
> TWebControl::getFont()
> TWebControl::getForeColor()
> TWebControl::getHasStyle()
> TWebControl::getHeight()
> TWebControl::getStyle()
> TWebControl::getTabIndex()
> TWebControl::getTagName()
> TWebControl::getToolTip()
> TWebControl::getWidth()
> TWebControl::render()
> TWebControl::renderBeginTag()
> TWebControl::renderContents()
> TWebControl::renderEndTag()
> TWebControl::setAccessKey()
> TWebControl::setBackColor()
> TWebControl::setBorderColor()
> TWebControl::setBorderStyle()
> TWebControl::setBorderWidth()
> TWebControl::setCssClass()
> TWebControl::setDisplay()
> TWebControl::setForeColor()
> TWebControl::setHeight()
> TWebControl::setStyle()
> TWebControl::setTabIndex()
> TWebControl::setToolTip()
> TWebControl::setWidth()

Inherited From TControl

> TControl::__construct()
> TControl::addedControl()
> TControl::addParsedObject()
> TControl::addToPostDataLoader()
> TControl::applyStyleSheetSkin()
> TControl::autoBindProperty()
> TControl::autoDataBindProperties()
> TControl::bindProperty()
> TControl::broadcastEvent()
> TControl::bubbleEvent()
> TControl::clearChildState()
> TControl::clearControlState()
> TControl::clearNamingContainer()
> TControl::clearViewState()
> TControl::convertUniqueIdToClientId()
> TControl::createChildControls()
> TControl::createControlCollection()
> TControl::dataBind()
> TControl::dataBindChildren()
> TControl::dataBindProperties()
> TControl::ensureChildControls()
> TControl::findControl()
> TControl::findControlsByID()
> TControl::findControlsByType()
> TControl::focus()
> TControl::getAdapter()
> TControl::getAllowChildControls()
> TControl::getAttribute()
> TControl::getAttributes()
> TControl::getChildControlsCreated()
> TControl::getClientID()
> TControl::getControls()
> TControl::getControlStage()
> TControl::getControlState()
> TControl::getCustomData()
> TControl::getEnabled()
> TControl::getEnableTheming()
> TControl::getEnableViewState()
> TControl::getHasAdapter()
> TControl::getHasAttributes()
> TControl::getHasChildInitialized()
> TControl::getHasControls()
> TControl::getHasInitialized()
> TControl::getHasLoaded()
> TControl::getHasLoadedPostData()
> TControl::getHasPreRendered()
> TControl::getID()
> TControl::getNamingContainer()
> TControl::getPage()
> TControl::getParent()
> TControl::getRegisteredObject()
> TControl::getSkinID()
> TControl::getSourceTemplateControl()
> TControl::getTemplateControl()
> TControl::getUniqueID()
> TControl::getViewState()
> TControl::getVisible()
> TControl::hasAttribute()
> TControl::initRecursive()
> TControl::isDescendentOf()
> TControl::isObjectRegistered()
> TControl::loadRecursive()
> TControl::loadState()
> TControl::loadStateRecursive()
> TControl::onDataBinding()
> TControl::onInit()
> TControl::onLoad()
> TControl::onPreRender()
> TControl::onUnload()
> TControl::preRenderRecursive()
> TControl::raiseBubbleEvent()
> TControl::registerObject()
> TControl::removeAttribute()
> TControl::removedControl()
> TControl::render()
> TControl::renderChildren()
> TControl::renderControl()
> TControl::saveState()
> TControl::saveStateRecursive()
> TControl::setAdapter()
> TControl::setAttribute()
> TControl::setChildControlsCreated()
> TControl::setControlStage()
> TControl::setControlState()
> TControl::setCustomData()
> TControl::setEnabled()
> TControl::setEnableTheming()
> TControl::setEnableViewState()
> TControl::setID()
> TControl::setPage()
> TControl::setSkinID()
> TControl::setTemplateControl()
> TControl::setViewState()
> TControl::setVisible()
> TControl::trackViewState()
> TControl::traverseChildControls()
> TControl::unbindProperty()
> TControl::unloadRecursive()
> TControl::unregisterObject()
> TControl::__get()

Inherited From TApplicationComponent

> TApplicationComponent::getApplication()
> TApplicationComponent::getRequest()
> TApplicationComponent::getResponse()
> TApplicationComponent::getService()
> TApplicationComponent::getSession()
> TApplicationComponent::getUser()
> TApplicationComponent::publishAsset()
> TApplicationComponent::publishFilePath()

Inherited From TComponent

> TComponent::addParsedObject()
> TComponent::attachEventHandler()
> TComponent::canGetProperty()
> TComponent::canSetProperty()
> TComponent::createdOnTemplate()
> TComponent::detachEventHandler()
> TComponent::evaluateExpression()
> TComponent::evaluateStatements()
> TComponent::getEventHandlers()
> TComponent::getSubProperty()
> TComponent::hasEvent()
> TComponent::hasEventHandler()
> TComponent::hasProperty()
> TComponent::raiseEvent()
> TComponent::setSubProperty()
> TComponent::__get()
> TComponent::__set()

Class Constants
CMD_PAGE = 'Page' (line 54)

Command name that TPager understands.

CMD_PAGE_FIRST = 'First' (line 57)
CMD_PAGE_LAST = 'Last' (line 58)
CMD_PAGE_NEXT = 'Next' (line 55)
CMD_PAGE_PREV = 'Previous' (line 56)

#### Inherited Constants

Inherited from TControl

> TControl::AUTOMATIC_ID_PREFIX
> TControl::CLIENT_ID_SEPARATOR
> TControl::CS_CHILD_INITIALIZED
> TControl::CS_CONSTRUCTED
> TControl::CS_INITIALIZED
> TControl::CS_LOADED
> TControl::CS_PRERENDERED
> TControl::CS_STATE_LOADED
> TControl::ID_FORMAT
> TControl::ID_SEPARATOR
> TControl::IS_CHILD_CREATED
> TControl::IS_CREATING_CHILD
> TControl::IS_DISABLE_THEMING
> TControl::IS_DISABLE_VIEWSTATE
> TControl::IS_ID_SET
> TControl::IS_SKIN_APPLIED
> TControl::IS_STYLESHEET_APPLIED
> TControl::RF_ADAPTER
> TControl::RF_AUTO_BINDINGS
> TControl::RF_CHILD_STATE
> TControl::RF_CONTROLS
> TControl::RF_CONTROLSTATE
> TControl::RF_DATA_BINDINGS
> TControl::RF_EVENTS
> TControl::RF_NAMED_CONTROLS
> TControl::RF_NAMED_CONTROLS_ID
> TControl::RF_NAMED_OBJECTS
> TControl::RF_SKIN_ID

Documentation generated on Sun, 11 Jan 2009 20:23:21 -0500 by phpDocumentor 1.3.0RC4