Actions

J1.5

Difference between revisions of "Using JPagination in your component"

From Joomla! Documentation

Line 1: Line 1:
 
{{inuse}}
 
{{inuse}}
<span style="color:red;">Please Note:</span> This page has not been completed and instructions below apply specifically to adding Pagination in the Back-end.  Additional instructions for the Front-end will be added soon.
+
{{Content-incomplete}}
  
 
+
{{RightTOC}}
==Introduction==
+
==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.   
 
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.   
  
In the Back-end, the getListFooter() function is used to display the pagination object. This generates a limit dropdown listbox, start/end, previous/next, and current page buttons, and current page indicator (i.e., Page 1 of 5) as shown in the image below.
+
====Variables====
[[Image:Pagination.png]]
+
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()=====
 +
<pre>
 +
/**
 +
* Create and return the pagination pages counter string
 +
*
 +
* @access public
 +
* @return string Pagination pages counter string
 +
* @since 1.5
 +
*/
 +
function getPagesCounter()
 +
</pre>
 +
 
 +
Returns a string containing the current page and total pages as [[image:pagescounter.png]]
 +
 
 +
=====getResultsCounter()=====
 +
<pre>
 +
/**
 +
* Create and return the pagination result set counter string
 +
*
 +
* @access public
 +
* @return string Pagination result set counter string
 +
* @since 1.5
 +
*/
 +
function getResultsCounter()
 +
</pre>
 +
 
 +
Returns a string containing the results currently being displayed as [[image:resultscounter.png]]
 +
 
 +
=====getPagesLinks()=====
 +
<pre>
 +
/**
 +
* 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()
 +
</pre>
 +
 
 +
Returns an HTML string to display the Pages Links as [[image:pageslinks.png]]
 +
 
 +
=====getListFooter()=====
 +
<pre>
 +
/**
 +
* Return the pagination footer
 +
*
 +
* @access public
 +
* @return string Pagination footer
 +
* @since 1.0
 +
*/
 +
function getListFooter()
 +
</pre>
 +
 
 +
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:listfooter_back.png]]
 +
 
 +
=====getLimitBox()=====
 +
<pre>
 +
/**
 +
* 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()
 +
</pre>
 +
 
 +
Returns an HTML string that will output the Display Limit dropdown as [[image:limitbox.png]]
 +
 
 +
=====orderUpIcon()=====
 +
 
 +
=====orderDownIcon()=====
  
In the Front-end, several functions can be called in the template to produce each of these items separately.
 
  
==Changes to the Model==
+
==Implementation==
 +
====Changes to the Model====
 
Declare $_total and $_pagination variables in the model; these will be returned by the functions getTotal() and getPagination(), respectively.
 
Declare $_total and $_pagination variables in the model; these will be returned by the functions getTotal() and getPagination(), respectively.
 
<pre>
 
<pre>
Line 87: Line 171:
  
  
==Changes to the View==
+
====Changes to the View====
 
Revise the View to obtain the pagination object created in the Model and assign it for use in the template.
 
Revise the View to obtain the pagination object created in the Model and assign it for use in the template.
 
<pre>
 
<pre>
Line 102: Line 186:
  
  
==Changes to the Template==
+
====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.
 
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.
 
<pre>
 
<pre>

Revision as of 15:38, 17 February 2008

Replacement filing cabinet.png
This Namespace has been archived - Please Do Not Edit or Create Pages in this namespace. Pages contain information for a Joomla! version which is no longer supported. It exists only as a historical reference, will not be improved and its content may be incomplete.
Quill icon.png
Page Actively Being Edited!

This j1.5 page is actively undergoing a major edit for a short while.
As a courtesy, please do not edit this page while this message is displayed. The user who added this notice will be listed in the page history. This message is intended to help reduce edit conflicts; please remove it between editing sessions to allow others to edit the page. If this page has not been edited for several hours, please remove this template, or replace it with {{underconstruction}} or {{incomplete}}.

Template:Content-incomplete

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 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 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 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: File:Listfooter front.png Back-end: File:Listfooter back.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 Limitbox.png

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); // _getListCount is from JModel class
        }
        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>
  ...