diff --git a/articles/building-apps/architecture/project-structure/index.adoc b/articles/building-apps/architecture/project-structure/index.adoc index 388239a2c6..2e463e910e 100644 --- a/articles/building-apps/architecture/project-structure/index.adoc +++ b/articles/building-apps/architecture/project-structure/index.adoc @@ -13,7 +13,7 @@ The recommended setup for an application with a Vaadin UI is a https://spring.io If Spring Boot or Maven are new to you, though, you should first familiarize yourself with them before proceeding. Maven has a https://maven.apache.org/guides/getting-started/index.html[Getting Started Guide] that you'll find helpful. Spring Boot has an extensive https://docs.spring.io/spring-boot/index.html[reference manual] that includes a https://docs.spring.io/spring-boot/tutorial/first-application/index.html[tutorial]. -Spring Boot and Maven are recommendations, not requirements. You can also build your application with https://gradle.org/[Gradle] -- see <<{articles}/getting-started/starters/gradle#,Starting a Vaadin Project with Gradle>> -- and run it without Spring Boot, for example with Quarkus or CDI. See <<{articles}/flow/integrations#,Integrations>> for the supported technologies, and <<{articles}/compatibility#,Supported Technologies>> for their minimum versions. +Spring Boot and Maven are recommendations, not requirements. You can also build your application with https://gradle.org/[Gradle] -- see <<{articles}/getting-started/starters/gradle#,Using Vaadin with Gradle>> -- and run it without Spring Boot, for example with Quarkus or CDI. See <<{articles}/flow/integrations#,Integrations>> for the supported technologies, and <<{articles}/compatibility#,Supported Technologies>> for their minimum versions. == JAR vs. WAR diff --git a/articles/getting-started/dev-environment/import/eclipse.adoc b/articles/getting-started/dev-environment/import/eclipse.adoc index d008f8b4a3..019a5d0a09 100644 --- a/articles/getting-started/dev-environment/import/eclipse.adoc +++ b/articles/getting-started/dev-environment/import/eclipse.adoc @@ -1,7 +1,7 @@ --- title: Eclipse IDE page-title: How to import a Vaadin project into Eclipse IDE. -description: Learn how to import a Vaadin project into Eclipse IDE using the built-in Maven project import feature. +description: Learn how to import your project into Eclipse IDE using the built-in Maven project import feature. meta-description: Import your Vaadin project into Eclipse IDE easily by following these step-by-step instructions using the Maven import feature. order: 100 --- @@ -9,7 +9,7 @@ order: 100 = Import into Eclipse IDE -To import a Vaadin project into Eclipse IDE, click menu:File[Import] in the menu. Then, in the *Import* dialog, select menu:Maven[Existing Maven Projects] and click [guibutton]*Next*. +To import your project into Eclipse IDE, click menu:File[Import] in the menu. Then, in the *Import* dialog, select menu:Maven[Existing Maven Projects] and click [guibutton]*Next*. image::images/eclipse-import.png[Import dialog in Eclipse IDE] diff --git a/articles/getting-started/dev-environment/import/index.adoc b/articles/getting-started/dev-environment/import/index.adoc index 25eeeb54a9..45052d6335 100644 --- a/articles/getting-started/dev-environment/import/index.adoc +++ b/articles/getting-started/dev-environment/import/index.adoc @@ -1,7 +1,7 @@ --- title: Import a Project page-title: Import a Vaadin project to your IDE -description: Import your Vaadin project into your favorite IDE. +description: Import your project into your favorite IDE. meta-description: Learn to import a Vaadin project into your favorite Java IDE. Follow quick guides for IntelliJ IDEA, Visual Studio Code, Eclipse, and NetBeans. order: 15 --- @@ -9,11 +9,11 @@ order: 15 = Import a Project -A Vaadin project is a normal Maven project. You can import it into your favorite Java IDE in the same way as you would import any other Maven project. +A project with Vaadin is a normal Maven project. You can import it into your favorite Java IDE in the same way as you would import any other Maven project. If you are unsure how to do this, you'll find quick guides for common Java IDEs here: -* <> (both Ultimate and Community) +* <>, with or without a subscription * <> * <> * <> diff --git a/articles/getting-started/dev-environment/import/intellij.adoc b/articles/getting-started/dev-environment/import/intellij.adoc index bf639c3e58..6ab36e2816 100644 --- a/articles/getting-started/dev-environment/import/intellij.adoc +++ b/articles/getting-started/dev-environment/import/intellij.adoc @@ -1,7 +1,7 @@ --- title: IntelliJ IDEA page-title: How to import a Vaadin project into IntelliJ IDEA -description: Follow these steps to import a Vaadin project into IntelliJ IDEA using the Open project feature. +description: Follow these steps to import your project into IntelliJ IDEA using the Open project feature. meta-description: Import your Vaadin project into IntelliJ IDEA by opening the project folder and trusting it when prompted — quick and easy setup instructions. order: 10 --- @@ -9,7 +9,7 @@ order: 10 = Import into IntelliJ IDEA -To import a Vaadin project into IntelliJ IDEA, click [guibutton]*Open* on the *Welcome to IntelliJ IDEA* screen. +To import your project into IntelliJ IDEA, click [guibutton]*Open* on the *Welcome to IntelliJ IDEA* screen. image::images/idea-welcome.png[IntelliJ IDEA welcome screen] diff --git a/articles/getting-started/dev-environment/import/netbeans.adoc b/articles/getting-started/dev-environment/import/netbeans.adoc index 8ee59d6674..a1d77792a0 100644 --- a/articles/getting-started/dev-environment/import/netbeans.adoc +++ b/articles/getting-started/dev-environment/import/netbeans.adoc @@ -1,7 +1,7 @@ --- title: NetBeans page-title: How to import a Vaadin project into NetBeans -description: Learn how to import a Vaadin project into NetBeans using the Open Project option. +description: Learn how to import your project into NetBeans using the Open Project option. meta-description: Import your Vaadin project into NetBeans by selecting Open Project and trusting the build script for a smooth setup experience. order: 300 --- @@ -9,7 +9,7 @@ order: 300 = Import into NetBeans -To import a Vaadin project into NetBeans, click [guibutton]*Open Project* on the start screen. +To import your project into NetBeans, click [guibutton]*Open Project* on the start screen. image::images/netbeans-welcome.png[NetBeans welcome screen] diff --git a/articles/getting-started/dev-environment/import/vscode.adoc b/articles/getting-started/dev-environment/import/vscode.adoc index 2174656a04..ac578e239f 100644 --- a/articles/getting-started/dev-environment/import/vscode.adoc +++ b/articles/getting-started/dev-environment/import/vscode.adoc @@ -1,7 +1,7 @@ --- title: Visual Studio Code page-title: How to import a Vaadin project into Visual Studio Code -description: This guide shows how to import a Vaadin project into Visual Studio Code by opening the project folder and confirming trust settings. +description: This guide shows how to import your project into Visual Studio Code by opening the project folder and confirming trust settings. meta-description: Import your Vaadin project into Visual Studio Code by opening the folder, trusting the authors, and enabling project-specific settings if prompted. order: 20 --- @@ -9,7 +9,7 @@ order: 20 = Import into Visual Studio Code -To import a Vaadin project into Visual Studio Code, select menu:File[Open Folder] in the menu. Then, find the project directory and click [guibutton]*Open*. +To import your project into Visual Studio Code, select menu:File[Open Folder] in the menu. Then, find the project directory and click [guibutton]*Open*. image::images/open-dialog.png[Visual Studio Code open folder dialog] diff --git a/articles/getting-started/dev-environment/index.adoc b/articles/getting-started/dev-environment/index.adoc index d9287bda0c..120914aaba 100644 --- a/articles/getting-started/dev-environment/index.adoc +++ b/articles/getting-started/dev-environment/index.adoc @@ -10,10 +10,10 @@ include::{articles}/_vaadin-version.adoc[] = Development Environment -To develop Vaadin applications, you need a Java Development Kit (JDK) and a Java IDE. If you don't have them yet, this is the fastest path: +To build a Java application with a Vaadin UI, you need the same tools as for any other Java application: a Java Development Kit (JDK) and a Java IDE. You don't have to install any frontend tools, since Vaadin downloads the ones it needs during the build. If you don't have a JDK and an IDE yet, this is the fastest path: . <>, version {vaadin-start-java-version} or newer. -. <>. The free Community Edition is enough. +. <>. You can use it for free, without a subscription. . <> and <> using the Vaadin plugin. The pages in this section also cover other JDK distributions, and the Visual Studio Code, Eclipse, and NetBeans IDEs. For the minimum versions of Java and the other technologies that Vaadin works with, such as Spring Boot, Maven, and application servers, see <<{articles}/compatibility#,Supported Technologies>>. diff --git a/articles/getting-started/dev-environment/install-ide.adoc b/articles/getting-started/dev-environment/install-ide.adoc index 4495ab6cb7..4897e69df1 100644 --- a/articles/getting-started/dev-environment/install-ide.adoc +++ b/articles/getting-started/dev-environment/install-ide.adoc @@ -9,13 +9,13 @@ order: 10 = Install an IDE -Different IDEs have different levels of support for Java and TypeScript. You write Flow views in Java, so Java support is what matters for most Vaadin applications. TypeScript support matters only if you add <<{articles}/building-apps/react#,React views>> to your application. The following table gives a rough evaluation of language support in the most commonly used IDEs. +Different IDEs have different levels of support for Java and TypeScript. You write Flow views in Java, so Java support is what matters for most applications. TypeScript support matters only if you add <<{articles}/building-apps/react#,React views>> to your application. The following table gives a rough evaluation of language support in the most commonly used IDEs. [%header, cols="3,1,1"] |==== | IDE | Java | TypeScript -| link:https://www.jetbrains.com/idea/[IntelliJ IDEA Ultimate]| ☆☆☆ | ☆☆☆ -| link:https://www.jetbrains.com/idea/[IntelliJ IDEA Community Edition]| ☆☆☆ | – +| link:https://www.jetbrains.com/idea/[IntelliJ IDEA], with an Ultimate subscription| ☆☆☆ | ☆☆☆ +| link:https://www.jetbrains.com/idea/[IntelliJ IDEA], free| ☆☆☆ | ☆☆ | link:https://code.visualstudio.com/[Visual Studio Code] | ☆☆ | ☆☆☆ | link:https://eclipseide.org/[Eclipse IDE] | ☆☆☆ | ☆☆ | link:https://netbeans.apache.org/[NetBeans]| ☆☆☆ | ☆ @@ -29,13 +29,13 @@ Different IDEs have different levels of support for Java and TypeScript. You wri Each IDE has installation packages for Windows, macOS, and Linux. [TIP] -IntelliJ IDEA Ultimate gives the best developer experience. +IntelliJ IDEA with an Ultimate subscription gives the best developer experience. Students and teachers can get the subscription for free. == IDE Extensions & Plugins If you are using IntelliJ IDEA, install the link:https://plugins.jetbrains.com/plugin/23758-vaadin[Vaadin plugin]. -If you are using Visual Studio Code, install the link:https://marketplace.visualstudio.com/items?itemName=vaadin.vaadin-vscode[Vaadin extension], the link:https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack[Extension Pack for Java], and the link:https://marketplace.visualstudio.com/items?itemName=vmware.vscode-boot-dev-pack[Spring Boot Extension Pack]. +If you are using Visual Studio Code, install the link:https://marketplace.visualstudio.com/items?itemName=vaadin.vaadin-vscode[Vaadin extension], the link:https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack[Extension Pack for Java], and, for Spring Boot applications, the link:https://marketplace.visualstudio.com/items?itemName=vmware.vscode-boot-dev-pack[Spring Boot Extension Pack]. If you are using Eclipse IDE, you should use the Eclipse IDE for Enterprise Java and Web Developers. Install the link:https://marketplace.eclipse.org/content/vaadin-tools[Vaadin plugin] for Vaadin Copilot integration and for <>. diff --git a/articles/getting-started/dev-environment/run/eclipse.adoc b/articles/getting-started/dev-environment/run/eclipse.adoc index fbd27e27c7..58ca5c73a6 100644 --- a/articles/getting-started/dev-environment/run/eclipse.adoc +++ b/articles/getting-started/dev-environment/run/eclipse.adoc @@ -8,7 +8,7 @@ order: 100 = Run in Eclipse IDE -You can run and debug your Vaadin application in Eclipse IDE as you would any other Java application. Open the main `Application` class. Then click the *Debug* button in the toolbar indicated by a red circle in this screenshot: +You can run and debug your application in Eclipse IDE as you would any other Java application. Open the main `Application` class. Then click the *Debug* button in the toolbar indicated by a red circle in this screenshot: image::images/eclipse-debug-menu.png[Eclipse IDE debug menu] @@ -25,7 +25,7 @@ If you use the Vaadin plugin, you don't have to install it yourself: the plugin [[enabling-hotswap-using-the-vaadin-plugin]] == Enabling Hotswap Using the Vaadin Plugin -The easiest way of running a Vaadin application with hotswap in Eclipse IDE is by installing the link:https://marketplace.eclipse.org/content/vaadin-tools[Vaadin plugin] from the Eclipse Marketplace. If you haven't done so already, do it now. Use the Eclipse IDE for Enterprise Java and Web Developers package. The same plugin also integrates Eclipse IDE with Vaadin Copilot, so that changes you make in the browser are written to your sources through the IDE. +The easiest way of running your application with hotswap in Eclipse IDE is by installing the link:https://marketplace.eclipse.org/content/vaadin-tools[Vaadin plugin] from the Eclipse Marketplace. If you haven't done so already, do it now. Use the Eclipse IDE for Enterprise Java and Web Developers package. The same plugin also integrates Eclipse IDE with Vaadin Copilot, so that changes you make in the browser are written to your sources through the IDE. The plugin bundles HotswapAgent and installs it for you as [filename]`.vaadin/eclipse-plugin/hotswap-agent.jar` in your home directory, and it takes care of JetBrains Runtime as well, so there's nothing else to install. diff --git a/articles/getting-started/dev-environment/run/generic.adoc b/articles/getting-started/dev-environment/run/generic.adoc index 06d757f769..b31aa6bbdf 100644 --- a/articles/getting-started/dev-environment/run/generic.adoc +++ b/articles/getting-started/dev-environment/run/generic.adoc @@ -9,11 +9,11 @@ order: 400 = Run in Any Java IDE :toclevels: 2 -You can run and debug your Vaadin application in any IDE or editor that supports Java. The `Application` class has a `main()` method, that you should run. The application starts up and you'll be able to access it at http://localhost:8080. Changes to stylesheets are applied to the browser automatically. However, to enable Java hotswap, you have to take some additional actions. +You can run and debug your application in any IDE or editor that supports Java. The `Application` class has a `main()` method, that you should run. The application starts up and you'll be able to access it at http://localhost:8080. Changes to stylesheets are applied to the browser automatically. However, to enable Java hotswap, you have to take some additional actions. == Enabling Hotswap Manually -To manually enable hotswap support for a Vaadin application, complete the following steps: +To manually enable hotswap support for your application, complete the following steps: 1. Install JetBrains Runtime (JBR) 2. Install HotswapAgent into JBR @@ -22,7 +22,7 @@ To manually enable hotswap support for a Vaadin application, complete the follow === Install JetBrains Runtime -Download the latest JetBrains Runtime from the https://github.com/JetBrains/JetBrainsRuntime/releases[JetBrainsRuntime GitHub Releases] page. Pick the _JBR (vanilla)_ archive for your platform (for example, osx-aarch64, linux-x64, or windows-x64), and extract it to a suitable location. The variants _with JCEF_ add an embedded browser engine for desktop applications, which a Vaadin application doesn't need. +Download the latest JetBrains Runtime from the https://github.com/JetBrains/JetBrainsRuntime/releases[JetBrainsRuntime GitHub Releases] page. Pick the _JBR (vanilla)_ archive for your platform (for example, osx-aarch64, linux-x64, or windows-x64), and extract it to a suitable location. The variants _with JCEF_ add an embedded browser engine for desktop applications, which a web application doesn't need. On macOS, the JVM is in the `Contents/Home` folder of the extracted directory. Use that folder wherever these instructions refer to the JetBrains Runtime folder. diff --git a/articles/getting-started/dev-environment/run/index.adoc b/articles/getting-started/dev-environment/run/index.adoc index 84e080e4bc..cb8761d5ae 100644 --- a/articles/getting-started/dev-environment/run/index.adoc +++ b/articles/getting-started/dev-environment/run/index.adoc @@ -1,7 +1,7 @@ --- title: Run a Project page-title: Run a Vaadin application in your IDE -description: Run your Vaadin application with hotswap and live reload from within your favorite IDE. +description: Run your application with hotswap and live reload from within your favorite IDE. meta-description: Run your app directly from your IDE - IntelliJ IDEA, VS Code, Eclipse, and NetBeans - with hotswap and live reload for a faster development workflow. order: 20 --- @@ -9,16 +9,16 @@ order: 20 = Run a Project -You can run a Vaadin application from the command line with `./mvnw spring-boot:run` (`mvnw spring-boot:run` on Windows), but during development you should run it from your IDE with hotswap enabled. The quick guides for common Java IDEs are here: +You can run your application from the command line the way your platform does it, for example with `./mvnw spring-boot:run` (`.\mvnw spring-boot:run` on Windows) for a Spring Boot project. During development, though, you should run it from your IDE with hotswap enabled. The quick guides for common Java IDEs are here: -* <> (both Ultimate and Community) +* <>, with or without a subscription * <> * <> * <> * <> [TIP] -IntelliJ IDEA Ultimate gives the best developer experience. +IntelliJ IDEA with an Ultimate subscription gives the best developer experience. Students and teachers can get the subscription for free. There's also another option: the <<{articles}/flow/configuration/live-reload/dev-loop-cli#,Dev Loop CLI>> runs your application under a daemon that owns the edit-to-running-app loop, and gives you a single command that makes your edits live and reports whether they are. It's especially useful when an AI coding agent is doing the editing; the <<{articles}/building-apps/agentic-development/dev-loop-tutorial#,Dev Loop Tutorial>> shows that end to end. @@ -45,6 +45,6 @@ When hot deploy mode is enabled, all JavaScript, TypeScript, and CSS files insid When live reload is enabled, changes to your Java source files are automatically applied once they have been compiled by your IDE. This can happen either through an automatic restart of the server application, or by hotswapping the changed classes. -Not all changes to a Vaadin application can be hotswapped. For instance, if a changed class modifies some global state at application startup, you'd have to restart the application to see that change. There may also be cases where your application starts to behave strangely after having a class hotswapped. In this case, restarting the application manually is often enough to fix the problem. +Not all changes to an application can be hotswapped. For instance, if a changed class modifies some global state at application startup, you'd have to restart the application to see that change. There may also be cases where your application starts to behave strangely after having a class hotswapped. In this case, restarting the application manually is often enough to fix the problem. The IDE guides above set up hotswap with HotswapAgent. For the other options -- Spring Boot Developer Tools, which restarts the application instead, and the commercial JRebel -- see <<{articles}/flow/configuration/live-reload#java-changes,Hot Deploy & Live Reload>>. diff --git a/articles/getting-started/dev-environment/run/intellij.adoc b/articles/getting-started/dev-environment/run/intellij.adoc index 204bb7e69b..f8609bce33 100644 --- a/articles/getting-started/dev-environment/run/intellij.adoc +++ b/articles/getting-started/dev-environment/run/intellij.adoc @@ -8,7 +8,7 @@ order: 10 = Run in IntelliJ IDEA -You can run and debug your Vaadin application in IntelliJ IDEA as you would any other Java application. When you imported the project into IntelliJ IDEA, a run/debug configuration called _Application_ should have been created automatically. You can start the application by clicking the *Debug* button in the toolbar. It is indicated by a red circle in this screenshot: +You can run and debug your application in IntelliJ IDEA as you would any other Java application. When you imported the project into IntelliJ IDEA, a run/debug configuration called _Application_ should have been created automatically. You can start the application by clicking the *Debug* button in the toolbar. It is indicated by a red circle in this screenshot: image::images/idea-debug.png[Debug button in IntelliJ IDEA] @@ -32,7 +32,7 @@ When using hot deploy with Gradle, ensure that `frontendHotdeploy` is set to `tr == Enabling Hotswap -The easiest way of running a Vaadin application with hotswap in IntelliJ IDEA is by installing the link:https://plugins.jetbrains.com/plugin/23758-vaadin[Vaadin plugin]. If you haven't done so already, do it now. +The easiest way of running your application with hotswap in IntelliJ IDEA is by installing the link:https://plugins.jetbrains.com/plugin/23758-vaadin[Vaadin plugin]. If you haven't done so already, do it now. Click on the button with three small dots next to the run/debug configuration. It is highlighted on this screenshot with a red circle: diff --git a/articles/getting-started/dev-environment/run/netbeans.adoc b/articles/getting-started/dev-environment/run/netbeans.adoc index 1dafebc824..390640954a 100644 --- a/articles/getting-started/dev-environment/run/netbeans.adoc +++ b/articles/getting-started/dev-environment/run/netbeans.adoc @@ -8,7 +8,7 @@ order: 300 = Run in NetBeans -You can run and debug your Vaadin application in NetBeans as you would any other Java application. Start by selecting menu:File[Project Properties]. Select the *Run* category and specify your *Main Class*, like this: +You can run and debug your application in NetBeans as you would any other Java application. Start by selecting menu:File[Project Properties]. Select the *Run* category and specify your *Main Class*, like this: image::images/netbeans-properties.png[NetBeans project properties dialog] diff --git a/articles/getting-started/dev-environment/run/vscode.adoc b/articles/getting-started/dev-environment/run/vscode.adoc index 9f59994577..c852e6155b 100644 --- a/articles/getting-started/dev-environment/run/vscode.adoc +++ b/articles/getting-started/dev-environment/run/vscode.adoc @@ -9,7 +9,7 @@ order: 20 = Run in Visual Studio Code -You can run and debug your Vaadin application in Visual Studio Code as you would any other Java application. Open the main `Application` class. Then select either *Run Java* or *Debug Java* in the upper-right corner indicated by a red circle in this screenshot: +You can run and debug your application in Visual Studio Code as you would any other Java application. Open the main `Application` class. Then select either *Run Java* or *Debug Java* in the upper-right corner indicated by a red circle in this screenshot: image::images/vscode-run.png[Run Java button in VS Code] diff --git a/articles/getting-started/index.adoc b/articles/getting-started/index.adoc index 34cb4a7fc4..57779b0004 100644 --- a/articles/getting-started/index.adoc +++ b/articles/getting-started/index.adoc @@ -1,7 +1,7 @@ --- title: Getting Started page-title: Guide for Getting Started with Vaadin -description: Get started building applications with Vaadin. +description: Get started building the UI of your Java applications with Vaadin. meta-description: Explore this beginner's guide to start building applications with Vaadin. order: 5 section-nav: flat @@ -9,15 +9,19 @@ section-nav: flat = Welcome to the Getting Started Guide! -New to Vaadin? Start with the Quick Start. It takes about 10 minutes, and you end up with a running Vaadin application and your first view. +Vaadin lets you build the web user interface of a Java application in Java. An application with a Vaadin UI is a regular Java application: you write the UI with the same language, tools, and libraries as the rest of the application. Java skills are all you need to be productive. Knowing CSS, JavaScript, or TypeScript helps, for example when you fine-tune the look of your application, but it isn't a requirement. + +Vaadin works with Spring Boot, Quarkus, Jakarta EE servers, and plain servlet containers. The Quick Start and the Tutorial use Spring Boot, because it's the easiest platform to start with. + +New to Vaadin? Start with the Quick Start. In minutes, it gets you from nothing to a running application that you've changed yourself. xref:quick-start#[Start the Quick Start, role="button primary water"] -When you have an application running, continue with the <>. It takes you step by step through building a complete application with a database, forms, and navigation. +When you have an application running, continue with the <>. It takes you step by step through building a complete Spring Boot application with a Vaadin UI, a database, forms, and navigation. Evaluating Vaadin for a project? Start with <<{articles}/building-apps/architecture/when-to-use-vaadin#,When to Use Vaadin>> to learn which applications Vaadin fits, which it doesn't, and why. Then read <<{articles}/building-apps/architecture/runtime-model#,How Vaadin Works at Runtime>> to learn where the UI state lives, what each interaction costs, and what that means for deploying and scaling the application. Finally, see <<{articles}/building-apps/architecture/licensing-and-maintenance#,Licensing, Support & Maintenance>> for which features are free and which need a commercial subscription, and <<{articles}/compatibility#,Supported Technologies>> for the minimum versions of Java, Spring Boot, and other technologies. -Need to install Java or an IDE first? See the <> guide. Looking for other ways to create a project, such as Gradle or Spring Initializr? See <>. +Need to install Java or an IDE first? See the <> guide. Looking for other ways to create a project, such as Gradle, Spring Initializr, or a template for Quarkus or Jakarta EE? See <>. == Everything in This Section diff --git a/articles/getting-started/next-steps.adoc b/articles/getting-started/next-steps.adoc index 072a9a45e9..876e19d803 100644 --- a/articles/getting-started/next-steps.adoc +++ b/articles/getting-started/next-steps.adoc @@ -1,15 +1,17 @@ --- title: Next Steps page-title: Add features to your Vaadin project -description: Add features to your Vaadin project to turn it into a full-featured application. +description: Add features to your project to turn it into a full-featured application. meta-description: Turn your Vaadin project into a full application. Add views, forms, security, and a production database, then test your app and deploy it to production. order: 100 --- -= Expand Your Vaadin Project += Expand Your Application -You now have a working Vaadin application, built either in the <> or the <>. The next step is to turn it into an application that you can put in front of real users. The <<{articles}/building-apps#,Building Apps>> section of the documentation has guides for this. These are the ones most applications need next. +You now have a working application with a Vaadin UI, built either in the <> or the <>. The next step is to turn it into an application that you can put in front of real users. The <<{articles}/building-apps#,Building Apps>> section of the documentation has guides for this. These are the ones most applications need next. + +Like the Tutorial, Building Apps uses Spring Boot. If your application runs on another platform, the guides about the UI apply as they are, and the <<{articles}/flow/integrations#,Integrations>> reference covers what differs. == Build Your User Interface diff --git a/articles/getting-started/quick-start/index.adoc b/articles/getting-started/quick-start/index.adoc index 2cdee23912..664af82106 100644 --- a/articles/getting-started/quick-start/index.adoc +++ b/articles/getting-started/quick-start/index.adoc @@ -10,24 +10,24 @@ include::{articles}/_vaadin-version.adoc[] = Quick Start Tutorial -This is a quick tutorial *for developers trying out Vaadin for the first time*. It walks you through creating a simple Vaadin application from scratch, demonstrating the core concepts along the way. It takes about 10 minutes to complete. +This is a quick tutorial *for developers trying out Vaadin for the first time*. It walks you through creating a simple web application with a Vaadin UI from scratch, demonstrating the core concepts along the way. It takes about 10 minutes to complete. -Vaadin allows you to build modern web applications in 100% Java. You don't need to know HTML, CSS, or JavaScript to get started. +Vaadin allows you to build modern web user interfaces in 100% Java. You don't need to know HTML, CSS, or JavaScript to get started. They help later, when you want to fine-tune your UI, but Java is all this tutorial needs. == Before You Start You need two things installed on your computer: -* *A Java Development Kit (JDK), version {vaadin-start-java-version} or newer.* If you don't have one, download and install link:https://adoptium.net/temurin/releases/[Eclipse Temurin] for your operating system. -* *A Java IDE.* If you don't have one, download and install link:https://www.jetbrains.com/idea/download/[IntelliJ IDEA]. The free Community Edition is enough for this tutorial. +* *A Java Development Kit (JDK), version {vaadin-start-java-version} or newer.* If you don't have one, download and install link:https://adoptium.net/temurin/releases/[Eclipse Temurin] for your operating system. To check which version you have, run `java -version` in a terminal. +* *A Java IDE.* If you don't have one, download and install link:https://www.jetbrains.com/idea/download/[IntelliJ IDEA]. You can use it for free: this tutorial doesn't need a subscription. If you already have a JDK and an IDE, you're ready to go. Other JDK distributions and IDEs work too. See the <<../dev-environment#,Development Environment>> guide for options. -== Bootstrap a Vaadin Project +== Bootstrap a Project -Click the button below to download a minimal Vaadin project skeleton: +Click the button below to download a minimal project skeleton with Vaadin: link:https://start.vaadin.com/skeleton?platformVersion={vaadin-start-platform-version}&javaVersion={vaadin-start-java-version}&groupId=com.example&artifactId=app&frameworks=none&aiTool=NONE[Download Project, role="button primary water", id="docs-quick-start-download-project-cta"] @@ -35,7 +35,7 @@ After downloading the project, unzip it and open the project directory in your I .This is a Spring Boot Project [NOTE] -The downloaded project skeleton is a Spring Boot project. The <<../starters#,Starters>> documentation page describes *how to create Vaadin projects using different technology stacks*. +The downloaded project skeleton is a Spring Boot project, because Spring Boot is the easiest platform to start with. The view code you write in this tutorial is the same on other Java platforms, such as Quarkus or a Jakarta EE server. The <<../starters#,Starters>> documentation page describes *how to create projects with Vaadin on different technology stacks*. == Create Your First View @@ -71,7 +71,7 @@ public class MainView extends VerticalLayout { // <3> <4> `H1` is a component that corresponds to the HTML `

` element (a top-level heading). <5> This line creates a new Button with the label "Say Hello". When clicked, it triggers a lambda function that adds a new `Paragraph` with the message "Hello, Vaadin!" to the view. -This programming model is typical for Vaadin applications. You construct the UI from components, and define behavior using event listeners. If you have used Swing or JavaFX before, this should feel familiar. +This programming model is typical for Vaadin. You construct the UI from components, and define behavior using event listeners. If you have used Swing or JavaFX before, this should feel familiar. == Run the Application @@ -87,7 +87,7 @@ Open a terminal in the project directory and start the application with the Mave .Windows [source,terminal] ---- -mvnw spring-boot:run +.\mvnw spring-boot:run ---- The first startup may take a while as Maven and npm download the required dependencies. @@ -252,7 +252,7 @@ If you now enter your name and click the button, you'll see that the greeting me == Call a Java Library -A Vaadin application is a regular Java application. Because the user interface runs on the server side, you can call any Java library directly from your UI code. You'll now try this by adding a QR code to your application using the popular `zxing` library. +An application with a Vaadin UI is a regular Java application. Because the user interface runs on the server side, you can call any Java library directly from your UI code. You'll now try this by adding a QR code to your application using the popular `zxing` library. Start by adding the following dependency to your `pom.xml` file inside the `` section: @@ -352,7 +352,7 @@ image::images/fifth-view.png[The Vaadin view with a button to generate a QR code If you click the button with an empty text field, an error message is shown instead. -Having access to the entire Java ecosystem allows you to leverage existing libraries and tools in your Vaadin applications, making development faster and easier. +Having access to the entire Java ecosystem allows you to leverage existing libraries and tools in your UI code, making development faster and easier. Running the user interface on the server has other consequences, too. For example, every click on the button is a round trip to the server, and the server keeps the state of the view in its memory. <<{articles}/building-apps/architecture/runtime-model#,How Vaadin Works at Runtime>> explains what this means for your application. @@ -361,7 +361,7 @@ Running the user interface on the server has other consequences, too. For exampl Up to this point, you have been running the application in development mode, which is optimized for fast feedback during development. Before deploying your application to production, you should create a production build that is optimized for performance. -Execute the Maven `package` goal to create a production build. Stop the application, then run the following command from the project directory (on Windows, use `mvnw` instead of `./mvnw`): +Execute the Maven `package` goal to create a production build. Stop the application, then run the following command from the project directory (on Windows, use `.\mvnw` instead of `./mvnw`): [source,terminal] ---- @@ -377,13 +377,13 @@ You can run the production build using the following command: java -jar target/app-1.0-SNAPSHOT.jar ---- -Open your browser and navigate to http://localhost:8080 to see your application running in production mode. You'll notice that the Copilot toolbar is no longer visible. +Open your browser and navigate to http://localhost:8080 to see your application running in production mode. You'll notice that the Copilot toolbar is no longer visible. When you're done, stop the application with kbd:[Ctrl+C], so that it doesn't keep port 8080 busy. == Next Steps -You have now created a simple Vaadin application from scratch, learning some core concepts along the way. Continue with the Tutorial, where you build a complete application with a database, forms, and navigation, one step at a time. +You have now created a simple web application with a Vaadin UI from scratch, learning some core concepts along the way. Continue with the Tutorial, where you build a complete Spring Boot application with a database, forms, and navigation, one step at a time. xref:../tutorial#[Start the Tutorial, role="button primary water"] -If you'd rather start building an application of your own right away, see <<../next-steps#,Expand Your Vaadin Project>> for the guides that most applications need next. +If you'd rather start building an application of your own right away, see <<../next-steps#,Expand Your Application>> for the guides that most applications need next. diff --git a/articles/getting-started/starters/gradle.adoc b/articles/getting-started/starters/gradle.adoc index a773a92ef6..7fa39a98c5 100644 --- a/articles/getting-started/starters/gradle.adoc +++ b/articles/getting-started/starters/gradle.adoc @@ -1,19 +1,19 @@ --- title: Gradle page-title: Create, Build, and Run a Vaadin Project with Gradle -description: How to create a Vaadin project with Gradle. +description: How to create, build, and run a project with Vaadin using Gradle. meta-description: Create a Vaadin project with Gradle. Add the Vaadin Gradle plugin and Spring Boot, run the application in development mode, and build a package for production. order: 300 --- include::{articles}/_vaadin-version.adoc[] -= Starting a Vaadin Project with Gradle += Using Vaadin with Gradle [.introText] -https://gradle.org/[Gradle] is a build tool for Java and other JVM languages, and an alternative to Maven. You can use it to manage the dependencies of a Vaadin application, run the application during development, and build it for production. +https://gradle.org/[Gradle] is a build tool for Java and other JVM languages, and an alternative to Maven. You can use it to manage the dependencies of your application, run it during development, and build it for production. -This page describes how to create a Vaadin project with Gradle, either as a Spring Boot application or as a web application that runs in a servlet container. For the tasks and configuration options of the Vaadin Gradle plugin, see <<{articles}/flow/configuration/gradle#,Gradle Configuration Properties>>. For information about using Gradle, see the link:https://docs.gradle.org/current/userguide/userguide.html[Gradle User Manual]. +This page describes how to create a project with Vaadin using Gradle, either as a Spring Boot application or as a web application that runs in a servlet container. For the tasks and configuration options of the Vaadin Gradle plugin, see <<{articles}/flow/configuration/gradle#,Gradle Configuration Properties>>. For information about using Gradle, see the link:https://docs.gradle.org/current/userguide/userguide.html[Gradle User Manual]. .Requirements [NOTE] @@ -21,9 +21,9 @@ The Vaadin Gradle plugin requires Java 21 or later and Gradle 8.14 or later. See If you plan to use Vaadin's Gradle-based starter projects, there's no need to install Gradle on your machine. A Gradle Wrapper script is included in starter projects. It manages locally the download and execution of Gradle for your project. For more information on using Gradle Wrapper, see the https://docs.gradle.org/current/userguide/gradle_wrapper.html[Official Gradle Documentation]. -== Creating a Vaadin Project +== Creating a Project -You can create a Vaadin project with Gradle in the following ways: +You can create a project with Vaadin using Gradle in the following ways: * Clone one of the starter repositories described in the next section. * Generate a Spring Boot project with <<{articles}/getting-started/starters/spring-initializr#,Spring Initializr>>. Choose Gradle as the build tool and add the _Vaadin_ dependency. @@ -77,7 +77,7 @@ To avoid unnecessary verbosity, only the Unix style of running `./gradlew` is us [[build-file]] == The Build Files -A Vaadin project applies the Vaadin Gradle plugin and imports the Vaadin bill of materials (BOM), which manages the versions of the Vaadin dependencies. The plugin and the BOM should use the same version. The starter projects define the version once, in [filename]`gradle.properties`: +A project that uses Vaadin applies the Vaadin Gradle plugin and imports the Vaadin bill of materials (BOM), which manages the versions of the Vaadin dependencies. The plugin and the BOM should use the same version. The starter projects define the version once, in [filename]`gradle.properties`: .`gradle.properties` [source,properties,subs="+attributes"] diff --git a/articles/getting-started/starters/index.adoc b/articles/getting-started/starters/index.adoc index b0dd46d6a1..b897cd441e 100644 --- a/articles/getting-started/starters/index.adoc +++ b/articles/getting-started/starters/index.adoc @@ -1,14 +1,16 @@ --- title: Starters page-title: Create a Vaadin Project - Start, Maven, Gradle, Initializr -description: Learn about different ways to start a Vaadin project. +description: Learn about different ways to start a project with Vaadin. meta-description: Five ways to create a Vaadin project, with the steps for each. Vaadin Start, project templates on GitHub, Spring Initializr, the Maven archetype, and Gradle. order: 20 --- -= Different Ways of Starting a Vaadin Project += Different Ways of Starting a Project -You can create a new Vaadin project in several ways: +Vaadin Start and Spring Initializr create Spring Boot projects, because Spring Boot is the easiest platform to start with. The templates also cover Quarkus, Jakarta EE servers, and plain servlet containers. + +You can create a new project with Vaadin in several ways: section_outline::[] diff --git a/articles/getting-started/starters/maven-archetype.adoc b/articles/getting-started/starters/maven-archetype.adoc index 8afd721e37..a5c6a7aebb 100644 --- a/articles/getting-started/starters/maven-archetype.adoc +++ b/articles/getting-started/starters/maven-archetype.adoc @@ -1,7 +1,7 @@ --- title: Maven Archetype page-title: How to create a project from Maven Archetype | Vaadin -description: How to use a Maven Archetype to generate a Vaadin web application. +description: How to use a Maven Archetype to generate a web application that uses Vaadin. meta-description: Kickstart your Vaadin projects with Maven archetypes. Learn how to generate project structures and streamline your Java web app development. order: 200 --- @@ -12,7 +12,7 @@ order: 200 :vaadin-version: {moduleMavenVersion:com.vaadin:vaadin} -You can use a https://vaadin.com/blog/learning-maven-concepts[Maven archetype] to generate a Vaadin web application with a preconfigured Jetty Maven plugin in it. Once it's created, you can import it into your IDE. +You can use a https://vaadin.com/blog/learning-maven-concepts[Maven archetype] to generate a web application that uses Vaadin, with a preconfigured Jetty Maven plugin in it. Once it's created, you can import it into your IDE. Most IDEs support creating a project from a Maven archetype. See your IDE and its documentation for instructions. diff --git a/articles/getting-started/starters/spring-initializr.adoc b/articles/getting-started/starters/spring-initializr.adoc index 6e672f8310..c25d7e3aac 100644 --- a/articles/getting-started/starters/spring-initializr.adoc +++ b/articles/getting-started/starters/spring-initializr.adoc @@ -1,7 +1,7 @@ --- title: Spring Initializr page-title: How to create a Vaadin project with Spring Initializr -description: How to create a Vaadin project with Spring Initializr. +description: How to create a Spring Boot project with Vaadin in Spring Initializr. meta-description: Learn how to create a Vaadin Project with Spring Initializr. order: 100 --- @@ -9,7 +9,7 @@ order: 100 = Spring Initializr -If you are familiar with Spring Boot, you can quickly create a new Vaadin project with *Spring Initializr*: +If you are familiar with Spring Boot, you can quickly create a new Spring Boot project with Vaadin in *Spring Initializr*: 1. Visit https://start.spring.io[Spring Initializr]. 2. Choose a build tool: _Maven_ (recommended in this documentation) or _Gradle_. diff --git a/articles/getting-started/starters/start/index.adoc b/articles/getting-started/starters/start/index.adoc index 2f9cdeca55..addffe054b 100644 --- a/articles/getting-started/starters/start/index.adoc +++ b/articles/getting-started/starters/start/index.adoc @@ -1,14 +1,14 @@ --- title: Vaadin Start page-title: Create a Project with Vaadin Start -description: The recommended way to start a Vaadin project. +description: The recommended way to start a project with Vaadin. meta-description: How to create a Vaadin project using Vaadin Start, the recommended way to start a Vaadin project. order: 1 --- = Create a Project with Vaadin Start -The recommended way to start a Vaadin project is by using https://start.vaadin.com[Vaadin Start], which generates a ready-to-run Spring Boot and Maven based project: +The recommended way to start a project with Vaadin is by using https://start.vaadin.com[Vaadin Start], which generates a ready-to-run Spring Boot and Maven based project: [.device] image::images/start.png[Vaadin Start] diff --git a/articles/getting-started/starters/templates.adoc b/articles/getting-started/starters/templates.adoc index 15c6b9d814..64f37a15fb 100644 --- a/articles/getting-started/starters/templates.adoc +++ b/articles/getting-started/starters/templates.adoc @@ -1,7 +1,7 @@ --- title: Templates page-title: Vaadin Project Templates -description: Clone a template project to create a Vaadin application with a different technology stack. +description: Clone a template project to create an application with a Vaadin UI on a different technology stack. meta-description: How to create a Vaadin project by cloning a template for a different technology stack. order: 2 --- @@ -22,4 +22,4 @@ For how Vaadin works with Quarkus, and with CDI on a Jakarta EE server, see <<{a [IMPORTANT] -Some guides, such as <> and <>, may not fully apply to projects that are not based on Spring Boot and Maven. +The <> and the <> guides use Spring Boot and Maven, so parts of them don't apply as they are to projects on other platforms. diff --git a/articles/getting-started/tutorial/add-data.adoc b/articles/getting-started/tutorial/add-data.adoc index a0596c66dd..c426e2ba80 100644 --- a/articles/getting-started/tutorial/add-data.adoc +++ b/articles/getting-started/tutorial/add-data.adoc @@ -642,7 +642,7 @@ class ProductCatalogView extends MasterDetailLayout { } ---- -Now when you add a new product, it should automatically be selected and show up in the drawer. +Restart the application, since you changed a repository interface. Now when you add a new product, it should automatically be selected and show up in the drawer. === Handle Constraint Violation @@ -791,7 +791,7 @@ Now try to create a new item with the SKU `NBK-A5-DOT`. You should receive a not How is this possible? How can another user have edited a product that you haven't even inserted yet? -You have now discovered a mismatch between how Spring Data and Vaadin assume data objects should be used. These mismatches are prone to happen whenever you're dealing with mutable data objects, like `ProductDetails` in this case. +You have now run into a problem that can happen whenever a form keeps editing the same mutable object across saves, like `ProductDetails` in this case. Spring Data changes the object while saving it, and a rolled-back transaction doesn't undo that change. Here's what happened: @@ -806,16 +806,16 @@ Here's what happened: If this had been a REST API, the `ProductDetails` object would always be a new instance and this would not be a problem. Since you're reusing the object, you have to work around this problem. You can do this in different ways, but the user interface shouldn't need to know about any of them. It's a persistence detail, and the view already saves products through `ProductCatalogService`. That makes the service the right place for the workaround. -=== Work Around the Version Bug +=== Save a Copy of the Product -The easiest ways to work around this bug are the following: +The easiest ways to avoid this problem are the following: 1. Set the version to `null` before saving an item that doesn't yet have an ID. 2. Make a copy of the object and pass the copy to the repository, then return it if successful. Making a copy is more elegant because it ensures the original object remains unchanged until the transaction commits successfully. This follows a principle of keeping data objects immutable during uncertain operations. Also, you have already designed your UI callbacks to support backends that return new instances of data objects after saving them. -This bug is a cost of using the entity as the FDO. A separate FDO would avoid it as well, because the form would never hold the object that Spring Data changes. Copying the entity before saving gives the same protection without a second class, which is enough while the form and the table match one-to-one. +This problem is a cost of using the entity as the FDO. A separate FDO would avoid it as well, because the form would never hold the object that Spring Data changes. Copying the entity before saving gives the same protection without a second class, which is enough while the form and the table match one-to-one. Start by adding two constructors to `ProductDetails` - a _default constructor_ for creating new instances, and a _copy constructor_ for creating copies: @@ -1674,7 +1674,7 @@ class AddProductDialog extends Dialog { == Next Steps -You have now built a fully functional Vaadin application with the following features: +You have now built a fully functional Spring Boot application with a Vaadin UI. It has the following features: - Paginated data loading - Sorting and filtering diff --git a/articles/getting-started/tutorial/add-tests.adoc b/articles/getting-started/tutorial/add-tests.adoc index 5c08cd2d68..8cab823195 100644 --- a/articles/getting-started/tutorial/add-tests.adoc +++ b/articles/getting-started/tutorial/add-tests.adoc @@ -19,7 +19,7 @@ In a real project, you'd write each test while you build the feature that it cov .More Information Available [TIP] -This step is based on the <> guides. Read them if you want more detailed information about testing Vaadin applications. +This step is based on the <> guides. Read them if you want more detailed information about testing your application. == Check the Test Dependencies @@ -120,7 +120,7 @@ The first test does more than check that saving works. It also proves that `newP Spring starts the application only once, and reuses it for the other tests in the same run, as long as they have the same configuration. That includes the in-memory database. Without `@Transactional`, the travel mug that the first test saves would stay in the database, and show up in the tests that you write next. With it, every test starts with the data from `data.sql`. -Run the test class from your IDE. In IntelliJ IDEA, click the green arrow next to the class name, and select [guibutton]*Run 'ProductCatalogServiceTest'*. You can also run all tests from a terminal with `./mvnw test` (`mvnw test` on Windows). All three tests should pass. +Run the test class from your IDE. In IntelliJ IDEA, click the green arrow next to the class name, and select [guibutton]*Run 'ProductCatalogServiceTest'*. You can also run all tests from a terminal with `./mvnw test` (`.\mvnw test` on Windows). All three tests should pass. A test is only useful if it fails when something breaks. Try it: remove the `@Valid` annotation from the `save()` method of `ProductCatalogService`, and run the tests again. The negative price test now fails: @@ -356,4 +356,4 @@ This was the last step of the tutorial. You've built a product catalog where use Before you can put the catalog in front of real users, you need to secure it, move it to a real database, and deploy it. The next page points you to the guides for each of these. -link:{articles}/getting-started/next-steps[Next: Expand Your Vaadin Project, role="button primary water", id="docs-tutorial-add-tests-next-cta"] +link:{articles}/getting-started/next-steps[Next: Expand Your Application, role="button primary water", id="docs-tutorial-add-tests-next-cta"] diff --git a/articles/getting-started/tutorial/edit-details.adoc b/articles/getting-started/tutorial/edit-details.adoc index d5839b0219..8bb00df989 100644 --- a/articles/getting-started/tutorial/edit-details.adoc +++ b/articles/getting-started/tutorial/edit-details.adoc @@ -570,10 +570,6 @@ You could get the same result by overriding `equals()` and `hashCode()` in `Prod If you now try the application, you should notice that the grid preserves the selection between saves. -.Vaadin 25.3.2 or Later Required -[NOTE] -In earlier versions, the grid ignores the identifier provider when it selects items, so the selection is still lost after saving. If your project uses an earlier version, update the `vaadin.version` property in `pom.xml`. - === Validate the Form diff --git a/articles/getting-started/tutorial/index.adoc b/articles/getting-started/tutorial/index.adoc index a9a914447b..42e92ded4f 100644 --- a/articles/getting-started/tutorial/index.adoc +++ b/articles/getting-started/tutorial/index.adoc @@ -8,7 +8,11 @@ order: 30 = Welcome to the Vaadin Tutorial -This tutorial guides you through the basics of building a web application using Vaadin. You'll start with an empty project and gradually add features to create a functional web application step by step. +This tutorial guides you through the basics of building a Spring Boot application with a Vaadin UI. You'll start with an empty project and gradually add features to create a functional web application step by step. + +You write the application in Java. Spring Boot runs it, Spring Data reads and writes its database, and Vaadin builds its user interface. You don't need to know Spring Boot beforehand. The tutorial uses Spring Boot features, such as dependency injection, repositories, and transactions, without teaching them in depth. If one is new to you, the https://docs.spring.io/spring-boot/index.html[Spring Boot documentation] explains it. + +One step adds four short CSS rules to style the main layout, and explains each of them. That's all the frontend code you need. You'll be building parts of the back office of a fictional Click & Collect service for a retail company. In the full back office, employees would manage the product catalog, process customer orders, and track deliveries. In this tutorial, you'll build the product catalog, and the main layout with a navigation menu that the other parts would share: @@ -21,6 +25,6 @@ Expect to spend 15 to 45 minutes on each step. You don't need to finish the tuto .In a Hurry? [TIP] -If you only want to see Vaadin in action, the <<../quick-start#,Quick Start>> gets you from nothing to a running application in about 10 minutes. You don't need to complete it before this tutorial, which starts from an empty project. +If you only want to see Vaadin in action, the <<../quick-start#,Quick Start>> gets you from nothing to a running application in minutes. You don't need to complete it before this tutorial, which starts from an empty project. section_outline::[] diff --git a/articles/getting-started/tutorial/setup.adoc b/articles/getting-started/tutorial/setup.adoc index f643df9bc6..db1e6e784d 100644 --- a/articles/getting-started/tutorial/setup.adoc +++ b/articles/getting-started/tutorial/setup.adoc @@ -1,7 +1,7 @@ --- title: Set Up Project page-title: Set Up the Project for the Vaadin Tutorial -description: Set up a new Vaadin project with the necessary dependencies and configuration. +description: Set up a new Spring Boot project with Vaadin, and add the necessary dependencies and configuration. meta-description: Set up the project for the Vaadin tutorial. Install a JDK and an IDE, download the project skeleton, add the database dependencies, and verify that the application starts. order: 5 --- @@ -10,28 +10,28 @@ include::{articles}/_vaadin-version.adoc[] = Set Up the Project -In this section, you'll set up the project that you'll be using throughout this tutorial. When you're done, you have an empty Vaadin application running on your computer, connected to a database with sample data. +In this section, you'll set up the project that you'll be using throughout this tutorial. When you're done, you have an empty Spring Boot application with Vaadin running on your computer, connected to a database with sample data. == Prerequisites You need two things installed on your development machine: -* *A Java Development Kit (JDK), version {vaadin-start-java-version} or newer.* If you don't have one, download and install link:https://adoptium.net/temurin/releases/[Eclipse Temurin] for your operating system. -* *A Java IDE.* If you don't have one, download and install link:https://www.jetbrains.com/idea/download/[IntelliJ IDEA]. The free Community Edition is enough for this tutorial. +* *A Java Development Kit (JDK), version {vaadin-start-java-version} or newer.* If you don't have one, download and install link:https://adoptium.net/temurin/releases/[Eclipse Temurin] for your operating system. To check which version you have, run `java -version` in a terminal. +* *A Java IDE.* If you don't have one, download and install link:https://www.jetbrains.com/idea/download/[IntelliJ IDEA]. You can use it for free: this tutorial doesn't need a subscription. Other JDK distributions and IDEs work too. See the <<../dev-environment#,Development Environment>> guide for options. .Use Hotswap for Faster Development [TIP] -It is recommended to use hotswap while developing Vaadin applications. Hotswap reloads changed classes in a running JVM without restarting the application, so you see your changes within seconds. The Vaadin plugin for your IDE sets it up for you. See the instructions for <<../dev-environment/run/intellij#,IntelliJ IDEA>>, <<../dev-environment/run/vscode#,Visual Studio Code>>, <<../dev-environment/run/eclipse#,Eclipse IDE>>, or <<../dev-environment/run/netbeans#,NetBeans>>. +It is recommended to use hotswap while developing your application. Hotswap reloads changed classes in a running JVM without restarting the application, so you see your changes within seconds. The Vaadin plugin for your IDE sets it up for you. See the instructions for <<../dev-environment/run/intellij#,IntelliJ IDEA>>, <<../dev-environment/run/vscode#,Visual Studio Code>>, <<../dev-environment/run/eclipse#,Eclipse IDE>>, or <<../dev-environment/run/netbeans#,NetBeans>>. == Create the Project -This tutorial starts from an empty project skeleton. Even if you have completed the <<../quick-start#,Quick Start>>, download a new project here rather than reusing that one, since the view you created there would clash with the views you create in this tutorial. +This tutorial starts from an empty project skeleton. Even if you have completed the <<../quick-start#,Quick Start>>, download a new project here rather than reusing that one, since its code would clash with the code you write in this tutorial. -Click the button below to download a minimal Vaadin project skeleton: +Click the button below to download a minimal Spring Boot project skeleton with Vaadin: link:https://start.vaadin.com/skeleton?platformVersion={vaadin-start-platform-version}&javaVersion={vaadin-start-java-version}&groupId=com.example&artifactId=app&frameworks=none&aiTool=NONE[Download Project, role="button primary water", id="docs-tutorial-setup-download-project-cta"] @@ -74,7 +74,7 @@ Because the database lives in memory, any changes you make in the application di == Run the Application -To make sure everything is set up correctly, run the application. Either start it from your IDE with hotswap enabled, as described in the tip above, or open a terminal in the project directory and run `./mvnw spring-boot:run` (`mvnw spring-boot:run` on Windows). +To make sure everything is set up correctly, run the application. If an application from the Quick Start is still running, stop it first, since both use port 8080. Either start it from your IDE with hotswap enabled, as described in the tip above, or open a terminal in the project directory and run `./mvnw spring-boot:run` (`.\mvnw spring-boot:run` on Windows). The first startup may take a while as Maven and npm download the required dependencies. @@ -88,7 +88,7 @@ Before you continue, verify that your setup matches this list: * The application starts without errors. A log line starting with `Started Application` near the end of the console output confirms that it's running. * Opening http://localhost:8080 shows a "No views found" page. This is expected: the application has no views yet, and you create the first one in the next step. -If the application fails to start, the console output usually names the cause. A compilation error that mentions `org.springframework.data` means a dependency is missing from `pom.xml`. If the SQL files are in the wrong directory, the application still starts, but the view you build in the next step fails with an error about a missing table. +If the application fails to start, the console output usually names the cause. An error such as `release version {vaadin-start-java-version} not supported` means that the build uses an older JDK. Check the JDK of your project in your IDE, or the `JAVA_HOME` environment variable if you run the application from a terminal. A compilation error that mentions `org.springframework.data` means a dependency is missing from `pom.xml`. If the SQL files are in the wrong directory, the application still starts, but the view you build in the next step fails with an error about a missing table. == Next Steps diff --git a/articles/getting-started/tutorial/show-details.adoc b/articles/getting-started/tutorial/show-details.adoc index 6d4b782e7d..915b8d6218 100644 --- a/articles/getting-started/tutorial/show-details.adoc +++ b/articles/getting-started/tutorial/show-details.adoc @@ -583,7 +583,7 @@ class ProductCatalogView extends MasterDetailLayout { <5> Show the drawer in the detail area if there are details to show. Otherwise, remove it, which hides the detail area. <6> When the drawer appears as an overlay, the user can close it by clicking outside it, or by pressing kbd:[Esc]. Both clear the grid selection, which hides the drawer through the selection listener. -The view should now look like this: +Restart the application, since you added an entity and a repository interface. The view should now look like this: [.device] image::images/product-drawer-with-data.png[The product drawer with data] diff --git a/articles/getting-started/tutorial/sort-filter.adoc b/articles/getting-started/tutorial/sort-filter.adoc index 1135e417c3..1ae219bbe3 100644 --- a/articles/getting-started/tutorial/sort-filter.adoc +++ b/articles/getting-started/tutorial/sort-filter.adoc @@ -319,7 +319,7 @@ searchField.addValueChangeListener(e -> grid.getDataProvider().refreshAll()); // ... ---- -If you try the application now, you'll see that typing in the search field filters the products in the grid based on their names. However, the filtering only happens when you press Enter or the field loses focus. To improve the user experience, set the value change mode of the `searchField` to `LAZY`. This triggers value change events a short time after the user stops typing: +Restart the application, since you changed a repository interface. If you try it now, you'll see that typing in the search field filters the products in the grid based on their names. However, the filtering only happens when you press Enter or the field loses focus. To improve the user experience, set the value change mode of the `searchField` to `LAZY`. This triggers value change events a short time after the user stops typing: [source,java] ----