HTMX for Java with Spring Boot and Thymeleaf

Not way back, we checked out the best way to construct an HTMX software with JavaScript. HTMX additionally works with Java, so now we’ll attempt that out utilizing Spring Boot and Thymeleaf. This superior stack offers you all the facility and flexibility of Java with Spring, mixed with the ingenious simplicity of HTMX.

HTMX: A rising star

HTMX is a more moderen expertise that takes plain previous HTML and provides it additional powers like Ajax and DOM swaps. It’s included in my private checklist of good concepts as a result of it eliminates a complete realm of complexity from the everyday net app. HTMX works by changing forwards and backwards between JSON and HTML. Consider it as a sort of declarative Ajax.

Learn an interview with HTMX creator Carson Gross.

Java, Spring, and Thymeleaf

On the opposite facet of this equation is Java: one of the mature and but progressive server-side platforms bar none. Spring is a simple selection for including a spread of Java-based capabilities, together with the well-designed Spring Boot Net venture for dealing with endpoints and routing. 

Thymeleaf is a whole server-side templating engine and the default for Spring Boot Net. When mixed with HTMX, you will have every part you want to construct a full-stack net app with out moving into quite a lot of JavaScript. 

HTMX and Java instance app

We’re going to construct the canonical Todo app. It is going to appear to be this:

Matthew Tyson

We checklist the present to-do’s, and permit for creating new ones, deleting them, and altering their completion standing.

Overview

That is what the completed Todo app appears to be like like on disk:

$ tree
.
├── construct.gradle
├── gradlew
├── gradlew.bat
├── settings.gradle
└── src
    └── essential
        ├── java
        │   └── com
        │       └── instance
        │           └── iwjavaspringhtmx
        │               ├── DemoApplication.java
        │               ├── controller
        │               │   └── MyController.java
        │               └── mannequin
        │                   └── TodoItem.java
        └── sources
            ├── software.properties
            ├── static
            │   └── model.css
            └── templates
                ├── index.html
                ├── model.css
                └── todo.html

So, moreover the everyday Gradle stuff, the app has two essential elements contained within the /src listing: The /essential listing holds the Java code and /sources holds the properties file and two subdirectories with the CSS and Thymeleaf templates.

You’ll find the supply for this venture on its GitHub repo. To run it, go to the basis and sort $ gradle bootRun. You may then use the app at localhost:8080.

If you wish to begin the app from the bottom up, you’ll be able to start with: $ spring init --dependencies=net,thymeleaf spring-htmx. That may set up Thymeleaf and Spring Boot right into a Gradle venture.

The app is a traditional Spring Boot software run by DemoApplication.java.

The Java Spring HTMX mannequin class

Let’s start by taking a look at our mannequin class: com/instance/iwjavaspringhtmx/TodoItem.java. That is the server-side mannequin class that can symbolize a to-do. Right here’s what it appears to be like like:

public class TodoItem {
  personal boolean accomplished;
  personal String description;
  personal Integer id;
  public TodoItem(Integer id, String description) {
    this.description = description;
    this.accomplished = false;
    this.id = id;
  }
  public void setCompleted(boolean accomplished) {
    this.accomplished = accomplished;
  }
  public boolean isCompleted() {
    return accomplished;
  }
  public String getDescription() {
    return description;
  }
  public Integer getId(){ return id; }
  public void setId(Integer id){ this.id = id; }
  @Override
  public String toString() {
    return id + " " + (accomplished ? "[COMPLETED] " : "[ ] ") + description;
  }
}

It is a easy mannequin class with getters and setters. Nothing fancy, which is simply what we wish.

The Java Spring HTMX controller class

On the server, the controller is the boss. It accepts requests, orchestrates the logic, and formulates the response. In our case, we’d like 4 endpoints used for itemizing the gadgets, altering their completion standing, including gadgets, and deleting them. Here is the controller class:

@Controller
public class MyController {

  personal static Record<TodoItem> gadgets = new ArrayList();
  static {
    TodoItem todo = new TodoItem(0,"Make the mattress");
    gadgets.add(todo);
    todo = new TodoItem(1,"Purchase a brand new hat");
    gadgets.add(todo);
    todo = new TodoItem(2,"Take heed to the birds singing");
    gadgets.add(todo);
  }

  public MyController(){ }

  @GetMapping("https://www.infoworld.com/")
  public String gadgets(Mannequin mannequin) {
    mannequin.addAttribute("itemList", gadgets);
    return "index";
  }

  @PostMapping("/todos/{id}/full")
  public String completeTodo(@PathVariable Integer id, Mannequin mannequin) {
    TodoItem merchandise = null;
    for (TodoItem existingItem : gadgets) {
      if (existingItem.getId().equals(id)) {
        merchandise = existingItem;
        break; 
      }
    }
    if (merchandise != null) {
      merchandise.setCompleted(!merchandise.isCompleted());
    }
    mannequin.addAttribute("merchandise",merchandise);
    return "todo"; 
  }

  @PostMapping("/todos")
  public String createTodo(Mannequin mannequin, @ModelAttribute TodoItem newTodo) {
    int nextId = gadgets.stream().mapToInt(TodoItem::getId).max().orElse(0) + 1;
    newTodo.setId(nextId);
    gadgets.add(newTodo);
    mannequin.addAttribute("merchandise", newTodo);
    return "todo";
  }

  @DeleteMapping("/todos/{id}/delete")
  @ResponseBody
  public String deleteTodo(@PathVariable Integer id) {
    for (int i = 0;  i < gadgets.dimension(); i++) {
      TodoItem merchandise = gadgets.get(i);
      if (merchandise.getId() == id) {
        gadgets.take away(i);
        break;
      }
    }
    return "";
  }
}

You’ll discover that I’ve simply created a static Record to carry the gadgets in reminiscence. In actual life, we’d use an exterior knowledge retailer.

For this tour, there are a number of further factors of curiosity.

First, the endpoints are annotated with @GetMapping, @PostMapping, and @DeleteMapping. That is the way you map Spring Net paths to handlers. Every annotation corresponds to its HTTP technique (GET, POST, DELETE).

Spring Boot additionally makes it straightforward to seize parameters off the trail utilizing argument annotation @PathParameter. So, for the trail /todos/{id}/delete, @PathVariable Integer id will include the worth within the {id} a part of the trail.

Within the case of the createTodo() technique, the argument annotated @ModelAttribute TodoItem newTodo, will routinely take the POST physique and apply its values to the newTodo object. (It is a fast and simple method to flip a type submit right into a Java object.)

Subsequent, we use the merchandise IDs to govern the checklist of things. That is customary REST API fare.

There are two methods to ship a response. If the @ResponseBody annotation is current on the strategy (like it’s for deleteTodo()) then no matter is returned will likely be despatched verbatim. In any other case, the return string will likely be interpreted as a Thymeleaf template path (you may see these in a second).

The Mannequin mannequin argument is particular. It is used so as to add attributes to the scope that’s handed off to Thymeleaf. We will interpret the next gadgets technique as saying: Given a GET request to the basis/path, add the gadgets variable to the scope as “itemList” and render a response utilizing the “index” template.

@GetMapping("https://www.infoworld.com/")
  public String gadgets(Mannequin mannequin) {
    mannequin.addAttribute("itemList", gadgets);
    return "index";
  }

In circumstances the place we’re dealing with an AJAX request despatched from the entrance finish by HTMX, the response will likely be utilized by the HTMX part to replace the UI. We’ll get an excellent take a look at this in follow quickly.

The Thymeleaf templates

Now let’s take a look at Thymeleaf’s index template. It lives within the /sources/templates/index.html file. Spring Boot maps the “index” string returned from the gadgets() technique to this file utilizing conventions. Here is our index.html template:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Objects Record</title>
    <script src="https://unpkg.com/htmx.org@1.9.12"></script>
    <hyperlink rel="stylesheet" href="model.css">
  </head>
  <physique>
    <h1>Stuff To Do</h1>
      <ul>
        <th:block th:every="merchandise : ${itemList}">
          <th:block th:substitute="~{'todo.html'}" th:args="${merchandise}"></th:block>
        </th:block>
      </ul>
      <hr>
      <type hx-post="/todos" th:object="${newTodo}" hx-target="ul" hx-swap="beforeend">
        <enter kind="textual content" identify="description" placeholder="Add a brand new merchandise..." required>
        <button kind="submit">Add</button>
      </type>
  </physique>
</html>

The essential concept in Thymeleaf is to take an HTML construction and use Java variables in it. (That is equal to utilizing a template system like Pug.)

Thymeleaf makes use of HTML attributes or parts prefixed by th: to indicate the place it does its work. Keep in mind after we mapped the basis/path within the controller, we added the itemList variable to the scope. Right here, we’re utilizing that inside a th:block with a th:every attribute. The th:every attribute is the iterator mechanism in Thymeleaf. We use it to entry the weather of itemList and expose every as a variable-named merchandise: merchandise : ${itemList}.

In every iteration of itemList, we hand off the rendering to a different template. This type of template reuse is vital to avoiding code duplication. The road

<th:block th:substitute="~{'todo.html'}"th:args="${merchandise}"></th:block>

tells Thymeleaf to render the todo.html template and supply the merchandise as an argument.

We’ll take a look at the todo template subsequent, however first discover that we’re utilizing the identical template again within the controller, in each completeTodo and createTodo, to offer the markup that we ship again to HTMX throughout Ajax requests. Put one other method, we’re utilizing the todo.html as a part of each the preliminary checklist rendering and to ship updates to the UI throughout Ajax requests. Reusing the Thymeleaf template retains us DRY.

The todo template

Now right here’s todo.html:

<li>
  <enter kind="checkbox" th:checked="${merchandise.isCompleted}" hx-trigger="click on" hx-target="closest li" hx-swap="outerHTML" th:hx-post="|/todos/${merchandise.id}/full|">
  <span th:textual content="${merchandise.description}" th:classappend="${merchandise.isCompleted ? 'full' : ''}"></span>
  <button kind="button" th:hx-post="|/todos/${merchandise.id}/delete|" hx-swap="outerHTML" hx-target="closest li">🗑</button>
</li>

You may see we’re offering a list-item factor and utilizing a variable, merchandise, to populate it with values. Here is the place we get into some attention-grabbing work with each HTMX and Thymeleaf.

First, we use th:checked to use the checked standing of merchandise.isComplete to the checkbox enter.

When clicking the checkbox, we challenge an Ajax request to the back-end utilizing HTMX:

1. hx-trigger="click on" tells HTMX to provoke Ajax on a click on.
2. hx-target="closest li" tells HTMX the place to place the response from the Ajax request. In our case, we need to substitute the closest list-item factor. (Do not forget that our delete endpoint returns the entire list-item markup for the merchandise.)
3. hx-swap="outerHTML" tells HTMX the best way to swap within the new content material, on this case, changing the entire factor.
4. th:hx-post="|/todos/${merchandise.id}/full|" tells HTMX that that is an energetic Ajax factor that points a POST request to the desired URL (our to completeTodo endpoint).

One thing to notice in utilizing Thymeleaf with HTMX is that you find yourself with complicated attribute prefixes, as you see with th:hx-post. Basically, Thymeleaf runs first on the server (the th: prefix) and populates the ${merchandise.id} interpolation, then hx-post works as regular on the consumer.

Subsequent up, for the span, we simply show the textual content from merchandise.description. (Discover that Thymelef’s expression language lets us entry fields with out utilizing the get prefix.) Additionally of word is how we apply the finished model class to the span factor. Here’s what our CSS will use to place the strike-through ornament on accomplished gadgets:

th:classappend="${merchandise.isCompleted ? 'full' : ''}"

This Thymeleaf attribute makes it easy to conditionally apply a category primarily based on boolean circumstances like merchandise.isComplete.

Our Delete button works equally to the whole checkbox. We ship the Ajax request to the URL utilizing the Thymeleaf-supplied merchandise.id, and when the response comes again, we replace the checklist merchandise. Do not forget that we despatched again an empty string from deleteTodo(). The impact will due to this fact be to take away the checklist merchandise from the DOM.

The CSS stylesheet

The CSS stylesheet is at src/essential/sources/static/model.css and it is nothing outstanding. The one attention-grabbing bit is dealing with the strike-through ornament on the spans:

span {
  flex-grow: 1;
  font-size: 1rem;
  text-decoration: none;
  colour: #333;
  opacity: 0.7;
}

span.full {
  text-decoration: line-through;
  opacity: 1;
}

Conclusion

The mixture of HTMX, Java, Spring, and Thymeleaf opens up a world of prospects for constructing pretty subtle interactions with a really minimal quantity of boilerplate code. We will do an enormous quantity of typical interactivity with out ever writing JavaScript.

At first look, the Java-HTMX stack looks as if it lastly delivers on the promise of Java-centric Ajax; one thing like what Google Net Toolkit as soon as got down to do. However there’s extra. HTMX is an try to re-orient net purposes to the true nature of REST, and this stack exhibits us the way in which. HTMX is server-side agnostic, so we are able to combine it with our Java back-end with out issue.