Interface ThemeProvider
-
- All Known Implementing Classes:
StandardThemeProvider
,StandardThemeProvider
,StandardThemeProvider
public interface ThemeProvider
Used to replace the theme defined in the language definitions (lang.xml and lang-addon.xml),ThemeURIHandler
and the configuration (thetheme-uri
elements in web.xml).When a desktop is about to be rendered,
getThemeURIs(org.zkoss.zk.ui.Execution, java.util.List<java.lang.Object>)
will be called to allow developer to rename, add or remove CSS/WCS files.When loading each WCS (Widget CSS descriptor) file (excluding CSS files),
beforeWCS(org.zkoss.zk.ui.Execution, java.lang.String)
will be called to allow developer to rename or remove the WCS file.When a WCS file is about to load the CSS file of a widget,
beforeWidgetCSS(org.zkoss.zk.ui.Execution, java.lang.String)
will be called to allow developer to rename or remove the CSS file associated with a widget.To allow the client to cache the WCS file, you can inject a special fragment into the URI of the WCS file such that a different URI represents a different theme. To inject, you can use @{link Aide#injectURI} when preprocessing URIs in
getThemeURIs(org.zkoss.zk.ui.Execution, java.util.List<java.lang.Object>)
. Therefore, we can retrieve the injected fragment inbeforeWCS(org.zkoss.zk.ui.Execution, java.lang.String)
by use ofThemeProvider.Aide.decodeURI(java.lang.String)
.- Since:
- 3.0.0
- Author:
- tomyeh
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
ThemeProvider.Aide
Utilities to help the implementation ofThemeProvider
to manipulate the URI such that it is able to use a different URI for a different theme.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description java.lang.String
beforeWCS(Execution exec, java.lang.String uri)
Called when a WCS (Widget CSS descriptor) file is about to be loaded.java.lang.String
beforeWidgetCSS(Execution exec, java.lang.String uri)
Called when a WCS (Widget CSS descriptor) file is about to load the CSS file associated with a widget.java.util.Collection<java.lang.Object>
getThemeURIs(Execution exec, java.util.List<java.lang.Object> uris)
Returns a list of the theme's URIs of the specified execution, or null if no theme shall be generated.int
getWCSCacheControl(Execution exec, java.lang.String uri)
Returns the number of hours that the specified WCS (Widget CSS descriptor) file won't be changed.
-
-
-
Method Detail
-
getThemeURIs
java.util.Collection<java.lang.Object> getThemeURIs(Execution exec, java.util.List<java.lang.Object> uris)
Returns a list of the theme's URIs of the specified execution, or null if no theme shall be generated. Each item could be an instance of eitherString
orStyleSheet
. If you want to specify themedia
attribute, useStyleSheet
.It is called when a desktop is about to be rendered. It is called only once for each desktop.
Notice that
StyleSheet
is allowed since 5.0.3.- Parameters:
exec
- the current execution (never null), where you can retrieve the desktop, request and response. Note: if your Web application supports multiple devices, you have to checkDesktop.getDevice()
.uris
- the default set of theme's URIs, i.e., the themes defined in language definitions (lang.xml and lang-addon.xml) and the configuration (thetheme-uri
elements in web.xml). Each URI is an instance of of eitherString
orStyleSheet
. Notice that, unless it is customized by application specific lang-addon, all URIs are, by default, String instances.- Returns:
- the collection of the theme's URIs
that the current desktop shall use.
Each URI is an instance of of either
String
orStyleSheet
.
-
getWCSCacheControl
int getWCSCacheControl(Execution exec, java.lang.String uri)
Returns the number of hours that the specified WCS (Widget CSS descriptor) file won't be changed. In other words, the client is allowed to cache the file until the returned hours expires.- Parameters:
uri
- the URI of the WCS file, e.g., ~./zul/css/zk.wcs- Returns:
- number of hours that the WCS file is allowed to cache. If it is never changed until next ZK upgrade, you could return 8760 (the default if ThemeProvider is not specified). If you don't want the client to cache, return a non-positive number.
-
beforeWCS
java.lang.String beforeWCS(Execution exec, java.lang.String uri)
Called when a WCS (Widget CSS descriptor) file is about to be loaded. This method then returns the real URI of the WCS file to load. If no need to change, just return theuri
parameter.If you want to change the font size, you can set the attributes of the execution accordingly as follows.
- fontSizeM
- The default font size. Default: 12px
- fontSizeMS
- The font size for menus. Default: 11px
- fontSizeS
- The font size for smaller fonts, such as toolbar. Default: 11px
- fontSizeXS
- The font size for extreme small fonts. Default 10px
- fontFamilyT
- The font family for titles. Default: arial, sans-serif
- fontFamilyC
- The font family for content. Default: arial, sans-serif
For example,
String beforeWCS(Execution exec, String uri) { exec.setAttribute("fontSizeM", "15px"); return uri; }
- Parameters:
exec
- the current execution (never null), where you can retrieve the request and response. However, unlikegetThemeURIs(org.zkoss.zk.ui.Execution, java.util.List<java.lang.Object>)
, the desktop might not be available when this method is called.uri
- the URI of the WCS file, e.g., ~./zul/css/zk.wcs- Returns:
- the real URI of the WCS file to load. If null is returned, the WCS file is ignored.
- Since:
- 5.0.0
-
beforeWidgetCSS
java.lang.String beforeWidgetCSS(Execution exec, java.lang.String uri)
Called when a WCS (Widget CSS descriptor) file is about to load the CSS file associated with a widget. This method then returns the real URI of the WCS file to load. If no need to change, just return theuri
parameter.This method is usually overridden to load the CSS files from a different directory. For example,
String beforeWidgetCSS(Execution exec, String uri) { return uri.startsWith("~./") ? "~./foo/" + uri.substring(3): uri; }
- Parameters:
exec
- the current execution (never null), where you can retrieve the request ad response. However, unlikegetThemeURIs(org.zkoss.zk.ui.Execution, java.util.List<java.lang.Object>)
, the desktop might not be available when this method is called.uri
- the URI of the CSS file associated with a widget, e.g., ~./js/zul/wgt/css/a.css.dsp- Returns:
- the real URI of the CSS file to load If null is returned, the CSS file is ignored.
- Since:
- 5.0.0
-
-