popup

Popups act like a hybrid of a label, a button, and a list. Unopened, a popup occupies only the space required for its label plus a small activation button. Open, the popup displays a list of selections and actions. A popup displays its label until the user makes a selection. After the user chooses a selection or an action, the list closes and the popup displays the label of the selected cell or xforms:item.

Available options

acclabel, activated, active, bgcolor, border, borderinfo, focused, fontcolor, fontinfo, format, group, help, itemlocation, itemnext, itemprevious, justify, keypress, label, mouseover, next, previous, printbgcolor, printfontcolor, printvisible, readonly, size, suppresslabel, value, visible, xformsenabled, xformsreadonly, xformsrequired, xformsvalid, xforms:select1

Examples

This is an example of a popup that allows the user to select the gender of a patient. The example shows a fragment of an XForms instance and an XFDL popup item, both of which are inside the same form. The XForms fragment contains an empty gender element. The gender element remains empty until the user makes a selection from the popup list.

<xforms:instance id="Patient">
   <record xmlns="">
      <patient>
         <name>Jane Doe</name>
         <gender></gender> <!-- empty until a selection is made, then F or M -->
         ...
      </patient>
   </record>
</xforms:instance>
...
<popup sid="Gender">
   <xforms:select1 ref="patient/gender" appearance="minimal">
      <xforms:label>Patient Gender</xforms:label>
      <xforms:item>
         <xforms:label>Female</xforms:label>
         <xforms:value>F</xforms:value>
      </xforms:item>
      <xforms:item>
         <xforms:label>Male</xforms:label>
         <xforms:value>M</xforms:value>
      </xforms:item>
   </xforms:select1>
</popup>

Because the data node that is referenced by the XPath expression patient/gender is empty, the popup displays the text in the <xforms:select1>/<xforms:label>, which is Patient Gender. Clicking on the popup opens a list that displays Female and Male. When the user selects one of the list items, the value is stored in the XForms model and the popup displays the label associated with the selection. In the example, if the user selects Female, the text F is stored in the node patient/gender and the text Female is displayed in the popup.

The popup list can also be populated with data from an XForms instance, as follows:

...
<xforms:instance id="Patient">
   <record xmlns="">
      <patient>
         <name>Jane Doe</name>
         <gender></gender> <!-- empty until a selection is made, then F or M -->
         ...
      </patient>
   </record>
</xforms:instance>
...
<xforms:instance id="Genders">
   <genders xmlns="">
      <gender label="Female" code="F"/>
      <gender label="Male" code="M"/>
   </genders>
</xforms:instance>
...
<popup sid="Gender">
   <xforms:select1 ref="patient/gender" appearance="minimal">
      <xforms:label>Patient Gender</xforms:label>
      <xforms:itemset nodeset="instance('Genders')/gender">
         <xforms:label ref="@label"/>
         <xforms:value ref="@code"/>
      </xforms:itemset>
   </xforms:select1>
</popup>

This allows you to dynamically update the popup list by updating the <xforms:instance id="Genders"> element with Web service results obtained by an <xforms:submission> or by XForms actions such as <xforms:insert> and <xforms:delete>.

For examples of list entries that trigger actions, see the XFDL cell item.

Usage details

1. Use of the non-XForms version of this item is deprecated because it does not work when placed in a pane or table. Form authors are encouraged to use this item with its XForms element even when not placed in a pane or table in order to maximize form maintainability.
2. The popup displays its label if no value is set. If a popup does not have a label or a value, the popup displays no text.
3. When a popup is activated, it displays a list that is generated from the <xforms:label> strings obtained from the <xforms:item> elements or from the <xforms:itemset> element. When cell items are used with the popup instead of <xforms:select1>, the list is generated from the cell labels.
4. You must use appearance="minimal" in the <xforms:select1> element.
5. If you want the popup to display the value instead of the label, use the xfdl:showvalue attribute and set it to true. In the examples, <xforms:select1 ref="patient/gender" appearance="minimal" xfdl:showvalue="true"> causes the popup to display F instead of Female.
6. To get the value of a popup when using <xforms:select1>, dereference it in the following manner:

   page_sid.popup_sid.value
   

   For example:

   compute="PAGE1.Gender.value"
   

7. When cell items are used instead of <xforms:select1>, the value of the popup is empty unless the selected cell is a select type (the default), in which case you can obtain the value of the popup by using the dereference operator as follows:

   page_sid.popup_sid.value->value

   Similarly, to obtain the <label> of the selected cell:

   page_sid.popup_sid.value->label

   Similarly, to obtain the sid of the selected cell:

   page_sid.popup_sid.value

8. When setting the size option of a popup, the height and width of the popup is based on the average character size for the font that is in use.
9. In Webform Server, popups have type-ahead search functionality. For example, in a popup menu containing the names of countries, you can type "ca" in the popup to immediately find "Cameroon" and other country names with the same starting letters. This function is not available in the Viewer.