Using JPagination in your component

From Joomla! Documentation

Jump to: navigation, search
Note

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

Contents

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 image:pagescounter.png

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 image:resultscounter.png

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 image:pageslinks.png

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: image:listfooter-front.png

Back-end: image:pagination.png

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 image:limitbox.png

orderUpIcon()

orderDownIcon()

Examples

with JDatabase

Here is a nice method that uses the strength of mysql who knows pagination too. Really!

Most developers don't use the SQL_CALC_FOUND_ROWS and just double the query without limit. Just don't!! ;-)

$db =& JFactory::getDBO();
$lim   = $mainframe->getUserStateFromRequest("$option.limit", 'limit', 14, 'int'); //I guess getUserStateFromRequest is for session or different reasons
$lim0  = JRequest::getVar('limitstart', 0, '', 'int');
$db->setQuery('SELECT SQL_CALC_FOUND_ROWS x, y, z FROM jos_content WHERE x',$lim0, $lim);
$rL=&$db->loadAssocList();
if (empty($rL)) {$jAp->enqueueMessage($db->getErrorMsg(),'error'); return;}  
else {
////Here the beauty starts
$db->setQuery('SELECT FOUND_ROWS();');  //no reloading the query! Just asking for total without limit
jimport('joomla.html.pagination');
$pageNav = new JPagination( $db->loadResult(), $lim0, $lim );
foreach($rL as $r) {
//your display code here
}
echo $pageNav->getListFooter(  ); //Displays a nice footer

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 = JRequest::getVar('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>
  ...
Retrieved from "http://docs.joomla.org/Using_JPagination_in_your_component"
Personal tools