5.11. Pagination

Caution

This version is already obsolete. Please check the latest guideline.

5.11.1. Overview

This chapter describes the Pagination functionality wherein the data matching the search criteria is divided into pages and displayed.

It is recommended to use pagination functionality when a large amount of data matches the search criteria.

Retrieving and displaying a large amount of data at a time on screen may lead to following problems.

• Memory exhaustion at server side

  java.lang.OutOfMemoryError occurs when multiple requests are executed simultaneously.
• Network load

  Transferring unnecessary data over the network results in increased network load and thereby may affect the response time of the entire system.
• Delay in response on screen

  Server process, network traffic process and client rendering process take time to handle a large amount of data; hence the response on screen may get delayed.

5.11.1.1. Display of list screen at the time of dividing into pages

When a page is divided using pagination, the screen looks as follows:

Sr. No.	Description
(1)	Display the link to navigate to various pages. On clicking link, send a request to display the corresponding page. JSP tag library to display this area is provided as common library.
(2)	Display the information related to pagination (total records, total pages and number of displayed pages etc.). Tag library to display this area does not exist; hence it should be implemented separately as JSP processing.

5.11.1.2. Page search

For implementing pagination, it is essential to first implement the server-side search processing to make page searching possible.

It is assumed in this guideline that the mechanism provided by Spring Data is used for page search at server side.

5.11.1.2.1. Page search functionality of Spring Data

Page search functionality provided by Spring Data is as follows:

Sr. No.	Description
1	Extract the information required for page search (location of page to be searched, number of records to be fetched and sort condition) from request parameter and pass the extracted information as objects of org.springframework.data.domain.Pageable to the argument of Controller. This functionality is provided as org.springframework.data.web.PageableHandlerMethodArgumentResolver class and is enabled by adding to <mvc:argument-resolvers> element of spring-mvc.xml . For request parameters, refer to “Note column”.
2	Save the page information (total records, data of corresponding page, location of page to be searched, number of records to be fetched and sort condition). This functionality is provided as org.springframework.data.domain.Page interface and org.springframework.data.domain.PageImpl is provided as default implementation class. As per specifications, it fetches the required data from Page object in JSP tag library to output pagination link provided by common library.
3	When Spring Data JPA is used for database access, the information of corresponding page is returned as Page object by specifying Pageable object as an argument of Repository Query method. All the processes such as executing SQL to fetch total records, adding sort condition and extracting data matching the corresponding page are carried out automatically. When MyBatis is used for database access, the process that is automatically carried out in Spring Data JPA needs to be implemented in Java (Service) and SQL mapping file.

Note

Request parameters for page search

Request parameters for page search provided by Spring Data are as follows:

Sr. No.	Parameter name	Description
	page	Request parameter to specify the location of page to be searched Specify value greater than or equal to 0. As per default setting, page location starts from 0 (zero). Hence, specify 0 (zero) to fetch the data of the first page and 1 (one) to fetch the data of the second page.
	size	Request parameter to specify the count of fetched records. Specify value greater than or equal to 1. When value specified is greater than the value in maxPageSize of PageableHandlerMethodArgumentResolver, maxPageSize value becomes size value.
	sort	Parameter to specify sort condition (multiple parameters can be specified). Specify the value in "{sort item name(,sort order)}" format. Specify either "ASC" or "DESC" as sort order. When nothing is specified, "ASC" is used. Multiple item names can be specified using "," separator. For example, when "sort=lastModifiedDate,id,DESC&sort=subId" is specified as query string, Order By clause "ORDER BY lastModifiedDate DESC, id DESC, subId ASC" is added to the query.

Warning

Operations at the time of specifying “size=0” in spring-data-commons 1.6.1.RELEASE

spring-data-commons 1.6.1.RELEASE having terasoluna-gfw-common 1.0.0.RELEASE has a bug wherein if "size=0" is specified, all the records matching the specified condition are fetched. As a result, java.lang.OutOfMemoryError may occur when a large amount of records are fetched.

This problem is handled using JIRA DATACMNS-377 of Spring Data Commons and is being resolved in spring-data-commons 1.6.3.RELEASE. Post modification, if "size<=0" is specified, the default value when size parameter is omitted will be applied.

In cases where terasoluna-gfw-common 1.0.0.RELEASE is used, the version should be upgraded to terasoluna-gfw-common 1.0.1.RELEASE or higher version.

Warning

About operations when invalid values are specified in request parameters of spring-data-commons 1.6.1.RELEASE

spring-data-commons 1.6.1.RELEASE having terasoluna-gfw-common 1.0.0.RELEASE has a bug wherein if an invalid value is specified in request parameters for page search (page, size, sort etc.), java.lang.IllegalArgumentException or java.lang.ArrayIndexOutOfBoundsException occurs and SpringMVC settings when set to default values leads to system error (HTTP status code=500).

This problem is handled using JIRA DATACMNS-379 and DATACMNS-408 and is being resolved in spring-data-commons 1.6.3.RELEASE. Post modification, if invalid values are specified, the default value when parameters are omitted will be applied.

In cases where terasoluna-gfw-common 1.0.0.RELEASE is used, the version should be upgraded to terasoluna-gfw-common 1.0.1.RELEASE or higher version.

Note

Points to be noted due to the changes in API specifications of Spring Data Commons

In case of “terasoluna-gfw-common 5.0.0.RELEASE or later version” dependent spring-data-commons (1.9.1 RELEASE or later), there is a change in API specifications of interface for page search functionality (org.springframework.data.domain.Page) and class (org.springframework.data.domain.PageImpl and org.springframework.data.domain.Sort.Order).

Specifically,

• In Page interface and PageImpl class, isFirst() and isLast() methods are added in spring-data-commons 1.8.0.RELEASE, and isFirstPage() and isLastPage() methods are deleted from spring-data-commons 1.9.0.RELEASE.
• In Sort.Order class, nullHandling property is added in spring-data-commons 1.8.0.RELEASE.

If deleted API is used, there will be a compilation error and application will have to be modified. In addition, when using Page interface (PageImpl class) as resource object of REST API, that application may also need to be modified, as JSON and XML format get changed.

5.11.1.3. Display of pagination link

This section describes the pagination link which is output using JSP tag library of common library.

Style sheet to display pagination link is not provided from common library, hence it should be created in each project.

Bootstrap v3.0.0 style sheet is applied for the screens used in the explanation below.

5.11.1.3.1. Structure of pagination link

Pagination link consists of the following elements.

Sr. No.	Description
(1)	Link to navigate to the first page.
(2)	Link to navigate to the previous page.
(3)	Link to navigate to the specified page.
(4)	Link to navigate to the next page.
(5)	Link to navigate to the last page.

Pagination link has the following status.

Sr. No.	Description
(6)	Status indicating link where operations cannot be performed on the currently displayed page. The status is specifically “Link to navigate to the first page” and “Link to navigate to the previous page” when the first page is displayed and “Link to navigate to the next page” “Link to navigate to the last page” when the last page is displayed. This status is defined as "disabled" in the JSP tag library of common library.
(7)	Status indicating currently displayed page. This status is defined as "active" in the JSP tag library of common library.

HTML to be output using common library is as follows:

The numbers in figure correspond to serial numbers of “Structure of pagination link” and “Status of pagination link” mentioned above.

• JSP

<t:pagination page="${page}" />

• HTML to be output

5.11.1.3.2. HTML of pagination link

HTML of pagination link to be output using common library is as follows:

• HTML

• Screen image

Sr. No.	Description	Default values
(1)	Elements to combine the components of pagination link. In common library, this part is called “Outer Element” which stores multiple “Inner Elements”. The elements to be used can be changed using the parameters of JSP tag library.	<ul> element
(2)	Attribute to specify style class of “Outer Element”. In common library, this part is called “Outer Element Class”. The attribute values are specified using the parameters of JSP tag library.	No specification
(3)	Elements to configure pagination link. Call this portion as “Inner Element” and maintain <a> element to send request for navigating the page in common library. The elements can be changed using parameter of JSP tag library.	<li> elements
(4)	Attribute to specify style class of “Inner Elements”. In common library, this part is called “Inner Element Class”. The attribute values are switched during JSP tag library processing according to the location of the displayed page.	Refer to “Note column”.
(5)	Element to send page navigation request. In common library, this part is called “Page Link”.	Fixed as <a>
(6)	Attribute to specify URL for page navigation. In common library, this part is called “Page Link URL”.	Refer to the following “Note column”.
(7)	Specify the text to be displayed for page navigation link In common library, this part is called “Page Link Text”.	Refer to the following ” Note column “.

Note

About number of “Inner Elements”

As per default setting, there are maximum 14 “Inner Elements”. Their division is as follows:

• Link to navigate to the first page : 1
• Link to navigate to the previous page : 1
• Link to navigate to the specified page : Maximum 10
• Link to navigate to the next page : 1
• Link to navigate to the last page : 1

The number of “Inner Elements” can be changed by specifying parameters of JSP tag library.

Note

About setting values of “Inner Element Class”

As per default setting, following are the three values depending on location of the page.

• "disabled" : Style class indicating the link which cannot be operated on the currently displayed page.
• "active" : Style class indicating the link of currently displayed page.
• No specification : Indicating the link other than those mentioned above.

"disabled" and "active" values can be changed by specifying the parameters of JSP tag library.

Note

About default values of “Page Link URL”

When link status is "disabled" and "active", the default value is "javascript:void(0)" and in other cases, the default value is "?page={page}&size={size}".

“Page Link URL” can be changed to another value by specifying parameters of JSP tag library.

From terasoluna-gfw-web 5.0.0.RELEASE, default value of link in "active"status is changed from "?page={page}&size={size}" to "javascript:void(0)". This is to match with the implementation of pagination links of major Web sites and the implementation of major CSS libraries (Bootstrap, etc.)

Note

About default values of “Page Link Text”

Sr. No.	Link name	Default values
	Link to navigate to the first page	"<<"
	Link to navigate to the previous page	"<"
	Link to navigate to the specified page	Page number of the corresponding page (cannot be changed)
	Link to navigate to the next page	">"
	Link to navigate to the last page	">>"

Links other than “Link to navigate to the specified page” can be changed as per the specification of parameters of JSP tag library.

5.11.1.3.3. Parameters of JSP tag library

Default operations can be changed by specifying values in parameters of JSP tag library.

List of parameters is shown below.

Parameters to control layout

Sr. No.	Parameter name	Description
	outerElement	Specify HTML element name to be used as “Outer Element”. Example: div
	outerElementClass	Specify class name of style sheet to be set in “Outer Element Class”. Example: pagination
	innerElement	Specify HTML element name to be used as “Inner Element”. Example: span
	disabledClass	Specify the value to be set in the class attribute of “Inner Element” with "disabled" status. Example: hiddenPageLink
	activeClass	Specify the value to be set in the class attribute of “Inner Element” with "active" status. Example: currentPageLink
	firstLinkText	Specify the value to be set in “Page Link Text” of “Link to navigate to the first page”. If "" is specified, “Link to navigate to the first page” itself is not output. Example: First
	previousLinkText	Specify the value to be set in “Page Link Text” of “Link to navigate to the previous page”. If "" is specified, “Link to navigate to the previous page” itself is not output. Example: Prev
	nextLinkText	Specify the value to be set in “Page Link Text” of “Link to navigate to the next page”. If "" is specified, “Link to navigate to the next page” itself is not output. Example: Next
	lastLinkText	Specify the value to be set in “Page Link Text” of “Link to navigate to the last page”. If "" is specified, “Link to navigate to the next page” itself is not output. Example: Last
	maxDisplayCount	Specify maximum display count for “Link to navigate to the specified page”. If 0 is specified, “Link to navigate to the specified page” itself is not output. Example: 5

When default values of all parameters to control the layout are changed, the following HTML is output. The numbers in figure correspond to serial numbers in the parameter list mentioned above.

• JSP

<t:pagination page="${page}"
    outerElement="div"
    outerElementClass="pagination"
    innerElement="span"
    disabledClass="hiddenPageLink"
    activeClass="currentPageLink"
    firstLinkText="First"
    previousLinkText="Prev"
    nextLinkText="Next"
    lastLinkText="Last"
    maxDisplayCount="5"
    />

• Output HTML

Parameters to control operations

Sr. No.	Parameter name	Description
	disabledHref	Specify the value to be set in “Page Link URL” having "disabled" state.
	pathTmpl	Specify the template of request path to be set in “Page Link URL”. When request path at the time of page display and the request path for page navigation are different, request path for page navigation needs to be specified in this parameter. In the template of request path to be specified, location of page (page) and number of records to be fetched (size) can be specified as path variables (placeholders). The specified value of URL is encoded in UTF-8.
	queryTmpl	Specify the template of query string of “Page Link URL”. Specify the template for generating pagination related query string (page, size, sort parameters) required at the time of page navigation. When setting request parameter name for location of page or the number of records to be fetched to values other than default values, the query string needs to be specified in this parameter. In the template of query string to be specified, location of page (page) and number of records to be fetched (size) can be specified as path variables (placeholders). The specified value of URL is encoded in UTF-8. This attribute is used to generate pagination related query string (page, size, sort parameters); hence query string for adding search conditions should be specified in criteriaQuery attribute.
	criteriaQuery	Specify the query string for search conditions to be added to “Page Link URL”. Specify the query string for search conditions in this parameter when adding search conditions to “Page Link URL”. The specified value of URL is not encoded; hence encoded URL query string needs to be specified. If EL function (f:query(Object)) of common library is used when converting the search conditions stored in form object into encoded URL query string, the search conditions can be added easily. This parameter can be used in terasoluna-gfw-web 1.0.1.RELEASE or higher version.
	disableHtmlEscapeOfCriteriaQuery	Flag to disable HTML escaping for the values specified in criteriaQuery parameter. When the flag is set to true, HTML escaping is no longer possible for the values specified in criteriaQuery parameter. (Default value is false). When specifying true, it should be ensured that the characters vulnerable to XSS are not included in the query string. This parameter can be used in terasoluna-gfw-web 1.0.1.RELEASE or higher version.
	enableLinkOfCurrentPage	Flag to send request for redisplaying the corresponding page on clicking page link in "active" status. When it is set to true, URL (default value is "?page={page}&size={size}") to redisplay the corresponding page is set to “Page Link URL”. (If default value is false, the value of disabledHref attribute is set to “Page Link URL”) This parameter can be used in terasoluna-gfw-web 5.0.0.RELEASE or higher version.

Note

About setting values of disabledHref

"javascript:void(0)"is set in disabledHref attribute by default. It may remain as default in order to disable only the operation of page link click.

However, if the focus is moved or on mouseover to page link in default state, "javascript:void(0)" may be displayed on browser status bar. To change this behavior, it is necessary to disable the operation of page link click by using JavaScript. Refer to “To disable page link using JavaScript” for implementation example.

From terasoluna-gfw-web 5.0.0.RELEASE, default value of disabledHref attribute is changed from "#" to "javascript:void(0)". By doing so, the focus does not move to top of the page on clicking page link in "disabled" state.

Note

Path variables (placeholders)

Path variables that can be specified in pathTmpl and queryTmpl are as follows:

Sr. No.	Path variable name	Description
	page	Path variable for inserting page location.
	size	Path variable for inserting number of records to be fetched.
	sortOrderProperty	Path variable for inserting sort field of sort condition.
	sortOrderDirection	Path variable for inserting sort order of sort condition.

Specify path variables in "{Path variable name}" format.

Warning

Constraints related to sort condition

Only one sort condition can be set as a sort condition path variable. Therefore, when the search result obtained by specifying multiple sort condition needs to be displayed using pagination, it is necessary to extend the JSP tag library of common library.

When parameters to control the operations are changed, the following HTML is output. The numbers in figure correspond to serial numbers of parameter list mentioned above.

• JSP

<t:pagination page="${page}"
    disabledHref="#"
    pathTmpl="${pageContext.request.contextPath}/article/list/{page}/{size}"
    queryTmpl="sort={sortOrderProperty},{sortOrderDirection}"
    criteriaQuery="${f:query(articleSearchCriteriaForm)}"
    enableLinkOfCurrentPage="true" />

• HTML to be output

5.11.1.4. Process flow when pagination is used

Process flow when using pagination functionality of Spring Data and JSP tag library of common library is as follows:

Sr. No.	Description
(1)	Apart from search conditions, specify the location of page to be searched (page) and number of records to be fetched (size) as request parameters and send the request.
(2)	PageableHandlerMethodArgumentResolver fetches location of page to be searched (page) and number of records to be fetched (size) specified in request parameter and creates Pageable object. The created Pageable object is set as an argument of Controller processing method.
(3)	Controller passes the Pageable object received as an argument to Service method.
(4)	Service passes the Pageable object received as an argument to Query method of Repository.
(5)	Repository fetches total records (totalElements) of data matching the search conditions. It also fetches the data falling in the range of page location (page) and number of records to be fetched (size) specified in Pageable object received as an argument, from the database.
(6)	Repository creates Page object based on total records fetched (totalElements), fetched data (content) and Pageable object received as an argument, and returns it to Service and Controller.
(7)	Controller stores the returned Page object in Model object and displays JSP.
(8)	JSP fetches the Page object stored in Model object and calls JSP tag library (<t:pagination>) for pagination provided by common library. JSP tag library for pagination refers to Page object and creates pagination link.
(9)	The HTML created in JSP is returned to client (browser).
(10)	On clicking pagination link, the request to display the corresponding page is sent.

Note

Implementation of Repository

The implementation method of (5) & (6) are different depending on the O/R Mapper to be used.

• When using MyBatis3, implementation of Java (Service) and SQL mapping file is necessary.
• When using Spring Data JPA, implementation is not necessary because it is carried out automatically through the use of Spring Data JPA functionality.

For implementation example refer to:

• Database Access (MyBatis3)
• Database Access (JPA)

5.11.2. How to use

The method of using pagination functionality is as follows:

5.11.2.1. Application settings

5.11.2.1.1. Settings for enabling pagination functionality of Spring Data

Location of page to be searched (page), number of records to be fetched (size) and sort condition (sort) are specified in the request parameter. The functionality to set these properties in the argument of Controller as Pageable object should be enabled.

The settings mentioned below are preset in a blank project.

spring-mvc.xml

<mvc:annotation-driven>
    <mvc:argument-resolvers>
        <!-- (1) -->
        <bean
            class="org.springframework.data.web.PageableHandlerMethodArgumentResolver" />
    </mvc:argument-resolvers>
</mvc:annotation-driven>

Sr. No.	Description
(1)	Specify org.springframework.data.web.PageableHandlerMethodArgumentResolver in <mvc:argument-resolvers>. For the properties that can be specified in PageableHandlerMethodArgumentResolver, refer to “About property values of PageableHandlerMethodArgumentResolver”.

5.11.2.2. Page search

The method of implementing page search is as follows:

5.11.2.2.1. Implementation of application layer

The information required for page search (such as location of page to be searched, number of records to be fetched and sort condition) is received as an argument and passed to Service method.

• Controller

@RequestMapping("list")
public String list(@Validated ArticleSearchCriteriaForm form,
        BindingResult result,
        Pageable pageable, // (1)
        Model model) {

    ArticleSearchCriteria criteria = beanMapper.map(form,
            ArticleSearchCriteria.class);

    Page<Article> page = articleService.searchArticle(criteria, pageable); // (2)

    model.addAttribute("page", page); // (3)

    return "article/list";
}

Sr. No.	Description
(1)	Specify Pageable as an argument of processing method. Pageable object stores the information required for page search (such as location of page to be searched, number of records to be fetched and sort condition).
(2)	Specify the Pageable object as an argument of Service method and then call the same.
(3)	Add the search result (Page object) returned by Service to Model. It can be referred from View (JSP) after it is added to Model.

Note

Operations when the information required for page search is not specified in request parameter

Default values are applied when the information required for page search (such as location of page to be searched, number of records to be fetched and sort condition) is not specified in request parameter. Default values are as follows:

• Location of page to be searched: 0 (first page)
• number of records to be fetched: 20
• Sort condition: null (no sort condition)

Default values can be changed using the following two methods.

• Define the default values by specifying @org.springframework.data.web.PageableDefault annotation as an argument of Pageable of processing method.
• Specify Pageable object wherein default values are defined in fallbackPageable property of PageableHandlerMethodArgumentResolver.

See the method below for specifying default values using @PageableDefault annotation.

Use @PageableDefault annotation to change the default values for each page search.

@RequestMapping("list")
public String list(@Validated ArticleSearchCriteriaForm form,
        BindingResult result,
        @PageableDefault( // (1)
                page = 0,    // (2)
                size = 50,   // (3)
                direction = Direction.DESC,  // (4)
                sort = {     // (5)
                    "publishedDate",
                    "articleId"
                    }
                ) Pageable pageable,
        Model model) {
    // ...
    return "article/list";
}

Sr. No.	Description	Default values
(1)	Specify @PageableDefault annotation as an argument of Pageable.	-
(2)	To change the default value of location of page, specify the value in page attribute of @PageableDefault annotation. Normally it need not be changed.	0 (first page)
(3)	To change the default value of number of records to be fetched, specify the value in size or value attribute of @PageableDefault annotation.	10
(4)	To change the default value of sort condition, specify the value in direction attribute of @PageableDefault annotation.	Direction.ASC (Ascending order)
(5)	Specify the sort fields of sort condition in sort attribute of @PageableDefault annotation. When sorting the records using multiple sort fields, specify the property name to be sorted in array. In the above example, sort condition "ORDER BY publishedDate DESC, articleId DESC" is added to Query.	Empty array (No sort field)

Note

About sort order that can be specified using @PageableDefault annotation

Sort order that can be specified using @PageableDefault annotation is either ascending or descending; hence when you want to specify different sort order for each field, it is necessary to use @org.springframework.data.web.SortDefaults annotation. For example, when sorting the fields using "ORDER BY publishedDate DESC, articleId ASC" sort order.

Tip

Specifying annotation when only the default value of number of records to be fetched is to be changed

In order to change only the default value of number of records to be fetched, the annotation can also be specified as @PageableDefault(50). This operation is same as @PageableDefault(size = 50).

See the method below to specify default values using @SortDefaults annotation.

@SortDefaults annotation is used when sorting needs to be done on multiple fields and in order to have different sort order for each field.

@RequestMapping("list")
public String list(
        @Validated ArticleSearchCriteriaForm form,
        BindingResult result,
        @PageableDefault(size = 50)
        @SortDefaults(  // (1)
                {
                    @SortDefault(  // (2)
                                 sort = "publishedDate",    // (3)
                                 direction = Direction.DESC // (4)
                                ),
                    @SortDefault(
                                 sort = "articleId"
                                )
                }) Pageable pageable,
        Model model) {
    // ...
    return "article/list";
}

Sr. No.	Description	Default values
(1)	Specify @SortDefaults annotation as an argument of Pageable. Multiple @org.springframework.data.web.SortDefault annotations can be specified as arrays in @SortDefaults annotation.	-
(2)	Specify @SortDefault annotation as value attribute of @SortDefaults annotation. Specify as array when specifying multiple annotations.	-
(3)	Specify sort fields in sort or value attribute of @PageableDefault. Specify as array when specifying multiple fields.	Empty array (No sort field)
(4)	Specify value in direction attribute of @PageableDefault to change default sort condition.	Direction.ASC (Ascending)

In the above example, sort condition called "ORDER BY publishedDate DESC, articleId ASC" is added to query.

Tip

Specifying annotation when only the default value of sort fields is to be specified

In order to specify only the records to be fetched, the annotation can also be specified as @PageableDefault("articleId"). This operation is same as @PageableDefault(sort = "articleId") and @PageableDefault(sort = "articleId", direction = Direction.ASC).

When it is necessary to change the default values of entire application, specify Pageable object wherein default values are defined in fallbackPageable property of PageableHandlerMethodArgumentResolver that is defined in spring-mvc.xml.

For description of fallbackPageable and example of settings, refer to “About property values of PageableHandlerMethodArgumentResolver”.

5.11.2.2.2. Implementation of domain layer (MyBatis3)

When accessing the database using MyBatis3, extract the necessary information from Pageable object received from Controller and pass it to the Repository.

Sort conditions and SQL for extracting the corresponding data need to be implemented in SQL mapping.

For details on page search process to be implemented at domain layer, refer to:

• Pagination search of Entity (MyBatis3 standard method)
• Pagination search for Entity (SQL refinement method)

5.11.2.2.3. Implementation of domain layer (JPA)

When accessing the database using JPA (Spring Data JPA), pass the Pageable object received from Controller to Repository.

For details on page search process to be implemented at domain layer, refer to:

• Searching page of entities matching the conditions

5.11.2.3. Implementation of JSP (Base version)

The method to display pagination link and pagination information (total records, total pages, number of displayed pages etc.) by displaying the Page object fetched during page search on list screen, is described below.

5.11.2.3.1. Display of fetched data

An example to display the data fetched during page search is shown below.

• Controller

@RequestMapping("list")
public String list(@Validated ArticleSearchCriteriaForm form, BindingResult result,
        Pageable pageable, Model model) {

    if (!StringUtils.hasLength(form.getWord())) {
        return "article/list";
    }

    ArticleSearchCriteria criteria = beanMapper.map(form,
            ArticleSearchCriteria.class);

    Page<Article> page = articleService.searchArticle(criteria, pageable);

    model.addAttribute("page", page); // (1)

    return "article/list";
}

Sr. No.	Description
(1)	Store Page object with the attribute name "page" in Model. In JSP, Page object can be accessed by specifying attribute name "page".

• JSP

<%-- ... --%>

<%-- (2) --%>
<c:when test="${page != null && page.totalPages != 0}">

  <table class="maintable">
    <thead>
      <tr>
        <th class="no">No</th>
        <th class="articleClass">Class</th>
        <th class="title">Title</th>
        <th class="overview">Overview</th>
        <th class="date">Published Date</th>
      </tr>
    </thead>

    <%-- (3) --%>
    <c:forEach var="article" items="${page.content}" varStatus="rowStatus">
      <tr>
        <td class="no">
          ${(page.number * page.size) + rowStatus.count}
        </td>
        <td class="articleClass">
          ${f:h(article.articleClass.name)}
        </td>
        <td class="title">
          ${f:h(article.title)}
        </td>
        <td class="overview">
          ${f:h(article.overview)}
        </td>
        <td class="date">
          ${f:h(article.publishedDate)}
        </td>
      </tr>
    </c:forEach>

  </table>

  <div class="paginationPart">

    <%-- ... --%>

  </div>
</c:when>

<%-- ... --%>

Sr. No.	Description
(2)	In the above example, it is checked whether data matching the specified conditions exists. If there is no such data, the header row is also not displayed. When it is necessary to display the header row even if there is no matching data, this branching is no longer required.
(3)	Display the list of data fetched using <c:forEach> tag of JSTL. The fetched data is stored in a list in content property of Page object.

• Example of screen output in JSP

5.11.2.3.2. Display of Pagination link

See the example below to display the link for page navigation (pagination link).

Pagination link is output using JSP tag library of common library.

• include.jsp

Declare the JSP tag library of common library. The settings below are carried out in a blank project.

<%@ taglib uri="http://terasoluna.org/tags" prefix="t"%>       <%-- (1) --%>
<%@ taglib uri="http://terasoluna.org/functions" prefix="f"%>  <%-- (2) --%>

Sr. No.	Description
(1)	JSP tag to display pagination link is stored.
(2)	EL function of JSP used at the time of using pagination link, is stored.

• JSP

<t:pagination page="${page}" /> <%-- (3) --%>

Sr. No.	Description
(3)	Use <t:pagination> tag. In page attribute, specify Page object stored in Model of Controller.

• Output HTML

The example below shows the search results obtained upon specifying "?page=0&size=6".

 <ul>
    <li class="disabled"><a href="javascript:void(0)">&lt;&lt;</a></li>
    <li class="disabled"><a href="javascript:void(0)">&lt;</a></li>
    <li class="active"><a href="javascript:void(0)">1</a></li>
    <li><a href="?page=1&size=6">2</a></li>
    <li><a href="?page=2&size=6">3</a></li>
    <li><a href="?page=3&size=6">4</a></li>
    <li><a href="?page=4&size=6">5</a></li>
    <li><a href="?page=5&size=6">6</a></li>
    <li><a href="?page=6&size=6">7</a></li>
    <li><a href="?page=7&size=6">8</a></li>
    <li><a href="?page=8&size=6">9</a></li>
    <li><a href="?page=9&size=6">10</a></li>
    <li><a href="?page=1&size=6">&gt;</a></li>
    <li><a href="?page=9&size=6">&gt;&gt;</a></li>
</ul>

If style sheet for pagination link is not created, the display will be as follows:

As it is visible below, the pagination link is not established.

The display will be as follows if minimal changes are carried out like adding a definition of style sheet for pagination link and changing the JSP.

• Screen image

• JSP

<%-- ... --%>

<t:pagination page="${page}"
    outerElementClass="pagination" /> <%-- (4) --%>

<%-- ... --%>

Sr. No.	Description
(4)	Specify the class name indicating that it is a pagination link. By specifying the class name, the applicable range of styles to be specified in style sheet can be restricted to pagination link.

• Style sheet

.pagination li {
    display: inline;
}

.pagination li>a {
    margin-left: 10px;
}

Even after the pagination link is established, the following two problems still persist.

• clickable and non-clickable links cannot be distinguished.
• The location of currently displayed page cannot be identified.

When Bootstrap v3.0.0 style sheet is applied to resolve the above problems, the display is as follows:

• Screen image

• Style sheet

Place the css file of bootstrap v3.0.0 under $WEB_APP_ROOT/resources/vendor/bootstrap-3.0.0/css/bootstrap.css.

Abstract of pagination related style definition.

.pagination {
  display: inline-block;
  padding-left: 0;
  margin: 20px 0;
  border-radius: 4px;
}

.pagination > li {
  display: inline;
}

.pagination > li > a,
.pagination > li > span {
  position: relative;
  float: left;
  padding: 6px 12px;
  margin-left: -1px;
  line-height: 1.428571429;
  text-decoration: none;
  background-color: #ffffff;
  border: 1px solid #dddddd;
}

.pagination > li:first-child > a,
.pagination > li:first-child > span {
  margin-left: 0;
  border-bottom-left-radius: 4px;
  border-top-left-radius: 4px;
}

.pagination > li:last-child > a,
.pagination > li:last-child > span {
  border-top-right-radius: 4px;
  border-bottom-right-radius: 4px;
}

.pagination > li > a:hover,
.pagination > li > span:hover,
.pagination > li > a:focus,
.pagination > li > span:focus {
  background-color: #eeeeee;
}

.pagination > .active > a,
.pagination > .active > span,
.pagination > .active > a:hover,
.pagination > .active > span:hover,
.pagination > .active > a:focus,
.pagination > .active > span:focus {
  z-index: 2;
  color: #ffffff;
  cursor: default;
  background-color: #428bca;
  border-color: #428bca;
}

.pagination > .disabled > span,
.pagination > .disabled > a,
.pagination > .disabled > a:hover,
.pagination > .disabled > a:focus {
  color: #999999;
  cursor: not-allowed;
  background-color: #ffffff;
  border-color: #dddddd;
}

• JSP

Add a definition to read the css file placed under JSP.

<link rel="stylesheet"
    href="${pageContext.request.contextPath}/resources/vendor/bootstrap-3.0.0/css/bootstrap.css"
    type="text/css" media="screen, projection">

5.11.2.3.3. Display of pagination information

An example to display the information related to pagination (such as total records, total pages and total displayed pages) is as follows:

• Screen example

• JSP

<div>
    <fmt:formatNumber value="${page.totalElements}" /> results <%-- (1) --%>
</div>
<div>
    ${f:h(page.number + 1) } /       <%-- (2) --%>
    ${f:h(page.totalPages)} Pages    <%-- (3) --%>
</div>

Sr. No.	Description
(1)	To display total number of data records matching the search conditions, fetch value from totalElements property of Page object.
(2)	To display number of displayed pages, fetch value from number property of Page object and increment the value by 1. number property of Page object starts with 0; hence value should be incremented by 1 at the time of displaying the page number.
(3)	To display total pages of data matching the search conditions, fetch the value from totalPages property of Page object.

Example to display the display data range of the corresponding page is shown below.

• Example of screen

• JSP

<div>
    <%-- (4) --%>
    <fmt:formatNumber value="${(page.number * page.size) + 1}" /> -
    <%-- (5) --%>
    <fmt:formatNumber value="${(page.number * page.size) + page.numberOfElements}" />
</div>

Sr. No.	Description
(4)	To display start location, calculate the value using number property and size property of Page object. number property of Page object starts with 0; hence the value needs to be incremented by 1 at the time of displaying data start location.
(5)	To display end location, calculate the value using number property, size property and numberOfElements property of Page object. numberOfElements needs to be calculated since the last page is likely to be a fraction.

Tip

About format of numeric value

When the numeric value to be displayed needs to be formatted, use tag library ( <fmt:formatNumber> ) provided by JSTL.

5.11.2.3.4. Carrying forward search conditions using page link

The method of carrying forward the search conditions to the page navigation request is shown below.

• JSP

<%-- (1) --%>
<div id="criteriaPart">
  <form:form action="${pageContext.request.contextPath}/article/list" method="get"
             modelAttribute="articleSearchCriteriaForm">
    <form:input path="word" />
    <form:button>Search</form:button>
    <br>
  </form:form>
</div>

<%-- ... --%>

<t:pagination page="${page}"
    outerElementClass="pagination"
    criteriaQuery="${f:query(articleSearchCriteriaForm)}" /> <%-- (2) --%>

Sr. No.	Description
(1)	Form to specify search conditions. word is specified as a search condition.
(2)	When carrying forward the search conditions to page navigation request, specify the encoded URL query string in criteriaQuery attribute. When storing the search conditions in form object, conditions can be carried forward easily if EL function ( f:query(Object) ) provided by common library is used. In the above example, query string of "?page=page location&size=number of records to be fetched&word=input value" format is generated. criteriaQueryattribute can be used in terasoluna-gfw-web 1.0.1.RELEASE or higher version.

Note

Specifications of f:query(Object)

JavaBean of form object and Map object can be specified as an argument of f:query. In case of JavaBean, property name is treated as request parameter name and in case of Map object, map key name is treated as request parameter. URL of the generated query string is encoded in UTF-8.

Refer to f:query() for detail specification of the f:query (URL encoding specification etc).

Warning

Operations when Query string created using f:query is specified in queryTmpl attribute

It has been found that specifying the query string generated using f:query, in queryTmpl attribute leads to duplication of URL encoding. Thus, special characters are not carried forward correctly.

This URL encoding duplication can be avoided by using criteriaQuery attribute which can be used in terasoluna-gfw-web 1.0.1.RELEASE or higher version.

5.11.2.3.5. Carrying forward the sort condition using page link

The method to carry forward the sort condition to page navigation request is as follows:

• JSP

<t:pagination page="${page}"
    outerElementClass="pagination"
    queryTmpl="page={page}&size={size}&sort={sortOrderProperty},{sortOrderDirection}" />  <%-- (1) --%>

Sr. No.	Description
(1)	To carry forward the sort condition to page navigation request, specify queryTmpl and add sort condition to query string. For parameter specifications to specify sort condition, refer to “Request parameters for page search “ In the above example, "?page=0&size=20&sort=sort item, sort order(ASC or DESC)" is a query string.

5.11.2.4. Implementation of JSP (layout change)

5.11.2.4.1. Removal of link to navigate to the first page and the last page

Example to remove “Link to navigate to the first page” and “Link to navigate to the last page” is shown below.

• Screen example

• JSP

<t:pagination page="${page}"
    outerElementClass="pagination"
    firstLinkText=""
    lastLinkText="" /> <%-- (1) (2) --%>

Sr. No.	Description
(1)	Specify "" as firstLinkText attribute of <t:pagination> tag to hide “Link to navigate to the first page”.
(2)	Specify "" as lastLinkText attribute of <t:pagination> tag to hide “Link to navigate to the last page”.

5.11.2.4.2. Removal of link to navigate to previous page and next page

Example to remove “Link to navigate to the first page” and “Link to navigate to the last page” is shown below.

• Screen example

• JSP

<t:pagination page="${page}"
    outerElementClass="pagination"
    previousLinkText=""
    nextLinkText="" /> <%-- (1) (2) --%>

Sr. No.	Description
(1)	Specify "" as previousLinkText attribute of <t:pagination> tag to hide “Link to navigate to the previous page”.
(2)	Specify "" as nextLinkText attribute of <t:pagination> tag to hide “Link to navigate to the next page”.

5.11.2.4.3. Removal of disabled link

Example to remove the link in "disabled" state is shown below.

Add the following definition to style sheet when the status is "disabled".

• Screen example

• Style sheet

.pagination .disabled {
    display: none;  /* (1) */
}

Sr. No.	Description
(1)	Specify "display: none;" as an attribute value of "disabled" class.

5.11.2.4.4. Change in maximum number of display links to navigate to the specified page

Example to change maximum number of display links to navigate to the specified page is shown below.

• Screen example

• JSP

<t:pagination page="${page}"
    outerElementClass="pagination"
    maxDisplayCount="5" /> <%-- (1) --%>

Sr. No.	Description
(1)	In order to change maximum number of display links to navigate to the specified page, specify value in maxDisplayCount attribute of <t:pagination> tag.

5.11.2.4.5. Removal of link to navigate to the specified page

Example to remove link to navigate to the specified page is shown below.

• Screen example

• JSP

<t:pagination page="${page}"
    outerElementClass="pagination"
    maxDisplayCount="0" /> <%-- (1) --%>

Sr. No.	Description
(1)	In order to hide the link to navigate to the specified page, specify "0" as maxDisplayCount attribute of <t:pagination> tag.

5.11.2.5. Implementation of JSP (Operation)

5.11.2.5.1. Specifying sort condition

Example to specify sort condition from client is shown below.

• Screen example

• JSP

<div id="criteriaPart">
  <form:form
    action="${pageContext.request.contextPath}/article/search"
    method="get" modelAttribute="articleSearchCriteriaForm">
    <form:input path="word" />
    <%-- (1) --%>
    <form:select path="sort">
        <form:option value="publishedDate,DESC">Newest</form:option>
        <form:option value="publishedDate,ASC">Oldest</form:option>
    </form:select>
    <form:button>Search</form:button>
    <br>
  </form:form>
</div>

Sr. No.	Description
(1)	For specifying the sort condition from client, add the corresponding parameters for specifying the sort condition. For parameter specifications to specify sort condition, refer to “Request parameters for page search ” . In the above example, publishedDate can be selected in ascending order or descending order from pull-down.

5.11.2.5.2. To disable page link using JavaScript

By default "javascript:void(0)" is set in disabledHref attribute of <t:pagination> tag to disable the operation on clicking page link in "disabled" state and "active" state. In such a state, if focus is moved or on mouseover to page link, "javascript:void(0)" is displayed on browser status bar. To change this behavior, it is necessary to disable the operation of page link click by using JavaScript.

Implementation example is shown below.

JSP

<%-- (1) --%>
<script type="text/javascript"
        src="${pageContext.request.contextPath}/resources/vendor/js/jquery.js"></script>

<%-- (2) --%>
<script type="text/javascript">
    $(function(){
        $(document).on("click", ".disabled a, .active a", function(){
            return false;
        });
    });
</script>

<%-- ... --%>

<%-- (3) --%>
<t:pagination page="${page}" disabledHref="#" />

Sr. No.	Description
(1)	Read js file of jQuery. In the above example, jQuery API is used to disable the operation of page link click using JavaScript.
(2)	Disable click event of page link of "disabled" and "active" states by using API of jQuery. However, when enableLinkOfCurrentPage attribute of <t:pagination> tag is set to "true", the click event of page link in "active" state should not be disabled.
(3)	Set "#" in disabledHref attribute.

5.11.3. Appendix

5.11.3.1. About property values of PageableHandlerMethodArgumentResolver

Properties that can be specified in PageableHandlerMethodArgumentResolver are as follows:

Values should be changed as required in the application.

Sr. No.	Property name	Description	Default value
	maxPageSize	Specify maximum permissible value for the number of records to be fetched. When the specified number of records to be fetched exceeds maxPageSize, only the number of records specified as maxPageSize will be fetched.	2000
	fallbackPageable	Specify default values for page location, number of records to be fetched and sort condition of the entire application. When page location, number of records to be fetched and sort condition are not specified, the values set in fallbackPageable are used.	Page location : 0 Number of records to be fetched : 20 Sort condition : null
	oneIndexedParameters	Specify start value of page location. When false is specified, start value of page location becomes 0 and when true is specified, it becomes 1.	false
	pageParameterName	Specify request parameter name to specify page location.	"page"
	sizeParameterName	Specify request parameter name to specify number of records to be fetched.	"size"
	prefix	Specify prefix (namespace) of request parameter to specify page location and number of records to be fetched. When there is a conflict between default parameter name and the parameter to be used in the application, it is recommended to specify namespace to avoid this issue. If prefix is specified, request parameter name to specify page location will be prefix + pageParameterName and request parameter name to specify number of records to be fetched will be prefix + sizeParameterName.	"" (No namespace)
	qualifierDelimiter	To search multiple pages in the same request, specify request parameter name in qualifier + delimiter + standard parameter name format to distinguish the information required for page search (such as location of page to be searched, number of records to be fetched). For this property, set delimiter value of the above format. To change this setting, it is necessary to change the setting of qualifierDelimiter of SortHandlerMethodArgumentResolver.	"_"

Note

Setting value of maxPageSize

Default value is 2000; however it is recommended to change the setting to maximum permissible value for the application. If maximum permissible value for the application is 100, maxPageSize should also be set to 100.

Note

Setting fallbackPageable

To change default values used in the entire application, set Pageable ( org.springframework.data.domain.PageRequest ) object wherein default value is defined in fallbackPageable property . To change the default sort condition, org.springframework.data.domain.Sort object where default value is defined in fallbackSort property of SortHandlerMethodArgumentResolver.

It is assumed that the fields given below will normally be changed in each application to be developed. The example to change the default values of such fields is given below.

• Maximum permissible value for number of records to be fetched ( maxPageSize )
• Default values ( fallbackPageable ) of page location and number of records to be fetched in the entire application
• Default sort condition ( fallbackSort )

<mvc:annotation-driven>
    <mvc:argument-resolvers>
        <bean
            class="org.springframework.data.web.PageableHandlerMethodArgumentResolver">
            <!-- (1) -->
            <property name="maxPageSize" value="100" />
            <!-- (2) -->
            <property name="fallbackPageable">
                <bean class="org.springframework.data.domain.PageRequest">
                    <!-- (3) -->
                    <constructor-arg index="0" value="0" />
                    <!-- (4) -->
                    <constructor-arg index="1" value="50" />
                </bean>
            </property>
            <!-- (5) -->
            <constructor-arg index="0">
                <bean class="org.springframework.data.web.SortHandlerMethodArgumentResolver">
                    <!-- (6) -->
                    <property name="fallbackSort">
                        <bean class="org.springframework.data.domain.Sort">
                            <!-- (7) -->
                            <constructor-arg index="0">
                                <list>
                                    <!-- (8) -->
                                    <bean class="org.springframework.data.domain.Sort.Order">
                                        <!-- (9) -->
                                        <constructor-arg index="0" value="DESC" />
                                        <!-- (10) -->
                                        <constructor-arg index="1" value="lastModifiedDate" />
                                    </bean>
                                    <!-- (8) -->
                                    <bean class="org.springframework.data.domain.Sort.Order">
                                        <constructor-arg index="0" value="ASC" />
                                        <constructor-arg index="1" value="id" />
                                    </bean>
                                </list>
                            </constructor-arg>
                        </bean>
                    </property>
                </bean>
            </constructor-arg>
        </bean>
    </mvc:argument-resolvers>
</mvc:annotation-driven>

Sr. No.	Description
(1)	In the above example, maximum value of number of records to be fetched is set to 100. When value specified in number of records to be fetched (size) is 101 or more, search is performed for 100 records only.
(2)	Create an instance of org.springframework.data.domain.PageRequest and set to fallbackPageable.
(3)	Specify default value of page location as the first argument of constructor of PageRequest. In the above example, 0 is specified, hence the default value is not changed.
(4)	Specify default value of number of records to be fetched as the second argument of constructor of PageRequest. In the above example, the value will be considered 50 when number of records to be fetched is not specified in request parameter.
(5)	Set an instance of SortHandlerMethodArgumentResolver as constructor of PageableHandlerMethodArgumentResolver .
(6)	Create an instance of Sort and set to fallbackSort.
(7)	Set the list of Order objects to be used as default value as the first argument of Sort constructor.
(8)	Create an instance of Order and add to the list of Order objects to be used as default value. In the above example, sort condition of "ORDER BY x.lastModifiedDate DESC, x.id ASC" is added to query when sort condition is not specified in request parameter.
(9)	Specify sort order (ASC/DESC) as the first argument of Order constructor.
(10)	Specify sort item as the second argument of Order constructor.

5.11.3.2. Property value of SortHandlerMethodArgumentResolver

Properties that can be specified in SortHandlerMethodArgumentResolver are as follows:

Values should be changed as required in the application.

Sr. No.	Property name	Description	Default value
	fallbackSort	Specify default sort condition for the entire application. When sort condition is not specified, the value set in fallbackSort is used.	null (No sort condition)
	sortParameter	Specify request parameter name to specify the sort condition. When there is a conflict between default parameter name and the parameter to be used in the application, it is recommended to change the request parameter name to avoid this issue.	"sort"
	propertyDelimiter	Specify delimiter of sort items and sort order (ASC,DESC).	","
	qualifierDelimiter	To search multiple pages in the same request, specify request parameter name in `` qualifier + delimiter + sortParameter `` format to distinguish the information required for page search (such as sort condition). For this property, set delimiter value of the above format.	"_"