diff --git a/documentation/src/main/html/ThemeVariants.html b/documentation/src/main/html/ThemeVariants.html new file mode 100644 index 000000000..83aa62f2b --- /dev/null +++ b/documentation/src/main/html/ThemeVariants.html @@ -0,0 +1,3 @@ +tutorial::theme/using-component-themes.asciidoc +Themed button + diff --git a/documentation/src/main/java/com/vaadin/flow/tutorial/theme/ReadyMadeThemes.java b/documentation/src/main/java/com/vaadin/flow/tutorial/theme/ReadyMadeThemes.java index d82946950..47170347f 100644 --- a/documentation/src/main/java/com/vaadin/flow/tutorial/theme/ReadyMadeThemes.java +++ b/documentation/src/main/java/com/vaadin/flow/tutorial/theme/ReadyMadeThemes.java @@ -1,6 +1,9 @@ package com.vaadin.flow.tutorial.theme; +import java.util.Arrays; + import com.vaadin.flow.component.button.Button; +import com.vaadin.flow.component.button.ButtonVariant; import com.vaadin.flow.component.html.Div; import com.vaadin.flow.router.Route; import com.vaadin.flow.router.RouterLayout; @@ -54,6 +57,22 @@ public class MyTheme extends Lumo { public void buttonVariant() { Button button = new Button("Themed button"); - button.getElement().setAttribute("theme", "contrast primary"); + button.addThemeVariants(ButtonVariant.LUMO_PRIMARY, + ButtonVariant.LUMO_CONTRAST); + } + + public void buttonVariant2() { + Button button = new Button("Themed button"); + button.getThemeNames().addAll(Arrays.asList("contrast", "primary")); + } + + public void buttonVariant3() { + Button button = new Button("Themed button"); + String themeAttributeName = "theme"; + String oldValue = button.getElement().getAttribute(themeAttributeName); + String variantsToAdd = "contrast primary"; + button.getElement().setAttribute(themeAttributeName, + oldValue == null || oldValue.isEmpty() ? variantsToAdd + : ' ' + variantsToAdd); } } diff --git a/documentation/theme/using-component-themes.asciidoc b/documentation/theme/using-component-themes.asciidoc index 9ed01aebe..0452136d1 100644 --- a/documentation/theme/using-component-themes.asciidoc +++ b/documentation/theme/using-component-themes.asciidoc @@ -66,16 +66,20 @@ If the Theme annotation is not on a `@Route` Component or a top `RouterLayout` a == Theme variants -You can use a Theme variant by defining it on the `@Theme` annotation: -[source,java] +A variant is a special string value that can be placed in the `theme` attribute value of any html element. +When the corresponding theme enabled, those values change the components' visual appearance. + +Multiple variants can be applied to the element, if specified separated by whitespace: + +.Html representation of the variants +[source,html] ---- -@Route(value = "") -@Theme(value = MyTheme.class, variant = "large") -public class LargeThemedApplication extends Div { -} +Themed button ---- -Variants are like "skins" for the theme - it uses the same files for the theme, but sets special selectors in the body to make it appear different. +There are two types of variants: theme variants, specific for the current theme and working globally +and component variants, specific to the current component and theme. +Different themes and different components may have different sets of variants (or none). == Available Themes and Customizations @@ -94,7 +98,18 @@ See link:https://github.com/vaadin/vaadin-themable-mixin/wiki[vaadin-themable-mi === Using Vaadin theme variants -Lumo and Material themes come with two variants: light (the default) and dark. You can use the dark variant by using: +In Flow, you can set a theme variant by defining it on the `@Theme` annotation: +[source,java] +---- +@Route(value = "") +@Theme(value = MyTheme.class, variant = "large") +public class LargeThemedApplication extends Div { +} +---- + +Lumo and Material themes come with two variants: light (the default) and dark. + +By default, no theme variants are used. You can use the dark variant by using: .Setting the dark variant for Lumo [source,java] @@ -105,6 +120,7 @@ public class DarkApplication extends Div { } ---- and the same can be done for Material theme: + .Setting the dark variant for Material [source,java] ---- @@ -116,14 +132,61 @@ public class DarkMaterialApplication extends Div { Individual components have also variants available. Component variants are applied by using the element API to set the variant as the `theme` attribute. -For example, to create a Button with https://vaadin.com/components/vaadin-button/html-examples/button-lumo-theme-demos[increased legibility], you can use: +For example, to create a Button with https://vaadin.com/components/vaadin-button/html-examples/button-lumo-theme-demos[increased legibility], +you can use `addThemeVariants` method: + +.Adding theme variants for the component +[source,java] +---- +Button button = new Button("Themed button"); + button.addThemeVariants(ButtonVariant.LUMO_PRIMARY, + ButtonVariant.LUMO_CONTRAST); +---- + +For each component, there is a predefined set of variants that you can use. +Those variants are theme-specific and different for each of the component (some may have none). +For each component that has variants, Flow provides an api similar to the one in the example above to use it. + +When added, variants are converted to their html values +(for a button variant, `ButtonVariant.LUMO_PRIMARY.getVariantName()` is used) +and those representations are added to the `theme` attribute values. + +If the component implements `HasTheme` interface (which is true for every component that has `addThemeVariants` method), +then the following API can be used: + +.Adding theme values for the component that implements `HasTheme` interface +[source,java] +---- +Button button = new Button("Themed button"); +button.getThemeNames().addAll(Arrays.asList("contrast", "primary")); +---- -.Setting a theme variant for a component +If you want more flexibility (which may come in handy when adding non-standard theme variants to the component), +you can manipulate the value of the `theme` attribute directly: + +.Adding variants to the 'theme' attribute of the component [source,java] ---- Button button = new Button("Themed button"); -button.getElement().setAttribute("theme", "contrast primary"); + String themeAttributeName = "theme"; + String oldValue = button.getElement().getAttribute(themeAttributeName); + String variantsToAdd = "contrast primary"; + button.getElement().setAttribute(themeAttributeName, + oldValue == null || oldValue.isEmpty() ? variantsToAdd + : ' ' + variantsToAdd); ---- -The `contrast primary` String in this case are theme variants for the Button component. For looking up all available component variants, -https://vaadin.com/components/browse[see the component HTML examples] and look under the _Lumo Theme_ tab for examples of the variants. +Each of the three examples above do the very same thing in the end: +add `contrast` and `primary` Lumo Theme variants to the `theme` attribute value of the button component. + +For looking up all available component variants, https://vaadin.com/components/browse[see the component HTML examples] +and look under the _Lumo Theme_ tab for examples of the variants. + +[NOTE] +Theme variants for components work only when the corresponding theme is enabled. +If a different theme or no theme is enabled, then with variants present in `theme` attribute of the corresponding component, +no actual changes for the component's look and feel are made. + +As was mentioned earlier, by default, if no explicit theme configuration is done and `vaadin-lumo-theme` +dependency is present in the classpath, LumoTheme is used. +