Skip to content

Commit 6d1f5e1

Browse files
mshabarovmshabarov
committed
Add theming system chapter, reordering
1 parent edcb8de commit 6d1f5e1

File tree

1 file changed

+107
-72
lines changed

1 file changed

+107
-72
lines changed

‎articles/upgrading/index.adoc‎

Lines changed: 107 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,49 @@ vaadinVersion={vaadin-version}
8181

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

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

85128
== Spring Upgrade Instructions
86129

@@ -102,8 +145,70 @@ You'll need to upgrade Spring to the latest versions, including the starter pare
102145
</parent>
103146
----
104147

148+
== Application Servers
149+
150+
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.
151+
152+
== Maven & Gradle Plugins
153+
154+
Ensure that the Maven plugins which are explicitly defined in your project, are compatible with Java 21.
155+
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.
156+
157+
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.
158+
159+
If you're using a Gradle wrapper, update it to version 8.14 by executing the following from the command line:
160+
161+
[source,terminal]
162+
----
163+
./gradlew wrapper --gradle-version 8.14
164+
----
165+
166+
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.
167+
168+
== Quarkus
169+
170+
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.
171+
172+
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.
173+
174+
== Changes In Theming System
175+
176+
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.
177+
178+
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].
179+
180+
181+
The special `frontend/themes` folder, and the `components` sub-folder for CSS shadow-DOM injection, is deprecated (but still supported).
182+
183+
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).
184+
185+
`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:
186+
187+
[source,java]
188+
----
189+
// theme selection
190+
@StyleSheet(Aura.STYLESHEET) // or Lumo.STYLESHEET
191+
public class Application implements AppShellConfigurator {}
192+
193+
// or loading custom styles and theme:
105194
106-
=== Security Configuration Changes
195+
@StyleSheet("styles.css")
196+
public class Application implements AppShellConfigurator {}
197+
198+
// then using @import in the src/main/resources/META-INF/resources/styles.css:
199+
200+
@import '@vaadin/aura/aura.css';
201+
// your custom styles go here ...
202+
203+
----
204+
205+
The [filename]`theme.json` configuration file is deprecated (but still supported, except the `lumoImports` property).
206+
207+
The `themeFor` parameter of the [classname]`@CssImport` annotation (for shadow-DOM injection) is deprecated (but still supported).
208+
209+
The special [filename]`document.css` file (for loading styles into the document root in embedded components) is removed as no longer necessary.
210+
211+
== Security Configuration Changes
107212

108213
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:
109214

@@ -322,85 +427,15 @@ public class SecurityConfiguration {
322427
==== Restrict Access By Default For Url-Based Security
323428
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.
324429

325-
==== Deny Access Ff Flow Layout Has No Security Annotation
430+
==== Deny Access If Flow Layout Has No Security Annotation
326431
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.
327432

328-
== Java Version
329-
330-
Java 21 or later is required. Below is an example of how to use this version:
331-
332-
[.example]
333-
--
334-
[source,xml]
335-
----
336-
<source-info group="Maven"></source-info>
337-
<properties>
338-
<java.version>21</java.version>
339-
<!-- OR: -->
340-
<maven.compiler.source>21/maven.compiler.source>
341-
<maven.compiler.target>21</maven.compiler.target>
342-
</properties>
343-
----
344-
[source,kotlin]
345-
----
346-
<source-info group="Gradle (Kotlin DSL)"></source-info>
347-
plugins {
348-
java
349-
}
350-
351-
java {
352-
toolchain {
353-
languageVersion = JavaLanguageVersion.of(21)
354-
}
355-
}
356-
----
357-
[source,groovy]
358-
----
359-
<source-info group="Gradle (Groovy DSL)"></source-info>
360-
plugins {
361-
id 'java'
362-
}
363-
364-
java {
365-
toolchain {
366-
languageVersion = JavaLanguageVersion.of(21)
367-
}
368-
}
369-
----
370-
--
371-
372-
== Application Servers
373-
374-
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.
375-
376-
== Maven & Gradle Plugins
377-
378-
Ensure that the Maven plugins which are explicitly defined in your project, are compatible with Java 21.
379-
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.
380-
381-
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.
382-
383-
If you're using a Gradle wrapper, update it to version 8.14 by executing the following from the command line:
384-
385-
[source,terminal]
386-
----
387-
./gradlew wrapper --gradle-version 8.14
388-
----
389-
390-
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.
391-
392433
== TestBench
393434

394435
[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.
395436

396437
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.
397438

398-
== Quarkus
399-
400-
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.
401-
402-
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.
403-
404439
== Binder
405440
[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).
406441

0 commit comments

Comments
 (0)