ui:popup

This element generates a Javascript function that opens another page as popup window. The contents of this page are generated at the time the ui:popup element is expanded, which means that the popop window can only contain simple dialogs that are constant from the perspective of the main window. The element ui:server-popup is able to create fully dynamic popup windows, however.

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 a string argument which is the window option list known from the Javascript window.open function; it specifies the visual properties of the new window. By calling the generated function, the window pops up and displays the constant material found in the referenced page. For example, the following button shows the page sample in a new popup window with the specified width and height:

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

The page, here sample, must set the attribute popup to yes:

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

This is necessary because the generated HTML code is slightly different from that of normal pages.

The popup window can include interactors like text boxes, selection lists, etc., as well as buttons and hyperlinks. The interactors are handled as if they occured on the main window. When pressed, the buttons and hyperlinks close the popup window, and submit the main window. This is very important: Popup windows are not independent of the main window, but they are rather an extension of the main window that is first hidden, and only exhibited on request of the user. Both windows form a unit, and can only be processed as a whole by the WDialog toolkit.

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.

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.

Declaration

Level: Generative element

<!ELEMENT ui:popup EMPTY>

<!ATTLIST ui:popup
          page  NMTOKEN  #REQUIRED>

It is required that there is a ui:form in the current page; however, the ui:popup element can occur outside the ui:form element.

Attributes

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.

Example

<ui:dialog name="enter-your-name" start-page="main">
  <ui:variable name="your-name"/>

  <ui:page name="main">
    <html>
      <ui:popup page="popup"/>
      <body>
        <ui:form onsubmit="return lock_popup()">
          Your name is: $[your-name]
          <input type="button" value="Change"
                 onclick="open_popup('width=200,height=200')"/>
          <br/>
          <ui:button name="main_ok" label="OK"/>
        </ui:form>
      </body>
    </html>
  </ui:page>

  <ui:page name="popup" popup="yes">
    <html>
      <body>
        <ui:form>
          Enter your name:
          <ui:text variable="your-name"/><br/>
          <ui:button name="popup_ok" label="OK"/>
          <input type="button" value="Cancel" onclick="window.close()"/>
        </ui:form>
      </body>
    </html>
  </ui:page>
</ui:dialog>

In this example, the main page shows the current name of the user only as string constant. In order to change it, the user must press the "Change" button, which opens the popup window containing the text box. When the user presses "OK" in the popup window, the new user name is put into the variable, the popup window is closed, and the main window is redisplayed (because of form submission). When the user presses "Cancel" in the popup window, the popup window is closed, and the new name is ignored.

When the popup window is open, the "OK" button of the main window is locked because of the ONSUBMIT handler.

Further Questions

I want that the popup window behaves differently depending on user interactions in the main window. How do I do this? Either you can program the special behavior fully in Javascript, or you use ui:server-popup instead. The latter element causes that the popup window is generated after the open_popup function is called, and goes back to the server for this.

Can I define my own ONSUBMIT handler for the popup window? It is not allowed to set the ONSUBMIT attribute of the ui:form element in popup windows. This attribute is reserved for WDialog. However, you can modify the handler after WDialog has set its own handler. Execute after the whole ui:form element these Javascript statements:

var wd_onsubmit = document.uiform.onsubmit;
document.uiform.onsubmit = my_handler;

Furthermore, program your own handler my_handler:

function my_handler () {
   ...
   // If you do not want form submission:
   return false;
   ...
   // If you do want form submission:
   return wd_onsubmit();
}