PHP:Paging uses a special HTML syntax to create paging. There are several different tags that are used by PHP:Paging. Below is a complete list of all the tags.
| Tag | Attributes | Info | Example |
|---|---|---|---|
| php:paging | name always-show src style |
Used as the opening and closing for a PHP:Paging Control. | <php:paging name="samplepaging"> ... paging html goes here ... </php:paging> |
| next | page | Used to show a link to a next page. | <next page="1"> <a href="{next:page_url}">Go to the next page</a> </next> |
| previous | page | Used to show a link to a previous page. | <previous page="1"> <a href="{previous:page_url}">Go to the previous page</a> </previous> |
| NextOrPrevious | page | Used to show something when either a next page or a previous page is available. | <nextorprevious page="1"> You can go back or forward (or both) </nextorprevious> |
| perpage | value | Used to show a link for a different perpage value. | <perpage value="25"> <a href="{perpage:page_url}">Show 25 items per page</a> </perpage> |
| page | value | Used to show a link to a certain page | <page value="10"> <a href="{page:page_url}">Go to page 10</a> </page> |
Below is a sample layout of a paging control. The output of the below code will be like this: « 4 5 6 | 7 | 8 9 10 »
<php:paging name="test">
<previous page="1"><a href="{previous:page_url}" title="Previous Page">«</a></previous>
<previous page="3"><a href="{previous:page_url}" title="Go to page {previous:page}">{previous:page}</a></previous>
<previous page="2"><a href="{previous:page_url}" title="Go to page {previous:page}">{previous:page}</a></previous>
<previous page="1"><a href="{previous:page_url}" title="Go to page {previous:page}">{previous:page}</a></previous>
<nextorprevious page="1">
<strong>
<previous page="1"> | </previous>
{var:page}
<next page="1"> | </next>
</strong>
</nextorprevious>
<next page="1"><a href="{next:page_url}" title="Go to page {next:page}">{next:page}</a></next>
<next page="2"><a href="{next:page_url}" title="Go to page {next:page}">{next:page}</a></next>
<next page="3"><a href="{next:page_url}" title="Go to page {next:page}">{next:page}</a></next>
<next page="1"><a href="{next:page_url}" title="Next Page">»</a></next>
</php:paging>
As you can see in this example, we use the previous tags to create links to previous pages, and the next tags for next pages. The NextOrPrevious tag is used to show the current page.
That's how PHP:Paging works, and how you should create all of your paging. But that's not all. There's the perpage tag as well, with an example below. The output of this example will be: Show 25, 50, 75 or 100 items per page.
<php:paging name="test">
Show
<perpage value="25"><a href="{perpage:page_url}">25</a></perpage>,
<perpage value="50"><a href="{perpage:page_url}">50</a></perpage>,
<perpage value="75"><a href="{perpage:page_url}">75</a></perpage> or
<perpage value="100"><a href="{perpage:page_url}">100</a></perpage>
items per page.
</php:paging>
This example clearly demonstrates the use of the perpage tag. It makes it extremely easy to give your visitors the choice on how many items they want to view at a time.
For PHP:Paging to be able to work properly, you must set the totalrecords variable of the paging control. To do this, use the following code:
<?php
$_PAGING->set_totalrecords ('[paging-name]', 500);
?>
That's the only thing that is necessary to make your paging control work properly. To get the totalrecords count, you probably have to do something like SELECT COUNT(*) AS totalrecords FROM yourTable using mysql_query().
However that isn't the only option that can be set. There are 6 more: set_perpage(), set_max_perpage(), set_min_perpage(), set_default_perpage(), set_custom_url(), add_style(). Below is a short example, showing them all, with explanation.
<?php
// Is used to set a minimum perpage, to make sure the perpage can't be any lower
// This prevents tampering by your visitors.
$_PAGING->set_min_perpage ('[paging-name]', 10);
// Is used to set a maximum perpage, to make sure the perpage can't by any higher
$_PAGING->set_max_perpage ('[paging-name]', 100);
// Is used to set a default perpage when no perpage is specified in the URL
$_PAGING->set_default_perpage ('[paging-name]', 50);
// Is used to set a fixed perpage (so only one perpage can be used, the URL is ignored)
$_PAGING->set_perpage ('[paging-name]', 25);
// Is used to set a custom URL. Should be used in combination with mod_rewrite.
// Please note that you must use {var:page} and {var:perpage} in the URL
// for it to work correctly
$_PAGING->set_custom_url ('[paging-name]', 'http://www.example.com/articles/{var:page}/{var:perpage}/');
// Is used to add a custom style
$_PAGING->add_style ('[paging-name]', 'style_name', 'STYLE HTML');
?>
PHP:Paging also has three methods to help you, when creating your SQL query for paging. These methods are called get_perpage(), get_page() and get_limitby(). Below is an example, with explanation.
<?php
// Will return the current perpage of a paging control
$_PAGING->get_perpage('[paging-name']);
// Will return the current page of a paging control
$_PAGING->get_page('[paging-name']);
// Will return the current LIMIT BY clause of a paging control, e.g. LIMIT BY 0, 30
$_PAGING->get_limitby('[paging-name']);
?>
There are also a few global variables that can be used to display certain values. At the moment there are four global variables: page, totalrecords, totalpages, perpage. To display them, use the {var:variable} syntax, e.g. {var:page} will show the current page.
Global variables can be used to make your page look neater, e.g. you can add something like:
Currently viewing page {var:page} out of {var:totalpages} with {var:totalrecords} results
Next and Previous tags are used to create links to previous or next pages. These are the most important tags of the paging control. The full syntax is <next page="[number of next pages]"><a href="{next:page_url}">Go to page {next:page}</a></next> or for the previous tag <previous page="[number of previous pages]"><a href="{previous:page_url}">Go to page {previous:page}</a></next>.
These tags will automatically create the proper URL for you. It will append a new variable to the end of the URL called [paging-name]_page=[newpage]. The [paging-name] is the name of the paging control. They will also automatically check if the page actually exists. For example, if you're already at the last page, the next tags will not show, because those pages don't exist.
Another tag related to the next and previous tags is the NextOrPrevious tag. This tag will allow you to show something when either a next or previous page is available (or both). This is excellent for displaying information that you only want visible when there is actually a need for paging.
Finally, there is also the page tag. This is used to link to a static page, e.g. if you want a link to page 10, then use the following: <page value="10"><a href="{page:page_url}">Go to page 10</a></page>. This tag also checks to make sure the page actually exists.
PerPage tags are used to create links to different perpage pages. PerPage is used to display a different amount of items, e.g. 25 or 50 items. This gives your visitors a choice on how many items they want to view per page.
The full syntax of a perpage tag is as following: <perpage value="[number of items]"><a href="{perpage:page_url}">View {perpage:value} items per page</a></perpage>.
The perpage tag will automatically check if the value isn't lower than the min_perpage or higher than the max_perpage. If that's the case, then it won't be shown. But if you haven't set a min or max perpage, then there's nothing to worry about.
Another unique feature of PHP:Paging are styles. It's likely that you want to use a certain style of paging for your whole PHP script. In that case, you can create a simple HTML file that contains all your paging HTML (excluding the php:paging tags), and use the src attribute to specify a src, for example;
<php:paging name="test" src="/home/you/site/paging.html" />
The HTML that was in paging.html will now be used the as the paging HTML. This will save you a huge amount of time if you use the same style all the time.
You can also specify a certain style, that you have added using the add_style() method (described under PHP Code Necessary). The style attribute is used for this, for example;
<php:paging name="test" style="your_style" />
Now the your_style HTML will be used as the paging HTML. There are also a few in-built styles. At the moment there is only one called 'simple'.
ob_end_* then PHP:Paging will most likely not work. For any questions, problems, comments or anything else, please visit our Community Support Forums or send us an e-mail at support@pallettgroup.com