Dialogs and pages
The user interface definition contained in the index.ui file is divided up into dialogs which are themselves divided up into pages.
A typical index.ui file looks as follows:
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE ui:application PUBLIC "-//NPC//DTD WDIALOG 2.1//EN" ""> <ui:application start-dialog="dlg_A"> <ui:dialog name="dlg_A" start-page="page_1"> <ui:page name="page_1">...</ui:page> <ui:page name="page_2">...</ui:page> ... </ui:dialog> <ui:dialog name="dlg_B" start-page="page_1"> <ui:page name="page_1">...</ui:page> <ui:page name="page_2">...</ui:page> ... </ui:dialog> </ui:application>
The file format is XML-1.0 with the addition that the prefix ui: is pre-bound to all tags defined by the WDialog system (actually, this prefix is used like a namespace prefix; however a namespace declaration for ui: would not be understood by the system); in contrast to this, tags without prefix are used for the generated HTML code. For example:
<ui:page name="page_2"> <html> <body> <h1>This is a HTML page!</h1> ... </body> </html> </ui:page>Here, the tag defining page_2 is part of the WDialog language, and its name ui:page has the prefix, while the contents of page_2 are normal HTML tags lacking this prefix.
A dialog is a container for a piece of the state of the application. Dialogs begin to exist when the user of the application visits the first page, their state is changed when the user fills out forms and presses buttons, and they vanish when the user leaves the application. The lifecycle of a dialog is the series of interactions of one user in one session. Note that dialogs cannot be used to save the state of the application from one session to the next session; for this purpose an appropriate background store (i.e. database) is required, which is beyond the scope of WDialog.
A dialog has instance variables which can be individually referenced and modified. For example, an application to manage phonebooks has dialogs describing entries of the book:
<ui:dialog name="entry" start-page="page_1"> <ui:variable name="person"/> <ui:variable name="number"/> <ui:page name="page_1">...</ui:page> <ui:page name="page_2">...</ui:page> ... </ui:dialog>Note that variables contain strings by default; however, there are other data types which are important in the context of dynamically generated HTML.
It is very natural that an application consists of several types of dialogs, as there are normally different views on the topic the application manages (e.g. the application may display a list of phonebook entries, or a single entry).
The pages of an object define different visualizations of one dialog. This feature can be used to provide different views on the same dialog state, or to split up the state such that every page shows only a subset of all variables.
There is an analogy between dialogs, pages, and variables and the well-known terminology of object-oriented programming:
A page is like a method for the object producing HTML output. For example, we can define a page showing the contents of an entry of a phonebook:
<ui:dialog name="entry" start-page="show"> <ui:variable name="person"/> <ui:variable name="number"/> <ui:page name="show"> <html> <body> <h1>Entry</h1> <b>Person:</b> <ui:dynamic variable="person"/><br/> <b>Number:</b> <ui:dynamic variable="number"/> </body> </html> </ui:page> </ui:dialog>Here, the page "show" outputs the name of the person and the associated number. The code contains the special elements ui:dynamic which are dynamically replaced by the current contents of the variables they are referring to.
We can define another page, input, allowing the user to edit the current contents of the two variables:
<ui:page name="input"> <html> <body> <h1>Entry</h1> <b>Person:</b> <ui:text variable="person"/><br/> <b>Number:</b> <ui:text variable="number"/><br/> <ui:button label="Change" name="change_entry"/> </body> </html> </ui:page>The special elements ui:text generate the HTML code for text input boxes which are initialized with the current values of the two variables. Furthermore, the special element ui:button is transformed to HTML code for a submit button. When the user hits this button, the default behaviour is to update the dialog variables which have been bound to input widgets. In this example, first the contents of the variables person and number are put into the text boxes when the page is displayed by the browser, but after the use has edited them and has pressed the button, the (possibly modified) values of the text boxes are stored back into the variables. This is called automatic update of interactor variables.
This shows an important difference to other web platforms for dynamic content: Input and output are seen as a unit during the whole transaction. It is the job of the toolkit to propagate user input to the corresponding programmable containers (i.e. to the variables). Furthermore, the interactors can be output as HTML in a way such that the link to the container is not lost, which makes the automatic update of variables possible.