Web Themes

Web Themes are a way to customise the layout and styling of end-user visible web pages hosted on the Service. These include pages such as:

• OpenID authorisation (sign in),

• New user registration,

• Password reset,

• and most others, excluding the “/ui” management site.

For some pages the whole layout as well as style is configurable. For others only the style is configurable.

Breaking changes

Web themes replaces the “Branding Styles” feature by providing similar functionality. “Branding styles” allows injection of CSS rules into the page. Web themes allows this as well. Using both at the same time is not recommended. Most existing “Branding Styles” rules can be used as-is in a web theme.

Some built-in customer specific CSS rules are no longer available. They must be implemented as Web Themes to keep the existing style.

Web theme contents

A web theme can contain several alternative layouts for various pages, a default style, and several additional alternative styles. Web themes are given a name. Changing the name of an existing web theme does not affect selections.

Layouts

Some layouts contain components whose content will be other layouts. For example, the login view has a “base” layout which contains a dynamically changing internal section which may contain the “enter username and password” layout or other layouts.

Some pages can have alternative layouts. Which layout is picked depends on how the page was opened. The OpenID authorisation pages (and user registration opened from it) may have a standard “display” query parameters, with values such as “page”, “touch”, “popup” or “wap” as described in the OpenID Connect standard. The “page” layout is the default if display is not specified.

Styles

A default style can be included, as well as several additional styles which can be combined with the default style.

The default style is provided by adding a CSS stylesheet named “default”. If no default style is included, a built-in default style is used. If a default style is written into the theme, the built-in default style is not used.

Additional stylesheets can be provided with other names. The additional styles are injected into the page after the default style. Only one of the additional styles is used at a time. This enables using the same theme in different situations with minor stylistic changes. When a theme is selected, either the default style or the default plus an additional style are selected at the same time.

Management of web themes

Web themes are managed in the management interface. Editors need some of the following permissions:

• View web themes

• Create web themes

• Modify web themes

• Remove web themes

Web themes are not namespace-specific, so having access to them means having access to all of them. On some service installations this means great trust is placed on the editors.

Management view

Management view is opened from the main menu by selecting “Web themes”.

The management view enables users to list, create, copy, edit and remove web themes.

Web theme editor

Creating or editing an existing theme opens the Theme editor. You can name the editor and configure layouts and styles within.

The editor contains a tree selector where you can select or add layouts and and stylesheets. The layouts and styles are named, and you pick the name when the layout or style is first created.

The theme is saved by clicking the Save button. The changes are viewable immediately in pages where web themes are used.

Activating web themes

One theme can be picked as the default theme. This is done in the System Preferences / Branding section. One theme and one style combination can be selected there.

In OpenID Client settings, any theme and style combination can be selected per client. By default the same theme as is selected in Branding configuration is used.

Layout structure

The layouts are defined as HTML documents. The content must be compatible with Vaadin 8 Designer. Additional documentation is found at the Vaadin 8 documentation site.

They layout document is structured as a description of Vaadin components. The selection of layout components is open for selection, except for the root component which must remain the same as in built-in default layouts. This is usually a <vaadin-vertical-layout>.

The layout document can include <html>, <head>, <body> elements or those can be skipped. They should not be needed unless mapping of custom components is needed. This is done in the <head> section.

The layout must include all the components the related Java class expects. If any are missing, the layout cannot be used correctly. In this situation the built-in layout is loaded instead, but the web page may appear or be functionally broken until this situation is corrected. The mapping between a layout component description and the Java class is done with the “_id” attributes. The name of these attributes must match (case sensitive).

Component types must match Java class component types. In some cases the Java class may support multiple alternative component types, but it is safest to copy what is in the default layout.

Elements

Examples of some common elements:

Element	Java component	Description
<vaadin-vertical-layout> </vaadin-vertical-layout>	VerticalLayout	Contains other components, displays them on top of each other.
<vaadin-horizontal-layout> </vaadin-horizontal-layout>	HorizontalLayout	Contains other components, displays them on one row.
<vaadin-css-layout> </vaadin-css-layout>	CssLayout	Simple layout which converts to a <DIV> element in final HTML. This allows more configuration is CSS rules.
<vaadin-text-field />	TextField	Single-line text field
<vaadin-text-area />	TextArea	Multiline text field
<vaadin-check-box />	CheckBox	Checkbox field
<vaadin-button />	Button	A push button
<vaadin-label />	Label	A text label.
<vaadin-link />	Link	Clickable link
<vaadin-image />	Image	Image display

Built-in Vaadin components are named as described in Vaadin 8 documentation. Custom components will have custom prefixes.

Attributes

Examples of common attributes used in layouts:

Attribute	Value	Description
_id	Component field name.	Must match the name of the component field in the associated Java class.
id	Unique name within page.	Translates into “id” attribute in final HTML
style-name	One or more CSS style names separated with space.	Translates into “class” attribute in final HTML.
width and height	“100%” or “100px” or other supported width/height value	Sets the width or height in the Java component. Translates to inline CSS in final HTML.
width-full and height-full	No value	Same as width=”100%” or height=”100%”
margin	“true” or “false”	Enables or disables built-in margin in VerticalLayout or HorizontalLayout.
spacing	“true” or “false”	Enables or disables built-in spacing between sub-components in VerticalLayout or HorizontalLayout.
:top, :middle, :bottom, :left, :center, :right	No value	Sets the alignment of a component in it’s parent layout.
responsive	No value	Enables the responsiveness in components
plain-text	No value	Displayed text is escaped instead of being interpreted as HTML. Used in Buttons, Labels.

Stylesheet structure

Stylesheets are normal CSS documents. They are injected into the <head> section of the web page.