page"
| (7 intermediate revisions by 3 users not shown) | |||
| Line 11: | Line 11: | ||
[xml="version="1.0" encoding="UTF-8""] | [xml="version="1.0" encoding="UTF-8""] | ||
[complete="true|'''false'''"] | [complete="true|'''false'''"] | ||
| − | [automaticTimeout="true|'''false'''"]?> | + | [automaticTimeout="true|'''false'''"] |
| + | [viewport="width=device-width,initial-scale=1.0"]?> | ||
| − | It specifies how a page should be handled. The < | + | It specifies how a page should be handled. The <code>id</code> and <code>title</code> arguments are the two most important ones. |
= automaticTimeout = | = automaticTimeout = | ||
| Line 44: | Line 45: | ||
It specifies whether the client can cache the output. | It specifies whether the client can cache the output. | ||
| − | '''Note''': Browsers, such as Firefox and IE, don't handle the cache of DHTML correctly, so it is not safe to specify < | + | '''Note''': Browsers, such as Firefox and IE, don't handle the cache of DHTML correctly, so it is not safe to specify <code>cacheable</code> with true for Ajax devices. |
= complete = | = complete = | ||
| Line 52: | Line 53: | ||
</source> | </source> | ||
| − | It specifies that this page is a complete page. By complete we mean the page has everything that the client expects. For example, if the client is a HTML browser, then a complete page will generate all necessary HTML tags, such as < | + | It specifies that this page is a complete page. By complete we mean the page has everything that the client expects. For example, if the client is a HTML browser, then a complete page will generate all the necessary HTML tags, such as <code><html></code>, <code><head></code> and <code><body></code>. |
| − | By default (false), a ZK page is assumed to be complete ''if and only if'' it is ''not'' included by other page. In other words, if a ZK page is included by other page, ZK will generate < | + | By default (false), a ZK page is assumed to be complete ''if and only if'' it is ''not'' included by other page. In other words, if a ZK page is included by other page, ZK will generate <code>< div></code> (if the client is a HTML browser) to enclose the output of the (incomplete) ZK page.<div> |
| − | If you have a ZK page that contains a complete HTML page and is included by other | + | If you have a ZK page that contains a complete HTML page and is included by other pages, you have to specify <code>true</code> for this option. For example, the includer is nothing but it includes another page: |
<source lang="xml" > | <source lang="xml" > | ||
| Line 83: | Line 84: | ||
[Default: ''depends on the device''] | [Default: ''depends on the device''] | ||
| − | It specifies the content type. If not specified, it depends on the device. For Ajax devices, it is < | + | It specifies the content type. If not specified, it depends on the device. For Ajax devices, it is <code>text/html;charset=UTF-8</code>. For XML and MIL devices, it is <code>text/xml;charset=UTF-8</code>. |
Application developers rarely need to change it, unless for XML devices. | Application developers rarely need to change it, unless for XML devices. | ||
| − | The encoding charset specified here only affects the output of a ZUML document. For | + | The encoding charset specified here only affects the output of a ZUML document. For browsers, it is the HTML page which receives. The encoding of the JavaScript files or CSS files that a HTML page might reference are not affected. |
= docType = | = docType = | ||
| Line 94: | Line 95: | ||
[Default: ''depends on the device''] | [Default: ''depends on the device''] | ||
| − | It specifies the < | + | It specifies the <code>DOCTYPE</code> (the root tag and DTD) that will be generated to the output directly. This directive is mainly used by XML devices. You rarely need to specify the DOCTYPE directive for Ajax or MIL devices. For example, |
| Line 107: | Line 108: | ||
</source> | </source> | ||
| − | Notice that the < | + | Notice that the <code><!DOCTYPE...></code> specified in a ZUML page is processed by ZK Loader. It is not part of the output. |
If an empty string is specified, DOCTYPE won't be generated (since 5.0.5): | If an empty string is specified, DOCTYPE won't be generated (since 5.0.5): | ||
| Line 120: | Line 121: | ||
[Default: ''generated automatically''][EL allowed] | [Default: ''generated automatically''][EL allowed] | ||
| − | Specifies the identifier of the page, such that we can retrieve it back. If an alphabetical identifier is assigned, it will be available to scripts (aka., < | + | Specifies the identifier of the page, such that we can retrieve it back. If an alphabetical identifier is assigned, it will be available to scripts (aka., <code>zscript</code>) and EL expressions embedded in ZUML pages. |
<source lang="xml" > | <source lang="xml" > | ||
| Line 129: | Line 130: | ||
[Optional] | [Optional] | ||
| − | [Default: ''depending on the extension''][Allowed values: < | + | [Default: ''depending on the extension''][Allowed values: <code>xul/html</code> | <code>xhtml</code>] |
| − | Specifies the markup language for this page. The markup language determines the default component set. Currently, it supports < | + | Specifies the markup language for this page. The markup language determines the default component set. Currently, it supports <code>xul/html</code> and <code>xhtml</code>. |
| − | '''Note''': You can place the page directive in any location of a XML document, but the < | + | '''Note''': You can place the page directive in any location of a XML document, but the <code>language</code> attribute is meaningful only if the directive is located at the topmost level. |
= style = | = style = | ||
[Optional] | [Optional] | ||
| − | [Default: < | + | [Default: <code>width:100%</code>] |
[EL allowed] | [EL allowed] | ||
| − | Specifies the CSS style used to render the page. If not specified, it depends on the mold. The default mold uses < | + | Specifies the CSS style used to render the page. If not specified, it depends on the mold. The default mold uses <code>width:100%</code> as the default value. |
<source lang="xml" > | <source lang="xml" > | ||
| Line 154: | Line 155: | ||
Specifies the page title that will be shown as the title of the browser. | Specifies the page title that will be shown as the title of the browser. | ||
| − | It can be changed dynamically by calling the < | + | It can be changed dynamically by calling the <code>setTitle</code> method in the <javadoc type="interface">org.zkoss.zk.ui.Page</javadoc> interface. |
<source lang="xml" > | <source lang="xml" > | ||
<?page title="${param.title}"?> | <?page title="${param.title}"?> | ||
| + | </source> | ||
| + | |||
| + | = viewport = | ||
| + | {{versionSince | 6.5.0}} | ||
| + | [Optional] | ||
| + | [Default: ''auto''] | ||
| + | [EL allowed] | ||
| + | |||
| + | |||
| + | Specifies the page viewport that will define the resolution and scale on browsers. ZK only generates this when it detects a mobile browser. | ||
| + | |||
| + | It can be changed dynamically by [https://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/Page.html#setViewport-java.lang.String- Page.setViewport()]. | ||
| + | |||
| + | <source lang="xml" > | ||
| + | <?page viewport="width=device-width,initial-scale=1.0,maximum-scale=5.0"?> | ||
</source> | </source> | ||
| Line 178: | Line 194: | ||
[Default: ''none''] | [Default: ''none''] | ||
| − | Specifies the < | + | Specifies the <code>xml</code> processing instruction (i.e., <code><?xml?></code>) that will be generated to the output. Currently only XML devices support this option. |
For example, | For example, | ||
| Line 195: | Line 211: | ||
[Optional] | [Optional] | ||
| − | [Default: < | + | [Default: <code>Java</code>][Allowed values: <code>Java</code> | <code>JavaScript</code> | <code>Ruby</code> | <code>Groovy</code>] |
| − | Specifies the default scripting language, which is assumed if an < | + | Specifies the default scripting language, which is assumed if an <code>zscript</code> element doesn't specify any scripting language explicitly. |
<source lang="xml" > | <source lang="xml" > | ||
| Line 223: | Line 239: | ||
| October, 2010 | | October, 2010 | ||
| The widgetClass attribute was introduced. | | The widgetClass attribute was introduced. | ||
| + | |- | ||
| + | | 6.5.0 | ||
| + | | September, 2012 | ||
| + | | The viewport attribute was introduced. | ||
|} | |} | ||
{{ZUMLReferencePageFooter}} | {{ZUMLReferencePageFooter}} | ||
Latest revision as of 12:11, 17 May 2022
Syntax:
<?page [id="..."] [title="..."] [style="..."] [cacheable="false|true"] [language="xul/html"] [zscriptLanguage="Java"] [contentType="text/html;charset=UTF-8"] [docType="tag PUBLIC "doctype name" "doctype UI""] [widgetClass="..."] [xml="version="1.0" encoding="UTF-8""] [complete="true|false"] [automaticTimeout="true|false"] [viewport="width=device-width,initial-scale=1.0"]?>
It specifies how a page should be handled. The id and title arguments are the two most important ones.
automaticTimeout
[Optional] [Since 3.6.3] [Default: the applicatioin default]
It specifies whether to automatically redirect to the timeout URI. If it is false, a page will be redirected to the timeout URI when the user takes some action after timeout. In other words, nothing would happen if the user does nothing.
If omitted, whether to automatically timeout depends on the application's configuration. Please refer to ZK Configuration Reference: session-config.
A typical use is to turn off the automatic timeout for the timeout page (otherwise, it will be reloaded again after the session is timeout again). For example,
<!-- my timeout page -->
<?page automaticTimeout="false"?>
<zk>
You didn't access for a while. Please login again.
</zk>
Of course, you don't need to do anything, if the timeout page is not a ZUML page.
cacheable
[Optional] [Default: false if Ajax devices, true if XML and MIL devices]
It specifies whether the client can cache the output.
Note: Browsers, such as Firefox and IE, don't handle the cache of DHTML correctly, so it is not safe to specify cacheable with true for Ajax devices.
complete
[Optional][Default: false]
It specifies that this page is a complete page. By complete we mean the page has everything that the client expects. For example, if the client is a HTML browser, then a complete page will generate all the necessary HTML tags, such as <html>, <head> and <body>.
By default (false), a ZK page is assumed to be complete if and only if it is not included by other page. In other words, if a ZK page is included by other page, ZK will generate < div> (if the client is a HTML browser) to enclose the output of the (incomplete) ZK page.
If you have a ZK page that contains a complete HTML page and is included by other pages, you have to specify true for this option. For example, the includer is nothing but it includes another page:
//includer.jsp
<jsp:include page="includee.zhtml"/>
And, the included page contains a complete HTML page:
<?page complete="true"?>
<html xmlns="http://www.zkoss.org/2005/zk/native">
<head>
<title>My Title</tile>
</head>
<body>
My Content
</body>
</html>
contentType
[Optional] [Default: depends on the device]
It specifies the content type. If not specified, it depends on the device. For Ajax devices, it is text/html;charset=UTF-8. For XML and MIL devices, it is text/xml;charset=UTF-8.
Application developers rarely need to change it, unless for XML devices.
The encoding charset specified here only affects the output of a ZUML document. For browsers, it is the HTML page which receives. The encoding of the JavaScript files or CSS files that a HTML page might reference are not affected.
docType
[Optional] [Default: depends on the device]
It specifies the DOCTYPE (the root tag and DTD) that will be generated to the output directly. This directive is mainly used by XML devices. You rarely need to specify the DOCTYPE directive for Ajax or MIL devices. For example,
<?page docType="svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd""?>
will cause the output to be generated with the following snippet
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"">
Notice that the <!DOCTYPE...> specified in a ZUML page is processed by ZK Loader. It is not part of the output.
If an empty string is specified, DOCTYPE won't be generated (since 5.0.5):
<?page docType="" ?>
id
[Optional] [Default: generated automatically][EL allowed]
Specifies the identifier of the page, such that we can retrieve it back. If an alphabetical identifier is assigned, it will be available to scripts (aka., zscript) and EL expressions embedded in ZUML pages.
<?page id="${param.id}"?>
language
[Optional] [Default: depending on the extension][Allowed values:xul/html|xhtml]
Specifies the markup language for this page. The markup language determines the default component set. Currently, it supports xul/html and xhtml.
Note: You can place the page directive in any location of a XML document, but the language attribute is meaningful only if the directive is located at the topmost level.
style
[Optional]
[Default: width:100%]
[EL allowed]
Specifies the CSS style used to render the page. If not specified, it depends on the mold. The default mold uses width:100% as the default value.
<?page style="width:100%;height:100%"?>
title
[Optional] [Default: none][EL allowed]
Specifies the page title that will be shown as the title of the browser.
It can be changed dynamically by calling the setTitle method in the Page interface.
<?page title="${param.title}"?>
viewport
Since 6.5.0
[Optional] [Default: auto] [EL allowed]
Specifies the page viewport that will define the resolution and scale on browsers. ZK only generates this when it detects a mobile browser.
It can be changed dynamically by Page.setViewport().
<?page viewport="width=device-width,initial-scale=1.0,maximum-scale=5.0"?>
widgetClass
[Options] [Default: depending on the device] [EL allowed] [Since 5.0.5]
Specifies the widget class of this page. If not specified, the device's default is assumed. For example, the Ajax device's default is Page.
<?page widgetClass="foo.MyPage"?>
xml
[Optional] [Default: none]
Specifies the xml processing instruction (i.e., <?xml?>) that will be generated to the output. Currently only XML devices support this option.
For example,
<?page xml="version="1.0" encoding="UTF-8""?>
will generate the following as the first line of the output
<?xml version="1.0" encoding="UTF-8"?>
zscriptLanguage
[Optional] [Default:Java][Allowed values:Java|JavaScript|Ruby|Groovy]
Specifies the default scripting language, which is assumed if an zscript element doesn't specify any scripting language explicitly.
<?page zscriptLanguage="JavaScript"?>
<zscript>
var m = round(box.value); //JavaScript is assumed.
</zscript>
If this option is omitted, Java is assumed. Currently ZK supports four different languages: Java, JavaScript, Ruby and Groovy. This option is case insensitive.
Note: Deployers can extend the number of supported scripting languages. Please refer to ZUML Reference for more details.
Version History
| Version | Date | Content |
|---|---|---|
| 5.0.5 | October, 2010 | If empty, DOCTYPE won't be generated. |
| 5.0.5 | October, 2010 | The widgetClass attribute was introduced. |
| 6.5.0 | September, 2012 | The viewport attribute was introduced. |