 [UP] The UI language |
The element ui:page Every dialog object consists of one or several pages, which are the HTML documents visualizing the state of the object. When the web browser sends a request to the WDialog system, the reply is one of the pages of the current dialog object. Because of this, pages are the units of communications to the browser. For example, the following page defines a minimal HTML document:
<ui:page name="sample">
<html>
<head>
<title>This is a sample page</title>
</head>
<body>
This is the body of the sample page.
</body>
</html>
</ui:page>
The dialog object stores the name of the current page, and this name is used to select the page replied to the browser. In detail, the dialog object distinguishes between the current page and the next page. This can be explained by illustrating the actions taken by the WDialog system to display the next page:
For instance, there is a possible page change from sample1 to sample2 in the following example:
<ui:page name="sample1">
<html>
<head>
<title>This is sample page 1</title>
</head>
<body>
<ui:a name="mylink" goto="sample2">Click here to go to page 2</ui:a>
</body>
</html>
</ui:page>
<ui:page name="sample2">
<html>
<head>
<title>This is sample page 2</title>
</head>
<body>
This is the body of the sample page 2.
</body>
</html>
</ui:page>
It is assumed that the dialog object starts with sample1. This page contains a
hyperlink (ui:a) with a goto attribute pointing to
sample2. When the user clicks on this hyperlink, the current page is sample1,
and the designated next page is sample2. The handle callback of the
dialog object can now change the name of the next page if this is required for
some reason. Unless this actually happens, the next page remains to be sample2,
and the current page changes to sample2. The prepare_page callback
will already find that sample2 is the current page. Finally, sample2 is
displayed as the next page on the browser window.
The first page of a dialog object can be specified in the start-page attribute of the ui:dialog element. Example: <ui:dialog name="sampleobject" start-page="sample1"> <!-- Now ui:pages sample1 and sample2 --> ... </ui:dialog> A page is a template that is called by WDialog. It may contain template parameters, and it can declare parameters using from-caller and from-context. For example, the following page displays the sentence specified in the parameter s five times:
<ui:page name="repeater" from-caller="s">
<ui:default name="s">
I have to write this sentence five times.
</ui:default>
<html>
<body>
$s $s $s $s $s
</body>
</html>
</ui:page>
Note that the usual rules for template parameters apply: The ui:default
element defines the default value of the parameter which is used if there
is no directly passed parameter value. As pages are automatically called, it is
not possible to pass parameters directly to pages. Because of this, the default
value is always taken by the system.This simply means: In the context of pages, it is possible to bind a parameter p locally to a value v by including the statement <ui:default name="p">v</ui:default>at the beginning of the ui:page element, and by declaring p using from-caller="p". It is also possible that several pages share parameters. The shared parameters must be defined in the ui:context section of the dialog object, and the parameters must be imported by from-context. Example:
<ui:dialog name="sample" start-page="sample1">
<ui:context>
<ui:param name="bgcolor">#342312</ui:param>
</ui:context>
<ui:page name="sample1" from-context="bgcolor">
<html>
<body bgcolor="$bgcolor">
...
</body>
</html>
</ui:page>
<ui:page name="sample2" from-context="bgcolor">
<html>
<body bgcolor="$bgcolor">
...
</body>
</html>
</ui:page>
</ui:dialog>
In general, the ui:context section specifies the parameter context valid
for the whole dialog; i.e. when the instantiation procedure begins, the current
context for this procedure is initialized with the parameter values defined in
ui:context. Because of this early binding rule, the parameters can also
be imported into pages. - Note that the ui:context section affects all
template instantiations within pages, too; i.e. context parameters can be
imported by any template invoked directly or indirectly from the page.
For general information about templates and the instantiation mechanism, see the Templates section. Declaration Level: Both dialog structure and control structure
<!ELEMENT ui:page ANY>
<!ATTLIST ui:page
name NMTOKEN #REQUIRED
from-caller NMTOKENS #IMPLIED
from-context NMTOKENS #IMPLIES
popup (yes|no) "no"
>
The subelements of ui:page must match the informal rule
( ui:default*, %page-body;* ) where %page-body; stands symbolically
for all allowed sub elements. Note that whitespace between the
%page-body; elements counts, but at the other places it does not count.
Attributes
Sub elements The sub elements %page-body; of ui:page are either HTML elements, or the following ui elements that generate HTML elements. |
