Pagination

There are multiple approaches to implement item pagination, with the simplest being the utilization of the paginate method either on the query builder or an Eloquent query in OstroJS. The paginate method conveniently manages the setting of the query's "limit" and "offset" based on the user's current page. By default, OstroJS identifies the current page through the value of the "page" query string parameter in the HTTP request. This value is automatically detected and incorporated into the links generated by the paginator.

In the provided example, the paginate method is invoked with a single argument, indicating the desired number of items to be displayed "per page." Here, the specification is set to display 15 items per page.

const Controller = require('~/app/http/controllers/controller');
const DB = require('@ostro/support/facades/database')

class UserController extends Controller {

    async index({request,view,params}) {
        view('user.index', {
            'users' : await DB.table('users').request(request).paginate(15)
        });
    }
}

module.exports = UserController

You can paginate Eloquent queries in Ostro.js as well. In this example, we'll paginate the app/models/user model and specify that we want to display 15 records per page. The syntax is very similar to paginating query builder results, as illustrated below:

const User =  require('~/app/models/user');
 
const users = await User.paginate(15);

Certainly, you can invoke the paginate method after applying additional constraints to the query, such as where clauses, in OstroJS:

// Example of paginating an Eloquent query with additional constraints
const usersPerPage = 15;

const users = await User.where('status', 'active') // Additional constraint
                        .orderBy('created_at', 'desc') // Another constraint
                        .request(request)
                        .paginate(usersPerPage);

In certain scenarios, there might be a need to display two distinct paginators on a single screen in your OstroJS application. However, if both paginator instances utilize the same page query string parameter to track the current page, conflicts may arise. To address this issue, you can resolve the conflict by specifying the name of the query string parameter you want to use for storing the current page in the third argument provided to the paginate methods:

// Example of using a custom query string parameter for pagination
const itemsPerPage = 10;

const firstPaginator = await SomeModel.request(request).paginate(itemsPerPage, 1, 'firstPage'); // Using 'firstPage' as the query string parameter

const secondPaginator = await AnotherModel.request(request).paginate(itemsPerPage, 1, 'secondPage'); // Using 'secondPage' as the query string parameter

The OstroJS paginator classes Interface contract and provide the toJson method, making it straightforward to convert pagination results to JSON. You can achieve this by returning a paginator instance from a route or controller action:

const itemsPerPage = 10;

// Example of converting a paginator instance to JSON in Ostro.js
const paginatedData = await SomeModel.request(request).paginate(itemsPerPage);

// Convert paginator instance to JSON
const paginatedJson = paginatedData.toJson();

// Return JSON response from a route or controller action
response.send( {
  status: 'success',
  data: paginatedJson,
});

The JSON generated by the paginator in Ostro.js includes meta information such as total, current_page, last_page, and more. The result records can be accessed via the data key in the JSON object. Here's an example of the JSON structure created by returning a paginator instance from a route or controller action:

{
   "total": 50,
   "per_page": 15,
   "current_page": 1,
   "last_page": 4,
   "first_page_url": "http://ostrojs.app?page=1",
   "last_page_url": "http://ostrojs.app?page=4",
   "next_page_url": "http://ostrojs.app?page=2",
   "prev_page_url": null,
   "path": "http://ostrojs.app",
   "from": 1,
   "to": 15,
   "data":[
        {
            // Record...
        },
        {
            // Record...
        }
   ]
}