Pagination Library

revIgniter's Pagination library is very easy to use. It is 100% customizable, either dynamically or via stored preferences, and it even works with AJAX and furthermore with ASYNergy.

If you are not familiar with the term "pagination", it refers to links that allows you to navigate from page to page, like this:

« First  < 1 2 3 4 5 >  Last »

The Pagination library builds the markup consisting of links used to navigate from page to page.

Initializing the Library

Like most other libraries in revIgniter, the Pagination library is initialized in your controller using the rigLoaderLoadLibrary handler:

rigLoaderLoadLibrary "Pagination"

Example

Here is a simple example showing how to create pagination in one of your controller handlers:

rigLoaderLoadLibrary "Pagination"
# PAGINATION CONFIGURATION
put "page" into tConfig["paginationHandler"]
put 200 into tConfig["totalRows"]
put 20 into tConfig["perPage"]

# INITIALIZE PAGINATION
rigInitializePagination tConfig

# GET PAGINATION HTML LINKS
put rigCreatePaginationLinks() into gData["pagination"]

Notes:

The tConfig array contains your configuration variables. It is passed to the rigInitializePagination handler as shown above. Although there are some twenty items you can configure, at minimum you need the three shown. Here is a description of what those items represent:

• paginationHandler This is the name of the handler containing your pagination. In the example above, it is pointing to a handler called "page". If you add the pagination code to your index handler, you do not need to specify this variable because the default value is "index".
• baseUrl Alternatively you can define the full URL to the controller/handler containing your pagination. The following example points to a controller called "test" and a handler called "page". Keep in mind that you can re-route your URI if you need a different structure.

put "http://example.com/index.lc/test/page/" into tConfig["baseUrl"]

• totalRows This number represents the total rows in the result set you are creating pagination for. Typically this number will be the total rows that your database query returned.
• perPage The number of items you intend to show per page. In the above example, you would be showing 20 items per page.

The rigCreatePaginationLinks() function returns an empty string when there is no pagination to show.

Another Example

As explained above, to build the pagination HTML links the library needs to be provided either with the name of your pagination handler, or with the URL of your page including the segments consisting of the name of your controller and the name of the corresponding handler unless you don't include the code in question in the default handler (index). Now the important part: The third segment is a number, the page number calculated by the library which should be evaluated by your pagination handler as shown below:

# LET'S ASSUME YOU RETRIEVE YOUR DATA FROM A SQL DATABASE
# USING ACTIVE RECORD FEATURES
command test
  rigLoaderLoadLibrary "Pagination"
  # CONNECT TO DATABASE
  get rigLoadDatabase("yourDatabase")
end test

command page
  # GET TOTAL NUMBER OF ROWS
  put rigDbCountAllResults("yourTable") into tTotalNumRecords

  # PAGINATION CONFIGURATION
  # DO THE PAGINATION HANDLER CONFIGURATION
  put "page" into tConfig["paginationHandler"]
  
  # SET LIMIT OF ROWS TO BE DISPLAYED
  # LET'S SAY YOU WANT TO SHOW 20 ITEMS PER PAGE
  put 20 into tConfig["perPage"]
  
  # SET TOTAL ROWS CONFIGURATION
  put tTotalNumRecords into tConfig["totalRows"]
  # CONFIGURATION END
  
  # INITIALIZE PAGINATION
  rigInitializePagination tConfig

  # GET PAGE NUMBER
  # NOTE: THIS IS THE OFFSET FOR YOUR QUERY
  put rigFetchSegment(3) into tPageNum
  if (tPageNum is an integer) and (tPageNum > 0) and (tPageNum < tTotalNumRecords) then
    put tPageNum into tOffset
  else
    put 0 into tOffset
  end if

  # GET DATABASE QUERY RESULT DATA 
  # YOUR DATABASE QUERY STUFF HERE . . . LIKE
  # rigDbOrderBy, rigDbWhere OR WHATEVER

  # SET THE QUERY LIMITS
  rigDbLimit tConfig["perPage"], tOffset

  # GET QUERY RESULT
  put rigDbGet("yourTable") into tQueryResult

  if tQueryResult["numrows"] > 0 then
    # DEAL WITH THE QUERY RESULT DATA HERE, BUILD A TABLE OR WHATEVER
    # . . .
    # STORE YOUR PAGINATION DATA IN gData
    put tYourData into gData["paginationData"]
  
    # FINALLY GET PAGINATION HTML LINKS
    put rigCreatePaginationLinks() into gData["paginationLinks"]
  end if

  # LOAD THE VIEW FILE
  get rigLoadView("testView")
end page

Now all you have to do is to provide your view file with the pagination like [[gData["paginationLinks"]]] and the edited data retrieved from your database like [[gData["paginationData"]]].

AJAX Example

The simplest way to make the pagination work with XMLHTTP requests is to add the following two lines of code right after calling the rigCreatePaginationLinks function like:

# SEND JSON DATA TO BE PROCESSED BY AJAX PAGINATION SCRIPT TO BROWSER
rigAjaxPagination gData["paginationData"], gData["paginationLinks"]
  
# GET AJAX PAGINATION SCRIPT
put rigAjaxPaginationCode() into gData["ajaxCode"]

Notes:

• Add the AJAX pagination script like [[gData["ajaxCode"]]] to your view file preferably at the bottom just before the closing body tag.
• The AJAX pagination code includes a X-Requested-With header (the value is "XMLHttpRequest"). This allows us to check if the controller was called by the AJAX pagination script or, in case the user disabled JavaScript, by a standard HTTP request.
• The example implies that the HTML element containing the pagination data has an ID named "paginationData" and that the HTML element containing the pagination links has an ID named "pagination" like:

<div id="paginationData">[[gData["paginationData"] ]]</div>

and:

<div id="pagination">[[gData["paginationLinks"] ]]</div>

• If you like to use different IDs you need to extend your settings like:

put "myPaginationLinksID" into tConfig["linksElementID"]
put "myPaginationDataID" into tConfig["dataElementID"]

• You can easily add a Content Security Policy nonce to the AJAX script tag like:

put rigNonce() into tNonce
# GET AJAX PAGINATION SCRIPT
put rigAjaxPaginationCode(tNonce) into gData["ajaxCode"]

Note: revIgniter's AJAX pagination is not compatible with Internet Explorer 7 and below.

 ASYNergy Example

For XMLHTTP requests to add entries into the browser's session history stack, so that you can navigate back and forth through the individual pages with the corresponding buttons in the browser's toolbar, you must use ASYNergy. Please read about the ASYNergy JavaScript application in chapter ASYNergy Library.

# AGAIN WE ASSUME YOU RETRIEVE YOUR DATA FROM A SQL DATABASE
# USING ACTIVE RECORD FEATURES
command test
  # IN ADDITION TO THE Pagination LIBRARY
  # LOAD THE ASYNergy LIBRARY. IT MUST BE
  # LOADED BEFORE THE Pagination LIBRARY!
  rigLoaderLoadLibrary "ASYNergy"
	
  rigLoaderLoadLibrary "Pagination"
  # CONNECT TO DATABASE
  get rigLoadDatabase("yourDatabase")
end test

command page
  # CHECK IF THIS IS AN ASYNergy REQUEST
  put  rigGetHTTPheader("X-ASYNergy") into tAJAXrequest

  # GET PAGE NUMBER FROM THE
  # MODEL / ACTION PARAMETER
  # NOTE: THIS IS THE OFFSET FOR YOUR QUERY
  if tAJAXrequest is TRUE then
    put rigAsynParams() into tParamsA
    put tParamsA[1] into tRecordsOffset
  else
    # GET PAGE NUMBER FROM THE 3rd URI SEGMENT
    # IN CASE THE USER DISABLED JavaScript
    put rigFetchSegment(3) into tRecordsOffset
  end if

  # GET TOTAL NUMBER OF ROWS
  put rigDbCountAllResults("yourTable") into tTotalNumRecords

  # PAGINATION CONFIGURATION
  # DO THE PAGINATION HANDLER CONFIGURATION
  put "page" into tConfig["paginationHandler"]
  
  # SET LIMIT OF ROWS TO BE DISPLAYED
  # LET'S SAY YOU WANT TO SHOW 20 ITEMS PER PAGE
  put 20 into tConfig["perPage"]
  
  # SET TOTAL ROWS CONFIGURATION
  put tTotalNumRecords into tConfig["totalRows"]
  # CONFIGURATION END
  
  # INITIALIZE PAGINATION
  rigInitializePagination tConfig

  # GET PAGE NUMBER
  # NOTE: THIS IS THE OFFSET FOR YOUR QUERY
  put rigFetchSegment(3) into tPageNum
  if (tPageNum is an integer) and (tPageNum > 0) and (tPageNum < tTotalNumRecords) then
    put tPageNum into tOffset
  else
    put 0 into tOffset
  end if

  # GET DATABASE QUERY RESULT DATA 
  # YOUR DATABASE QUERY STUFF HERE . . . LIKE
  # rigDbOrderBy, rigDbWhere OR WHATEVER

  # SET THE QUERY LIMITS
  rigDbLimit tConfig["perPage"], tOffset

  # GET QUERY RESULT
  put rigDbGet("yourTable") into tQueryResult

  if tQueryResult["numrows"] > 0 then
    # DEAL WITH THE QUERY RESULT DATA HERE, BUILD A TABLE OR WHATEVER
    # . . .
    # STORE YOUR PAGINATION DATA IN gData
    put tYourData into gData["paginationData"]
  
    # GET PAGINATION HTML LINKS
    # THE PARAMETER IS OPTIONAL, BUT IT IS MANDATORY IF ASYNergy IS USED
    put rigCreatePaginationLinks(tRecordsOffset) into gData["paginationLinks"]
  end if

  # FINALLY SEND THE RESPONSE (JSON DATA) TO ASYNergy
  if tAJAXrequest is TRUE then
    put rigAsynAddResponseData(gData["paginationData"], , , "paginationData") into tResponseA
    put rigAsynAddResponseData(gData["paginationLinks"], , , "pagination") into tResponseA
    rigAsynRespond tResponseA
    # STOP THE EXECUTION OF THE HANDLER BEFORE LOADING THE VIEW FILE!
    exit to top
  end if

  # LOAD THE VIEW FILE
  get rigLoadView("testView")
end page

Notes:

• Add the ASYNergy script like [[gData["asynergyScript"] ]] to your view file preferably at the bottom just before the closing body tag.
• The example implies that the HTML element containing the pagination data has an asyn:mutable attribute whose value is "paginationData" and that the HTML element containing the pagination links has an asyn:mutable attribute whose value is "pagination" like:

<div asyn:mutable="paginationData">[[gData["paginationData"] ]]</div>

and:

<div asyn:mutable="pagination">[[gData["paginationLinks"] ]]</div>

Note: In case the user disabled JavaScript, standard HTTP requests are used.

Setting preferences in a config file

If you prefer not to set preferences using the above method, you can instead put them into a config file. Simply create a new file called pagination.lc, add an array in that file, call the rigRunInitialPaginationConfig handler at the bottom of your file with the array as parameter. Then save the file in: application/config/pagination.lc and it will be used automatically.

Example:

<?lc
if gRigA is not an array then
  put "No direct script access allowed."
  exit to top
end if

local sConfig

put "http://example.com/index.lc/test/page/" into sConfig["baseUrl"]
put 200 into sConfig["totalRows"]
put 20 into sConfig["perPage"]
put "« First" into sConfig["firstLink"]
put "Last »" into sConfig["lastLink"]
put "<div class=" & quote & "fullTag" & quote & ">" into sConfig["fullTagOpen"]
put "</div>" into sConfig["fullTagClose"]


# START PAGINATION CONFIGURATION
# THIS LINE IS MANDATORY
rigRunInitialPaginationConfig sConfig

Note: You will NOT need to use the rigInitializePagination handler if you save your preferences in a config file.

Customizing the Pagination

The following tables list all of the preferences you can pass to the initialization handler to tailor the display.

Adding Enclosing Markup

If you would like to surround the entire pagination with some markup you can do it with these two prefs:

Customizing the "First" Link

Customizing the "Last" Link

Customizing the "Next" Link

Customizing the "Previous" Link

Customizing the "Current Page" Link

Customizing the "Digit" Link

AJAX Preferences

Handler Reference

rigInitializePagination pConfig

Run initial configuration procedures. You will NOT need to use this handler if you save your preferences in a config file.

Parameters

• pConfig: is an array containing your configuration settings

rigCreatePaginationLinks(pRecordsOffset)

Generates and returns the pagination links.

• pRecordsOffset: is an integer and defines the current page. This parameter is optional, but it is mandatory if ASYNergy is used

rigAjaxPagination pPaginationData, pPaginationLinks

Build and send JSON data used by the AJAX pagination script.

Parameters

• pPaginationData: contains the current data to be displayed
• pPaginationLinks: contains the current pagination links

rigAjaxPaginationCode(pNonce)

Generates and returns the AJAX pagination JavaScript code.

Parameters

• pNonce: (optional) is a Content Security Policy nonce