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:

When the user clicks on a button or a hyperlink, this event causes that the handle callback of the dialog object is invoked. At this time, the current page is still the old page, and the next page is the designated new page (either the again the old page, or the page specified by the goto attribute of the button or hyperlink element). The callback method can now change the name of the next page.
Now the page change occurs: The name of the next page is stored in the variable containing the name of the current page.
The prepare_page callback is invoked, and at this moment, the current page is the new page. (You can still ask the dialog object for the "next page"; however it will simply return the current page as there is currently no next page.)
The final HTML document is created by expanding the current page until all templates are instantiated. This document is sent back to the browser.

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

name: Specifies the name of the page. The name must be unique among all page of the current dialog.
from-caller: Lists the parameters with lexical scope that occur inside the page body.
from-context: Lists the parameters with dynamic scope that occur inside the page body.
popup: If "yes", it is allowed that this page is the target of a ui:popup or ui:server-popup.

Sub elements

The sub elements %page-body; of ui:page are either HTML elements, or the following ui elements that generate HTML elements.