Skip to content

Commit cc86e8f

Browse files
mshabarovmshabarov
committed
Add theming system chapter, reordering
1 parent 4cbc59b commit cc86e8f

File tree

1 file changed

+108
-78
lines changed

1 file changed

+108
-78
lines changed

‎articles/upgrading/index.adoc‎

Lines changed: 108 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,49 @@ vaadinVersion={vaadin-version}
8383

8484
See the link:https://github.com/vaadin/platform/releases[list of releases on GitHub] for the latest one.
8585

86+
== Java Version
87+
88+
Java 21 or later is required. Below is an example of how to use this version:
89+
90+
[.example]
91+
--
92+
[source,xml]
93+
----
94+
<source-info group="Maven"></source-info>
95+
<properties>
96+
<java.version>21</java.version>
97+
<!-- OR: -->
98+
<maven.compiler.source>21/maven.compiler.source>
99+
<maven.compiler.target>21</maven.compiler.target>
100+
</properties>
101+
----
102+
[source,kotlin]
103+
----
104+
<source-info group="Gradle (Kotlin DSL)"></source-info>
105+
plugins {
106+
java
107+
}
108+
109+
java {
110+
toolchain {
111+
languageVersion = JavaLanguageVersion.of(21)
112+
}
113+
}
114+
----
115+
[source,groovy]
116+
----
117+
<source-info group="Gradle (Groovy DSL)"></source-info>
118+
plugins {
119+
id 'java'
120+
}
121+
122+
java {
123+
toolchain {
124+
languageVersion = JavaLanguageVersion.of(21)
125+
}
126+
}
127+
----
128+
--
86129

87130
== Spring Upgrade Instructions
88131

@@ -104,8 +147,70 @@ You'll need to upgrade Spring to the latest versions, including the starter pare
104147
</parent>
105148
----
106149

150+
== Application Servers
151+
152+
Before migrating, find the corresponding version of the Jakarta EE 11-compatible application server used in your project. See link:https://jakarta.ee/compatibility/[Jakarta Compatible Products] for more information.
153+
154+
== Maven & Gradle Plugins
155+
156+
Ensure that the Maven plugins which are explicitly defined in your project, are compatible with Java 21.
157+
A safe choice: Maven 3.9.11 (or the latest in the 3.9 line) or Maven 4.0.x (once stable) if you are comfortable with that.
158+
159+
To run Gradle on top of Java 21 and latest Spring Boot 4 versions, you'll need to use version 8.14 or later. See the link:https://docs.gradle.org/8.14/release-notes.html[Gradle release notes] for further details. If your project uses Spring Boot, upgrade the plugin `org.springframework.boot` to version 4.0.0.
160+
161+
If you're using a Gradle wrapper, update it to version 8.14 by executing the following from the command line:
162+
163+
[source,terminal]
164+
----
165+
./gradlew wrapper --gradle-version 8.14
166+
----
167+
168+
For Java 21 compatibility, you may need to update the `sourceCompatibility` setting in your project's build file to version 21. Check your project's build file and make any necessary changes.
169+
170+
== Quarkus
171+
172+
Vaadin Quarkus extension is changed to build production package by default. No need for production profile with exclusions for development tools in Maven configurations because Vaadin Quarkus extension has build-in Vaadin plugin handling production packaging.
173+
174+
To allow project to keep build configuration unchanged, Vaadin Quarkus extension has `vaadin.build.enabled` property to change the default behavior. Disable Vaadin plugin by adding `vaadin.build.enabled=false` in `application.properties` file to keep using profile based configuration.
175+
176+
== Changes In Theming System
177+
178+
Vaadin 25 simplifies the theme/styling system to bring it closer to normal/native web development, and minimizes Vaadin-specific peculiarities, while keeping migration from earlier versions as painless as possible.
179+
180+
Below are the main highlights of the changes and more detailed instructions are described in link:https://github.com/vaadin/platform/issues/7453[Theming System Renewal].
181+
182+
183+
The special `frontend/themes` folder, and the `components` sub-folder for CSS shadow-DOM injection, is deprecated (but still supported).
184+
185+
The [classname]`@Theme` annotation is deprecated. Instead, [classname]`StyleSheet` annotation to be used for loading one or more stylesheets from public static resources locations (e.g. `META-INF/resources/`), whereas [classname]`CssImport` loads one or more stylesheets from the `src/main/frontend/` folder and use mechanisms native to HTML, CSS, and React (e.g. `@import url("morestyles.css")` in CSS).
186+
187+
`StyleSheet` annotation is now a recommended way to load Vaadin theme for the application — to be placed on the application class implementing [classname]`AppShellConfigurator`. Below are some examples of how to use it:
188+
189+
[source,java]
190+
----
191+
// theme selection
192+
@StyleSheet(Aura.STYLESHEET) // or Lumo.STYLESHEET
193+
public class Application implements AppShellConfigurator {}
194+
195+
// or loading custom styles and theme:
196+
197+
@StyleSheet("styles.css")
198+
public class Application implements AppShellConfigurator {}
199+
200+
// then using @import in the src/main/resources/META-INF/resources/styles.css:
201+
202+
@import '@vaadin/aura/aura.css';
203+
// your custom styles go here ...
204+
205+
----
206+
207+
The [filename]`theme.json` configuration file is deprecated (but still supported, except the `lumoImports` property).
107208

108-
=== Security Configuration Changes
209+
The `themeFor` parameter of the [classname]`@CssImport` annotation (for shadow-DOM injection) is deprecated (but still supported).
210+
211+
The special [filename]`document.css` file (for loading styles into the document root in embedded components) is removed as no longer necessary.
212+
213+
== Security Configuration Changes
109214

110215
The deprecated [classname]`VaadinWebSecurity` class has been removed from Vaadin 25. Use instead the [classname]`VaadinSecurityConfigurer` base class for your security configuration. Below is an example of this:
111216

@@ -325,85 +430,15 @@ public class SecurityConfiguration {
325430
==== Restrict Access By Default For Url-Based Security
326431
URLs not explicitly specified in security configuration changed from being allowed for authenticated users to restricted by default. This requires extra security rules (path matchers) for URLs that were allowed only for authentication users.
327432

328-
==== Deny Access Ff Flow Layout Has No Security Annotation
433+
==== Deny Access If Flow Layout Has No Security Annotation
329434
Vaadin Flow layouts now require access annotation (e.g. [classname]`RolesAllowed`) on layout classes. This was added to align with auto-layout default security rules.
330435

331-
== Java Version
332-
333-
Java 21 or later is required. Below is an example of how to use this version:
334-
335-
[.example]
336-
--
337-
[source,xml]
338-
----
339-
<source-info group="Maven"></source-info>
340-
<properties>
341-
<java.version>21</java.version>
342-
<!-- OR: -->
343-
<maven.compiler.source>21/maven.compiler.source>
344-
<maven.compiler.target>21</maven.compiler.target>
345-
</properties>
346-
----
347-
[source,kotlin]
348-
----
349-
<source-info group="Gradle (Kotlin DSL)"></source-info>
350-
plugins {
351-
java
352-
}
353-
354-
java {
355-
toolchain {
356-
languageVersion = JavaLanguageVersion.of(21)
357-
}
358-
}
359-
----
360-
[source,groovy]
361-
----
362-
<source-info group="Gradle (Groovy DSL)"></source-info>
363-
plugins {
364-
id 'java'
365-
}
366-
367-
java {
368-
toolchain {
369-
languageVersion = JavaLanguageVersion.of(21)
370-
}
371-
}
372-
----
373-
--
374-
375-
== Application Servers
376-
377-
Before migrating, find the corresponding version of the Jakarta EE 11-compatible application server used in your project. See link:https://jakarta.ee/compatibility/[Jakarta Compatible Products] for more information.
378-
379-
== Maven & Gradle Plugins
380-
381-
Ensure that the Maven plugins which are explicitly defined in your project, are compatible with Java 21.
382-
A safe choice: Maven 3.9.11 (or the latest in the 3.9 line) or Maven 4.0.x (once stable) if you are comfortable with that.
383-
384-
To run Gradle on top of Java 21 and latest Spring Boot 4 versions, you'll need to use version 8.14 or later. See the link:https://docs.gradle.org/8.14/release-notes.html[Gradle release notes] for further details. If your project uses Spring Boot, upgrade the plugin `org.springframework.boot` to version 4.0.0.
385-
386-
If you're using a Gradle wrapper, update it to version 8.14 by executing the following from the command line:
387-
388-
[source,terminal]
389-
----
390-
./gradlew wrapper --gradle-version 8.14
391-
----
392-
393-
For Java 21 compatibility, you may need to update the `sourceCompatibility` setting in your project's build file to version 21. Check your project's build file and make any necessary changes.
394-
395436
== TestBench
396437

397438
[classname]`ComponentTester` in UI Unit test has been updated to prove a common [methodname]`void click()` method. However, the new method clashes with a similar existing method in [classname]`AnchorTester` and [classname]`RouterLinkTester` that returns an [classname]`HasElement` instance as a result of the navigation. Existing tests that rely on the return type have to migrate to the new [methodname]`navigate()` method; if the return value is not used, there is no need for changes.
398439

399440
Because of the change, the [classname]`com.vaadin.flow.component.html.testbench.ClickHandler` class has been removed. The interface, meant to be used with [classname]`ComponentTester` subclasses, should not be needed anymore. In this case, [classname]`com.vaadin.testbench.unit.Clickable` is a valid substitute.
400441

401-
== Quarkus
402-
403-
Vaadin Quarkus extension is changed to build production package by default. No need for production profile with exclusions for development tools in Maven configurations because Vaadin Quarkus extension has build-in Vaadin plugin handling production packaging.
404-
405-
To allow project to keep build configuration unchanged, Vaadin Quarkus extension has `vaadin.build.enabled` property to change the default behavior. Disable Vaadin plugin by adding `vaadin.build.enabled=false` in `application.properties` file to keep using profile based configuration.
406-
407442
== Binder
408443
[methodname]`Binder.validate()` implementation has been changed to behave as its javadoc states. In other words, [methodname]`Binder.validate()` no longer fails when bean level validators have been configured but no bean is currently set (i.e. [classname]`Binder` is used in buffered mode).
409444

@@ -430,9 +465,4 @@ Vaadin uses the [filename]`{project directory}/src/main/frontend/` directory as
430465

431466
== Removed Deprecations
432467

433-
APIs deprecated earlier have now been removed. The following linked GitHub issue lists these removals — link:https://github.com/vaadin/flow/issues/21396[Remove deprecated API in Flow 25.0]
434-
435-
== Side Navigation Replaces AppNav and AppNavItem
436-
437-
Some starter projects previously used the `AppNav` and `AppNavItem` components, which relied on the Vaadin Component Factory components, vcf-nav and vcf-nav-item. These Component Factory components are no longer supported and you should replace `AppNav` and `AppNavItem` with their successor, <</components/side-nav#,Side Navigation>>.
438-
468+
APIs deprecated earlier have now been removed. The following linked GitHub issue lists these removals — link:https://github.com/vaadin/flow/issues/21396[Remove deprecated API in Flow 25.0].

0 commit comments

Comments
 (0)