Pager

There are two sides to Pager: the display and the feed. The display occurs in your controller's HTML view.

    public function getHtmlView($data, \Request $request)
    {
        \Pager::prepare();
        $template = new \Template;
        $template->setModuleTemplate('your_module', 'templateSubDirectory/Pager_Template_file.html');
        return $template;
    }

The prepare function just includes the pager javascript. Your html template should look like the following:

<div class="pager-listing" id="pet-list" data-rpp="10">
    <div style="text-align:right" class="pager-search"></div>
    <table class="table table-striped">
        <thead class="pager-head">
            <tr>
                <th class="pager-header animal"></th>
                <th class="pager-header name"></th>
                <th class="pager-header color"></th>
            </tr>
        </thead>
        <tbody class="pager-body">
            <tr class="pager-row">
                <td class="pager-column animal"></td>
                <td class="pager-column name"></td>
                <td class="pager-column color"></td>
            </tr>
        </tbody>
    </table>
    <div class="pagination pagination-centered"></div>
</div>

Make sure you have a block node (like <div>) surrounding your pager html. This block MUST have a distinct id and the class "pager-listing". The data field (data-rpp="10") indicates how many "rows per page" should be shown. Pager will call the current url the pager is on by default. If you want to use a custom url to collect the pager data then your pager-listing needs a pager-url data attribute, like so:

<div class="pager-listing" id="pet-list" data-rpp="10" data-pager-url="modulename/jsonpath/">

In this example, the next required node is "pager-search." This will create a search box for the pager. The last UI requirement is near the bottom. The "pagination" class node will contain a listing of pages the user can navigate through.

Sorting the columns of information occurs in "pager-header" class node. Make sure each header contains that class AND, very important, the name of the column the header will sort.

Finally, the rows themselves appear in the "pager-row" by using the "pager-column" nodes. Again, it is important that the column names appear as classes in the pager-column. You only need to give a single example row. The Pager will use it as a stamp for the remaining rows.

The Pager will now attempt to access your controller's JSON view. This view should exist at the same url used to access the html view.

The first example we will use is a static listing of rows.

 protected function getJsonView($data, \Request $request)
    {
        $rows[] = array('animal' => 'dog', 'name' => 'Lassie', 'color' => 'Brown and white');
        $rows[] = array('animal' => 'dog', 'name' => 'Beethoven', 'color' => 'Brown and white');
        $rows[] = array('animal' => 'cat', 'name' => 'Meow Se Tung', 'color' => 'Black');
        $rows[] = array('animal' => 'bird', 'name' => 'Tweety', 'color' => 'Yellow');
        $rows[] = array('animal' => 'mouse', 'name' => 'Mickey', 'color' => 'White and black');
        $rows[] = array('animal' => 'mongoose', 'name' => 'Ricki Ticki Tavi', 'color' => 'Brown');
        $pager = new \Pager;
        $pager->setId('pet-list');
        $pager->setHeaders(array('animal', 'name', 'color'));
        $pager->setRows($rows);
        $data = $pager->getJson();
        return parent::getJsonView($data, $request);
}

Construct a new Pager. Use setId to tell Pager which pager to update. Use setHeaders to inform Pager what you are planning to sort. If you send an associative array here, the key of the array will be checked as the header and the value will be displayed on the pager. Note: you can have other headers in your template, but since you aren't sorting them, do not include them. Next, set the rows you want using setRows. Finally, getJson to get the data object you will import into getJsonView. If all goes well, your rows and headers will be imported into your template via Ajax. Pagination and sorting will be handled automatically.

Much of your Pager experience will involve the database. For this interaction, use the DatabasePager class.

protected function getJsonView($data, \Request $request)
    {
          $db = \Database::newDB();
          $users = $db->addTable('pets');

          $pager = new \DatabasePager($db);
          $pager->setId('pet-list');
          $pager->setHeaders(array('animal' => 'Animal', 'name' => 'Name', 'color' => 'Color'));
          $tbl_headers['animal'] = $users->getField('animal');
          $tbl_headers['name'] = $users->getField('name');
          $tbl_headers['color'] = $users->getField('color');
          $pager->setTableHeaders($tbl_headers);

          $data = $pager->getJson();
          return parent::getJsonView($data, $request);
    }

DatabasePager is an extension of Pager that requires a little more information to function properly. Use the setTableHeaders method to associate the header names to table column fields. This will facilitate proper sorting.

Working with Rows

There are two methods to manipulate the row output which will allow you to perform actions upon them.

The first method is to give each row a "row-id." In your JSON view function, use Pager's setRowIdColumn method. For example:

$rows[] = array('animal' => 'mouse', 'name' => 'Mickey', 'color' => 'White and 
$rows[] = array('animal' => 'mongoose', 'name' => 'Ricki Ticki Tavi', 'color' => 'Brown');
$pager = new \Pager;
$pager->setId('pet-list');
$pager->setHeaders(array('animal', 'name', 'color'));
$pager->setRows($rows);
$pager->setRowIdColumn('animal');
$data = $pager->getJson();
return parent::getJsonView($data, $request);

Using a portion of the above template, you need to add the row-id using a data attribute:

        <tbody class="pager-body">
            <tr class="pager-row" data-row-id="">
                <td class="pager-column animal"></td>
                <td class="pager-column name"></td>
                <td class="pager-column color"></td>
            </tr>
        </tbody>

Now, when the rows are returned in the JSON object, the data-row-id attribute will contain the result of the column you set in setRowIdColumn. Now you could use jquery, for example, to pull that attribute:

$('.pager-row').click(function(){
    alert($(this).data('rowId'));
});

The second method of manipulating the row results is to set a callback:

 // Make sure the class name contains the correct namespace.
 $pager->setCallback(array('PetController', 'addNewColumn'));
 // works like call_user_func()

Now, after the rows have been collected, the PetController::addNewColumn method will receive each row array as a parameter. In return, the method should return the altered row:

class PetController {
    public static function addNewColumn($row_array) {
        $row_array['animal'] = strtoupper($row_array['animal']);
        return $row_array;
    }
}