Switching Themes

From Documentation
Revision as of 07:26, 3 November 2020 by Hawk (talk | contribs)

Prerequisite

The user can switch to a registered theme by setting a cookie or a library property. Please ensure your application contains the corresponding theme jar first. The default theme doesn't require a separate jar file.


Theme Resolution Priority

ZK determines(resolves) a theme in the following order:

  1. Cookies
  2. Library property
  3. Theme priority


Apply a Theme for the Whole Application

Specify a theme name as a value. This will apply to the whole application as a default theme.

zk.xml

<library-property>
    <name>org.zkoss.theme.preferred</name>
    <value>deepsea</value> <!-- no whitespace in theme names -->
</library-property>

Check the complete theme name of the theme pack at ZK Developer's Reference/Theming and Styling/ZK Official Themes#All Theme Names of Theme Pack

Dynamically switching themes using Cookies

To provide different themes for different end users (sessions), you can use cookies since it's stored in a browser.

Themes.setTheme(Executions.getCurrent(), "custom");
Executions.sendRedirect("");

Internally, CookieThemeResolver provides this functionality.

Dynamically Switching Themes Using Library Property

Library property is used to apply a preferred theme when the current theme setting could not be obtained from Cookies. Notice that the property change affects the whole application (all end users).

Programmatically:

Library.setProperty("org.zkoss.theme.preferred", "custom");
Executions.sendRedirect("");

Theme Priority

If the previous two options do not yield any result, the theme with the highest priority would be applied. Theme priority is usually assigned when registering a theme but could also be changed dynamically.

Please refer to Themes for its family of register() methods.

Customize the Theme Resolution Process

Web developers could also add other ways for setting the current theme by writing a custom ThemeResolver'.

If you would like to communicate theme name via session instead, you would create a class like the following:

package foo;

public class SessionThemeResolver implements ThemeResolver {
    @Override
    public String getTheme(HttpServletRequest request) {
        Session sess = request.getSession();
        if (sess != null) {
            return sess.getAttribute("mytheme");
        }
    }

    @Override
    public void setTheme(HttpServletRequest request, HttpServletResponse response, String themeName) {
        Session sess = request.getSession();
        if (sess != null) {
            sess.setAttribute("mytheme", themeName);
        }
    }
}

and configure the custom ThemeResolver in WEB-INF/zk.xml.

<zk>
    <desktop-config>
        <theme-resolver-class>foo.SessionThemeResolver</theme-resolver-class>
    </desktop-config>
</zk>

To access the current theme resolver, please refer to ThemeFns.getThemeResolver() and ThemeFns.setThemeResolver(ThemeRegistry).