Using JPagination in your component

Note Please note that the content on this page is currently incomplete. Please treat it as a work in progress.

Class Overview

The JPagination class, introduced in Joomla! 1.5, allows developers to reliably and consistently add pagination to the Front-end and Back-end display of their components. The file containing the class can be found at /libraries/joomla/html/pagination.php.

Variables

The construct function of the class requires three variables:

• $total - the total number of items in a list,
• $limitstart - the offset of the item at which to start, and
• $limit - the number of items to display per page.

Static Class Methods

getRowOffset($index)

getData()

getPagesCounter()

	/**
	 * Create and return the pagination pages counter string
	 *
	 * @access	public
	 * @return	string	Pagination pages counter string
	 * @since	1.5
	 */
	function getPagesCounter()

Returns a string containing the current page and total pages as

getResultsCounter()

	/**
	 * Create and return the pagination result set counter string
	 *
	 * @access	public
	 * @return	string	Pagination result set counter string
	 * @since	1.5
	 */
	function getResultsCounter()

Returns a string containing the results currently being displayed as

getPagesLinks()

	/**
	 * Create and return the pagination page list string, ie. Previous, Next, 1 2 3 ... x
	 *
	 * @access	public
	 * @return	string	Pagination page list string
	 * @since	1.0
	 */
	function getPagesLinks()

Returns an HTML string to display the Pages Links as

getListFooter()

	/**
	 * Return the pagination footer
	 *
	 * @access	public
	 * @return	string	Pagination footer
	 * @since	1.0
	 */
	function getListFooter()

Returns a combination of the several page-related elements, including: the Display Limit dropdown, the Pages Links and the Pages Counter. Appearance differs in the Front-end and Back-end due to additional CSS formatting applied with the Khepri template.

Front-end:

Back-end:

getLimitBox()

	/**
	 * Creates a dropdown box for selecting how many records to show per page
	 *
	 * @access	public
	 * @return	string	The html for the limit # input box
	 * @since	1.0
	 */
	function getLimitBox()

Returns an HTML string that will output the Display Limit dropdown as

orderUpIcon()

orderDownIcon()

Implementation

Changes to the Model

Declare $_total and $_pagination variables in the model; these will be returned by the functions getTotal() and getPagination(), respectively.

  /**
   * Items total
   * @var integer
   */
  var $_total = null;

  /**
   * Pagination object
   * @var object
   */
  var $_pagination = null;

Add to or create a __construct() function that will establish values for the $limitstart and $limit variables as these are needed by the JPagination class.

  function __construct()
  {
 	parent::__construct();

	global $mainframe, $option;

	// Get pagination request variables
	$limit = $mainframe->getUserStateFromRequest('global.list.limit', 'limit', $mainframe->getCfg('list_limit'), 'int');
	$limitstart = $mainframe->getUserStateFromRequest($option.'.limitstart', 'limitstart', 0, 'int');

	// In case limit has been changed, adjust it
	$limitstart = ($limit != 0 ? (floor($limitstart / $limit) * $limit) : 0);

	$this->setState('limit', $limit);
	$this->setState('limitstart', $limitstart);
  }

Revise the getData() function, adding the $limitstart and $limit values to the _getList() query. This causes only the needed rows to be returned, rather than all rows.

  function getData() 
  {
 	// if data hasn't already been obtained, load it
 	if (empty($this->_data)) {
 	    $query = $this->_buildQuery();
 	    $this->_data = $this->_getList($query, $this->getState('limitstart'), $this->getState('limit'));	
 	}
 	return $this->_data;
  }

Create a getTotal() function. This function uses the _getListCount() method from JModel to return the total number of rows in the query. The value returned will be used by the getPagination() function.

  function getTotal()
  {
 	// Load the content if it doesn't already exist
 	if (empty($this->_total)) {
 	    $query = $this->_buildQuery();
 	    $this->_total = $this->_getListCount($query);	
 	}
 	return $this->_total;
  }

Create a getPagination() function. The function will create and return a new Pagination object that can be accessed by the View.

  function getPagination()
  {
 	// Load the content if it doesn't already exist
 	if (empty($this->_pagination)) {
 	    jimport('joomla.html.pagination');
 	    $this->_pagination = new JPagination($this->getTotal(), $this->getState('limitstart'), $this->getState('limit') );
 	}
 	return $this->_pagination;
  }

Changes to the View

Revise the View to obtain the pagination object created in the Model and assign it for use in the template.

  ...
  	// Get data from the model
 	$items =& $this->get('Data');	
 	$pagination =& $this->get('Pagination');

	// push data into the template
	$this->assignRef('items', $items);	
	$this->assignRef('pagination', $pagination);
  ...

Changes to the Template

Add a footer area to the display table in the template which holds the pagination object. The method getListFooter() from the JPagination class generates the buttons and their next/previous functionality as shown in the image above. Edit colspan="9" to reflect the number of columns in the table.

  ...
  <tfoot>
    <tr>
      <td colspan="9"><?php echo $this->pagination->getListFooter(); ?></td>
    </tr>
  </tfoot>
  ...