Skip to content

Commit

Permalink
chore: Add a link to example project for application theme (#3729)
Browse files Browse the repository at this point in the history 
* chore: Add a link to example project for application theme

* Edited all of touched document.

* More editing

---------

Co-authored-by: Russell J.T. Dyer <[email protected]>
  • Loading branch information
@mshabarov @russelljtdyer
mshabarov and russelljtdyer authored Sep 30, 2024
1 parent 787b359 commit 2fd7d71
Showing 1 changed file with 19 additions and 19 deletions.
38 changes: 19 additions & 19 deletions articles/styling/application-theme.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,32 +7,32 @@ order: 20

= Application Theme

The recommended way to load CSS stylesheets for styling Vaadin components and other UI elements is to place them in an application theme folder. Themes created this way are always loaded _on top of_ the default <<lumo#, Lumo theme>>.
It's best to put CSS stylesheets for styling Vaadin components and other UI elements in an application theme folder. Themes organization this way are loaded on top of the default <<lumo#, Lumo theme>>.

For use in a single application, place the theme folder in the `frontend/themes` folder, with a name you prefer. Vaadin application projects generated with https://start.vaadin.com[Vaadin Start,window=_blank] have a predefined theme folder with the same name as the project.
For use in a single application, place your theme folder in the [filename]`frontend/themes` directory. Vaadin application projects generated with https://start.vaadin.com[Vaadin Start,window=_blank] have a pre-defined theme folder with the same name as the project.

.Theme Folder Example
[source]
----
frontend
└── themes
└── my-theme (1)
├── styles.css (2)
└── theme.json (3)
└── my-theme /* <1> */
├── styles.css /* <2> */
└── theme.json /* <3> */
----

The theme folder (1) must contain a <<#master-stylesheet, master stylesheet>> called `styles.css` (2). A <<#theme-configuration, theme configuration file>> called `theme.json` (3) is optional.
The theme folder (1) must contain a <<#master-stylesheet, master stylesheet>> called, [filename]`styles.css` (2). A <<#theme-configuration, theme configuration file>> called, [filename]`theme.json` (3) is optional.

Themes built this way can be <<advanced/multi-app-themes#, packaged as JAR files>> to be shared by multiple applications.

.Flow @CssImport Annotation
[NOTE]
In older versions of Vaadin, stylesheets were loaded using `@CssImport` and `@Stylesheet` annotations. In much old versions, they were loaded using the `@HtmlImport` annotation. Although `@CssImport `and `@Stylesheet` still work, they're recommended only for loading stylesheets into custom standalone components -- not as the primary way to load application styles.
In older versions of Vaadin, stylesheets were loaded using `@CssImport` and `@Stylesheet` annotations. In much older versions, they were loaded using the `@HtmlImport` annotation. Although `@CssImport `and `@Stylesheet` still work, they're recommended only for loading stylesheets into custom standalone components -- not as the primary way to load application styles.


== Applying a Theme

The theme contained in the folder is applied to the UI using the `@Theme` annotation, with the name of the theme folder as a parameter. The `@Theme` annotation must be placed on the class that implements the <</flow/advanced/modifying-the-bootstrap-page#application-shell-configurator, `AppShellConfigurator`>> interface. This interface is used for configuring various application features. For projects generated with Vaadin Start, that's the `Application` class.
The theme contained in the folder is applied to the UI using the `@Theme` annotation, with the name of the theme folder as a parameter. The `@Theme` annotation must be placed on the class that implements the <</flow/advanced/modifying-the-bootstrap-page#application-shell-configurator, `AppShellConfigurator`>> interface. This interface is used for configuring various application features. For projects generated with Vaadin Start, that would be the `Application` class.

[source,java]
----
Expand All @@ -59,7 +59,7 @@ Although a project may contain multiple theme folders, only one can be applied t

== Master Stylesheet

The master stylesheet, `styles.css` is loaded automatically into the UI. All CSS, including Lumo style property values and custom component styles, can be added there.
The master stylesheet, [filename]`styles.css` is loaded automatically into the UI. All CSS, including Lumo style property values and custom component styles, can be added there.

To apply Lumo style property modifications globally (i.e., in the whole application), they should be placed in a style block targeting the `html` root element selector like so:

Expand Down Expand Up @@ -113,13 +113,13 @@ html, :host() {

Stylesheets placed in a sub-folder called `components` in the application theme are loaded by default into the Shadow DOM of Vaadin components -- if their file names match the root element name of a component.

This is a legacy feature from earlier versions of Vaadin, in which Vaadin components were styled primarily though <<advanced/shadow-dom-styling#, Shadow DOM CSS injection>>. Although this approach to component styling is no longer recommended, the injection mechanism is still supported and enabled by default. This is to ease migration from earlier versions.
This is a legacy feature from earlier versions of Vaadin, in which Vaadin components were styled primarily through <<advanced/shadow-dom-styling#, Shadow DOM CSS injection>>. Although this approach to component styling is no longer recommended, the injection mechanism is still supported and enabled by default. This is to ease migration from earlier versions.

.Disable Pre-Compiled Frontend Bundle
[NOTE]
The loading of shadow DOM stylesheets from the `components` sub-folder is not compatible with the <</flow/configuration/development-mode#precompiled-bundle, pre-compiled frontend bundle>>. In order to use this mechanism for loading shadow DOM styles, the pre-compiled bundled must be <</flow/configuration/development-mode#disable-precompiled-bundle, disabled>>.
The loading of shadow DOM stylesheets from the [filename]`components` sub-folder is not compatible with the <</flow/configuration/development-mode#precompiled-bundle, pre-compiled frontend bundle>>. In order to use this mechanism for loading shadow DOM styles, the pre-compiled bundle must be <</flow/configuration/development-mode#disable-precompiled-bundle, disabled>>.

This legacy feature, though, may cause problems in application themes based on the <<styling-components#, current recommended approach to component styling>>, if a sub-folder called `components` is used. The feature can, however, be disabled by setting the `autoInjectComponents` flag in the theme configuration file to `false`:
This legacy feature, though, may cause problems in application themes based on the <<styling-components#, current recommended approach to component styling>>, if a sub-folder called, [filename]`components` is used. The feature can, however, be disabled by setting the `autoInjectComponents` flag in the theme configuration file to `false`:

.theme.json
[source,json]
Expand All @@ -133,7 +133,7 @@ This legacy feature, though, may cause problems in application themes based on t

== Images & Fonts

You can include font files and images in your theme folder. Create sub folders for them (i.e., `images` and `fonts`). You'll need to use the https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face[`@font-face`,window=_blank] CSS rule to load font files, like the `roboto.woff` file located in `my-theme/fonts/` in the example below:
You can include font files and images in your theme folder. Create sub folders for them (i.e., [filename]`images` and [filename]`fonts`). You'll need to use the https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face[`@font-face`,window=_blank] CSS rule to load font files, like the [filename]`roboto.woff` file located in [filename]`my-theme/fonts/` in the example below:

.styles.css
[source,css]
Expand All @@ -152,9 +152,9 @@ It's also possible to load images and fonts via https://developer.mozilla.org/en

.Embedded Components
[NOTE]
If a theme is to be used with <</flow/integrations/embedding#, embedded Flow applications or components>>, such as for use with <</tools/dspublisher#, Design System Publisher>>, `@font-face` declarations must be placed in a special stylesheet called `document.css` to ensure that they're loaded to the page root rather than into a shadow root.
If a theme is to be used with <</flow/integrations/embedding#, embedded Flow applications or components>>, such as for use with <</tools/dspublisher#, Design System Publisher>>, `@font-face` declarations must be placed in a special stylesheet called, [filename]`document.css` to ensure that they're loaded in the page root rather than in a shadow root.

Images stored in the theme folder can also be used with Flow's <</flow/application/resources#the-image-component, Image class>> using the path `themes/[theme-name]/filename.png`. The example below loads an image file from a theme folder called, `my-theme`:
Images stored in the theme folder can also be used with Flow's <</flow/application/resources#the-image-component, Image class>> using the path [filename]`themes/[theme-name]/filename.png`. The example below loads an image file from a theme folder called, [filename]`my-theme`:

[source,java]
----
Expand Down Expand Up @@ -189,7 +189,7 @@ frontend

== Theme Configuration

The theme configuration file, `theme.json`, can be used to configure various theme-related features. The most common of these is the `lumoImports` property, used to define which modules of the built-in Lumo theme are to be loaded.
The theme configuration file, [filename]`theme.json` can be used to configure various theme-related features. The most common of these is the `lumoImports` property, used to define which modules of the built-in Lumo theme are to be loaded.

[source,json]
----
Expand All @@ -198,7 +198,7 @@ The theme configuration file, `theme.json`, can be used to configure various the
}
----

The most common usage of this property is to enable <<{articles}/components/badge#, Badge>> styles and the <<lumo/utility-classes#, Lumo Utility Classes>>. If not defined, the following modules are loaded by default:
The most common usage of this property is to enable <<{articles}/components/badge#, Badge>> styles and the <<lumo/utility-classes#, Lumo Utility Classes>>. If undefined, the following modules are loaded by default:

- `typography`
- `color`
Expand All @@ -211,8 +211,8 @@ Other theme configuration features are covered in the <<advanced#, Advanced Styl
- <<advanced/npm-packages#fonts-and-images-from-npm, Loading other theme assets from npm packages>>; and
- <<advanced/parent-and-sub-themes#, Loading a parent theme as a basis for the current theme>>.

Embedded application theming is covered in a separate section:
Embedded application theming is covered in <<../flow/integrations/embedding/theming#, Theming Embedded Applications>>.

- <<../flow/integrations/embedding/theming#, Theming Embedded Applications>>.
You can find an example project that demonstrates the application theme in action at https://github.com/vaadin/custom-theme-demo[GitHub].

[discussion-id]`e5e984e4-6a4f-40ab-a6fc-665166a2d8c5`

0 comments on commit 2fd7d71

Please sign in to comment.