This element generates a Javascript function that opens another page as popup window. The contents of this page are generated after the function has been called, and it is even possible to intercept the popup request from O'Caml/Perl because a Popup_request event is triggered just before page generation. There is also a simpler variant of popup windows that does not go to the server to get the popup page: ui:popup.

The generated Javascript function has the name popup_<page> where <page> is the identifier found in the page attribute (see declaration below). The function takes two string arguments. The first argument is the window option list known from the Javascript window.open function; it specifies the visual properties of the new window. The second argument is an arbitrary string that is attached to the Popup_request event. By calling the generated function, the window pops up and requests the referenced page from the server. For example, the following button shows the page sample in a new popup window with the specified width and height, and attaches the string fourty-two to the popup request event:

<ui:popup page="sample"/>
<input type="button" onclick="open_sample('width=100,height=100', 'forty-two')"/>

<ui:page name="sample" popup="yes">
  ...
</ui:page>

After the Javascript function has been called, the following actions happen in turn:

• The current dialog object is copied, and the duplicate is used to generate the popup window. Note that the dialog variables are not updated from the interactors, i.e. the copied dialog has the same state as the original had when the main window was generated.

• The Popup_request event is sent to the copied dialog, and it can be caught from the handle method. It is allowed that the handle method changes the name of the popup page to be displayed (by raising Change_page, or calling set_next_page). It is not allowd that the handle method changes the dialog object, though.

• Of course, the prepare_page method is invoked, too.

• Finally, the popup page is generated.

Keep in mind that the dialog object is copied for the time of the popup generation. If the main window is submitted, the original object will continue to be the active object, and the duplicate is silently dropped. If the popup window is submitted, however, the original object will be dropped, and the copy will be used instead for all future interactions!

The popup window can include interactors like text boxes, selection lists, etc., as well as buttons and hyperlinks. If the popup window is submitted, the variables of the duplicated dialog are updated from the interactors of the popup page, the popup window is closed, the main window is discarded (!), the trigerred event is sent to the dialog, and the resulting page will be displayed in the main window using the copied dialog object as current object. Note that these actions are very different from what happens for submitted popup windows generated by ui:popup. Especially, the interactors of the main page are not used to update any dialog variables.

If the main window is submitted when there is an open popup window, the popup window is closed, and the underlying duplicated dialog object is discarded.

It is only possible to have one open popup window at the same time. Trials to open more than one popup window are silently ignored.

The popup window is automatically closed when any submit button or hyperlink of the main window is pressed, or when the page currently displayed in the main window is left by other means. In these cases, the user interactions in the popup window are ignored, and the copied dialog object is dropped.

It is possible to change this behavior by additional Javascript statements:

• You can close the popup window by calling window.close() from the popup window, or by calling close_popup() from the main window. The user interactions in the popup window will be ignored.

• You can force submission of the popup window by calling uiform_submit() from the popup window.

• You can lock the submission of the main window while a popup window is open by setting the ONSUBMIT handler of the ui:form element of the main window to return lock_popup()

Note that WDialog generates an ONUNLOAD handler for the main window and a ONSUBMIT handler for the popup window.

Level: Generative element

<!ELEMENT ui:server-popup EMPTY>

<!ATTLIST ui:server-popup
          page  NMTOKEN  #REQUIRED>

• page: The name of the page to display in the popup window. It is required that the popup attribute of this page is set to "yes". The Javascript function gets the name open_ plus the name of the opened page, e.g. open_menu if the page is called menu.