Providing Theme Resources

From Documentation


DocumentationZK Developer's ReferenceTheming and StylingUnderstanding the Theming SubsystemProviding Theme Resources
Providing Theme Resources


ThemeProvider

After switching to another theme, a ThemeProvider allows you the full control of CSS styling, including but not limited to

  • Switch among multiple sets of stylesheets based on, say, the user's preference, cookie, locale, or others
  • Replace the CSS styling of component(s) with your own custom styling
  • Inject additional CSS files

Since 6.5.2

Standard implementations of ThemeProvider are available for each of ZK editions (CE, PE, and EE).

Edition ThemeProvider
ZK CE org.zkoss.zul.theme.StandardThemeProvider
ZK PE org.zkoss.zkex.theme.StandardThemeProvider
ZK EE org.zkoss.zkmax.theme.StandardThemeProvider

We will illustrate the theme provider with two examples. One is straightforward: set the corresponding attributes based on the cookie. The other injects a fragment to the URI such that we can allow the browser to cache the CSS file.

For information of 3.6 and earlier, please refer to ZK 3 Theme Provider.

Examples

A Simple Example

In the following example, we store the preferred font size and the skin (theme) in the cookie and retrieve them when required. 

Since 7.0.0, the font size attributes are deprecated because of using LESS.

package my;
public class MyThemeProvider implements ThemeProvder {
	public Collection getThemeURIs(Execution exec, List uris) {
		if ("silvergray".equals(getSkinCookie(exec))) {
			uris.add("~./silvergray/color.css.dsp");
			uris.add("~./silvergray/img.css.dsp");
		}
		return uris;
	}
	public int getWCSCacheControl(Execution exec, String uri) {
		return -1;
	}
	public String beforeWCS(Execution exec, String uri) {
		final String fsc = getFontSizeCookie(exec);
		if ("lg".equals(fsc)) {
			exec.setAttribute("fontSizeM", "15px");
			exec.setAttribute("fontSizeMS", "13px");
			exec.setAttribute("fontSizeS", "13px");
			exec.setAttribute("fontSizeXS", "12px");
		} else if ("sm".equals(fsc)) {
			exec.setAttribute("fontSizeM", "10px");
			exec.setAttribute("fontSizeMS", "9px");
			exec.setAttribute("fontSizeS", "9px");
			exec.setAttribute("fontSizeXS", "8px");
		}
		return uri;
	}
	public String beforeWidgetCSS(Execution exec, String uri) {
		return uri;
	}
	/** Returns the font size specified in cooke. */
	private static String getFontSizeCookie(Execution exec) {
		Cookie[] cookies = ((HttpServletRequest)exec.getNativeRequest()).getCookies();
		if (cookies!=null)
			for (int i=0; i<cookies.length; i++)
				if ("myfontsize".equals(cookies[i].getName()))
					return cookies[i].getValue();
		return "";
	}
	/** Returns the skin specified in cookie. */
	private static String getSkinCookie(Execution exec) {
		Cookie[] cookies = ((HttpServletRequest)exec.getNativeRequest()).getCookies();
		if (cookies!=null)
			for (int i=0; i<cookies.length; i++)
				if ("myskin".equals(cookies[i].getName()))
					return cookies[i].getValue();
		return "";
	}
}

Notice that we return -1 when ThemeProvider.getWCSCacheControl(Execution, String) is called to disallow the browser to cache the CSS file. It is necessary since we manipulate the content of the CSS file by setting the attributes (based on the cookie). It means the content might be different with the same request URL. For a cacheable example, please refer to the next section.

Then, you configure WEB-INF/zk.xml by adding the following lines. 

 <desktop-config>
     <theme-provider-class>my.MyThemeProvider</theme-provider-class>
 </desktop-config>

A Cacheable Example

To improve the performance, it is better to allow the browser to cache the CSS file as often as possible. With the theme provider, it can be done by returning a positive number when ThemeProvider.getWCSCacheControl(Execution, String) is called. However, because the browser will use the cached version, we have to ensure the browser gets a different URL for each different theme. Here we illustrate a technique called fragment injection.

The idea is simple: when ThemeProvider.getThemeURIs(Execution, List) is called, we inject a special fragment to denote the content, such that each different theme is represented with a different URL. The injection can be done easily with the inner class called ThemeProvider.Aide. For example, 

final String fsc = getFontSizeCookie(exec);
if (fsc != null && fsc.length() > 0) {
	for (ListIterator it = uris.listIterator(); it.hasNext();) {
		final String uri = (String)it.next();
		if (uri.startsWith(DEFAULT_WCS)) {
			it.set(Aide.injectURI(uri, fsc));
			break;
		}
	}
}

Then, we can retrieve the fragment we encoded into the URI later when ThemeProvider.beforeWCS(Execution, String) is called. It can be done easily by use of ThemeProvider.Aide.decodeURI(String). ThemeProvider.Aide.decodeURI(String) returns a two-element array if the fragment is found. The first element is the URI without fragment, and the second element is the fragment. For example, 

public String beforeWCS(Execution exec, String uri) {
	final String[] dec = Aide.decodeURI(uri);
	if (dec != null) {
		if ("lg".equals(dec[1])) {
			exec.setAttribute("fontSizeM", "15px");
			exec.setAttribute("fontSizeMS", "13px");
			exec.setAttribute("fontSizeS", "13px");
			exec.setAttribute("fontSizeXS", "12px");
		} else if ("sm".equals(dec[1])) {
			exec.setAttribute("fontSizeM", "10px");
			exec.setAttribute("fontSizeMS", "9px");
			exec.setAttribute("fontSizeS", "9px");
			exec.setAttribute("fontSizeXS", "8px");
		}
		return dec[0];
	}
	return uri;
}

Here is a complete example: 

public class CacheableThemeProvider implements ThemeProvider{
	private static String DEFAULT_WCS = "~./zul/css/zk.wcs";

	public Collection getThemeURIs(Execution exec, List uris) {
		//font-size
		final String fsc = getFontSizeCookie(exec);
		if (fsc != null && fsc.length() > 0) {
			for (ListIterator it = uris.listIterator(); it.hasNext();) {
				final String uri = (String)it.next();
				if (uri.startsWith(DEFAULT_WCS)) {
					it.set(Aide.injectURI(uri, fsc));
					break;
				}
			}
		}

		//slivergray
		if ("silvergray".equals(getSkinCookie(exec))) {
			uris.add("~./silvergray/color.css.dsp");
			uris.add("~./silvergray/img.css.dsp");
		}
		return uris;
	}

	public int getWCSCacheControl(Execution exec, String uri) {
		return 8760; //safe to cache
	}
	public String beforeWCS(Execution exec, String uri) {
		final String[] dec = Aide.decodeURI(uri);
		if (dec != null) {
			if ("lg".equals(dec[1])) {
				exec.setAttribute("fontSizeM", "15px");
				exec.setAttribute("fontSizeMS", "13px");
				exec.setAttribute("fontSizeS", "13px");
				exec.setAttribute("fontSizeXS", "12px");
			} else if ("sm".equals(dec[1])) {
				exec.setAttribute("fontSizeM", "10px");
				exec.setAttribute("fontSizeMS", "9px");
				exec.setAttribute("fontSizeS", "9px");
				exec.setAttribute("fontSizeXS", "8px");
			}
			return dec[0];
		}
		return uri;
	}

	public String beforeWidgetCSS(Execution exec, String uri) {
		return uri;
	}

	/** Returns the font size specified in cooke. */
	private static String getFontSizeCookie(Execution exec) {
		Cookie[] cookies = ((HttpServletRequest)exec.getNativeRequest()).getCookies();
		if (cookies!=null)
			for (int i=0; i<cookies.length; i++)
				if ("myfontsize".equals(cookies[i].getName()))
					return cookies[i].getValue();
		return "";
	}
	/** Returns the skin specified in cookie. */
	private static String getSkinCookie(Execution exec) {
		Cookie[] cookies = ((HttpServletRequest)exec.getNativeRequest()).getCookies();
		if (cookies!=null)
			for (int i=0; i<cookies.length; i++)
				if ("myskin".equals(cookies[i].getName()))
					return cookies[i].getValue();
		return "";
	}
}

How to Specify the Media Types

Since 5.0.3

In addition to String instances, you can return instances of StyleSheet in the returned collection of ThemeProvider.getThemeURIs(Execution, List), such that you can control more about the generated CSS link. For example, if you want to add a CSS link for the media type, say, print, handheld, then you can do as follows. 

public Collection getThemeURIs(Execution exec, List uris) {
   uris.add(new StyleSheet("/theme/foo.css", "text/css", "print, handheld", false));
   return uris;
}

Version History

Version Date Content
5.0.3 June 2010 The media type was allowed in StyleSheet.



Last Update : 2022/07/08

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.


Retrieved from "https://www.zkoss.org/_w/index.php?title=ZK_Developer%27s_Reference/Theming_and_Styling/Understanding_the_Theming_Subsystem/Providing_Theme_Resources&oldid=54824"