13.6. Thymeleaf Forms

Templates allow you to build generic forms. This lets you reuse the structure by rendering the same template with different labels and data. Thus, a single form can serve different purposes, saving you extra effort.

Whenever possible, reuse existing templates!

13.6.1. Start a New Project

You will build a new project so you can practice with templates and forms. If you have not done so, commit and push any unsaved work from your hello-spring project.

Your new project will keep track of some fictional coding events.

  1. Use the start.spring.io website to initialize your new project.

  2. Follow the steps you used to setup hello-spring, but call the new project coding-events.

  3. Add the Thymeleaf dependency in addition to Spring Web, Spring Boot DevTools, and Validation.

  4. Generate the .zip file and then import it into IntelliJ.

13.6.2. Coding Events Setup - Video

Now that you have coding-events up and running, add features to it by coding along with the videos below:

Note

This video demonstrates the features we’ve added to a new MVC application we’ll be working with called coding-events.

The code presented in this video is found on the starter branch of coding-events-demo.

You should create your own version of coding-events from Spring Initializer and refer to the video and this branch to replicate our code. You may fork and clone from the coding-events-demo project for reference.

13.6.3. Coding Events Setup - Text

The code reviewed in the video uses concepts learned in the previous chapter to set up a controller and a couple of views. If you need to review any of these concepts, go back to that chapter.

  1. Create a controllers package.

  2. Within the new package, create a new controller class named HomeController. Annotate the class with @Controller.

  3. Add a single GET handler method that returns the name templated index, which will be the name of the template we create in the next step.

  4. Create a new Thymeleaf template named index.html in the src/main/resources/templates directory. This template could contain a single link to /events.

  5. In the controllers package, create a new controller named EventController. Annotate the class with @Controller and @RequestMapping("events").

  6. In the new controller, create a handler method for GET requests that takes a single parameter, Model model.

  7. Within the handler, create an empty list and add a few event names to it.

  8. Add the list to the model by calling model.addAttribute("events", events). Then return the template name "events/index".

  9. Within the src/main/resources/templates directory, create a new directory named events. Within this directory, create a new Thymeleaf template named index.html.

  10. Within the new template, loop over the events object and display the name of each event.

13.6.4. Create and Render a Form - Video

Note

The starter code for this video is found at the starter branch. of the coding-events-demo repo. The final code presented in this video is found on the form branch. As always, code along to the videos on your own coding-events project.

Before moving on, be sure to commit and push your changes. Do this after each video to create a fallback position just in case disaster strikes your project in the future.

A summary of Thymeleaf forms is given below, but remember that the text supports the videos and is NOT intended as a replacement.

13.6.5. Create and Render a Form - Text

A Thymeleaf form is simply a template that includes a <form> element inside the body of the HTML. The method for the form should be of type post.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<body>

   <!-- Other HTML -->

   <form method="post">
      <input type="text" name="inputName">
      <input type="submit" value="submitButtonText">
   </form>

   <!-- Other HTML -->

</body>

You can include as many inputs as you need in the form, and these can be of different types (e.g. text, email, checkbox, etc.). However, each different piece of data you want to collect needs to have a unique name attribute.

To render the form in the view, add a method to the controller using the @GetMapping annotation:

1
2
3
4
5
6
7
@GetMapping("formTemplateName")
public String renderFormMethodName(Model model) {

   // Method code...

   return "pathToTemplate";
}

Some points to note:

  1. Line 1: The string parameter for GetMapping must be the name of the form template you want to use.

  2. Line 2: Declare a Model object to hold data that needs to be passed to the template.

  3. The method code performs any data manipulation required before rendering the form. The model.addAttribute statements would be included here.

  4. The return string specifies the path to the template. Recall that Spring automatically adds MOST of the file path—up through .../templates. You need to add any path details that follow.

    1. For example, if our templates folder contains a subfolder called events that holds a template called create.html, then line 6 would be return "events/create";.

13.6.6. Add a Form Handler Method - Video

Now that you have created and rendered a form in your coding-events project, you need to add a method to the controller to handle its submission. Code along with the video below to add this functionality.

Note

The starter code for this video is found at the form branch. of the coding-events-demo repo. The final code presented in this video is found on the form2 branch. As always, code along to the videos on your own coding-events project.

As usual, the following summary outlines the ideas from the clip.

13.6.7. Add a Form Handler Method - Text

To process a form after the user clicks the Submit button, you need to add a method to the controller using the @PostMapping annotation:

1
2
3
4
5
6
7
@PostMapping("formTemplateName")
public String processFormMethodName(@RequestParam Type parameter1, Type parameter2, ...) {

   // Method code...

   return "redirect:templateName";
}

Some points to note:

  1. Line 1: The string parameter for PostMapping must be the name of the form template.

  2. Line 2: For each piece of data that needs to be retrieved from the form, declare a parameter of the appropriate type.

    Note

    @RequestParam matches the parameters to the submitted data. For this to work, the parameter names MUST match the name attributes used in each of the input elements.

  3. The method code performs any data manipulation required after the information gets submitted.

  4. Line 6: Generally, we want to send the user to a different page after they successfully submit a form. Instead of re-rendering the form, the return string redirects the user to a method that handles a different template.