Class WFPaginator

Description
Description | Vars (details) | Methods (details) Constants (details)

Base paginator class.

PHOCOA has its own pagination infrastructure. The UI layer of pagination is nicely separated from the data layer so that the PHOCOA pagination infrastructure can be easily used with any underlying data source (SQL, PHP arrays, etc).

The WFPaginator class is the core pagination functionality that coordiantes the PHOCOA Pagination UI widgets with the underlying data. The PHOCOA pagination infrastructure includes support for multi-key sorting as well.

It is extremely simple to paginate your data with PHOCOA.

To hook up the PHOCOA widgets with a data source, you must provide a Data Delegate to WFPaginator to provide the paged data to the pagination infrastructure. A Data delegate is any class that implements the WFPagedData interface.

PHOCOA ships with data delegates for PHP Arrays, Propel criteria-based queries, and Creole-based queries. There is also a data delegate for DieselPoint result sets.

Because of this architecture, the pagination widgets of PHOCOA can be easily "bound" to a pagination instance and make the display of paginated data easy.

USAGE First, figure out is which mode you need to use.

  • MODE_URL (default mode) effects all pagination via plain-old-urls, which is more compatible (with browsers), but of course cannot interact with form data (for instance a search form on the same page).
  • MODE_FORM effects all pagination via javascript and your form.
The default is MODE_URL.

Adding Pagination to an exist list view.

  1. Set up the paginator by declaring a WFPaginator instance in your shared instances.
  2. Manifest the paginatorState parameter id in the page's ParameterList method. By default, WFPaginator expects the id to be "paginatorState".
  3. If you're using MODE_FORM, enable MODE_FORM by configuring the paginator's "modeForm" element WFPaginator::setModeForm() with the value of the submit button on your form that should be clicked to "update" the display. Then, declare a WFPaginatorState in your page (the ID should be paginatorState parameter ID, "paginatorState" by default), and configure the paginator element. This is a special form element that WFPaginator uses to pass the new settings on via the form submission.
  4. Declare a WFPaginatorNavigation in your page, and configure the paginator element.
  5. Declare a WFPaginatorPageInfo in your page, and configure the paginator element.
  6. Declare a WFPaginatorSortLink in your page for each sorting option, and configure the paginator and value elements. The value of a WFPaginatorSortLink is the sortKey that the link is for, without the +/-.
  7. Configure the paginator in the sharedInstancesDidLoad method:
    1.      $this->myPaginator->setSortOptions(array('+price' => 'Price', '-price' => 'Price'));
    2.      $this->myPaginator->setDefaultSortKeys(array('+price'));
  8. In your page's PageDidLoad method, configure the paginator's data delegate and have the paginator read the state from the request.
    1.      $this->myPaginator->setDataDelegate(new WFPagedPropelQuery($criteria, 'MyPeer'));
    2.      $this->myPaginator->readPaginatorStateFromParams($params);    // this will read the paginator's desired state from the params.
  9. Finally, access the paged data set. Typically this is done in the PageDidLoad method if there is no form submission, otherwise it is done from the action method. $this->myArrayController->setContent($this->myPaginator->currentItems());
</code>

NOTE: The first page is page 1 (as opposed to page 0).

Located in /framework/WFPagination.php (line 64) 

WFObject
   |
   --WFPaginator
Class Constant Summary
Description | Constants (details) Vars (details) | | Methods (details)
MODE_FORM = 2
MODE_URL = 1
PAGINATOR_FIRST_PAGE = 1
PAGINATOR_PAGESIZE_ALL = -1
Variable Summary
Description | Vars (details) | Methods (details) Constants (details)
assoc_array $alternativeParams
array $currentItems
integer $currentPage
object WFPagedData $dataDelegate
array $defaultSortKeys
integer $itemCount
string $itemPhrasePlural
string $itemPhraseSingular
int $mode
integer $pageSize
string $paginatorStateParameterID
array $sortKeys
assoc_array $sortOptions
string $submitID
Method Summary
Description | Constants (details) Vars (details) | Methods (details)
WFPaginator __construct ()
void addSortKey (string $key)
void addSortOption (string $sortKey, string $displayName)
string alternativeParameterValue (string $id)
boolean atFirstPage ()
boolean atLastPage ()
void clearSortKeys ()
array currentItems ()
integer currentPage ()
object WFPagedData dataDelegate ()
void enableModeURL ()
integer endItem ()
integer itemCount ()
string itemPhrase (integer $count)
string jsForState ($state $state)
string jsPaginatorStateModeFormGoToStateFunctionName ()
string jsPaginatorStateModeFormSubmissionVarName ()
integer lastPage ()
void loadData ()
void mode ()
boolean nextPage ()
integer pageCount ()
integer pageSize ()
string paginatorState ([integer $page = NULL], [integer $pageSize = NULL], [mixed $sortKeys = NULL])
string paginatorStateParameterID ()
boolean prevPage ()
void readPaginatorStateFromParams (assoc_array $params)
void reloadData ()
void setAlternativeParameterValue (string $id, mixed $value)
void setCurrentPage (integer $pageNum)
void setDataDelegate (object WFPagedData $delegate)
void setDefaultSortKeys (mixed $keys)
void setItemPhrase (string $singular, [string $plural = NULL])
void setModeForm (string $submitID)
void setPageSize (integer $sz)
void setPaginatorState (string $paginatorState)
void setPaginatorStateParameterID (string $id)
void setSortOptions (assoc_array $opts)
array sortKeys ()
void sortOptions ()
integer startItem ()
string submitID ()
string urlForPaginatorState (object WFPage $page, string $paginatorState)
Variables
Description | Vars (details) Constants (details) | Methods (details)
assoc_array $alternativeParams (line 124)
  • var: An associative array of alternative replacement params for the current page's parameter list. This is used by the baseURL calculation to allow clients to change paramters before creating the pagination URLs.
  • access: protected
array $currentItems (line 77)
  • var: An array of items representing the current page of items. This is actually a cached value, see currentItems.
  • access: protected
integer $currentPage (line 81)
  • var: The current page number. The first page is page 1.
  • access: protected
object WFPagedData $dataDelegate (line 89)
  • var: An object conforming to the WFPagedData interface.
  • access: protected
array $defaultSortKeys (line 110)
  • var: The default sort keys to use if sortKeys is empty.
  • access: protected
integer $itemCount (line 73)
  • var: The total item count for the paginated data. This is actually a cached value, see itemCount.
  • access: protected
string $itemPhrasePlural (line 97)
  • var: The name of mutliple items being paged. Example: "people".
  • access: protected
string $itemPhraseSingular (line 93)
  • var: The name of a single item being paged. Example: "person".
  • access: protected
int $mode (line 69)
integer $pageSize (line 85)
  • var: The number of items that can fit on a single page. Default is all items.
  • access: protected
string $paginatorStateParameterID (line 119)
  • var: The name of the page's parameter ID containing the WFPaginatorState. Of course your parameterID declared in <pageName>_ParameterList and the ID of the WFPaginatorState widget should be the same.
  • access: protected
array $sortKeys (line 106)
  • var: An array in order of all sort keys that are applied to the paginator.
  • access: protected
assoc_array $sortOptions (line 102)
  • var: An associative array of sort options for the current paginator. In the format of array('sortKey' => 'Sort Description'). The sortKeys will be managed by WFPaginator and passed to the WFPagedData interface for actual implementation. IMPORTANT: if you name your sortKeys properly, the paginator can help you with toggling asc/desc. Precede your sortKey with + or - like so: "+name", "-name".
  • access: protected
string $submitID (line 114)
  • var: The ID of the form button to click to re-submit the form. Only used if MODE_FORM.
  • access: protected
Methods
Description | Vars (details) Constants (details) Methods (details)
Constructor __construct (line 148)
WFPaginator __construct ()
Redefinition of:
WFObject::__construct()
addSortKey (line 395)

Add a sortKey to the current paginator. Call multiple times for a multi-key-sort.

  • throws: WFException if the sortKey does not exist in sortOptions.
void addSortKey (string $key)
  • string $key: A sortKey to use.
addSortOption (line 360)

Add a sort option to the existing sort options.

void addSortOption (string $sortKey, string $displayName)
  • string $sortKey: The sortKey of the option. IMPORTANT: WFPaginator expects sort keys to be named +sortKey and -sortKey to indicate ascending or descending sort.
  • string $displayName: The display name for the sort option.
alternativeParameterValue (line 208)

Get the alternativeParameterValue for a particular ID.

  • return: The alternative value that's been set, or NULL if none is set.
string alternativeParameterValue (string $id)
  • string $id: The parameterID to get.
atFirstPage (line 645)

Is the current page the first page?

boolean atFirstPage ()
atLastPage (line 659)

Is the current page the last page?

boolean atLastPage ()
clearSortKeys (line 405)

Remove all sort information for the paginator.

void clearSortKeys ()
currentItems (line 618)

Get the array of items in the current page.

NOTE: uses a cached value.

array currentItems ()
currentPage (line 523)

Get the current page that the paginator is on.

  • return: The current page number. The first page is page 1.
integer currentPage ()
dataDelegate (line 488)

Get the data delegate.

  • return: object; the data delegate.
  • throws: Exception if no delegate assigned.
object WFPagedData dataDelegate ()
enableModeURL (line 326)

Turn on MODE_URL.

void enableModeURL ()
endItem (line 560)

Get the number of the last item in the current page.

  • return: The last item of the current page. Item 1 is the first item.
integer endItem ()
itemCount (line 600)

Get the current total item count for the current data delgate.

NOTE: uses a cached value.

integer itemCount ()
itemPhrase (line 453)

Get the item phrase for the passed count. Returns singular or plural name based on count.

string itemPhrase (integer $count)
  • integer $count: Count of items.
jsForState (line 787)

Get the javascript code for the onClick of a link needed to effect the given pasinatorState. For MODE_FORM only.

  • return: The JavaScript code that goes in onClick="".
  • throws: Exception if paginatorStateParameterID or submitID are not populated.
string jsForState ($state $state)
jsPaginatorStateModeFormGoToStateFunctionName (line 764)

Get the name of the js function which the various paginator widgets use when MODE_FORM is active to "go" to the correct paginator state.

  • return: The name of the js function.
string jsPaginatorStateModeFormGoToStateFunctionName ()
jsPaginatorStateModeFormSubmissionVarName (line 775)

Get the name of the js var which the various paginator widgets use when MODE_FORM is active to determine whether the "submit" button has been pressed by a user, or by the jsPaginatorStateModeFormGoToStateFunctionName() function.

  • return: The name of the js var.
string jsPaginatorStateModeFormSubmissionVarName ()
lastPage (line 673)

Get the page number of the last page.

  • return: The page number of the last page. The first page is page 1.
integer lastPage ()
loadData (line 499)

Load all data from the delegate.

NOTE: won't reload if alread cached. Use reloadData instead.

void loadData ()
mode (line 331)
void mode ()
nextPage (line 695)

Is there a next page?

boolean nextPage ()
pageCount (line 635)

Get the number of pages of data.

integer pageCount ()
pageSize (line 577)

Get the number of items in a single page.

integer pageSize ()
paginatorState (line 711)

Get the passed paginator state in a serialized format.

  • return: A serialized state that when passed to setPaginatorState will load those settings.
string paginatorState ([integer $page = NULL], [integer $pageSize = NULL], [mixed $sortKeys = NULL])
  • integer $page: The page number to use.
  • integer $pageSize: The page size to use.
  • mixed $sortKeys: array - The sortKeys to use. string - The single sortKey to use
paginatorStateParameterID (line 184)

Get the id of the paginatorState widget.

  • return: The ID of the paginatorState widget.
string paginatorStateParameterID ()
prevPage (line 683)

Is there a previous page?

boolean prevPage ()
readPaginatorStateFromParams (line 285)

Read the paginator's state from the page's parameters.

  • throws: Exception if the paginatorStateParameterID param cannot be found.
void readPaginatorStateFromParams (assoc_array $params)
  • assoc_array $params: The params array from the page.
reloadData (line 508)

Clear all caches and reload the data from the delegate.

void reloadData ()
setAlternativeParameterValue (line 197)

Provide alternate values for the page's params that will be used with urlForPaginatorState().

The passed value will be urlencoded when used.

void setAlternativeParameterValue (string $id, mixed $value)
  • string $id: The ID of the parameter.
  • mixed $value: The value of the parameter. RAW (ie NOT urlencoded).
setCurrentPage (line 533)

Set the current page for the paginator.

void setCurrentPage (integer $pageNum)
  • integer $pageNum: Set the current page; the first page is page 1.
setDataDelegate (line 474)

Set the data delegate.

The WFPaginator instance will call out to the data delegate to fetch the paged data.

void setDataDelegate (object WFPagedData $delegate)
setDefaultSortKeys (line 417)

Set the default sort keys that will be used if no other sort keys are added.

  • throws: object WFException If any of the passed keys fails (ie is not a valid sortOption).
void setDefaultSortKeys (mixed $keys)
  • mixed $keys: array - The sortKeys to use. string - The single sortKey to use.
setItemPhrase (line 434)

Set the names of the items being paged.

void setItemPhrase (string $singular, [string $plural = NULL])
  • string $singular: The singular name, example "person".
  • string $plural: The plural name, example "people". Leave blank to use singluar for plural as well, example: "fish".
setModeForm (line 317)

Turn on MODE_FORM.

void setModeForm (string $submitID)
  • string $submitID: The ID of the submit button that should be "clicked" to udpate the page.
setPageSize (line 587)

Set the number of items per page.

void setPageSize (integer $sz)
  • integer $sz: Number of items per page.
setPaginatorState (line 727)

Used to restore the paginator to the state specified.

void setPaginatorState (string $paginatorState)
  • string $paginatorState: The serialized state. Form is "currentPage|pageSize|sortKey1,sortKey2".
setPaginatorStateParameterID (line 303)

Tell the paginator the name of the "parameterId" which is used for maintaining the parameter state.

For MODE_URL, your page should have a declared paramater with this id. For MODE_FORM, your page should have a WFPaginatorState widget with this id.

NOTE: if you are using a paginator outside of a WFModule context, you should set the paginatorStateParameterID to NULL.

void setPaginatorStateParameterID (string $id)
  • string $id: The parameter ID.
setSortOptions (line 347)

Inform the paginator of all sort options that can be used via the UI.

The WFPaginatorSortLink widget will use this info to effect sorting.

void setSortOptions (assoc_array $opts)
  • assoc_array $opts: An associative array of sortKey => DisplayName. IMPORTANT: WFPaginator expects sort keys to be named +sortKey and -sortKey to indicate ascending or descending sort. The display name will be shown by the sort widgets.
sortKeys (line 380)

Get the effective sortKeys for the paginator.

This function will use the default sortKeys if there are no sortKeys set.

  • return: An array of sortKeys that are part of the sortOptions.
array sortKeys ()
sortOptions (line 368)

Get the assigned sort options for the paginator.

void sortOptions ()
startItem (line 543)

Get the number of the first item in the current page.

  • return: The first item of the current page. Item 1 is the first item.
integer startItem ()
submitID (line 174)

Get the id of the submit button used for pagination in MODE_FORM.

  • return: The ID of the submit button used for MODE_FORM.
string submitID ()
urlForPaginatorState (line 231)

Get an absolute URL that links to a different paginator state for the current setup.

This is a helper function used by the pagination widgets.

This function is used for MODE_URL, and degrade-no-javascript for MODE_FORM. Functionality won't be quite perfect for the latter, but it is only intended to let search engines be able to scan through MODE_FORM paginated content.

If any of the other parameters should be different than they were in the original params created for the page, set the new value(s) with setAlternativeParameterValue before displaying any of the pagination widgets.

string urlForPaginatorState (object WFPage $page, string $paginatorState)
  • object WFPage $page: The page that the widget is on.
  • string $paginatorState: The desired paginatorState for the link. See paginatorState.

Inherited Methods

Inherited From WFObject

WFObject::__construct()
WFObject::exposedProperties()
WFObject::getClass()
WFObject::keyPathToTargetAndKey()
WFObject::setValueForKey()
WFObject::setValueForKeyPath()
WFObject::validateValueForKey()
WFObject::validateValueForKeyPath()
WFObject::valueForKey()
WFObject::valueForKeyPath()
WFObject::valueForUndefinedKey()
WFObject::__toString()
Class Constants
Description | Constants (details) Vars (details) | Methods (details)
MODE_FORM = 2 (line 138)
MODE_URL = 1 (line 134)
PAGINATOR_FIRST_PAGE = 1 (line 146)
PAGINATOR_PAGESIZE_ALL = -1 (line 142)

Documentation generated on Thu, 17 Apr 2008 13:52:00 -0400 by phpDocumentor 1.4.1