Paging

This tutorial shows how to do pagination.

Creating object

Below examples show how to create a Paging object and set paging configs:

/* pass setting through the constructor */
$page = new Paging($settings);
$page = new Paging();
/* pass setting through setting method */
$page->setConfigs($settings);

configs can be accessed as properties:

/* set or modify settings as properties */
$page->page = 2;
$page->max_rows = 50;

This is an array of all possible configs set to defaults values:

$settings = array(
    'page'      => 1,
    'url'       => CURRENT_URL,
    'link'      => Paging::LINK_QUERY,
    'key'       => Paging::URL_KEY,
    'max_rows'  => Paging::MAX_ROWS,
    'max_links' => Paging::MAX_LINKS,
    'count'     => total row count,
    'abstract'  => False,
    'js'        => 'Dashboard.list(Paging::PAGE)',
    /* rendering settings */
    'style'    => Paging::LINK_NOM,
    'next'     => _('>'),
    'previous' => _('<'),
    'first'    => _('<<'),
    'last'     => _('>>'),
    'tag'      => 'li',
    'leftbox'  => Null,
    'rightbox' => Null,
    'info'     => _('Paging::FROM - Paging::TO / Paging::COUNT'),
    'infopos'  => 'right',
    'midware'  => Null,
    'plugin'   => Null;
);

Rendering configs are only used by HTML renderer and can be passed to the renderer method instead.

config keys are explained in Paging API - configs .

config decision making:

    • Set link type to JavaScript:
      $settings['link'] = Paging::LINK_JS;
      
      Set JavaScript function:
      /* Paging::PAGE and Paging::URL strings can be inside the value and
         will be replaced by their appropriate values
         Paging::PAGE === REPLACED TO ===> link page number
         Paging::URL  === REPLACED TO ===> URL set in settings
       */
      $settings['js'] = "callMeOnLinkClick(Paging::PAGE, 'Paging::URL')";
      
      Default value requires jQuery and arta.js and will call a function named Dashboard.list() which must be created by the programmer for handling the link clicks.
    • Set link type:
      /* to add page number to query string:
         $settings['url']?$settings['key']=2 */
      $settings['link'] = Paging::LINK_QUERY;
      
      /* to add page number to the end of URL:
         $settings['url']/2 */
      $settings['link'] = Paging::LINK_PATH;
      
      /* to add key and page number to the end of URL:
         $settings['url']/$settings['key']/2 */
      $settings['link'] = Paging::LINK_PATH_KEY;
      
      Set link URL:
      $settings['url'] = 'http://dev.example.com/list';
      
      Set a key:
      $settings['key'] = 'pagenom';
      
  • $configs['page'] = 2;
  • $configs['max_rows'] = 30;
  • $configs['max_links'] = 6;
    6 - 7 - 8 - [9] - 10 - 11 - 12
  • $configs['count'] = 3000;
    When possible calculate max row count once and cache it to be used for the same set of pages.

Getting raw array

To get raw paging links:

$settings = array(
    'page' => 1,
    'link' => Paging::LINK_JS,
    'js'   => 'myPagingJSFunction(Paging::PAGE)',
    /* other paging settings */
);
$page = new Paging($settings);
$raw = $this->raw();

Returned value is an array:

$raw = array(
    /* Current page and arrow links */
    'first' => array(
        'page'   => 1,
        'active' => False,
        'url'    => 'myPagingJSFunction(1)',
        'from'   => 1,
        'to'     => 30,
    ),
    'last' => array(
        'page'   => 122,
        'active' => True,
        'url'    => 'myPagingJSFunction(122)',
        'from'   => 3631,
        'to'     => 3645,
    ),
    'previous' => array(
        'page'   => 1,
        'active' => False,
        'url'    => 'myPagingJSFunction(1)',
        'from'   => 1,
        'to'     => 30,
    ),
    'next' => array(
        'page'   => 2,
        'active' => True,
        'url'    => 'myPagingJSFunction(2)',
        'from'   => 31,
        'to'     => 60,
    ),
    'current' => array(
        'page'   => 1,
        'active' => True,
        'url'    => 'myPagingJSFunction(1)',
        'from'   => 1,
        'to'     => 30,
    ),
    /* page liniks */
    'links' => array(
        /* links left to current page */
        'left' => array(
            /* empty for first page */
        ),
        /* links right to current page */
        'right' => array(
            array(
                'page'   => 2,
                'active' => True,
                'url'    => 'myPagingJSFunction(2)',
                'from'   => 31,
                'to'     => 60,
            ),
            array(
                'page'   => 3,
                'active' => True,
                'url'    => 'myPagingJSFunction(3)',
                'from'   => 61,
                'to'     => 90,
            ),
            array(
                'page'   => 4,
                'active' => True,
                'url'    => 'myPagingJSFunction(4)',
                'from'   => 91,
                'to'     => 120,
            ),
            array(
                'page'   => 5,
                'active' => True,
                'url'    => 'myPagingJSFunction(5)',
                'from'   => 121,
                'to'     => 150,
            ),
            array(
                'page'   => 6,
                'active' => True,
                'url'    => 'myPagingJSFunction(6)',
                'from'   => 151,
                'to'     => 180,
            ),
        ),
    ),
    /* total row count */
    'count' => 3645,
    'js'    => True,
);

Getting HTML links

To get links as HTML:

$settings = array(
    'page' => 1,
    'link' => Paging::LINK_JS,
    'js'   => 'myPagingJSFunction(Paging::PAGE)',
    /* other paging settings */
);
$page = new Paging($settings);
$html = $page->render();

Returned string would look like:

<ul>
  <li class="first disabled">
    <a href="#" onclick="myPagingJSFunction(1); return false;"
        class="hide">First</a>
  </li>
  <li class="dots disabled"><label>...</label></li>
  <li class="previous disabled">
    <a href="#" onclick="myPagingJSFunction(1); return false;"
        class="hide">«PREV</a>
  </li>
  <li class="current">
    <a href="#" onclick="myPagingJSFunction(1); return false;">1</a>
  </li>
  <li>
    <a href="#" onclick="myPagingJSFunction(2); return false;">2</a>
  </li>
  <li>
    <a href="#" onclick="myPagingJSFunction(3); return false;">3</a>
  </li>
  <li>
    <a href="#" onclick="myPagingJSFunction(4); return false;">4</a>
  </li>
  <li>
    <a href="#" onclick="myPagingJSFunction(5); return false;">5</a>
  </li>
  <li>
    <a href="#" onclick="myPagingJSFunction(6); return false;">6</a>
  </li>
  <li class="next">
    <a href="#" onclick="myPagingJSFunction(2); return false;">NEXT»</a>
  </li>
  <li class="dots"><label>...</label></li>
  <li class="last">
    <a href="#" onclick="myPagingJSFunction(122); return false;">Last</a>
  </li>
  <li class="info">1 - 30 / 3645</li>
</ul>

To customize HTML, rendering configs can be passed to method render. See Paging API - render configs

In below example two render configs are used to change the output:

$settings['style']   = Paging::FROM_TO;
$settings['midware'] = 'Persian::number';
$page = new Paging($settings);
$html = $page->render();

Config style to Paging::FROM_TO will change the page links to:

.
.
.
  <li>
    <a href="#" onclick="myPagingJSFunction(2); return false;">31 - 60</a>
  </li>
  <li>
    <a href="#" onclick="myPagingJSFunction(3); return false;">61 - 90</a>
  </li>
  <li>
    <a href="#" onclick="myPagingJSFunction(4); return false;">91 - 120</a>
  </li>
.
.
.

A midware can be used to change the paging numbers before being put in the HTML. Set midware to a static class method such as:

class Persian
{
    static public function number(&$string, $typeOfLink) {
        $digits = array('۰', '۱', '۲', '۳', '۴', '۵', '۶', '۷', '۸', '۹');
        if($return)
            return str_replace(array_keys($digits), $digits, $string);
        $string = str_replace(array_keys($digits), $digits, $string);
    }
}

The output would look like:

.
.
.
  <li>
    <a href="#" onclick="myPagingJSFunction(2); return false;">۳۱ - ۶۰</a>
  </li>
  <li>
    <a href="#" onclick="myPagingJSFunction(3); return false;">۶۱ - ۹۰</a>
  </li>
  <li>
    <a href="#" onclick="myPagingJSFunction(4); return false;">۹۱ - ۱۲۰</a>
  </li>
.
.
.

Styling with CSS

Here is an CSS example to style rendered paging links:



/* paging links > */
.page-links {
  padding-top: 10px;
  height: 30px;
}

.page-links ul {
  float: right;
  list-style-type: none;
}

.page-links li {
  float: left;
  height: 31px;
  padding: 1px;
}

.page-links li a {
  display: block;
  border: 1px solid #aaa;
  border-radius: 3px;
  -moz-border-radius: 3px;
  padding: 2px;
  color: #444;
  background-color: #fafafa;
  min-width: 20px;
  text-align: center;
}

.page-links li a:hover {
  text-decoration: none;
  background-color: #a4e7a4;
}

.page-links .first a,
.page-links .last a,
.page-links .previous a,
.page-links .next a {
  width: 30px;
  background-color: #ddd;
  border-color: #ccc;
}

.page-links .first a:hover,
.page-links .last a:hover,
.page-links .previous a:hover,
.page-links .next a:hover {
  background-color: #a4e7a4;
  border-color: #ccc;
}

.page-links .disabled {
  display: none;
}

.page-links .info {
  padding: 5px 2px 3px 2px;
  color: #444;
}

.page-links .current a:hover,
.page-links .current a {
  background-color: #999;
  color: white;
  border: 1px solid #999;
  font-weight: bold;
  cursor: default!important;
}

.page-links .dots {
  color: #888;
  padding: 3px;
}
/* < paging links */


Paging for database data

Examples of querying pages and getting paging links:

$settings = array(
    'page' => 1,
    /* other paging settings */
);
$page = new Paging($dbo->page('SELECT * FROM users;', $settings));
$settings = array(
    'page'      => $request->get(Paging::URL_KEY, 1, INT),
    'max_rows'  => 70,
    'max_links' => 10,
    /* other paging settings */
);

$page = new Paging(
    $dbo->page(
        'SELECT * FROM users WHERE group_id = $1;',
         79,
         $settings
    )
);

$pagingLinksRaw  = $page->raw();
$pagingLinksHTML = $page->render();

Paging for model data

Example of querying pages and getting paging links:

$settings = array(
    'page' => $request->get(Paging::URL_KEY, 1, INT),
    'link' => Paging::LINK_JS,
    /* other paging settings */
);

$user = new Users();

$user
    ->slice($settings)
    ->sort('id desc')
    ->query();

$pagingLinksRaw  = $user->__page__->raw();
$pagingLinksHTML = $user->__page__->render();

Example

Paging
TOP