|
|
| Line 1: |
Line 1: |
| | {{ZKConfigurationReferencePageHeader}} | | {{ZKConfigurationReferencePageHeader}} |
| | | | |
| − | __TOC__
| + | {{ZKConfigurationReferenceHeadingToc}} |
| − | It is used to customize how ZK handles desktops. You might have multiple <tt>desktop-config</tt> elements in one <tt>zk.xml</tt>.
| |
| − | | |
| − | <source lang="xml" >
| |
| − | <desktop-config>
| |
| − | <desktop-timeout>3600</desktop-timeout>
| |
| − | <disable-theme-uri>~./zul/css/norm*.css.dsp*</disable-theme-uri>
| |
| − | <file-check-period>5</file-check-period>
| |
| − | <extendlet-check-period>10</extendlet-check-period>
| |
| − | <theme-uri>/my/blue**.css</theme-uri>
| |
| − | <theme-provider-class>my.MyThemeProvider</theme-provider-class>
| |
| − | </desktop-config>
| |
| − | </source>
| |
| − | | |
| − | | |
| − | == The desktop-timeout Element ==
| |
| − | [Default: 3600]
| |
| − | | |
| − | It specifies the time, in seconds, between client requests before a desktop is invalidated. A negative time indicates the desktop should never timeout.
| |
| − | | |
| − | == The disable-theme-uri Element ==
| |
| − | [Default: ''none'']
| |
| − | | |
| − | It specifies what theme URI to be disabled. The theme URI shall be one of the default theme URI. For example, the following statement disables the generation of the default theme URI for the ZK XUL component set.
| |
| − | | |
| − | <source lang="xml" >
| |
| − | <desktop-config>
| |
| − | <disable-theme-uri>~./zul/css/zk.wcs</disable-theme-uri>
| |
| − | </desktop-config>
| |
| − | </source>
| |
| − | | |
| − | It is usually used with the <tt>theme-uri</tt> element to replace the default theme. Please refer to [[ZK Developer's Reference/Theming and Styling/Theme Customization|ZK Developer's Reference]] for more details about theming and styling.
| |
| − | | |
| − | Also notice that implementing [[ZK Developer's Reference/Theming and Styling/Theme Providers|a theme provider]] is a more controllable alternative.
| |
| − | | |
| − | == The extendlet-check-period Element ==
| |
| − | [Default: -1 (never expired)]
| |
| − | | |
| − | It specifies the time, in seconds, to wait before checking whether a resource loaded by an extendlet is modified. An extendlet is a processor to load the resources usually located in classpath, such as <tt>~./zul/desktop.dsp</tt>.
| |
| − | | |
| − | Resources located in classpath are usually packed as a JAR file, so they are immutable and not need to check if modified. However, in a development environment, you might want to check if they are deployed without reloading the JAR files.
| |
| − | | |
| − | == The file-check-period Element ==
| |
| − | [Default: 5]
| |
| − | | |
| − | It specifies the time, in seconds, to wait before checking whether a file is modified.
| |
| − | | |
| − | For better performance, ZK has employed a cache to store parsed ZUML file. The time specified here controls how often ZK checks whether a file is modified. The larger the number the better the performance.
| |
| − | | |
| − | == The id-to-uuid-prefix Element ==
| |
| − | [Default: <i>none</i>]
| |
| − | [Since 3.6.1]
| |
| − | [deprecated 5.0.3]
| |
| − | | |
| − | It specifies whether to generate UUID based on ID. It is useful for testing purpose, such that the generated UUID is predictable. For example, the following causes the UUID to be generated by prefixing ID with <code>_zid_</code>.
| |
| − | | |
| − | <source lang="xml">
| |
| − | <desktop-config>
| |
| − | <id-to-uuid-prefix>_zid_</id-to-uuid-prefix>
| |
| − | </desktop-config>
| |
| − | </source>
| |
| − | | |
| − | Then, the following component's UUID will be <code>_zid_foo</code>.
| |
| − | | |
| − | <source lang="xml">
| |
| − | <textbox id="foo"/>
| |
| − | </source>
| |
| − | | |
| − | Notice that UUID has to be unique in the whole desktop, so the above setting might cause the application unable to run (due to replicated UUID). You can minimize the possibility of ID conflicts by prefixing with page's UUID as follows.
| |
| − | | |
| − | <source lang="xml">
| |
| − | <desktop-config>
| |
| − | <id-to-uuid-prefix>_zid_${page}_</id-to-uuid-prefix>
| |
| − | </desktop-config>
| |
| − | </source>
| |
| − | | |
| − | Then, <code>${page}</code> will be replaced with the page's UUID (if the page is available). However, since a page might still have several ID space, the UUID conflict is still possible.
| |
| − | | |
| − | == The repeat-uuid Element ==
| |
| − | [Default: false]
| |
| − | [Since 3.6.0]
| |
| − | | |
| − | It specifies whether to use the same UUID sequence for desktops for each reboot.
| |
| − | By default, it is turned off so the desktop's UUID is completely different after reboot. It helps to avoid the consistency between the browser and the server. However, it is useful to turn this option on if you want to debug and test the application.
| |
| − | | |
| − | == The theme-uri Element ==
| |
| − | [Default: ''none'']
| |
| − | | |
| − | It specifies the URI of an addition theme (aka., a style sheet file).
| |
| − | | |
| − | Like other URI, it accepts "*" for loading browser and Locale dependent style sheet. Please refer to [[ZK Developer's Reference/Internationalization/Locale-Dependent Resources|ZK Developer's Reference]] for details.
| |
| − | | |
| − | You can specify any number of <tt>them-uri</tt> as follows.
| |
| − | | |
| − | <source lang="xml" >
| |
| − | <desktop-config>
| |
| − | <theme-uri>/my/blue**.css</theme-uri>
| |
| − | <theme-uri>/my/second.css</theme-uri>
| |
| − | </desktop-config>
| |
| − | </source>
| |
| − | | |
| − | | |
| − | If you want to replace a default theme, you have to use <tt>theme-uri</tt> with <tt>disable-theme-uri</tt>. Please refer to [[ZK Developer's Reference/Theming and Styling|ZK Developer's Reference]] for more information.
| |
| − | | |
| − | '''Notice:'''
| |
| − | | |
| − | # All style sheets defined in <tt>lang.xml</tt> and <tt>lang-addon.xml</tt> are loaded, no matter this parameter is defined or not. It is convenient for developers to override certain styles.
| |
| − | # Each JAR could specify a <tt>lang-addon.xml</tt> file (under the <tt>metainfo/zk</tt> directory), so you could specify style sheets there if you have more than one style sheets.
| |
| − | # You could specify extra CSS files for individual ZUML pages by use of the [[ZK Component Reference/Essential Components/Style|<tt>style</tt> component]].
| |
| − | | |
| − | == The theme-provider-class Element ==
| |
| − | [Default: ''none'']
| |
| − | | |
| − | It specifies the class to provide the theme (aka., a style sheet file) URI dynamically. If you want to determine the theme based on the current user, cookie or locale. You can implement a class with the <javadoc type="interface">org.zkoss.zk.ui.util.ThemeProvider</javadoc> interface, and specify it with the <tt>theme-provider-class</tt> element. Then, an instance of the class will be created, and it is called each time a desktop is rendered to the client to determine the theme URI.
| |
| − | | |
| − | Notice that the theme provider is called with all theme URIs that shall be generated (including what are specified in <tt>theme-uri</tt> and excluding what are specified in <tt>disable-theme-uri</tt>). And, only the return collection of URIs are actually generated. In other words, the theme provider has the highest priority.
| |
| − | | |
| − | For more information, please refer to [[ZK Developer's Reference/Theming and Styling/Theme Providers|ZK Developer's Reference]].
| |
| | | | |
| | ==Version History== | | ==Version History== |