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.

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 "http://example.com/index.lc/test/page/" into tConfig["baseUrl"]
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:

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 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 BASE URL CONFIGURATION
  put "http://example.com/index.lc/test/page/" into tConfig["baseUrl"]
  
  # 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

If you like to make the pagination work with XMLHTTP requests you just need to set the AJAX flag to true before initializing the library

put TRUE into tConfig["ajax"]

and 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:

put "myPaginationLinksID" into tConfig["linksElementID"]
put "myPaginationDataID" into tConfig["dataElementID"]
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.

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. You will NOT need to use the rigInitializePagination handler if you save your preferences in a config file.

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

Customizing the Pagination

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

Preference Default Value Options Description
sConfig["baseUrl"]NoneNoneThe full URL to the controller/handler containing your pagination. See examples above.
sConfig["totalRows"]NoneNoneThe number representing 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.
sConfig["perPage"]10NoneThe number of items you intend to show per page.
sConfig["uriSegment"]3NoneThe pagination function automatically determines which segment of your URI contains the page number. If you need something different you can specify it.
sConfig["numLinks"]2NoneThe number of "digit" links you would like before and after the selected page number. For example, the number 2 will place two digits on either side, as in the example links at the very top of this page.
sConfig["pageQueryString"]FALSETRUE or FALSEBy default, the pagination library assumes you are using URI Segments, and constructs your links something like

http://example.com/index.lc/test/page/20

If you have gConfig["enableQueryStrings"] set to TRUE your links will automatically be re-written using Query Strings. This option can also be explictly set. Using tConfig["pageQueryString"] set to TRUE, the pagination link will become.

http://example.com/index.lc?c=test&m=page&perPage=20

Note that "perPage" is the default query string passed, however can be configured using put "your_string" into tConfig["queryStringSegment"]

Adding Enclosing Markup

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

Preference Default Value Options Description
sConfig["fullTagOpen"]NoneNoneThe opening tag placed on the left side of the entire result.
sConfig["fullTagClose"]NoneNoneThe closing tag placed on the right side of the entire result.

Customizing the "First" Link

Preference Default Value Options Description
sConfig["firstLink"]‹ FirstNoneThe text you would like shown in the "first" link on the left.
sConfig["firstTagOpen"]NoneNoneThe opening tag for the "first" link.
sConfig["firstTagClose"]NoneNoneThe closing tag for the "first" link.

Customizing the "Last" Link

Preference Default Value Options Description
sConfig["lastLink"]Last ›NoneThe text you would like to be shown in the "last" link on the right.
sConfig["lastTagOpen"]NoneNoneThe opening tag for the "last" link.
sConfig["lastTagClose"]NoneNoneThe closing tag for the "last" link.

Customizing the "Next" Link

Preference Default Value Options Description
sConfig["nextLink"]>NoneThe text you would like to be shown in the "next" page link.
sConfig["nextTagOpen"]NoneNoneThe opening tag for the "next" link.
sConfig["nextTagClose"]NoneNoneThe closing tag for the "next" link.

Customizing the "Previous" Link

Preference Default Value Options Description
sConfig["prevLink"]<NoneThe text you would like to be shown in the "previous" page link.
sConfig["prevTagOpen"]NoneNoneThe opening tag for the "previous" link.
sConfig["prevTagClose"]NoneNoneThe closing tag for the "previous" link.

Customizing the "Current Page" Link

Preference Default Value Options Description
sConfig["curTagOpen"]<strong>NoneThe opening tag for the "current" link.
sConfig["curTagClose"]</strong>NoneThe closing tag for the "current" link.

Customizing the "Digit" Link

Preference Default Value Options Description
sConfig["numTagOpen"]NoneNoneThe opening tag for the "digit" link.
sConfig["numTagClose"]NoneNoneThe closing tag for the "digit" link.

AJAX Preferences

Preference Default Value Options Description
sConfig["ajax"]NoneTRUE or FALSEXMLHTTP Pagination flag.
sConfig["ajaxServerTimeout"]10000NoneDelay to trigger an error while making an AJAX request (milliseconds).
sConfig["widgetName"]PaginationWidgetNoneName of Ajax pagination JavaScript object.
sConfig["linksElementID"]paginationNoneThe ID of the HTML element containing the pagination links.
sConfig["dataElementID"]paginationDataNoneThe ID of the HTML element containing the paginated data.

Handler Reference

rigInitializePagination pConfig

Run initial configuration procedures.

Parameters

rigCreatePaginationLinks()

Generates and returns the pagination links.

rigAjaxPagination pPaginationData, pPaginationLinks

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

Parameters

rigAjaxPaginationCode(pNonce)

Generates and returns the AJAX pagination JavaScript code.

Parameters