Class TPager
Direct Known Sub-classes:
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.
Constants Inherited From TControl |
AUTOMATIC_ID_PREFIX,
CLIENT_ID_SEPARATOR,
CS_CHILD_INITIALIZED,
CS_CONSTRUCTED,
CS_INITIALIZED,
CS_LOADED,
CS_PRERENDERED,
CS_STATE_LOADED,
ID_FORMAT,
ID_SEPARATOR,
IS_CHILD_CREATED,
IS_CREATING_CHILD,
IS_DISABLE_THEMING,
IS_DISABLE_VIEWSTATE,
IS_ID_SET,
IS_SKIN_APPLIED,
IS_STYLESHEET_APPLIED,
RF_ADAPTER,
RF_AUTO_BINDINGS,
RF_CHILD_STATE,
RF_CONTROLS,
RF_CONTROLSTATE,
RF_DATA_BINDINGS,
RF_EVENTS,
RF_NAMED_CONTROLS,
RF_NAMED_CONTROLS_ID,
RF_NAMED_OBJECTS,
RF_SKIN_ID,
|
Method Summary |
boolean
|
Processes a bubbled event.
|
protected
void
|
Builds a dropdown list pager
|
protected
void
|
Builds a next-prev pager
|
protected
void
|
Builds a numeric pager
|
protected
void
|
Builds the pager content based on the pager mode.
|
protected
mixed
|
createPagerButton
( string $buttonType, boolean $enabled, string $text, string $commandName, string $commandParameter)
Creates a pager button.
|
TPagerButtonType
|
|
string
|
|
integer
|
|
string
|
|
string
|
|
boolean
|
|
boolean
|
|
string
|
|
string
|
|
TPagerMode
|
|
string
|
|
string
|
|
string
|
|
integer
|
|
integer
|
|
protected
void
|
|
string
|
|
string
|
|
void
|
Event handler to the OnSelectedIndexChanged event of the dropdown list.
|
void
|
Restores the pager state.
|
void
|
This event is raised when page index is changed due to a page button click.
|
void
|
Performs databinding to populate data items from data source.
|
void
|
Renders the control.
|
void
|
|
void
|
Sets the ID path of the control whose content would be paginated.
|
protected
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
Sets the image URL for the numeric page buttons.
|
void
|
|
protected
void
|
|
void
|
|
void
|
|
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()
|
Methods Inherited From TControl |
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()
|
Methods 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()
|
Method Details |
bubbleEvent
Processes a bubbled event.
This method overrides parent's implementation by wrapping event parameter for OnCommand event with item information.
Input |
TControl | $sender | the sender of the event |
TEventParameter | $param | event parameter |
Output |
boolean
| whether the event bubbling should stop here. |
Exception |
|
buildListPager
protected void buildListPager |
() |
Builds a dropdown list pager
|
buildNextPrevPager
protected void buildNextPrevPager |
() |
Builds a next-prev pager
|
buildNumericPager
protected void buildNumericPager |
() |
Builds a numeric pager
|
buildPager
protected void buildPager |
() |
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.
|
createPagerButton
protected mixed createPagerButton |
(string $buttonType , boolean $enabled , string $text , string $commandName , string $commandParameter ) |
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.
Input |
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 |
Output |
mixed
| the button instance |
Exception |
|
getButtonType
Output |
TPagerButtonType
| the type of command button for paging. Defaults to TPagerButtonType::LinkButton. |
Exception |
|
getControlToPaginate
public string getControlToPaginate |
() |
Output |
string
| the ID path of the control whose content would be paginated. |
Exception |
|
getCurrentPageIndex
public integer getCurrentPageIndex |
() |
Output |
integer
| the zero-based index of the current page. Defaults to 0. |
Exception |
|
getFirstPageImageUrl
public string getFirstPageImageUrl |
() |
Output |
string
| the image URL for the first page button. This is only used when ButtonType is 'ImageButton'. |
Exception |
|
getFirstPageText
public string getFirstPageText |
() |
Output |
string
| text for the first page button. Defaults to ''. |
Exception |
|
getIsFirstPage
public boolean getIsFirstPage |
() |
Output |
boolean
| whether the current page is the first page Defaults to false. |
Exception |
|
getIsLastPage
public boolean getIsLastPage |
() |
Output |
boolean
| whether the current page is the last page |
Exception |
|
getLastPageImageUrl
public string getLastPageImageUrl |
() |
Output |
string
| the image URL for the last page button. This is only used when ButtonType is 'ImageButton'. |
Exception |
|
getLastPageText
public string getLastPageText |
() |
Output |
string
| text for the last page button. Defaults to '>>'. |
Exception |
|
getMode
Output |
TPagerMode
| pager mode. Defaults to TPagerMode::NextPrev. |
Exception |
|
getNextPageImageUrl
public string getNextPageImageUrl |
() |
Output |
string
| the image URL for the next page button. This is only used when ButtonType is 'ImageButton'. |
Exception |
|
getNextPageText
public string getNextPageText |
() |
Output |
string
| text for the next page button. Defaults to '>'. |
Exception |
|
getNumericPageImageUrl
public string getNumericPageImageUrl |
() |
Output |
string
| the image URL for the numeric page buttons. This is only used when ButtonType is 'ImageButton' and Mode is 'Numeric'. |
Exception |
|
getPageButtonCount
public integer getPageButtonCount |
() |
Output |
integer
| maximum number of pager buttons to be displayed. Defaults to 10. |
Exception |
|
getPageCount
public integer getPageCount |
() |
Output |
integer
| number of pages of data items available |
Exception |
|
getPageImageUrl
protected void getPageImageUrl |
(string $text , string $commandName ) |
Input |
string | $text | the caption of the image button |
string | $commandName | the command name associated with the image button |
Output |
Exception |
|
getPrevPageImageUrl
public string getPrevPageImageUrl |
() |
Output |
string
| the image URL for the previous page button. This is only used when ButtonType is 'ImageButton'. |
Exception |
|
getPrevPageText
public string getPrevPageText |
() |
Output |
string
| text for the previous page button. Defaults to '<'. |
Exception |
|
listIndexChanged
Event handler to the OnSelectedIndexChanged event of the dropdown list.
This handler will raise OnPageIndexChanged event.
|
loadState
Restores the pager state.
This method overrides the parent implementation and is invoked when the control is loading persistent state.
|
onPageIndexChanged
This event is raised when page index is changed due to a page button click.
|
onPreRender
public void onPreRender |
(Traversable $param ) |
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.
Input |
Traversable | $param | the bound data |
Output |
Exception |
|
render
Renders the control.
The method overrides the parent implementation by rendering the pager only when there are two or more pages.
|
setButtonType
Input |
TPagerButtonType | $value | the type of command button for paging. |
Output |
Exception |
|
setControlToPaginate
public void setControlToPaginate |
(string $value ) |
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.
Input |
string | $value | the ID path |
Output |
Exception |
|
setCurrentPageIndex
protected void setCurrentPageIndex |
(integer $value ) |
Input |
integer | $value | the zero-based index of the current page |
Output |
Exception |
throws | TInvalidDataValueException if the value is less than 0 |
|
setFirstPageImageUrl
public void setFirstPageImageUrl |
(string $value ) |
Input |
string | $value | the image URL for the first page button. This is only used when ButtonType is 'ImageButton'. |
Output |
Exception |
|
setFirstPageText
public void setFirstPageText |
(string $value ) |
Input |
string | $value | text for the first page button. If empty, the first page button will not be rendered. |
Output |
Exception |
|
setLastPageImageUrl
public void setLastPageImageUrl |
(string $value ) |
Input |
string | $value | the image URL for the last page button. This is only used when ButtonType is 'ImageButton'. |
Output |
Exception |
|
setLastPageText
public void setLastPageText |
(string $value ) |
Input |
string | $value | text for the last page button. If empty, the last page button will not be rendered. |
Output |
Exception |
|
setMode
Input |
TPagerMode | $value | pager mode. |
Output |
Exception |
|
setNextPageImageUrl
public void setNextPageImageUrl |
(string $value ) |
Input |
string | $value | the image URL for the next page button. This is only used when ButtonType is 'ImageButton'. |
Output |
Exception |
|
setNextPageText
public void setNextPageText |
(string $value ) |
Input |
string | $value | text for the next page button. |
Output |
Exception |
|
setNumericPageImageUrl
public void setNumericPageImageUrl |
(string $value ) |
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.
Input |
string | $value | the image URL for the numeric page buttons. This is only used when ButtonType is 'ImageButton' and Mode is 'Numeric'. |
Output |
Exception |
|
setPageButtonCount
public void setPageButtonCount |
(integer $value ) |
Input |
integer | $value | maximum number of pager buttons to be displayed |
Output |
Exception |
throws | TInvalidDataValueException if the value is less than 1. |
|
setPageCount
protected void setPageCount |
(integer $value ) |
Input |
integer | $value | number of pages of data items available |
Output |
Exception |
throws | TInvalidDataValueException if the value is less than 0 |
|
setPrevPageImageUrl
public void setPrevPageImageUrl |
(string $value ) |
Input |
string | $value | the image URL for the previous page button. This is only used when ButtonType is 'ImageButton'. |
Output |
Exception |
|
setPrevPageText
public void setPrevPageText |
(string $value ) |
Input |
string | $value | text for the next page button. |
Output |
Exception |
|
Constant Details |
CMD_PAGE
Command name that TPager understands.
Type:
string
Value:
'Page'
|
CMD_PAGE_FIRST
Type:
string
Value:
'First'
|
CMD_PAGE_LAST
Type:
string
Value:
'Last'
|
CMD_PAGE_NEXT
Type:
string
Value:
'Next'
|
CMD_PAGE_PREV
Type:
string
Value:
'Previous'
|
|