eriklumme/cookbook

Copy & paste recipes for Vaadin

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

1. 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
2. Fork and clone the project
3. Create a Java package for your recipe

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

4. Create a Java file in the folder with the following

@Route("recipe-name-goes-here")
@Metadata(howdoI = "Short (< 50) character explanation")
public class RecipeNameGoesHere extends Recipe {
}

5. Code the recipe and test it. Start the project using mvn and you find your recipe at http://localhost:8080/recipe-name-goes-here

6. Commit and create a PR

7. Wait for 1-2 days for somebody to react to the PR

8. Fix any potential comments

9. 🎉

Contributing a TS based recipe

1. 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
2. Fork and clone the project
3. Create a TS folder for your recipe

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

4. Create a TS file in the folder with the following

import { customElement, html } from "lit-element";
import { Recipe, recipeInfo } from "../recipe";

@recipeInfo({
  url: "recipe-name-goes-here",
  howDoI: "Short (< 50) character explanation"
})
@customElement("recipe-name-goes-here")
export class RecipeNameGoesHere extends Recipe {
  render() {
    return html`
      <div>Template goes here</div>
      `;
  }
}

Add any additional source files to the sourceFiles array. Files should be relative to the same folder.

5. Code the recipe and test it. Start the project using mvn and you find your recipe at http://localhost:8080/recipe-name-goes-here

6. Commit and create a PR

7. Wait for 1-2 days for somebody to react to the PR

8. Fix any potential comments

9. 🎉