Lt. Peacock Thymeleaf Dialect

This Thymeleaf dialect provides some common utility features.

Installation

JDK 8 is required at a minimum.

This project is available as a Maven artifact. Maven users can include it with the following dependency in pom.xml:

<dependency>
	<groupId>com.lt-peacock</groupId>
	<artifactId>lp-thymeleaf-dialect</artifactId>
	<version>1.0.1</version>
</dependency>

To manually install the project to the local Maven repository, clone the project and run the following in the project root:

mvn clean install

Next, com.ltpeacock.thymeleaf_dialect.LPDialect must be added to the configured Thymeleaf TemplateEngine via TemplateEngine#addDialect. (For Spring users, SpringTemplateEngine should be configured.)

TemplateEngine templateEngine = new TemplateEngine();
templateEngine.addDialect(new LPDialect());

In Spring, it is only necessary to register an instance of LPDialect as a bean.

@Bean
public LPDialect lpDialect() {
	return new LPDialect();
}

Pagination

When displaying a large amount of data, it is often convenient to split it into pages. This dialect provides a lp:pagination tag for generating a list of page numbers to facilitate user navigation.

Syntax

<lp:pagination currentPage="7" firstPage="1" lastPage="20" basePageLink="@{/page}"/>

The element will be replaced by an unordered list (<ul>) element. Each page will be a list item (<li>) with an anchor (<a>) inside. Each anchor points to the configured base page link with slash (/) and the page number appended. There is no CSS applied by default: it is up to the user to style the classes on the generated elements. The classes used for certain generated elements can be configured by setting some attributes.

Attributes

All Thymeleaf expressions are supported as attribute values.

Attributes are specified on the lp:pagination tag with the syntax attributeName="attributeValue".

Attribute Name	Description	Default Value
currentPage	The current page number.	None; this attribute is required.
firstPage	The first page number. This page number is not necessarily displayed.	1
lastPage	The last page number. This page number is not necessarily displayed.	None; this attribute is required.
maxPages	The maximum number of pages to display in the list.	10
pageGenerator	The com.ltpeacock.thymeleaf_dialect.pagination.PageGenerator object to use for generating pages.	com.ltpeacock.thymeleaf_dialect.pagination.DefaultPageGenerator, but this can be configured when registering the LPDialect.
generatePrevLink	Whether or not to generate a link (at the start of the list of pages) pointing to the previous page. The value should be a boolean (either true or false).	true
generateNextLink	Whether or not to generate a link (at the end of the list of pages) pointing to the next page. The value should be a boolean (either true or false).	true
generateFirstLink	Whether or not to generate a link (at the start of the list of pages) pointing to the first page. The value should be a boolean (either true or false).	true
generateLastLink	Whether or not to generate a link (at the end of the list of pages) pointing to the last page. The value should be a boolean (either true or false).	true
generateDisabledLinks	Whether or not to generate disabled first, last, previous, and next links. The first and previous links would be disabled when the current page is the first page; the last and next links would be disabled when the current page is the last page. The value should be a boolean (either true or false).	false
currentClass	The CSS class to add to the list item for the current page (in addition to the page class).	"current"
pageClass	The CSS class to add to the list item elements for all pages.	"page"
pageLinkClass	The CSS class to add to the anchor in the list item for each page.	"page-link"
rootClass	The CSS class to add to the unordered list element that the lp:pagination tag is replaced with.	"pagination"
prevClass	The CSS class to add to the list item for the previous page link.	"prev-page"
nextClass	The CSS class to add to the list item for the next page link.	"next-page"
firstClass	The CSS class to add to the list item for the first page link.	"first-page"
lastClass	The CSS class to add to the list item for the last page link.	"last-page"
disabledClass	The CSS class to add to all disabled list items.	"disabled"
prevText	The content of the previous page link.	"« Prev"
nextText	The content of the next page link.	"Next »"
firstText	The content of the first page link.	"First"
lastText	The content of the last page link.	"Last"
basePageLink	The base page link for pages. The href for each page link will be the base page link appended with a slash and the page number. (If the specified value ends in a slash, it will first be removed.)	"javascript:;"

Additional Configuration

The default page generator when the pageGenerator attribute is not specified on the lp:pagination tag can be specified by calling setPageGenerator after instantiating the LPDialect.

LPDialect lpDialect = new LPDialect();
lpDialect.setPageGenerator(new MyPageGenerator());
templateEngine.addDialect(lpDialect);

Example

This example uses Bootstrap 4 to style the pagination element. For this integration, the pageClass and currentClass attributes need to be set to match the Bootstrap classes. (The default rootClass of "pagination" and pageLinkClass of "page-link" already match.)

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"
	xmlns:th="http://www.thymeleaf.org"
	xmlns:lp="http://lt-peacock.com/dialect">
<head>
<title>Pagination Example</title>
<link rel="stylesheet" 
	href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css" 
	integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm" 
	crossorigin="anonymous">
</head>
<body>
<div class="container">
	<!-- Content of current page here ... -->
	
	<!-- Pagination element -->
	<lp:pagination currentPage="7" firstPage="1" lastPage="20" maxPages="10"
		basePageLink="@{/page}" rootClass="pagination" currentClass="active"
		pageClass="page-item" generateDisabledLinks="true"/>
</div>
</body>
</html>

Result:

The generated HTML (prettified):

<ul class="pagination">
	<li class="page-item first-page"><a href="/page/1"
		class="page-link">First</a></li>
	<li class="page-item prev-page"><a href="/page/6"
		class="page-link">&laquo; Prev</a></li>
	<li class="page-item"><a href="/page/2" class="page-link">2</a></li>
	<li class="page-item"><a href="/page/3" class="page-link">3</a></li>
	<li class="page-item"><a href="/page/4" class="page-link">4</a></li>
	<li class="page-item"><a href="/page/5" class="page-link">5</a></li>
	<li class="page-item"><a href="/page/6" class="page-link">6</a></li>
	<li class="page-item active"><a href="/page/7" class="page-link">7</a></li>
	<li class="page-item"><a href="/page/8" class="page-link">8</a></li>
	<li class="page-item"><a href="/page/9" class="page-link">9</a></li>
	<li class="page-item"><a href="/page/10" class="page-link">10</a></li>
	<li class="page-item"><a href="/page/11" class="page-link">11</a></li>
	<li class="page-item next-page"><a href="/page/8"
		class="page-link">Next &raquo;</a></li>
	<li class="page-item last-page"><a href="/page/20"
		class="page-link">Last</a></li>
</ul>