diff --git a/articles/building-apps/ai/quickstart-guide.adoc b/articles/building-apps/ai/quickstart-guide.adoc index e0f70082f3..a5cdb2bccd 100644 --- a/articles/building-apps/ai/quickstart-guide.adoc +++ b/articles/building-apps/ai/quickstart-guide.adoc @@ -4,9 +4,9 @@ page-title: Quick Start-Guide | AI Chatbot with Vaadin description: A compact chat view with streaming, correct scrolling, and message context. meta-description: Hands-on tutorial - connect Vaadin to an LLM with Spring, build a streaming chat UI, and apply simple, reusable patterns for prompts, memory, and UX. order: 20 -section-nav: badge-preview badge-flow +section-nav: badge-preview --- -= [since:com.vaadin:vaadin@V25.1]#Quick Start-Guide: Add an AI Chat Bot to a Vaadin + Spring Boot Application# [badge-flow]#Flow# += [since:com.vaadin:vaadin@V25.1]#Quick Start-Guide: Add an AI Chat Bot to a Vaadin + Spring Boot Application# :preview-feature: AI integration features :feature-flag: com.vaadin.experimental.aiComponents diff --git a/articles/building-apps/ai/technical-setup/ide/index.adoc b/articles/building-apps/ai/technical-setup/ide/index.adoc index 16b0ad1e42..2e3f51f3ac 100644 --- a/articles/building-apps/ai/technical-setup/ide/index.adoc +++ b/articles/building-apps/ai/technical-setup/ide/index.adoc @@ -71,4 +71,4 @@ If you're unsure how to set environment variables in your specific IDE, see: Run the application and check that the model call succeeds. If you see authentication errors, confirm the variable is set in the environment that starts the JVM and that your configuration references `${OPENAI_API_KEY}`. [NOTE] -For Java/IDE requirements and plugins, see <>. +For Java/IDE requirements and plugins, see <>. diff --git a/articles/building-apps/architecture/layers.adoc b/articles/building-apps/architecture/layers.adoc index 99c31c40f9..adf5ce5059 100644 --- a/articles/building-apps/architecture/layers.adoc +++ b/articles/building-apps/architecture/layers.adoc @@ -17,14 +17,14 @@ In traditional web applications, you have the _frontend_ and the _backend_. The [.fill] [link=images/layers.png] -image::images/layers.png[A diagram illustrating the UI layer and application layer of a Flow and a Hilla app, respectively] +image::images/layers.png[A diagram illustrating the UI layer and application layer of a Flow view and a React view, respectively] -When you are building your user interface with Flow, you write the user interface in Java and run it on the server - the backend. Unless you have created any web components of your own, all the code that runs in the browser -- the frontend -- is provided by Vaadin in one way or the other. The frontend and backend don't map directly onto the user interface and business logic. +When you are building your user interface with Flow views, you write the user interface in Java and run it on the server -- the backend. Unless you have created any web components of your own, all the code that runs in the browser -- the frontend -- is provided by Vaadin in one way or the other. The frontend and backend don't map directly onto the user interface and business logic. -When you are building your user interface with Hilla, you write the user interface in React and run it in the browser. The rest of the application runs on the server. In this case, the frontend and backend correspond to the user interface and business logic. +When you are building your user interface with React views, you write the user interface in React and TypeScript, and run it in the browser. The rest of the application runs on the server. In this case, the frontend and backend correspond to the user interface and business logic. -It's also possible to write hybrid applications, where you write some parts of the user interface in Java and other parts in React. In this case, parts of the user interface run in the browser and parts on the server. +An application can also combine the two, with some views written as Flow views and others as React views. In this case, parts of the user interface run in the browser and parts on the server. -Because of this, it makes more sense to talk about the UI layer and the application layer, as opposed to the frontend and the backend, or the user interface and the business logic. It's important to remember that these layers are _conceptual_ rather than physical. In a Flow or hybrid application, the UI layer covers both the browser and a part of the server. In a Hilla application, the UI layer is limited to the browser alone. In all cases, the application layer resides on the server. +Because of this, it makes more sense to talk about the UI layer and the application layer, as opposed to the frontend and the backend, or the user interface and the business logic. It's important to remember that these layers are _conceptual_ rather than physical. For Flow views, the UI layer covers both the browser and a part of the server. For React views, the UI layer is limited to the browser alone. In all cases, the application layer resides on the server. In practice, the UI layer consists of your <<../views#,Flow views>> and, if you have any, your <<../react#,React views>>. The application layer consists of the <<../business-logic/add-service#,application services>> that the views call, and everything behind them. diff --git a/articles/building-apps/business-logic/background-jobs/interaction/callbacks.adoc b/articles/building-apps/business-logic/background-jobs/interaction/callbacks.adoc index 77e6b14f8d..a7e135cf61 100644 --- a/articles/building-apps/business-logic/background-jobs/interaction/callbacks.adoc +++ b/articles/building-apps/business-logic/background-jobs/interaction/callbacks.adoc @@ -4,11 +4,10 @@ page-title: How to use callbacks to interact with your UI | Vaadin description: How to use callbacks to interact with the user interface. meta-description: When using a Flow user interface, the simplest way of allowing background jobs to interact with it is through callbacks. Learn more here. order: 10 -section-nav: badge-flow --- -= Callbacks [badge-flow]#Flow# += Callbacks When using a Flow user interface, the simplest way of allowing background jobs to interact with it is through callbacks. You can use `Consumer`, `Runnable`, and `Supplier` as callback interfaces, depending on how you want to interact with the background job. diff --git a/articles/building-apps/business-logic/background-jobs/interaction/futures.adoc b/articles/building-apps/business-logic/background-jobs/interaction/futures.adoc index bb19b768f6..e00ef12769 100644 --- a/articles/building-apps/business-logic/background-jobs/interaction/futures.adoc +++ b/articles/building-apps/business-logic/background-jobs/interaction/futures.adoc @@ -4,11 +4,10 @@ page-title: How to use CompletableFuture to interact with your app's UI description: How to use CompletableFuture to interact with the user interface. meta-description: Learn to use standard Java `CompletableFuture` with your user interface in your application. order: 20 -section-nav: badge-flow --- -= Returning Futures [badge-flow]#Flow# += Returning Futures When using a Flow user interface, you can use a standard Java `CompletableFuture` to report results and errors to it, and to cancel the job. For reporting progress, however, you still need to use a callback. diff --git a/articles/building-apps/business-logic/background-jobs/interaction/index.adoc b/articles/building-apps/business-logic/background-jobs/interaction/index.adoc index 7a7f527b1e..7917894470 100644 --- a/articles/building-apps/business-logic/background-jobs/interaction/index.adoc +++ b/articles/building-apps/business-logic/background-jobs/interaction/index.adoc @@ -55,6 +55,6 @@ If the job can't report its progress, call `progressBar.setIndeterminate(true)` == Options -The example above is one way of letting the user interface and a background job interact. The following pages cover the different options in more detail: +The example above is one way of letting the user interface and a background job interact. Callbacks and futures work only with Flow views, whereas reactive streams also work with <>. The following pages cover the different options in more detail: section_outline::[] diff --git a/articles/building-apps/business-logic/background-jobs/interaction/reactive.adoc b/articles/building-apps/business-logic/background-jobs/interaction/reactive.adoc index 38362e24e2..5eef624f9c 100644 --- a/articles/building-apps/business-logic/background-jobs/interaction/reactive.adoc +++ b/articles/building-apps/business-logic/background-jobs/interaction/reactive.adoc @@ -9,7 +9,7 @@ order: 30 = Producing Reactive Streams -When using Flow or Hilla to build your user interface, you can use `Flux` or `Mono` from https://projectreactor.io/[Reactor] to allow your background jobs to interact with them. Reactor has an extensive API, which means you can do many things with it. This also means that it can be more difficult to learn than using callbacks or `CompletableFuture`. +You can use `Flux` or `Mono` from https://projectreactor.io/[Reactor] to allow your background jobs to interact with the user interface. Unlike <> and <>, reactive streams work with both Flow views and <>. Reactor has an extensive API, which means you can do many things with it. This also means that it can be more difficult to learn than using callbacks or `CompletableFuture`. This page is about returning the result of a background job to the user who started it. You can also use reactive streams to broadcast updates to all users. That use case is covered in <> and <>. @@ -32,21 +32,21 @@ public Mono startBackgroundJob() { If the `doSomethingThatTakesALongTime()` method throws an exception, the `Mono` terminates with an error. -To update the user interface, you have to subscribe to the `Mono` or `Flux`. For more information about how to do this, see the <> documentation page. +To update the user interface, you have to subscribe to the `Mono` or `Flux`. For more information about how to do this in a Flow view, see the <> documentation page. For React views, see <>. [IMPORTANT] -Hilla only supports `Flux`, so if your job is returning a `Mono`, you have to convert it to a `Flux` inside your `@BrowserCallable` service. You can do this by calling the `Mono.flux()` method. +A React view calls the job through a <>, which can return a `Flux` but not a `Mono`. If your job returns a `Mono`, convert it to a `Flux` inside your `@BrowserCallable` service by calling the `Mono.flux()` method. == Reporting Progress -If your background job only needs to report its progress without actually returning a result, you can return a `Flux`. Your job should then emit progress updates, and complete the stream when done. However, you may often want also to return a result. Since Hilla only supports returning a single `Flux`, you have to use the same stream for emitting both progress updates and the end result. The code may be a bit messy, but it works. +If your background job only needs to report its progress without actually returning a result, you can return a `Flux`. Your job should then emit progress updates, and complete the stream when done. However, you may often want also to return a result. The simplest way to do this, which also works for React views, is to use the same stream for emitting both progress updates and the end result. The code may be a bit messy, but it works. You first need to create a data type that can contain both progress updates and the result. For a job that returns a string, it could look like this: [source,java] ---- -import com.vaadin.hilla.Nullable; +import org.jspecify.annotations.Nullable; public record BackgroundJobOutput( @Nullable Double progressUpdate, @@ -64,9 +64,6 @@ public record BackgroundJobOutput( The two built-in methods, `progressUpdate()` and `finished()` make the code look better when it's time to create instances of `BackgroundJobOutput`. -[NOTE] -If you've worked with sealed classes, you may be tempted to create a sealed interface called `BackgroundJobOutput`, and then create two records that implement that interface: one for progress updates; and another for the result. However, Hilla doesn't support this at the moment. - Next, you have to implement the background job like this: [source,java] diff --git a/articles/building-apps/components/build-component.adoc b/articles/building-apps/components/build-component.adoc index 7afce40c6f..0c6e0d407e 100644 --- a/articles/building-apps/components/build-component.adoc +++ b/articles/building-apps/components/build-component.adoc @@ -55,7 +55,7 @@ Pair it with CSS in your stylesheet: ---- .status-badge { align-items: center; - gap: var(--lumo-space-xs); + gap: var(--vaadin-gap-xs); } .status-badge-indicator { @@ -64,11 +64,13 @@ Pair it with CSS in your stylesheet: border-radius: 50%; } -.status-success { background: var(--lumo-success-color); } -.status-warning { background: var(--lumo-warning-color); } -.status-error { background: var(--lumo-error-color); } +.status-success { background: var(--aura-green); } +.status-warning { background: var(--aura-yellow); } +.status-error { background: var(--aura-red); } ---- +The status colors come from Aura, the default theme. With Lumo, use `--lumo-success-color`, `--lumo-warning-color`, and `--lumo-error-color` instead. See <> for more about choosing properties. + == When to Create a Component diff --git a/articles/building-apps/components/style-component.adoc b/articles/building-apps/components/style-component.adoc index 2f52b46c00..5328c81291 100644 --- a/articles/building-apps/components/style-component.adoc +++ b/articles/building-apps/components/style-component.adoc @@ -9,7 +9,7 @@ order: 20 = Style a Component :toclevels: 2 -This article shows how to add styling to custom components you've built. The focus is on creating maintainable, theme-consistent styles that work in both light and dark mode. For general styling guidance, see <<../ui-basics/add-styling#,Add Styling>>. For the full styling reference, see the <> documentation. +This article shows how to add styling to custom components you've built. The focus is on creating maintainable, theme-consistent styles that work in both light and dark mode. For general styling guidance, see <<../ui-basics/add-styling#,Add Styling>>. For the full styling reference, see the <<{articles}/styling#,Styling>> documentation. == Copy-Paste Example @@ -152,9 +152,27 @@ Vaadin provides three levels of custom properties: | `var(--vaadin-radius-m)` |=== -See <> for the full list. +See <<{articles}/styling/themes/base#,Base Styles>> for the full list. -*Lumo properties* (`--lumo-*`) offer a richer set of properties for applications using the <<{articles}/styling/themes/lumo#,Lumo>> theme: +*Aura properties* (`--aura-*`) are for applications using the <<{articles}/styling/themes/aura#,Aura>> theme, which is the default theme. Aura defines its own color system and maps it to the base properties: + +[cols="1,1",options="header"] +|=== +| Instead of | Use + +| `#1676f3` +| `var(--aura-accent-color)` + +| `14px` +| `var(--aura-font-size-s)` + +| `#d32f2f` +| `var(--aura-red)` +|=== + +See <<{articles}/styling/themes/aura/color#,Aura Color>> and <<{articles}/styling/themes/aura/typography#,Aura Typography>> for the full list. + +*Lumo properties* (`--lumo-*`) are for applications using the <<{articles}/styling/themes/lumo#,Lumo>> theme: [cols="1,1",options="header"] |=== @@ -166,13 +184,11 @@ See <> for the full list. | `14px` | `var(--lumo-font-size-s)` -| `#333` -| `var(--lumo-body-text-color)` +| `#d32f2f` +| `var(--lumo-error-color)` |=== -See <> for the full list. - -*Aura properties* (`--aura-*`) are for applications using the <<{articles}/styling/themes/aura#,Aura>> theme, which defines its own color system and maps it to the base properties. +See <<{articles}/styling/themes/lumo/lumo-style-properties#,Lumo Style Properties>> for the full list. [TIP] .Choosing the Right Properties @@ -248,7 +264,7 @@ Prefix custom property names with the component name to avoid clashes. == Pitfalls -*Use theme properties, not hardcoded values.* Hardcoded colors, sizes, and fonts break theme consistency and don't adapt to dark mode. Use `--vaadin-*` base properties for theme-agnostic components, or `--lumo-*` / `--aura-*` properties if you target a specific theme. +*Use theme properties, not hardcoded values.* Hardcoded colors, sizes, and fonts break theme consistency and don't adapt to dark mode. Use `--vaadin-*` base properties for theme-agnostic components, or `--aura-*` / `--lumo-*` properties if you target a specific theme. *Use semantic class names.* Name classes after what the element represents, not its appearance. `notification-banner` is better than `yellow-box` — the color might change, but the purpose won't. diff --git a/articles/building-apps/forms-data/add-form/index.adoc b/articles/building-apps/forms-data/add-form/index.adoc index 029d34b82d..3dbb0f9054 100644 --- a/articles/building-apps/forms-data/add-form/index.adoc +++ b/articles/building-apps/forms-data/add-form/index.adoc @@ -15,4 +15,6 @@ In business applications, forms play a central role in *displaying and collectin Vaadin offers a range of components and utilities to simplify form building. However, because forms and data binding cover a broad area, the topic is divided into several focused guides. Each one covers a specific aspect of form development. +The guides use Flow views. For forms in React views, see the <> reference guide. + section_outline::[] diff --git a/articles/building-apps/forms-data/add-form/validation.adoc b/articles/building-apps/forms-data/add-form/validation.adoc index 4cda9e2681..0e76cf8ea2 100644 --- a/articles/building-apps/forms-data/add-form/validation.adoc +++ b/articles/building-apps/forms-data/add-form/validation.adoc @@ -275,9 +275,20 @@ For `Binder`-level validation errors, which do not belong to a specific field, y [source,java] ---- var beanValidationErrors = new Div(); -beanValidationErrors.addClassName(LumoUtility.TextColor.ERROR); +beanValidationErrors.addClassName("form-errors"); binder.setStatusLabel(beanValidationErrors); ---- +Then give the status label an error color in your stylesheet: + +[source,css] +---- +.form-errors { + color: var(--aura-red-text); +} +---- + +The color comes from Aura, the default theme. With Lumo, use `var(--lumo-error-text-color)` instead. + This ensures that validation messages are displayed appropriately, whenever they originate from `Binding`-level validation or `Binder`-level validation. diff --git a/articles/building-apps/forms-data/add-grid/index.adoc b/articles/building-apps/forms-data/add-grid/index.adoc index 0272d9f3ba..d66e6df22d 100644 --- a/articles/building-apps/forms-data/add-grid/index.adoc +++ b/articles/building-apps/forms-data/add-grid/index.adoc @@ -23,3 +23,5 @@ You can use the Grid component with all these data types, but the implementation section_outline::[] For detailed information about binding data sets to UI components in Vaadin, see the <> reference guide. + +The guides use Flow views. For grids in React views, see the <> reference guide. diff --git a/articles/building-apps/forms-data/consistency/domain-primitives.adoc b/articles/building-apps/forms-data/consistency/domain-primitives.adoc index d86c34e215..1a99202065 100644 --- a/articles/building-apps/forms-data/consistency/domain-primitives.adoc +++ b/articles/building-apps/forms-data/consistency/domain-primitives.adoc @@ -89,7 +89,7 @@ A domain primitive is a Java class that has some specific qualities. First, it's Second, it wraps one or more objects of other types. For example, a `Quantity` domain primitive could wrap an integer; a `Username` domain primitive could wrap a string. Domain primitives can wrap more than one object, and can also wrap other domain primitives. To represent a monetary amount, you need both the currency and the numeric amount. You may end up with a `CurrencyUnit` domain primitive, and also a `MonetaryAmount` domain primitive that wraps a `BigDecimal` and a `CurrencyUnit`. -Third, a domain primitive validates all of its input data in the constructor. Because it's also immutable, this means that it's guaranteed always to be valid. For more information about validation, see the <> documentation page. +Third, a domain primitive validates all of its input data in the constructor. Because it's also immutable, this means that it's guaranteed always to be valid. For more information about validation, see the <<{articles}/building-apps/forms-data/consistency/validation#,Validation>> documentation page. Here's how the quantity domain primitive from the example above could look: @@ -229,7 +229,7 @@ public final class Discount { Whenever you fetch the wrapped value from a domain primitive, you should ask why you need that value. Unless you need it for displaying or formatting, you should probably instead add a new method to the domain primitive. -== Usage in Flow +== Usage in Flow Views To use a single-value domain primitive in a Vaadin Flow user interface, you have to create a custom `Converter` for it. Because conversion errors are treated as validation errors by the `Binder`, there's no need to create a separate `Validator` to validate the input. For example, the converter of an `EmailAddress` domain primitive could look like this: @@ -347,9 +347,9 @@ public class MonetaryAmountField extends CustomField { For more information about creating custom fields, see <<{articles}/components/custom-field#,Custom Field>>. -== Usage in Hilla +== Usage in React Views -To use domain primitives in Hilla, you have to make sure that they can be serialized to and from JSON using https://github.com/FasterXML/jackson-databind[Jackson]. For single-value domain primitives, this involves adding `@JsonValue` and `@JsonCreator` annotations, like this: +To use domain primitives in <<{articles}/building-apps/react#,React views>>, you have to make sure that they can be serialized to and from JSON using https://github.com/FasterXML/jackson-databind[Jackson]. For single-value domain primitives, this involves adding `@JsonValue` and `@JsonCreator` annotations, like this: [source,java] ---- @@ -372,4 +372,4 @@ If you now use the `Quantity` domain primitive in a <<{articles}/hilla/guides/br Multi-value domain primitives are converted into their own TypeScript types, as long as they meet the requirements of <<{articles}/hilla/guides/browser-callable-services#objects,browser-callable service objects>>. -The input is validated on the server side by the domain primitive constructors, during JSON deserialization. However, an `IllegalArgumentException` thrown here becomes a `400 Bad Request` on the client side. Hilla is able to deduce that this is a validation error, but not from which field. Your system remains safe from bad data, but the user experience is not good. To improve it, you have to <<{articles}/hilla/guides/forms/binder-validation#defining-custom-client-side-validators,define custom client-side validators>> on your fields. +The input is validated on the server side by the domain primitive constructors, during JSON deserialization. However, an `IllegalArgumentException` thrown here becomes a `400 Bad Request` on the client side. The client is able to deduce that this is a validation error, but not from which field. Your system remains safe from bad data, but the user experience is not good. To improve it, you have to <<{articles}/hilla/guides/forms/binder-validation#defining-custom-client-side-validators,define custom client-side validators>> on your fields. diff --git a/articles/building-apps/forms-data/consistency/validation.adoc b/articles/building-apps/forms-data/consistency/validation.adoc index 345ae38cde..5621d2e8a1 100644 --- a/articles/building-apps/forms-data/consistency/validation.adoc +++ b/articles/building-apps/forms-data/consistency/validation.adoc @@ -13,7 +13,7 @@ An important part of data consistency and integrity is to make sure no bad data In a Vaadin application, data is typically validated both in the UI layer and in the application layer. Validation in the user interface is primarily about providing a good user experience, and preventing the user from entering bad data in the first place. However, although validation can happen in the browser, you should never trust it to be correct. -The most important validation takes place at the application layer boundary. This is typically inside an <>, but it could also be in some other system component that communicates with an external system. +The most important validation takes place at the application layer boundary. This is typically inside an <<{articles}/building-apps/business-logic/add-service#,application service>>, but it could also be in some other system component that communicates with an external system. In a Vaadin application, you would typically implement application-layer validation in two ways: by using Jakarta Bean Validation; or with domain primitives. Incidentally, you can use both at the same time. @@ -98,7 +98,7 @@ public class UserService { } ---- -Bean Validation annotations have the added benefit of being supported by both Flow and Hilla, for use in user interface validation. For more information about this, see the relevant <<{articles}/flow/binding-data/components-binder-beans#using-jsr-303-bean-validation,Flow>> and <<{articles}/hilla/guides/forms/binder-validation#,Hilla>> documentation pages. +Bean Validation annotations have the added benefit of being supported by both Flow views and React views, for use in user interface validation. For more information about this, see the relevant <<{articles}/flow/binding-data/components-binder-beans#using-jsr-303-bean-validation,Flow>> and <<{articles}/hilla/guides/forms/binder-validation#,React>> documentation pages. For more information about Jakarta Bean Validation, visit the https://beanvalidation.org/[Bean Validation website]. For more information about using Bean Validation in Spring, see the https://docs.spring.io/spring-framework/reference/core/validation/beanvalidation.html[Spring documentation]. diff --git a/articles/building-apps/forms-data/create-custom-field/index.adoc b/articles/building-apps/forms-data/create-custom-field/index.adoc index bf6111f104..6fdf243325 100644 --- a/articles/building-apps/forms-data/create-custom-field/index.adoc +++ b/articles/building-apps/forms-data/create-custom-field/index.adoc @@ -697,7 +697,7 @@ The field also supports localization and follows accessibility best practices. === Step 1: Set Up the Project -First, generate a new application at http://start.vaadin.com[start.vaadin.com], <> it in your IDE, and <> it with hotswap enabled. +First, generate a new application at http://start.vaadin.com[start.vaadin.com], <<{articles}/getting-started/dev-environment/import#,open>> it in your IDE, and <<{articles}/getting-started/dev-environment/run#,run>> it with hotswap enabled. === Step 2: Basic Setup diff --git a/articles/building-apps/forms-data/index.adoc b/articles/building-apps/forms-data/index.adoc index cb8a26d050..2cb61d7554 100644 --- a/articles/building-apps/forms-data/index.adoc +++ b/articles/building-apps/forms-data/index.adoc @@ -11,7 +11,7 @@ order: 20 Most business applications revolve around data. Users look it up in grids, edit it in forms, and expect their changes to be saved. These guides show how to do this in a Vaadin application. -For the user interface, start with <> and <>. To store the data, see <>, and <> for switching to a production database. The other guides cover custom fields, file uploads and downloads, and PDF reports. +For the user interface, start with <> and <>. To store the data, see <>, and <> for switching to a production database. The other guides cover custom fields, file uploads and downloads, and PDF reports. The forms and grids load and save data through <<../business-logic/add-service#,application services>>. The <> deep dive explains the reasoning behind this, and covers transactions, locking, and validation. diff --git a/articles/building-apps/forms-data/persistence/index.adoc b/articles/building-apps/forms-data/persistence/index.adoc index 814b04f208..86327e9f02 100644 --- a/articles/building-apps/forms-data/persistence/index.adoc +++ b/articles/building-apps/forms-data/persistence/index.adoc @@ -3,7 +3,7 @@ title: Persistence page-title: Persistence patterns and approaches | Vaadin description: How to choose and combine persistence strategies in Vaadin applications. meta-description: Learn how to persist data in Vaadin applications using JPA, jOOQ, and other technologies. Understand when to use aggregate-oriented vs table-oriented approaches. -order: 10 +order: 20 --- @@ -14,7 +14,7 @@ Most Vaadin applications need to store and retrieve data from a database. How yo This section covers the main approaches to persistence and helps you choose between them—or combine them, which is what most real applications end up doing. -If you're starting a new project, you'll also need to set up <> and add your chosen persistence technology (<>, <>, or both). +If you're starting a new project, you'll also need to set up <>, <> with your production database, and add your chosen persistence technology (<>, <>, or both). == Two Approaches diff --git a/articles/building-apps/forms-data/replace-h2.adoc b/articles/building-apps/forms-data/persistence/replace-h2.adoc similarity index 98% rename from articles/building-apps/forms-data/replace-h2.adoc rename to articles/building-apps/forms-data/persistence/replace-h2.adoc index b600c29409..e1d86616d3 100644 --- a/articles/building-apps/forms-data/replace-h2.adoc +++ b/articles/building-apps/forms-data/persistence/replace-h2.adoc @@ -3,7 +3,7 @@ title: Replace H2 page-title: How to replace H2 with PostgreSQL | Vaadin description: Learn how to replace the H2 database with PostgreSQL. meta-description: Learn how to replace the H2 database with PostgreSQL in your Vaadin application, using Testcontainers and proper configuration for development and testing. -order: 40 +order: 7 --- @@ -28,7 +28,7 @@ Start by removing the H2 dependency from your Maven `pom.xml`, and replace it wi ---- -If you are using <> -- which you should at this point -- you also need to add the correct Flyway database dependency: +If you are using <> -- which you should at this point -- you also need to add the correct Flyway database dependency: [source,xml] ---- diff --git a/articles/building-apps/index.adoc b/articles/building-apps/index.adoc index e3323c5896..4edb3b2425 100644 --- a/articles/building-apps/index.adoc +++ b/articles/building-apps/index.adoc @@ -14,6 +14,8 @@ Vaadin is a powerful framework for building real-world business applications. Li Business applications often start small and evolve over time. While you can figure things out as you go, having a clear roadmap from the start makes the journey smoother. This section of the documentation introduces a structured, opinionated approach to building business applications with Vaadin. +The guides build the user interface with server-side Flow views, written in Java, unless they say otherwise. To add client-side views written in React, see <>. + This section is divided into two main types of articles: * *How-to Guides* -- Practical, step-by-step instructions for adding features and implementing common tasks. diff --git a/articles/building-apps/react/add-view.adoc b/articles/building-apps/react/add-view.adoc index 2a39ab7e58..788acf658d 100644 --- a/articles/building-apps/react/add-view.adoc +++ b/articles/building-apps/react/add-view.adoc @@ -1,6 +1,7 @@ --- title: Add a React View page-title: How to add a React view to a Vaadin application +description: Create React views, see how their routes are determined from the file system, and organize them into directories. meta-description: Learn to create, name, and organize React views in a Vaadin application - file-based routing conventions, directory structures, route aliases, and explicit routes. order: 10 --- diff --git a/articles/building-apps/react/call-services.adoc b/articles/building-apps/react/call-services.adoc index 52f7d8ccef..4c4c6855a4 100644 --- a/articles/building-apps/react/call-services.adoc +++ b/articles/building-apps/react/call-services.adoc @@ -1,6 +1,7 @@ --- title: Call Java Services page-title: How to call Java services from a React view in Vaadin +description: Make a Java service browser-callable and call it from a React view through a generated TypeScript client. meta-description: Make a Java service browser-callable and call it from a React view in Vaadin in a type-safe way, with automatically generated TypeScript clients. order: 30 --- @@ -135,7 +136,7 @@ public class TimeService { <2> Drop values that can't be sent to the client in time. <3> Output the current date and time as a string. -For how to produce reactive streams on the server, including from background jobs, see <>. +For how to produce reactive streams on the server, including from background jobs, see <<{articles}/building-apps/business-logic/background-jobs/interaction/reactive#,Producing Reactive Streams>>. === Subscribing from a View diff --git a/articles/building-apps/react/index.adoc b/articles/building-apps/react/index.adoc index a96fa9caef..761f4f637b 100644 --- a/articles/building-apps/react/index.adoc +++ b/articles/building-apps/react/index.adoc @@ -30,7 +30,7 @@ If none of these apply, prefer a Flow view. Mixing client-side and server-side v .Wrapping a React Component Is Different [TIP] -This section is about adding React *views* (pages with their own route) to your application. If instead you want to use an individual React *component* inside a Flow view -- for example a third-party chart or color picker -- you don't need a React view. See <> instead. +This section is about adding React *views* (pages with their own route) to your application. If instead you want to use an individual React *component* inside a Flow view -- for example a third-party chart or color picker -- you don't need a React view. See <<{articles}/building-apps/components/wrap-react-component#,Wrap a React Component>> instead. == How React Views Fit In diff --git a/articles/building-apps/server-push/callbacks.adoc b/articles/building-apps/server-push/callbacks.adoc index 9afdda6427..8c4df29a50 100644 --- a/articles/building-apps/server-push/callbacks.adoc +++ b/articles/building-apps/server-push/callbacks.adoc @@ -9,12 +9,12 @@ order: 20 = Implementing Callbacks -When building the user interface with Vaadin Flow, the easiest way of allowing a background job to update the user interface is through callbacks. This is explained in more detail in the <> documentation page. +When building the user interface with Vaadin Flow, the easiest way of allowing a background job to update the user interface is through callbacks. This is explained in more detail in the <<{articles}/building-apps/business-logic/background-jobs/interaction/callbacks#,Callbacks>> documentation page. Whenever you implement a callback, remember that the callback is called by the background thread. This means that any updates to the user interface must happen inside a call to `UI.access()`. [NOTE] -The examples on this page only work with push enabled. For information about how to do that, see the <> documentation page. +The examples on this page only work with push enabled. For information about how to do that, see the <> documentation page. For every callback, you should create a private method in your user interface. The method is called inside `UI.access()`, so you can safely update the user interface inside it. @@ -54,4 +54,4 @@ button.addClickListener(clickEvent -> { <1> The `UI.accessLater()` method is explained on the <> documentation page. [TIP] -When a callback only updates UI _state_ — such as a progress value or a status message — you can update a <> from the callback instead of wrapping it in `UI.accessLater()`, and bind the component to that signal. See <>. +When a callback only updates UI _state_ — such as a progress value or a status message — you can update a <<{articles}/flow/ui-state#,signal>> from the callback instead of wrapping it in `UI.accessLater()`, and bind the component to that signal. See <>. diff --git a/articles/building-apps/server-push/futures.adoc b/articles/building-apps/server-push/futures.adoc index 33c5141283..a0250815dd 100644 --- a/articles/building-apps/server-push/futures.adoc +++ b/articles/building-apps/server-push/futures.adoc @@ -23,7 +23,7 @@ private void onJobCompleted(String result) { ---- [NOTE] -The examples on this page only work with push enabled (see <>). +The examples on this page only work with push enabled (see <>). A method for handling errors might look like this: diff --git a/articles/building-apps/server-push/index.adoc b/articles/building-apps/server-push/index.adoc index 92111f883e..4934d5d6ba 100644 --- a/articles/building-apps/server-push/index.adoc +++ b/articles/building-apps/server-push/index.adoc @@ -13,7 +13,7 @@ Server push is based on a client-server connection established by the client. Th The server-client communication uses a WebSocket connection, if supported by the browser and the server. If not, the connection resorts to whatever method is supported. Vaadin uses the link:https://github.com/Atmosphere/atmosphere[Atmosphere framework], internally. -In Hilla views, push is always enabled when you subscribe to a _reactive service_. For Flow views, you have to enable it, explicitly. +For Flow views, you have to enable push explicitly. In <<{articles}/building-apps/react#,React views>>, push is always enabled when you subscribe to a <<{articles}/hilla/guides/reactive-services#,reactive service>>. [IMPORTANT] Server push is not the same as Web Push, which is also supported by Vaadin Flow. For more information, see the <<{articles}/flow/configuration/webpush#,Web Push Notifications>> documentation page. @@ -52,7 +52,7 @@ You can also configure Flow to use manual pushing (`PushMode.MANUAL`). With manu For details on how to use `UI.access()` and `UI.push()`, see <>. -For state-driven updates, you usually don't need `UI.access()` at all: bind components to <> and update the signals from any thread, and Flow pushes the changes automatically. See <>. +For state-driven updates, you usually don't need `UI.access()` at all: bind components to <<{articles}/flow/ui-state#,signals>> and update the signals from any thread, and Flow pushes the changes automatically. See <>. == Transport Options diff --git a/articles/building-apps/server-push/reactive.adoc b/articles/building-apps/server-push/reactive.adoc index dd0c9ad3e6..d5eb21f97e 100644 --- a/articles/building-apps/server-push/reactive.adoc +++ b/articles/building-apps/server-push/reactive.adoc @@ -1,6 +1,8 @@ --- title: Consuming Reactive Streams +page-title: How to use server push with reactive streams | Vaadin description: How to use server push with reactive streams. +meta-description: Learn how to subscribe to Flux and Mono reactive streams in a Vaadin Flow user interface, handle errors, and buffer high-frequency updates with server push. order: 40 --- diff --git a/articles/building-apps/server-push/threads.adoc b/articles/building-apps/server-push/threads.adoc index eb5a4b8ca5..f390450109 100644 --- a/articles/building-apps/server-push/threads.adoc +++ b/articles/building-apps/server-push/threads.adoc @@ -2,7 +2,7 @@ title: Threads page-title: How to use threads in a Vaadin Flow user interface description: How to use threads in a Vaadin Flow user interface. -meta-description: Learn how to use use virtual threads in a Vaadin Flow user interface by reading this guide. +meta-description: Learn how to use virtual threads in a Vaadin Flow user interface by reading this guide. order: 10 --- @@ -16,7 +16,7 @@ If you have experience with Swing, you might be tempted to use a `Timer`, or to As a better strategy, use virtual threads, or Spring's `TaskExecutor` and `TaskScheduler`. These are explained in the following sections, with some examples. [NOTE] -The examples on this page only work with push enabled. For information about how to do that, see the <> documentation page. +The examples on this page only work with push enabled. For information about how to do that, see the <> documentation page. == Virtual Threads diff --git a/articles/building-apps/server-push/updates.adoc b/articles/building-apps/server-push/updates.adoc index 34daeff7f1..e5f7fff42c 100644 --- a/articles/building-apps/server-push/updates.adoc +++ b/articles/building-apps/server-push/updates.adoc @@ -15,16 +15,16 @@ Such errors are by nature hard to discover and fix, since they often occur rando There are two ways to push these updates: -* For *state-driven* updates, use <>. Signals are thread-safe and update any bound components automatically, so you don't have to lock the session yourself. This is the recommended approach for most cases, and the one this page leads with. +* For *state-driven* updates, use <<{articles}/flow/ui-state#,signals>>. Signals are thread-safe and update any bound components automatically, so you don't have to lock the session yourself. This is the recommended approach for most cases, and the one this page leads with. * For *imperative* updates — such as adding or removing components, or calling component methods that aren't expressed as state — lock the session manually with the `UI.access()` method. Understanding `UI.access()` also helps you understand what signals do for you under the hood. [NOTE] -The examples on this page only work with push enabled. This applies to signal-driven updates as well: when a signal is changed from a background thread, push is what delivers the change to the browser. For information about how to enable push, see the <> documentation page. +The examples on this page only work with push enabled. This applies to signal-driven updates as well: when a signal is changed from a background thread, push is what delivers the change to the browser. For information about how to enable push, see the <> documentation page. == Pushing State with Signals -A <> holds a piece of UI state. When you bind a component to a signal, the component updates itself whenever the signal's value changes — no matter which thread made the change. Signals are thread-safe and synchronize with the UI internally, so you don't need to call `UI.access()`, and you don't need to capture the `UI` instance in advance. +A <<{articles}/flow/ui-state#,signal>> holds a piece of UI state. When you bind a component to a signal, the component updates itself whenever the signal's value changes — no matter which thread made the change. Signals are thread-safe and synchronize with the UI internally, so you don't need to call `UI.access()`, and you don't need to capture the `UI` instance in advance. Just as importantly, bindings are tied to the component lifecycle: a binding is active only while the component is attached, and it's removed automatically when the component is detached. This means there's no listener to unsubscribe and no `UI` reference left dangling, so the whole class of memory leaks described later on this page doesn't arise. @@ -55,7 +55,7 @@ public class JobView extends VerticalLayout { === Broadcasting to All Users -For state that several users share, put a <> in a Spring bean and let the view bind to it. A singleton bean shares one signal instance across the whole application, so a change made by one user — or by a background thread — is pushed to every connected user that's bound to it: +For state that several users share, put a <<{articles}/flow/ui-state#,shared signal>> in a Spring bean and let the view bind to it. A singleton bean shares one signal instance across the whole application, so a change made by one user — or by a background thread — is pushed to every connected user that's bound to it: [source,java] ---- @@ -102,7 +102,7 @@ public class ChatView extends VerticalLayout { When any user calls `post()`, every open `ChatView` receives the new message. Compare this with the manual approach described in <<#avoiding-memory-leaks,Avoiding Memory Leaks>> below: there's no event bus to subscribe to, no `UI.access()`, and no detach handler to unsubscribe. The signal lives in the bean, so its lifetime is the bean's lifetime, and each view's binding is cleaned up automatically on detach. [NOTE] -Use a `@Component` singleton for application-wide state, or a `@VaadinSessionScope` bean for state shared between the tabs of a single user. For more on scoping signals, see <>. +Use a `@Component` singleton for application-wide state, or a `@VaadinSessionScope` bean for state shared between the tabs of a single user. For more on scoping signals, see <<{articles}/flow/ui-state/shared-signals#signal-scope-patterns,Signal Scope Patterns>>. .Running Several Application Instances [IMPORTANT] @@ -123,7 +123,7 @@ price.bindText(priceSignal.map(p -> "$" + p)) } }); ---- -<1> [methodname]`isBackgroundChange()` returns `true` when the change came from another session or a background thread. See <> for details. +<1> [methodname]`isBackgroundChange()` returns `true` when the change came from another session or a background thread. See <<{articles}/flow/ui-state/effects-computed#,Effects and Computed Signals>> for details. == Pushing Manually With UI.access() diff --git a/articles/building-apps/ui-basics/add-drag-and-drop.adoc b/articles/building-apps/ui-basics/add-drag-and-drop.adoc index ac03fd6379..15bb8fc363 100644 --- a/articles/building-apps/ui-basics/add-drag-and-drop.adoc +++ b/articles/building-apps/ui-basics/add-drag-and-drop.adoc @@ -9,7 +9,7 @@ order: 35 = Add Drag and Drop :toclevels: 2 -Vaadin lets you make any component draggable and any component a drop target. The user grabs a component with the mouse, drags it, and drops it onto another component — triggering server-side logic to move, copy, or associate items. This article covers the basics: making a component draggable, creating a drop target, and handling the drop event. For the full API including drag data, effects, drag images, and browser-specific behavior, see the <> reference documentation. +Vaadin lets you make any component draggable and any component a drop target. The user grabs a component with the mouse, drags it, and drops it onto another component — triggering server-side logic to move, copy, or associate items. This article covers the basics: making a component draggable, creating a drop target, and handling the drop event. For the full API including drag data, effects, drag images, and browser-specific behavior, see the <<{articles}/flow/component-internals/dnd#,Drag & Drop>> reference documentation. == Copy-Paste into Your Project @@ -189,4 +189,4 @@ This article covers the fundamentals, but Vaadin's drag-and-drop API offers more - *Drag start and end events* — react when dragging begins or ends, for example to highlight valid drop targets - *Grid row drag and drop* — `Grid` and `TreeGrid` have built-in support for <<{articles}/components/grid/drag-drop#,dragging and dropping rows>> -See the <> reference for details on these features. +See the <<{articles}/flow/component-internals/dnd#,Drag & Drop>> reference for details on these features. diff --git a/articles/building-apps/ui-basics/add-styling.adoc b/articles/building-apps/ui-basics/add-styling.adoc index 91c11952f5..12fdec85e2 100644 --- a/articles/building-apps/ui-basics/add-styling.adoc +++ b/articles/building-apps/ui-basics/add-styling.adoc @@ -9,7 +9,7 @@ order: 25 = Add Styling :toclevels: 2 -Vaadin gives you several ways to style components and elements. This article covers the three most common: theme variants and inline styles, which are pure Java — no CSS needed — and CSS class names, which give you full control through a stylesheet. The examples use the <<{articles}/styling/themes/lumo#,Lumo>> theme, but the techniques work the same way with <<{articles}/styling/themes/aura#,Aura>>. For utility classes, component style properties, and other advanced techniques, see the <<{articles}/styling#,Styling>> documentation. +Vaadin gives you several ways to style components and elements. This article covers the three most common: theme variants and inline styles, which are pure Java — no CSS needed — and CSS class names, which give you full control through a stylesheet. Wherever possible, the examples use the `--vaadin-*` <<{articles}/styling/themes/base#,base style properties>>, which work with both the <<{articles}/styling/themes/aura#,Aura>> and the <<{articles}/styling/themes/lumo#,Lumo>> theme. For utility classes, component style properties, and other advanced techniques, see the <<{articles}/styling#,Styling>> documentation. == Copy-Paste into Your Project @@ -33,18 +33,17 @@ public class StylingExampleView extends VerticalLayout { saveButton.addThemeVariants(ButtonVariant.PRIMARY); // 2. Inline style — one-off styling (pure Java) - Div accent = new Div("Accent bar"); - accent.getStyle() - .setBackground("var(--lumo-primary-color)") - .setColor("white") - .setPadding("var(--lumo-space-s) var(--lumo-space-m)") - .setBorderRadius("8px"); + Div highlight = new Div("Highlighted text"); + highlight.getStyle() + .setBackground("var(--vaadin-background-container-strong)") + .setPadding("var(--vaadin-padding-s) var(--vaadin-padding-m)") + .setBorderRadius("var(--vaadin-radius-m)"); // 3. CSS class name — styled via styles.css (requires CSS) Div banner = new Div("Welcome back!"); banner.addClassName("info-banner"); - add(saveButton, accent, banner); + add(saveButton, highlight, banner); } } ---- @@ -54,9 +53,9 @@ Add the following CSS to your `styles.css` file for the `.info-banner` class use [source,css] ---- .info-banner { - background: var(--lumo-contrast-5pct); - padding: var(--lumo-space-m); - border-radius: var(--lumo-border-radius-m); + background: var(--vaadin-background-container); + padding: var(--vaadin-padding-m); + border-radius: var(--vaadin-radius-m); } ---- @@ -98,12 +97,12 @@ Common CSS properties have dedicated methods, and you can use the generic `set() Div header = new Div("Dashboard"); header.getStyle() .setFontWeight(Style.FontWeight.BOLD) - .setBackground("var(--lumo-primary-color)") - .setColor("var(--lumo-primary-contrast-color)") - .set("border-radius", "var(--lumo-border-radius-m)"); + .setBackground("var(--vaadin-background-container)") + .setColor("var(--vaadin-text-color)") + .set("border-radius", "var(--vaadin-radius-m)"); ---- -Values like `var(--lumo-primary-color)` are theme custom properties — named values defined by the theme for colors, spacing, typography, and other styles. Both the <<{articles}/styling/themes/lumo/lumo-style-properties#,Lumo>> and <<{articles}/styling/themes/aura#,Aura>> themes provide them. Using custom properties instead of hardcoded values keeps your styles consistent and makes them adapt to dark mode automatically. +Values like `var(--vaadin-radius-m)` are style properties — CSS custom properties that hold named values for colors, spacing, and other styles. The `--vaadin-*` <<{articles}/styling/themes/base#,base style properties>> work with any theme. The <<{articles}/styling/themes/aura#,Aura>> and <<{articles}/styling/themes/lumo/lumo-style-properties#,Lumo>> themes add their own `--aura-*` and `--lumo-*` properties, for example for accent colors and font sizes, but these only work with the theme that defines them. Using style properties instead of hardcoded values keeps your styles consistent and makes them adapt to dark mode automatically. [NOTE] ==== @@ -134,24 +133,24 @@ Then write the matching CSS rules in your <<{articles}/styling/stylesheets#,styl [source,css] ---- .product-card { - background: var(--lumo-base-color); - border: 1px solid var(--lumo-contrast-10pct); - border-radius: var(--lumo-border-radius-l); - padding: var(--lumo-space-m); + background: var(--vaadin-background-color); + border: 1px solid var(--vaadin-border-color-secondary); + border-radius: var(--vaadin-radius-l); + padding: var(--vaadin-padding-m); } .status-label { - font-size: var(--lumo-font-size-s); - border-radius: var(--lumo-border-radius-s); - padding: var(--lumo-space-xs) var(--lumo-space-s); + border-radius: var(--vaadin-radius-s); + padding: var(--vaadin-padding-xs) var(--vaadin-padding-s); } .status-urgent { - background: var(--lumo-error-color-10pct); - color: var(--lumo-error-text-color); + color: var(--aura-red-text); } ---- +The base style properties don't include semantic colors, such as a color for errors, so the `.status-urgent` rule uses a color from Aura, the default theme. With Lumo, use `var(--lumo-error-text-color)` instead. + [TIP] Use semantic class names that describe what the element *is*, not how it looks. Prefer `status-urgent` over `red-text` — the visual style can change, but the meaning stays. @@ -172,9 +171,9 @@ The <<{articles}/styling#,Styling>> reference covers more advanced techniques wh This article covers the core styling approaches, but Vaadin's styling system offers more: -- *Utility classes* — apply styles from Java using `LumoUtility` constants, or use <<{articles}/styling/utility-classes#tailwind,Tailwind CSS>>. A Java-only alternative to writing CSS classes. +- *Utility classes* — apply styles from Java using <<{articles}/styling/utility-classes#tailwind,Tailwind CSS>> class names, or `LumoUtility` constants if you use the Lumo theme. A Java-only alternative to writing CSS classes. - *Component style properties* — customize component appearance with `--vaadin-*` properties without writing complex CSS selectors -- *Theme properties* — change the look of your entire application with `--lumo-*` or `--aura-*` properties +- *Theme properties* — change the look of your entire application with `--aura-*` or `--lumo-*` properties - *Styling component internals* — target internal elements with `::part()` selectors for deep customization - *Lazy-loading and scoping stylesheets* — control when and where stylesheets are loaded diff --git a/articles/building-apps/ui-basics/layouts/index.adoc b/articles/building-apps/ui-basics/layouts/index.adoc index 90012a2f55..d6a0596571 100644 --- a/articles/building-apps/ui-basics/layouts/index.adoc +++ b/articles/building-apps/ui-basics/layouts/index.adoc @@ -198,7 +198,7 @@ layout.setFlexShrink(0, fixedSizeComponent); .Experimental: the layoutComponentImprovements feature flag [NOTE] -Vaadin includes an experimental `layoutComponentImprovements` <> that makes `setWidthFull()` / `setHeightFull()` / `setSizeFull()` apply `flex: 1` instead of a literal percentage, avoiding the shrinking trap. It's *off by default* -- don't assume the behavior unless it's been enabled. +Vaadin includes an experimental `layoutComponentImprovements` <> that makes `setWidthFull()` / `setHeightFull()` / `setSizeFull()` apply `flex: 1` instead of a literal percentage, avoiding the shrinking trap. It's *off by default* -- don't assume the behavior unless it's been enabled. [#overflow-and-scrolling] diff --git a/articles/building-apps/views/add-view.adoc b/articles/building-apps/views/add-view.adoc index 3d34cba3f5..d392bf13c7 100644 --- a/articles/building-apps/views/add-view.adoc +++ b/articles/building-apps/views/add-view.adoc @@ -86,7 +86,7 @@ Navigation between views is covered in more detail in the <> architecture deep-dive. +For information about package structures for Vaadin applications, see the <<{articles}/building-apps/architecture/packages#,Package Structure>> architecture deep-dive. == View Naming diff --git a/articles/building-apps/views/pass-data/route-templates.adoc b/articles/building-apps/views/pass-data/route-templates.adoc index e734911fe7..b4c02745a4 100644 --- a/articles/building-apps/views/pass-data/route-templates.adoc +++ b/articles/building-apps/views/pass-data/route-templates.adoc @@ -10,7 +10,7 @@ order: 20 = Route Templates :toclevels: 2 -In this guide, you'll learn how to create a view that accepts multiple route parameters using route templates, and how to read those parameters reactively with a <>. You'll also learn how to use modifiers and regular expressions to tweak the behavior of the route parameters. +In this guide, you'll learn how to create a view that accepts multiple route parameters using route templates, and how to read those parameters reactively with a <<{articles}/flow/ui-state#,signal>>. You'll also learn how to use modifiers and regular expressions to tweak the behavior of the route parameters. Using a single <> is easier than using a route template. If you can get the job done using the [interfacename]`HasUrlParameter` interface, use that instead. @@ -53,7 +53,7 @@ Now, if you navigate to `/customer/cu12345/edit`, the router renders the [classn == Accessing Route Parameter Values -The current route parameters are available as a <>. Calling [methodname]`UI.getCurrentOrThrow().routerStateSignal()` returns a read-only signal whose value is a [classname]`RouterState` record; its [methodname]`routeParameters()` method gives you the [classname]`RouteParameters` for the active navigation. +The current route parameters are available as a <<{articles}/flow/ui-state#,signal>>. Calling [methodname]`UI.getCurrentOrThrow().routerStateSignal()` returns a read-only signal whose value is a [classname]`RouterState` record; its [methodname]`routeParameters()` method gives you the [classname]`RouteParameters` for the active navigation. A convenient pattern is to derive a separate signal for each parameter. Because [interfacename]`Signal` is a functional interface, you can define one with a lambda that reads the value from the router state: diff --git a/articles/getting-started/dev-environment/index.adoc b/articles/getting-started/dev-environment/index.adoc index ee79403779..2e95640e9c 100644 --- a/articles/getting-started/dev-environment/index.adoc +++ b/articles/getting-started/dev-environment/index.adoc @@ -1,5 +1,5 @@ --- -title: Dev Environment +title: Development Environment page-title: Set up your development environment for Vaadin description: Get the most out of Vaadin by setting up your development environment with the right tools and configurations. meta-description: Learn how to set up your development environment for Vaadin development with the necessary tools and configurations. @@ -8,7 +8,7 @@ order: 10 include::{articles}/_vaadin-version.adoc[] -= Development Environment Instructions += 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: diff --git a/articles/getting-started/dev-environment/install-ide.adoc b/articles/getting-started/dev-environment/install-ide.adoc index 726fe7a9b3..4495ab6cb7 100644 --- a/articles/getting-started/dev-environment/install-ide.adoc +++ b/articles/getting-started/dev-environment/install-ide.adoc @@ -9,7 +9,7 @@ order: 10 = Install an IDE -Different IDEs have different levels of support for Java and TypeScript. 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 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. [%header, cols="3,1,1"] |==== @@ -38,4 +38,4 @@ If you are using IntelliJ IDEA, install the link:https://plugins.jetbrains.com/p 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 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 Copilot integration and for <>. +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 4376c9bf6a..fbd27e27c7 100644 --- a/articles/getting-started/dev-environment/run/eclipse.adoc +++ b/articles/getting-started/dev-environment/run/eclipse.adoc @@ -12,7 +12,7 @@ You can run and debug your Vaadin application in Eclipse IDE as you would any ot image::images/eclipse-debug-menu.png[Eclipse IDE debug menu] -Now click menu:Debug As[Java Application]. The application starts up and you can access it at http://localhost:8080. Hot deploy of the frontend files is enabled automatically. However, to enable Java hotswap, you have to take some additional actions. +Now click menu:Debug As[Java Application]. The application starts up and you can 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. == JetBrains Runtime diff --git a/articles/getting-started/dev-environment/run/generic.adoc b/articles/getting-started/dev-environment/run/generic.adoc index 13bd616cb1..fdce8cd1cd 100644 --- a/articles/getting-started/dev-environment/run/generic.adoc +++ b/articles/getting-started/dev-environment/run/generic.adoc @@ -9,7 +9,7 @@ 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. Hot deploy of the frontend files is enabled automatically. However, to enable Java hotswap, you have to take some additional actions. +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. == Enabling Hotswap Manually diff --git a/articles/getting-started/dev-environment/run/index.adoc b/articles/getting-started/dev-environment/run/index.adoc index 0b7c87af0c..84e080e4bc 100644 --- a/articles/getting-started/dev-environment/run/index.adoc +++ b/articles/getting-started/dev-environment/run/index.adoc @@ -1,15 +1,15 @@ --- title: Run a Project page-title: Run a Vaadin application in your IDE -description: Run your Vaadin application with hot deploy and live reload from within your favorite IDE. -meta-description: Run your app directly from your IDE - IntelliJ IDEA, VSC, Eclipse, and NetBeans - with hot deploy and live reload for a faster development workflow. +description: Run your Vaadin 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 --- = 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 live reload and hot deploy enabled. The quick guides for common Java IDEs are here: +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: * <> (both Ultimate and Community) * <> @@ -22,13 +22,17 @@ IntelliJ IDEA Ultimate gives the best developer experience. 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. -To increase your productivity, you should run your application with live reload and hot deploy. By doing this, your changes are applied automatically without having to manually restart the application and reload the browser. +To increase your productivity, you should run your application with hotswap. By doing this, your changes are applied automatically without having to manually restart the application and reload the browser. The guides use the following terms: -Hot deploy and live reload are only used during development. They are disabled in production builds. +* *Live reload* applies your changes to the running application and refreshes the browser. For Java changes, it relies on either hotswap or an automatic restart of the application. +* *Hotswap* replaces changed Java classes in the running application without restarting it. It's faster than a restart, and the user session is preserved. +* *Hot deploy* is a development mode for the frontend files in `src/main/frontend`. It's useful when you actively develop client-side code, such as <<{articles}/building-apps/react#,React views>> or your own web components. + +Hotswap, live reload, and hot deploy are only used during development. They are disabled in production builds. .Are you behind a proxy? [TIP] -Vaadin uses Node.js to download the frontend toolchain during the build. If you are behind a proxy, you may need to configure Node to use that. See the <> guide for details. +Vaadin uses Node.js to download the frontend toolchain during the build. If you are behind a proxy, you may need to configure Node to use that. See the <<{articles}/flow/configuration/development-mode/node-js#proxy-settings-for-downloading-frontend-toolchain,Flow Reference>> guide for details. == Frontend Changes @@ -39,8 +43,8 @@ When hot deploy mode is enabled, all JavaScript, TypeScript, and CSS files insid == Java Changes -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 hot swapping. Hot swapping is the process of reloading changed classes in a running JVM without restarting the application. +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. -The IDE guides above set up hot swapping 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>>. +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 93a05f60c4..204bb7e69b 100644 --- a/articles/getting-started/dev-environment/run/intellij.adoc +++ b/articles/getting-started/dev-environment/run/intellij.adoc @@ -12,7 +12,7 @@ You can run and debug your Vaadin application in IntelliJ IDEA as you would any image::images/idea-debug.png[Debug button in IntelliJ IDEA] -The application starts up and you can access it at http://localhost:8080. Hot deploy of the frontend files is enabled automatically. However, to enable Java hotswap, you have to take some additional actions. +The application starts up and you can 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. == Gradle Projects diff --git a/articles/getting-started/dev-environment/run/netbeans.adoc b/articles/getting-started/dev-environment/run/netbeans.adoc index 8478fd891f..f6f441bda0 100644 --- a/articles/getting-started/dev-environment/run/netbeans.adoc +++ b/articles/getting-started/dev-environment/run/netbeans.adoc @@ -16,7 +16,7 @@ Click [guibutton]*OK* to close the dialog. Next, click the *Debug* button on the image::images/netbeans-debug.png[NetBeans debug button] -The application starts up and you can access it at http://localhost:8080. Hot deploy of the frontend files is enabled automatically. However, to enable Java hotswap, you have to take some additional actions. +The application starts up and you can 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 diff --git a/articles/getting-started/dev-environment/run/vscode.adoc b/articles/getting-started/dev-environment/run/vscode.adoc index e79c20640b..9f59994577 100644 --- a/articles/getting-started/dev-environment/run/vscode.adoc +++ b/articles/getting-started/dev-environment/run/vscode.adoc @@ -13,7 +13,7 @@ You can run and debug your Vaadin application in Visual Studio Code as you would image::images/vscode-run.png[Run Java button in VS Code] -The application starts up and you'll be able to access it at http://localhost:8080. Hot deploy of the frontend files is enabled automatically. However, to enable Java hotswap, you have to take some additional actions. +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 Using Vaadin Copilot diff --git a/articles/getting-started/next-steps.adoc b/articles/getting-started/next-steps.adoc index 30252d6347..6d48b9937e 100644 --- a/articles/getting-started/next-steps.adoc +++ b/articles/getting-started/next-steps.adoc @@ -29,7 +29,7 @@ Secure your application with user authentication and authorization. Refer to the == Use a Real Database -The tutorial uses an in-memory H2 database, which loses its data when the application stops. Replace it with a production-ready database, and manage its schema with migrations. Follow the <> and <> guides for details. +The tutorial uses an in-memory H2 database, which loses its data when the application stops. Replace it with a production-ready database, and manage its schema with migrations. Follow the <<{articles}/building-apps/forms-data/persistence/add-flyway#,Add Flyway>> and <<{articles}/building-apps/forms-data/persistence/replace-h2#,Replace H2>> guides for details. == Test Your Application diff --git a/articles/getting-started/quick-start/index.adoc b/articles/getting-started/quick-start/index.adoc index 55ab67200a..9e97e86bf4 100644 --- a/articles/getting-started/quick-start/index.adoc +++ b/articles/getting-started/quick-start/index.adoc @@ -110,7 +110,7 @@ image::images/second-view.png[The first Vaadin view with a button and a text spa The paragraph is added to the end of the view, below the button. If you click multiple times, new paragraphs are added each time. -The toolbar in the bottom-right corner is the *Copilot toolbar*, which is visible when running in development mode. See the <> for details. +The toolbar in the bottom-right corner is the *Vaadin Copilot* toolbar, which is visible when running in development mode. Vaadin Copilot is a visual development tool that runs in the browser, on top of your application. It's unrelated to GitHub Copilot. See the <<{articles}/tools/copilot#,Vaadin Copilot documentation>> for details. == Add Input diff --git a/articles/getting-started/starters/start/playground/index.adoc b/articles/getting-started/starters/start/playground/index.adoc index 4141f0d191..b1a4f0df0a 100644 --- a/articles/getting-started/starters/start/playground/index.adoc +++ b/articles/getting-started/starters/start/playground/index.adoc @@ -3,7 +3,7 @@ title: Playground page-title: Create a new Vaadin project using Vaadin Start Playground order: 20 description: Description of possibilities with Vaadin Start Playground. -meta-description: Create a Vaadin project using Vaadin Start Playground, a tool that allows you to visually create a custom Spring Boot based Vaadin Flow or Hilla app starter. +meta-description: Create a Vaadin project using Vaadin Start Playground, a tool that allows you to visually create a custom Spring Boot based Vaadin app starter with Flow or React views. banner: The Vaadin Start Playground is being discontinued and shouldn't be used for new projects. Create new projects with link:../start[Vaadin Start] instead. banner-id: start-playground-discontinued banner-style: caution @@ -29,7 +29,7 @@ image::_images/my-projects.png[height=75%, width=75%, List of Projects] == Add Views -Vaadin Start Playground allows you to add several views to your project. You can select the initial content of each view from a list of more than fifteen Flow and Hilla templates. For example, you can include views based on the Master-Detail template, which can be used to manage an entity's data. +Vaadin Start Playground allows you to add several views to your project. You can select the initial content of each view from a list of more than fifteen Flow and React templates. For example, you can include views based on the Master-Detail template, which can be used to manage an entity's data. The screenshot here shows the Vaadin Start Playground UI with the Add View dialog open, showing the Master-Detail template selected: diff --git a/articles/getting-started/starters/start/playground/view-builder/index.adoc b/articles/getting-started/starters/start/playground/view-builder/index.adoc index be1e96177c..ef6d52c06f 100644 --- a/articles/getting-started/starters/start/playground/view-builder/index.adoc +++ b/articles/getting-started/starters/start/playground/view-builder/index.adoc @@ -2,7 +2,7 @@ title: Editable Views page-title: How to create custom views with Visual View Builder | Vaadin description: Visual View Builder enables you to create new views with custom layouts and components without touching code. -meta-description: Discover how to use Visual View Builder in Vaadin Start playground to design custom views with drag-and-drop functionality. +meta-description: Discover how to use Visual View Builder in Vaadin Start Playground to design custom views with drag-and-drop functionality. banner: The Vaadin Start Playground, including Visual View Builder, is being discontinued and shouldn't be used for new projects. Create new projects with link:../../start[Vaadin Start] instead. banner-id: start-playground-discontinued banner-style: caution @@ -11,20 +11,20 @@ banner-style: caution = Visual View Builder -Visual View Builder is a tool in the Vaadin Start playground application generator. It allows you to assemble custom views by dragging and dropping items into place. When you're done, you can download and run the application locally, or share a preview with others. +Visual View Builder is a tool in the Vaadin Start Playground application generator. It allows you to assemble custom views by dragging and dropping items into place. When you're done, you can download and run the application locally, or share a preview with others. Visual View Builder generates the required code declarations, configurations, and sample data for your application. .Theming & Other Features [TIP] -Visual View Builder is part of the Vaadin Start playground. You can customize the application theme, settings (e.g., Java version), and more before downloading or sharing the application. +Visual View Builder is part of the Vaadin Start Playground. You can customize the application theme, settings (e.g., Java version), and more before downloading or sharing the application. == Creating a Project with Custom View -Go to `https://start.vaadin.com` and start new project in the playground. After opening a project, click [guibutton]*+ Add View*. Then choose [guilabel]*Layout with Content Areas* from the list and confirm. This opens View Builder. +Go to `https://start.vaadin.com` and start new project in the Playground. After opening a project, click [guibutton]*+ Add View*. Then choose [guilabel]*Layout with Content Areas* from the list and confirm. This opens View Builder. -image::images/view-builder-start.png[Add New View Builder View to a Vaadin Start playground Project] +image::images/view-builder-start.png[Add New View Builder View to a Vaadin Start Playground Project] === Building a View diff --git a/articles/getting-started/starters/templates.adoc b/articles/getting-started/starters/templates.adoc index 9bb90342ea..192bf1159b 100644 --- a/articles/getting-started/starters/templates.adoc +++ b/articles/getting-started/starters/templates.adoc @@ -15,7 +15,7 @@ If you prefer a different technology stack than Spring Boot and Maven, you can f * https://github.com/vaadin/base-starter-flow-quarkus[Flow / Java, Maven, and Quarkus] * https://github.com/vaadin/base-starter-spring-gradle[Flow / Java, Gradle, and Spring Boot] * https://github.com/vaadin/skeleton-starter-kotlin-spring[Flow / Kotlin, Maven, and Spring Boot] -* https://github.com/vaadin/skeleton-starter-hilla-react-gradle[Hilla / React, Gradle, and Spring Boot] +* https://github.com/vaadin/skeleton-starter-hilla-react-gradle[React / TypeScript, Gradle, and Spring Boot] [IMPORTANT] diff --git a/dspublisher/config/default.json b/dspublisher/config/default.json index ef34fde652..c23a97af27 100644 --- a/dspublisher/config/default.json +++ b/dspublisher/config/default.json @@ -10,7 +10,8 @@ "Lit" ], "redirects": { - "/building-apps/mcp": "/building-apps/agentic-development/mcp", + "/building-apps/forms-data/replace-h2": "/building-apps/forms-data/persistence/replace-h2", + "/building-apps/mcp":"/building-apps/agentic-development/mcp", "/building-apps/mcp/supported-tools": "/building-apps/agentic-development/mcp/supported-tools", "/building-apps/mcp/supported-tools/claude-code": "/building-apps/agentic-development/mcp/supported-tools/claude-code", "/building-apps/mcp/supported-tools/codex": "/building-apps/agentic-development/mcp/supported-tools/codex",