|
|
| (23 intermediate revisions by 5 users not shown) |
| Line 1: |
Line 1: |
| | {{ZKConfigurationReferencePageHeader}} | | {{ZKConfigurationReferencePageHeader}} |
| | | | |
| − | Here is a list of properties that ZK depends on.
| + | __TOC__ |
| | | | |
| − | == How to Define ==
| + | Here is a list of supported library properties that ZK supports. There are several different scopes you can configure for a library property. All properties support '''system/application''' scope, but some properties support '''page/component''' scope. Please check each property's page to know its supported scope. |
| − | To define a library property, you can configure it in <code>WEB-INF/zk.xml</code>.
| |
| − | [[ZK Configuration Reference/zk.xml/The library-property Element | The library-property Element]] for more information. For example,
| |
| | | | |
| − | <source lang="xml">
| + | = System Scope = |
| − | <library-property>
| + | If you define a library property as a system property within the configuration file of your web server, though the system property affects the whole system, not just one web application. |
| − | <name>org.zkoss.zul.Button.mold</name>
| |
| − | <value>trendy</value>
| |
| − | </library-property>
| |
| − | </source>
| |
| − | | |
| − | Alternatively, you can define it as a system property with the configuration file of your Web server, though the system property affects the whole system, not just one Web application.
| |
| | | | |
| − | == <i>class</i>.mold == | + | = Application Scope = |
| − | Default: none
| + | To make a library property effective for the whole application, configure it in <code>WEB-INF/zk.xml</code>. For more information, please refer to [[ZK Configuration Reference/zk.xml/The library-property Element | zk.xml]]. |
| − | [Since 5.0.0]
| |
| | | | |
| − | It specified the default mold of the specified component. The property name is a concatenation of the class name of the component and <tt>mold</tt>. For example, the property for the button's default mold is called <tt>org.zkoss.zul.Button.mold</tt>.
| + | For example, |
| | | | |
| | + | '''Single value''' |
| | <source lang="xml"> | | <source lang="xml"> |
| | <library-property> | | <library-property> |
| Line 29: |
Line 21: |
| | </source> | | </source> |
| | | | |
| − | == org.zkoss.util.label.classpath.charset ==
| + | '''Multiple values''' |
| − | Default: UTF-8
| |
| − | [since 3.6.0]
| |
| − | | |
| − | It defines the charset used to encode i3-label.properties if the file is located in classpath.
| |
| − | | |
| − | == org.zkoss.util.label.web.charset ==
| |
| − | Default: UTF-8
| |
| − | [since 3.6.2]
| |
| − | | |
| − | It defines the charset used to encode i3-label.properties if the file is located in a Web application.
| |
| − | | |
| − | Prior to 3.6.2, the property is called org.zkoss.util.label.WEB-INF.charset.
| |
| − | | |
| − | == org.zkoss.util.label.web.location ==
| |
| − | Default: /WEB-INF/i3-label.properties
| |
| − | [Since 3.6.2]
| |
| − | | |
| − | It specifies where i3-label.properties are named and located.
| |
| − | | |
| − | == org.zkoss.util.logging.realCauseBriefly ==
| |
| − | Default: 6
| |
| − | [Since 3.6.1]
| |
| − | | |
| − | It defines the number of lines to log an error message.
| |
| − | | |
| − | If nonpositive is specified, the full stack traces are logged. Notice that # of lines don't include packages starting with <tt>java</tt>, <tt>javax</tt>, <tt>sun</tt>, or <tt>bsh</tt>.
| |
| − | | |
| − | | |
| − | == org.zkoss.util.logging.warningBriefly ==
| |
| − | Default: 3
| |
| − | [Since 3.6.1]
| |
| − | | |
| − | It defines the number of lines to log a warning message.
| |
| − | | |
| − | If nonpositive is specified, the full stack traces are logged. Notice that # of lines don't include packages starting with <tt>java</tt>, <tt>javax</tt>, <tt>sun</tt>, or <tt>bsh</tt>.
| |
| − | | |
| − | == org.zkoss.web.classWebResource.cache ==
| |
| − | Default: true
| |
| − | [Since 3.6.3]
| |
| − | | |
| − | It specifies whether to allow the browsers to cache the so-called class Web resources<ref>Class Web resources are resources that can be loaded by use of "~./*".</ref>.
| |
| − | | |
| − | By default, it is true. It means the static class Web resources are cached in browsers if possible, unless you upgrade ZK to a different version.
| |
| − | | |
| − | Notice the you can control the immutable period of the CSS files of class Web resources with
| |
| − | another property called <code>org.zkoss.web.classWebResource.cache.CSS.hours</code>.
| |
| − | | |
| − | If you are developing a component, it is better to turn it off (so you can force browser to load modified CSS and JS files by pressing F5).
| |
| − | | |
| − | <source lang="xml">
| |
| − | <library-property>
| |
| − | <name>org.zkoss.web.classWebResource.cache</name>
| |
| − | <value>false</value>
| |
| − | </library-property>
| |
| − | </source>
| |
| − | | |
| − | <blockquote>
| |
| − | ----
| |
| − | <references/>
| |
| − | </blockquote>
| |
| − | | |
| − | == org.zkoss.web.classWebResource.cache.CSS.hours ==
| |
| − | Default: 8760
| |
| − | [Since 3.6.3]
| |
| − | | |
| − | It specifies the number of hours in that period the CSS files of class Web resources won't be changed.
| |
| − | | |
| − | By default, it is 8760 (the same as other class Web resources). Notice that the resource is reloaded. If you want to turn off the cache of the CSS files of class Web resources, you can specify a non-positive value.
| |
| − | | |
| | <source lang="xml"> | | <source lang="xml"> |
| | <library-property> | | <library-property> |
| − | <name>org.zkoss.web.classWebResource.cache.CSS.hours</name> | + | <name>org.zkoss.bind.proxy.IgnoredProxyClasses</name> |
| − | <value>8760</value>
| + | <appendable>true</appendable> |
| | + | <list> |
| | + | <value>java.util.Date</value> |
| | + | <value>java.sql.Date</value> |
| | + | <value>java.sql.Timestamp</value> |
| | + | <value>java.math.BigDecimal</value> |
| | + | <value>java.math.BigInteger</value> |
| | + | </list> |
| | </library-property> | | </library-property> |
| | </source> | | </source> |
| | | | |
| − | == org.zkoss.web.classWebResource.cache.etag ==
| |
| − | Default: false
| |
| − | [Since 5.0.1]
| |
| − |
| |
| − | It specifies whether to use ETag to detect and return 304 for matched resource.
| |
| − |
| |
| − | If turned on, the cached resource won't be reloaded if the user presses F5 to reload.
| |
| | | | |
| − | == org.zkoss.web.util.resource.dir == | + | = Page scope = |
| − | Default: <i>none</i> | + | Notice that '''not all properties support this scope''', please check each property's page. |
| − | [Since 5.0.0]
| + | Put <code><custom-attributes></code> in a zul out of any component: |
| | + | <source lang='xml'> |
| | + | <custom-attributes org.zkoss.zul.listbox.rod="false"/> |
| | | | |
| − | It specifies a directory, where ZK will load the so-called Class-Web Resources (CWR), in addition to the class path. CWR includes JavaScript files, CSS files, and other resources that are specified in the form of <tt>~./xxx</tt>.
| + | <listbox id="box1"> |
| | + | </listbox> |
| | | | |
| − | By default, ZK only searches the class path for the required CWR. By specifying a directory here, ZK will search the directory first and then the class path. It implies a developer can override the default behavior by providing a file with the same name.
| + | <listbox id="box2"> |
| − | | + | </listbox> |
| − | Notice: don't put security sensitive files in the directory specified here, since they can be accessed externally.
| |
| − | | |
| − | For example, assume we have a JavaScript package called <tt>foo.great</tt> and we want to put it to <code>WEB-INF/cwr</code>. Then, we have to specify the following in <tt>WEB-INF/zk.xml</tt>:
| |
| − | | |
| − | <source lang="xml"> | |
| − | <library-property>
| |
| − | <name>org.zkoss.web.util.resource.dir</name>
| |
| − | <value>/WEB-INF/cwr</value>
| |
| − | </library-property>
| |
| | </source> | | </source> |
| | | | |
| − | Then, you can place <tt>zk.wpd</tt> and required JavaScript files under the <tt>WEB-INF/cwr/js/foo/great</tt> directory.
| |
| − |
| |
| − | == org.zkoss.web.servlet.http.URLEncoder ==
| |
| − | Default: <code>javax.servlet.http.HttpServletResponse.encodeURL</code>
| |
| − | [Since 5.0.0]
| |
| − |
| |
| − | It specifies the class used to encode URL by including the session ID and the Servlet's context path, if necessary. The specified class must implement the <javadoc type="interface">org.zkoss.web.servlet.http.Encodes.URLEncoder</javadoc> interface.
| |
| − |
| |
| − | If the clients are far away from the server, you might override this class by encoding the URL of JavaScript and CSS files with a server nearby. Thus, it could shorten the time to load a page. For more information, please refer to [[ZK_Developer's_Reference/Performance_Tips/Load_JavaScript_and_CSS_from_Server_Nearby|Performance Tips]].
| |
| − |
| |
| − | In a sophisticated environment, e.g., [http://en.wikipedia.org/wiki/Reverse_proxy Reverse Proxy], the encoded URL might have to be prefixed with some special prefix. To do that, you can implement the <javadoc type="interface">org.zkoss.web.servlet.http.Encodes.URLEncoder</javadoc> interface, and then specify the class with this library property.
| |
| − |
| |
| − | == org.zkoss.zk.ui.EmulateIE7 ==
| |
| − | Default: false
| |
| − | [since 5.0.2]
| |
| − |
| |
| − | It specifies whether to make Internet Explorer 8 running in IE7 compatible mode. It is used if some of your JavaScript code doesn't work well in IE8.
| |
| − |
| |
| − | Refer to [http://blogs.msdn.com/ie/archive/2008/06/10/introducing-ie-emulateie7.aspx Introducing IE=EmulateIE7]
| |
| − |
| |
| − | == org.zkoss.zk.ui.event.EventQueueProvider.class ==
| |
| − | Default: <i>none</i> (it implies <javadoc>org.zkoss.zk.ui.event.impl.EventQueueProviderImpl</javadoc>)
| |
| − | [since 5.0.0]
| |
| − |
| |
| − | It specifies the name of the class used to provide the event queue. The class must implement the <javadoc type="interface">org.zkoss.zk.ui.event.impl.EventQueueProvider</javadoc> interface.
| |
| − |
| |
| − | == org.zkoss.zk.ui.input.grouping.allowed ==
| |
| − | Default: <i>true</i>
| |
| − | [since 5.0.5]
| |
| − |
| |
| − | Turn on/off whether the user is allowed to key in the grouping character when entering a number. The grouping character depends on the Locale. For example, it is a comma in English, and a dot in Germany. By default, ZK will allow the user to key in the grouping characters and the grouping characters are simply ignored when the input is parsed to a number.
| |
| | | | |
| − | Some people still get confused whether the application considers a comma as a decimal point or not, when he is new to the application. By disabling the entering of the grouping character will help in this case.
| + | = Component Scope = |
| | + | Notice that '''not all properties support this scope''', please check each property's page. |
| | + | Put <code><custom-attributes></code> under a specific component: |
| | + | <source lang='xml'> |
| | | | |
| − | <source lang="xml"> | + | <listbox> |
| − | <library-property> | + | <custom-attributes org.zkoss.zul.listbox.rod="false"/> |
| − | <name>org.zkoss.zk.ui.input.grouping.allowed</name>
| + | ... |
| − | <value>false</value>
| + | </listbox> |
| − | </library-property> | |
| | </source> | | </source> |
| | | | |
| − | If you want to disable it only for a particular page, you could specify it in the page's attribute (note: the page must be the root page). For example,
| |
| − |
| |
| − | <source lang="xml">
| |
| − | <zk>
| |
| − | <custom-attributes org.zkoss.zk.ui.input.grouping.allowed="false" scope="page"/>
| |
| − | <doublebox/>
| |
| − | </zk>
| |
| − | </source>
| |
| − |
| |
| − | == org.zkoss.zk.ui.macro.autoforward.disabled ==
| |
| − | Default: <i>false</i>
| |
| − | [since 5.0.4]
| |
| − |
| |
| − | Turn on/off auto forward mechanism for macro component
| |
| − |
| |
| − | <source lang="xml">
| |
| − | <library-property>
| |
| − | <name>org.zkoss.zk.ui.macro.autoforward.disabled</name>
| |
| − | <value>true</value>
| |
| − | </library-property>
| |
| − | </source>
| |
| − |
| |
| − | == org.zkoss.zk.ui.macro.autowire.disabled ==
| |
| − | Default: <i>false</i>
| |
| − | [since 5.0.4]
| |
| − |
| |
| − | Turn on/off auto wire mechanism for macro component
| |
| − |
| |
| − | <source lang="xml"><library-property>
| |
| − | <name>org.zkoss.zk.ui.macro.autowire.disabled</name>
| |
| − | <value>true</value>
| |
| − | </library-property>
| |
| − | </source>
| |
| − |
| |
| − | == org.zkoss.zk.ui.metainfo.page.Loader.class ==
| |
| − | Default: <i>none</i>
| |
| − | [since 5.0.4]
| |
| − |
| |
| − | It specifies the name of the class used to load the page definitions. The class must implement the <javadoc>org.zkoss.util.resource.Loader</javadoc> interface and it must have a constructor as follows.
| |
| − |
| |
| − | <source lang="java">
| |
| − | public FooLoader(org.zkoss.zk.ui.WebApp wapp) { //assume FooLoader is the implementation class
| |
| − | ...
| |
| − | </source>
| |
| − |
| |
| − | The default iimplementation is straightforward:
| |
| − |
| |
| − | <source lang="java">
| |
| − | private static class MyLoader extends org.zkoss.web.util.resource.ResourceLoader {
| |
| − | private final WebApp _wapp;
| |
| − | private MyLoader(WebApp wapp) {
| |
| − | _wapp = wapp;
| |
| − | }
| |
| − |
| |
| − | //-- super --//
| |
| − | protected Object parse(String path, File file, Object extra)
| |
| − | throws Exception {
| |
| − | final Locator locator =
| |
| − | extra != null ? (Locator)extra: getLocator(_wapp, path);
| |
| − | return new Parser(_wapp, locator).parse(file, path);
| |
| − | }
| |
| − | protected Object parse(String path, URL url, Object extra)
| |
| − | throws Exception {
| |
| − | final Locator locator =
| |
| − | extra != null ? (Locator)extra: getLocator(_wapp, path);
| |
| − | return new Parser(_wapp, locator).parse(url, path);
| |
| − | }
| |
| − | }
| |
| − | </source>
| |
| − |
| |
| − |
| |
| − | == org.zkoss.zk.ui.uuidRecycle.disabled ==
| |
| − | Default: <i>false</i> (i.e., UUID recycle is enabled)
| |
| − | [since 5.0.3]
| |
| − |
| |
| − | It specifies whether to disable the recycle of UUID. By recycling UUID will reduce the memory use of the browser. It is enabled by default.
| |
| − |
| |
| − | == org.zkoss.zk.ui.sys.XMLResourcesLocator.class ==
| |
| − | Default: <i>none</i> (it implies <javadoc>org.zkoss.util.resource.ClassLocator</javadoc>)
| |
| − | [since 5.5.0]
| |
| − |
| |
| − | It specifies the name of the class used to load <code>metainfo/config.xml</code>, <code>metainfo/lang.xml</code> and <code>metainfo/lang-addon.xml</code>. By default, they are loaded from the class path. If you prefer to load them from other location, implement the <javadoc>org.zkoss.util.resource.XMLResourcesLocator</javadoc> interface.
| |
| − |
| |
| − | * Notice that you can specify the property in <code>WEB-INF/zk.xml</code>, since it is too late. Rather, you have to specify in the server's configuration (as a system property).
| |
| − |
| |
| − | == org.zkoss.zkplus.embed.updateURI ==
| |
| − | Default: /zkau
| |
| − | [Since 5.0.5]
| |
| − |
| |
| − | It specifies the URI of the update engine. It is used when using a so-called embedded component. An embedded component is a native, say, JSF component that is implemented by embedding ZK components.
| |
| − |
| |
| − | For more information, please refer to [[ZK_Developer's_Reference/Integration/Embed_ZK_Component_in_Foreign_Framework|Embed ZK Component in Foreign Framework]].
| |
| − |
| |
| − | == org.zkoss.zkmax.zul.FiledownloadListener.class ==
| |
| − | Default: <i>none</i>
| |
| − | [Enterprise Edition]
| |
| − | [Since 3.5.0]
| |
| − |
| |
| − | It specifies the name of the class that will be notified when a file download is happening. The class must implement the <javadoc type="interface">org.zkoss.zkmax.zul.FiledownloadListener</javadoc> interface.
| |
| − |
| |
| − | A developer usually uses it to reject a download if the user tried to resume it in an unacceptable situation. For example, a developer can limit the user from downloading within upcoming 24 hours.
| |
| − |
| |
| − | == org.zkoss.zul.client.rod ==
| |
| − | Default: <i>true</i>
| |
| − | [Enterprise Edition]
| |
| − | [since 5.0.0]
| |
| − |
| |
| − | It specifies whether to apply [http://docs.zkoss.org/wiki/Performance_Tip#Client_Render_on_Demand Client Render on Demand].
| |
| − |
| |
| − | Notice that you can enable or disable this feature a particular component and all its descendants by specifying a custom attribute called <code>org.zkoss.zul.client.rod</code>.
| |
| − |
| |
| − | == org.zkoss.zul.include.mode ==
| |
| − | Default: defer (3.x)
| |
| − | Default: auto (5.0)
| |
| − | [Since 3.6.2]
| |
| − |
| |
| − | It specifies the default mode of the <tt>include</tt> component. In ZK 3, the default mode is <tt>defer</tt>, which is backward-compatible with the prior version. Since ZK 5, the default mode is <tt>auto</tt> for easier control.
| |
| − |
| |
| − | == org.zkoss.zul.listbox.checkmarkDeselectOthers ==
| |
| − | Default: false
| |
| − | [Since 5.0.5]
| |
| − |
| |
| − | If a listbox's checkmark (<javadoc method="isCheckmark()">org.zkoss.zul.Listbox</javadoc>) is enabled, the selection will be toggled when an user clicks an item. In other words, all other items will remain the same.
| |
| − |
| |
| − | If you prefer to deselect all other items and select the item being clicked (which the behavior of ZK 5.0.4 and earlier), you could specify true to this library property.
| |
| − |
| |
| − | == org.zkoss.zul.progressbox.position ==
| |
| − | Default: left, top
| |
| − | [Since 5.0.1]
| |
| − |
| |
| − | It specifies how to display the progress box at the client. The progress box is a message used to indicate the AU requests have being processed by the server. By default, it is displayed at the left, top corner.
| |
| − |
| |
| − | Here is a list of allowed values. If you want to specify two of them, separate them with a comma, such as <tt>left,top</tt>.
| |
| − |
| |
| − | {|border="1" cellspacing="0" width="100%"
| |
| − | |+ Allowed Values
| |
| − | |-
| |
| − | ! Value
| |
| − | ! Description
| |
| − | |-
| |
| − | | bottom
| |
| − | | Align the progress box at the bottom edge of the browser window.
| |
| − | |-
| |
| − | | center
| |
| − | | Align the progress box at the center of the browser window. If it is used with left and top, it means the center in the vertical orientation.
| |
| − | |-
| |
| − | | left
| |
| − | | Align the progress box at the left edge of the browser window.
| |
| − | |-
| |
| − | | mouse
| |
| − | | Align the progress box near by the mouse pointer. If specified, it ignores all other values.
| |
| − | |-
| |
| − | | right
| |
| − | | Align the progress box at the right edge of the browser window.
| |
| − | |-
| |
| − | | top
| |
| − | | Align the progress box at the top edge of the browser window.
| |
| − | |}
| |
| − |
| |
| − | == org.zkoss.zul.theme.browserDefault ==
| |
| − | Default: false (override browser default with ours)
| |
| − | [Since 3.6.0]
| |
| − |
| |
| − | It specifies whether not to override the standard HTML tags, such as body's margin and padding.
| |
| − |
| |
| − | == org.zkoss.zul.theme.fontFamilyC ==
| |
| − | Default: arial, sans-serif
| |
| − | [Since 3.6.0]
| |
| − |
| |
| − | It specifies the font used for the content in the ZUL CSS file.
| |
| − |
| |
| − | == org.zkoss.zul.theme.fontFamilyT ==
| |
| − | Default: arial, sans-serif
| |
| − | [Since 3.6.0]
| |
| − |
| |
| − | It specifies the font used for the title in the ZUL CSS file.
| |
| − |
| |
| − | == org.zkoss.zul.theme.fontSizeM ==
| |
| − | Default: 12px
| |
| − | [Since 3.6.0]
| |
| − |
| |
| − | It specifies the size of the middle font used in the ZUL CSS file.
| |
| − |
| |
| − | == org.zkoss.zul.theme.fontSizeMS ==
| |
| − | Default: 11px
| |
| − | [Since 3.6.0]
| |
| − |
| |
| − | It specifies the size of the middle-smaller font used in the ZUL CSS file.
| |
| − |
| |
| − | == org.zkoss.zul.theme.fontSizeS ==
| |
| − | Default: 11px
| |
| − | [Since 3.6.0]
| |
| − |
| |
| − | It specifies the size of the smaller font used in the ZUL CSS file.
| |
| − |
| |
| − | == org.zkoss.zul.theme.fontSizeXS ==
| |
| − | Default: 10px
| |
| − | [Since 3.6.0]
| |
| − |
| |
| − | It specifies the size of the extreme small font used in the ZUL CSS file.
| |
| − |
| |
| − | == org.zkoss.zul.tree.checkmarkDeselectOthers ==
| |
| − | Default: false
| |
| − | [Since 5.0.5]
| |
| − |
| |
| − | If a tree's checkmark (<javadoc method="isCheckmark()">org.zkoss.zul.Tree</javadoc>) is enabled, the selection will be toggled when an user clicks an item. In other words, all other items will remain the same.
| |
| − |
| |
| − | If you prefer to deselect all other items and select the item being clicked (which the behavior of ZK 5.0.4 and earlier), you could specify true to this library property.
| |
| | | | |
| − | ==Version History==
| |
| | | | |
| − | {| border='1px' | width="100%" | + | {{ZKConfigurationReferenceHeadingToc}} |
| − | ! Version !! Date !! Content
| |
| − | |-
| |
| − | | 5.0.4
| |
| − | | August 2010
| |
| − | | '''org.zkoss.zk.ui.macro.autoforward.disabled'''
| |
| − | Turn on/off auto forward mechanism for macro component
| |
| − | |-
| |
| − | | 5.0.4
| |
| − | | August 2010
| |
| − | | '''org.zkoss.zk.ui.macro.autowire.disabled'''
| |
| − | Turn on/off auto wire mechanism for macro component
| |
| − | |-
| |
| − | | 5.0.4
| |
| − | | August 2010
| |
| − | | '''org.zkoss.zk.ui.metainfo.page.Loader.class'''
| |
| − | It specifies the name of the class used to load the page definitions.
| |
| − | |-
| |
| − | | 5.0.5
| |
| − | | September 2010
| |
| − | | org.zkoss.zul.listbox.checkmarkDeselectOthers and org.zkoss.zul.tree.checkmarkDeselectOthers are introduced to control how to select items when an item is clicked on a tree or a listbox with checkmark.
| |
| − | |}
| |
| | | | |
| | {{ZKConfigurationReferencePageFooter}} | | {{ZKConfigurationReferencePageFooter}} |