What is getPage?¶
A general purpose snippet for presenting, navigating, and optionally caching, multi-page views from any Element that accepts a limit and offset properties for limiting a data set, and sets a placeholder which getPage can use to retrieve the total number of items to page over.
- MODX Revolution 2.0.0-beta5 or later
- PHP5 or later
getPage was first written by Jason Coward (opengeek) and released on March 19, 2010.
This Snippet does nothing by itself, but rather depends on another Snippet to return the output for a specified page (or range of data within a complete set). For example, the getResources, getFeed, and Archivist Snippets can both be wrapped by getPage.
The getPage snippet can be called using the tag:
[[!getPage? &elementClass=`modSnippet` &element=`getResources` ]]
Do Not Cache
The getPage snippet must never be called cacheable on a Resource that is cacheable. It is best to always call getPage with the non-cacheable token,
!, while still caching the rest of the Resource output. The same rule applies for the placeholder represented by the
pageNavVar property (
page.nav by default) so that its output is not cached into the cacheable page content.
Required Properties You must specify the element property, plus any additional properties required by the element you are calling via getPage.
|element||The name of the modElement to process the output from.|
|Name||Description||Default Value||Added in Version|
|limit||The result limit per page; can be overridden in the $_REQUEST. In 1.2.2+, $_GET is searched before $_REQUEST explicitly.||10|
|offset||The offset, or record position to start at within the collection for rendering results for the current page; should be calculated based on, total, limit and the page variable set in pageVarKey.||0|
|page||The page to display; this is determined based on the value of the $_REQUEST variable specified in pageVarKey.||calculated|
|pageCount||The total number of pages.||calculated|
|pageVarKey||The key of a property that indicates the current page within the $_REQUEST, and sets the value of page. In 1.2.2+, $_GET is searched before $_REQUEST explicitly.||page|
|totalVar||The key of a placeholder that must contain the total number of records in the limitable collection being paged.||total|
|total||The total number of records being paged through (see totalVar).||calculated|
|firstItem||The 1-based index of the first item being displayed on the current page.||calculated|
|lastItem||The 1-based index of the last item being displayed on the current page.||calculated|
|pageOneLimit||An optional result limit for the first page of results which can be different from the main limit||1.2.2-pl|
Page Navigation Properties¶
|pageLimit||The maximum number of page links to display when rendering page navigation controls.||5|
|pageNavVar||The key of a placeholder to be set with the paging navigation controls.||page.nav|
Page Navigation Template Properties¶
You can NOT modify these tpl properties from the snippet tag directly, due to the order in which tags are parsed in Revolution. If you do want to change these defaults you will need to use a property set:
- On the Elements tab, open the Snippets tree and find getPage. Open it.
- You will see a tab called "Element Properties". Open it.
- Create a new property set using the Add property set button and in the window that pops up ticking the "Create new property set" checkbox.
- Give your property set a name and click save.
- Now you can modify the values of the properties which will not be overwritten on upgrade.
- Finally, reference your property set name in your snippet call:
[[!getPage@PropertySetName? &element=`getResources` &parents=`3` ...]]
|Name||Description||Default Value||Added In Version|
|pageNavOuterTpl||A content tpl for controlling the layout of the various page navigation controls.||
|pageNavTpl||A content tpl representing a single page navigation control.||
|pageActiveTpl||A content tpl representing the current page navigation control.||
|pageFirstTpl||A content tpl representing the first page navigation control.||
|pageLastTpl||A content tpl representing the last page navigation control.||
|pagePrevTpl||A content tpl representing the previous page navigation control.||
|pageNextTpl||A content tpl representing the next page navigation control.||
|cache||Indicates if the content of each page request should be cached, by a unique request URI (not just the pageVarKey)||value of cache_resource setting, or false|
|cache_key||A key identifying a named xPDOCache instance to use for caching the page content.||value of cache_resource_key setting|
|cache_handler||Identifies an xPDOCache derivative class to use for the instance.||value of cache_resource_handler setting, or xPDOFileCache|
|cache_expires||Indicates the number of seconds for each item to live in the cache. Note that 0 indicates it will live in the cache until the cache is manually cleared, unless you have a custom handler caching data outside of the handler identified by the default cache_resource_key||value of expires setting for specified cache_key, or 0|
|elementClass||The modElement derivative classname you want getPage to process the output from, e.g. modChunk or the default modSnippet||modSnippet|
|namespace||An execution namespace that serves as a prefix for placeholders set by a specific instance of the getPage snippet.|
|toPlaceholder||Indicates the element will not return the output to getPage, but rather will set a placeholder containing the content getPage should present. This allows getPage to cache the placeholder output as it would any output returned by an element, and set it from the cache.|
Page a list of all child Resources of the current Resource, using a chunk called 'myRowTpl':
[[!getPage? &element=`getResources` &parents=`[[*id]]` &tpl=`myRowTpl`]] <div class="pageNav">[[!+page.nav]]</div>
Page all resources beneath the Resource with ID '5', with the exception of resource 10, using a chunk called 'myRowTpl':
[[!getPage? &element=`getResources` &parents=`5` &resources=`-10` &tpl=`myRowTpl`]] <div class="pageNav">[[!+page.nav]]</div>
If you are making your custom snippet to work with get page there are three things that your snippet needs to do ...
Had a couple of issues with getting it all to work ... check out this resources and answer on the forums.