Vaadin Cookbook

A collection of solutions to common use cases you run into when developing business web applications.

All solutions should be of the type "The user of my app wants to ..." and focus on functionality.

Solutions are implemented using Java, TS or a mix that is appropriate. The focus is on the solution, not how it is implemented.

The project is deployed at https://cookbook.vaadin.com/

General guidelines for recipes

Try to keep recipes short and show one thing. The focus is on the functionality which can be copy pasted to another project.

Try to keep recipes in one file. Use a few files if really needed. Use common sense.

Recipes cannot be wrong if they work but all recipes can be improved. It is better to improve an existing recipe than create another one which is almost the same.

Recipes are written in TS or Java. The Java version should be compatible with Vaadin 14. The TS version requires Vaadin 16+.

Contributing a Java UI based recipe

If you want to avoid problems with other people contributing the same idea at the same time, create or find an issue describing the intent (one sentence is typically enough) and accept the issue
Fork and clone the project
Create a Java package for your recipe

mkdir src/main/java/com/vaadin/recipes/recipe/recipenamegoeshere/

Create a Java file in the folder with the following

import com.vaadin.flow.router.Route;
import com.vaadin.recipes.recipe.Metadata;
import com.vaadin.recipes.recipe.Recipe;

@Route("recipe-name-goes-here")
@Metadata(
  howdoI = "Short (< 50) character explanation",
  description = "150-160 character description that is shown on the listing page and Google search results."
)
public class RecipeNameGoesHere extends Recipe {
}

Code the recipe and test it. Start the project using mvn and you find your recipe at http://localhost:8080/recipe-name-goes-here
If you created multiple files (Java or CSS), refer to them using the sourceFiles attribute of @Metadata
If your recipe needs push, add tag={Tag.PUSH} to @Metadata. Add any other suitable tags also.
Commit and create a PR
Wait for 1-2 days for somebody to react to the PR
Fix any potential comments
🎉

Contributing a TS based recipe

If you want to avoid problems with other people contributing the same idea at the same time, create or find an issue describing the intent (one sentence is typically enough) and accept the issue
Fork and clone the project
Create a TS folder for your recipe

mkdir frontend/recipe/recipe-name-goes-here/

Create a TS file in the folder with the following

import { html } from "lit";
import { customElement } from "lit/decorators.js";
import { Recipe, recipeInfo } from "../recipe";

@recipeInfo({
  url: "recipe-name-goes-here",
  howDoI: "Short (< 50) character explanation",
  description: "150-160 character description that is shown on the listing page and Google search results."
})
@customElement("recipe-name-goes-here")
export class RecipeNameGoesHere extends Recipe {
  render() {
    return html`
      <div>Template goes here</div>
      `;
  }
}

Code the recipe and test it. Start the project using mvn and you find your recipe at http://localhost:8080/recipe-name-goes-here
If you created multiple files (TS or CSS), refer to them using the sourceFiles attribute of @recipeInfo
Add any suitable tags to the tags part of @recipeInfo
Commit and create a PR
Wait for 1-2 days for somebody to react to the PR
Fix any potential comments
🎉

Running the project

In most cases you can run the project using

mvn

or by launching the Application class from an IDE.

If you want to run the project on a different port than 8080, you can do

PORT=9090 mvn

martinjunker/cookbook

Vaadin Cookbook

General guidelines for recipes

Contributing a Java UI based recipe

Contributing a TS based recipe

Running the project