Pagination

Since version 3.7.6 WP e-Commerce provides a suite of functions so that you can customise the pagination display on product category and group pages.

This page will give you an overview of those paging functions and how you can customise the pagination in your WPEC templates.

Where to start?

Pagination can be implemented in the templates that are used to display multiple products such as a category. This includes the default view, grid view and list view:

  • products_page.php
  • grid_view.php
  • list_view.php

If you look at the products_page.php file in the default WPEC template theme you’ll be able to see how the pagination functions are implemented.

In the WP e-Commerce settings you can choose wether to show pagination and if so wether it should be shown at the top of the page, the bottom, or both. In order for this to work correctly, the pagination functions you use must be wrapped in a bit code so that the pagination is only show in accordance with these settings.

For the pagination at the top of the page:

<!-- Start Pagination -->
<?php if ( ( get_option( 'use_pagination' ) == 1 && ( get_option( 'wpsc_page_number_position' ) == 1 || get_option( 'wpsc_page_number_position' ) == 3 ) ) ) : ?>
<div>
<?php if ( wpsc_has_pages() ) : ?>
<!-- Insert paging functions here -->
<?php endif; ?>
</div>
<?php endif; ?>
<!-- End Pagination -->

For the pagination at the bottom of the page you should use the same code as above but change the first line to check that get_option( ‘wpsc_page_number_position’ ) == 2:

<?php if ( ( get_option( 'use_pagination' ) == 1 && ( get_option( 'wpsc_page_number_position' ) == 2 || get_option( 'wpsc_page_number_position' ) == 3 ) ) ) : ?>

Pagination Functions

The following functions can be used to display pagination. You can insert them into the code above, replacing the <!– Insert paging functions here –> placeholder. Each function returns HTML and should be displayed using echo. Check the default WPEC theme for an example.

wpsc_pagination( $show )

Displays page numbers as links. The current page number link will have a ‘selected’ class applied for styling.

$show (int) (optional) The maximum number of pages to show at a time. Setting $show to -1 will show all pages. Default: -1

wpsc_previous_products_link( $text, $show_disabled )

Show a link to the previous products page.

$text (string) (optional) The text to use for the link. Default: ‘Previous’
$show_disabled (bool) (optional) Wether the text show be shown even if there is no previous page (not as a link, will be wrapped in a span tag). Default: false

wpsc_next_products_link( $text, $show_disabled )

Show a link to the next products page.
$text (string) (optional) The text to use for the link. Default: ‘Next’
$show_disabled (bool) (optional) Wether the text show be shown even if there is no previous page (not as a link, will be wrapped in a span tag). Default: false

wpsc_first_products_link( $text, $show_disabled )

Show a link to the first products page.

$text (string) (optional) The text to use for the link. Default: ‘First’
$show_disabled (bool) (optional) Wether the text show be shown even if you are viewing the first page (not as a link, will be wrapped in a span tag). Default: false

wpsc_last_products_link( $text, $show_disabled )

Show a link to the last products page.

$text (string) (optional) The text to use for the link. Default: ‘Last’
$show_disabled (bool) (optional) Wether the text show be shown even if you are viewing the last page (not as a link, will be wrapped in a span tag). Default: false

wpsc_showing_products_page()

Displays where you are in the paging hierarchy. For example, page “2 of 5″.

wpsc_showing_products()

Displays on indication of which products you are viewing in the paging hierarchy. For example, viewing products “11 to 20″.

wpsc_total_product_count()

Displays the total number of products for the current query.

wpsc_current_page()

The current page number.

Examples

These examples should be wrapped in the pagination code mentioned at the top of this page.

Display standard paging limited to 10 pages with next, previous, first and last links.

<?php echo wpsc_first_products_link( '&laquo; First', true ); ?>
<?php echo wpsc_previous_products_link( '&laquo; Previous', true ); ?>
<?php echo wpsc_pagination( 10 ); ?>
<?php echo wpsc_next_products_link( 'Next &raquo;', true ); ?>
<?php echo wpsc_last_products_link( 'Last &raquo;', true ); ?>
;

Display the number of products you are currently viewing.

Showing <?php echo wpsc_showing_products(); ?> of <?php echo wpsc_total_product_count(); ?> products

A more complex example demonstrates how you can display paging if there are multiple pages, otherwise display the total number of products.

<!-- Start Pagination -->
<?php if ( ( get_option( 'use_pagination' ) == 1 && ( get_option( 'wpsc_page_number_position' ) == 1 || get_option( 'wpsc_page_number_position' ) == 3 ) ) ) : ?>
<div>
<?php if ( wpsc_has_pages() ) : ?>
Page <?php echo wpsc_showing_products_page(); ?>: <?php echo wpsc_previous_products_link( '&laquo; Previous', true ); ?>
<?php echo wpsc_pagination(); ?>
<?php echo wpsc_next_products_link( 'Next &raquo;', true ); ?>
<?php else : ?>
Showing <?php echo wpsc_total_product_count(); ?> products
<?php endif; ?>
</div>
<?php endif; ?>
<!-- End Pagination -->