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:

• baseUrl This is the full URL to the controller/handler containing your pagination. In the example above, it is pointing 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.
• 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 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:

command page
  # LET'S ASSUME YOU RETRIEVE YOUR DATA FROM A SQL DATABASE
  # USING ACTIVE RECORD FEATURES
  # SO, 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:

• 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 adds a segment named "ajaxrequest" to pagination links. This allows us with the help of the rigFetchSegment() function or the reigFetchRsegment() function respectively 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". If you like to use different IDs you need to extend your settings like:

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

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:

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.

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. The parameter is an array containing your configuration settings.

rigCreatePaginationLinks()

Generates and returns the pagination links.

rigAjaxPagination pPaginationData, pPaginationLinks

Build and send JSON data used by the AJAX pagination script. The fist parameter contains the current data to be displayed. The second parameter contains the current pagination links.

rigAjaxPaginationCode()

Generates and returns the AJAX pagination JavaScript code.