pane

A pane is used to contain one of the following:

• A group of items that can be positioned or made visible as a unit, and that can be given a common border or background.
• A switch, which allows you to group items into sets, and then display one set of items at a time to the user.
• An HTML web page.

The pane itself can also have a physical appearance, such as a border or a different background color, that visually groups the items for the user.

Available Options

active, bgcolor, border, borderinfo, first, focused, itemlocation, itemnext, itemprevious, last, label, labelbgcolor, labelfontcolor, labelfontinfo, next, padding, previous, printbgcolor, printlabelbgcolor, printlabelfontcolor, printvisible, suppresslabel, url, visible, xformsenabled, xformsreadonly, xformsrequired, xformsvalid, xforms:group, xforms:switch

Example

The following example shows a data model that we will link to a group of items contained within a pane:

   <xformsmodels>
      <xforms:model>
         <xforms:instance xlmns="" id="customerInfo">
            <customerData>
               <name></name>
               <address>
                  <street></street>
                  <city></city>
                  <country></country>
               </address>
            </customerData>
         </xforms:instance>
      </xforms:model>
   </xformsmodels>

The following pane contains a group of items in an xforms:group that link to the data model:

   <pane sid="Address">
      <xforms:group ref="address">
         <field sid="street">
            <xforms:input ref="street">
               <xforms:label>Street:</xforms:label>
            </xforms:input>
         </field>
         <field sid="City">
            <xforms:input ref="city">
               <xforms:label>City:</xforms:label>
            </xforms:input>
         </field>
         <field sid="Country">
            <xforms:input ref="country">
               <xforms:label>Country:</xforms:label>
            </xforms:input>
         </field>
      </xforms:group>
   </pane>

The following example shows a pane that contains an xforms:switch. This pane creates a "wizard" style form, in which the user completes one section then clicks a button to move to the next section. Each section is enclosed by an xforms:case within the xforms:switch, and each section except the last contains a button that changes the switch to the next case:

   <pane sid="wizard">
      <xforms:switch>
         <xforms:case id="applicantName" selected="true">
            <field sid="firstName">
               <xforms:input ref="applicant/firstname">
                  <xforms:label>Enter your first name:</xforms:label>
               </xforms:input>
            </field>
            <field sid="lastName">
               <xforms:input ref="applicant/lastname">
                  <xforms:label>Enter your last name:</xforms:label>
               </xforms:input>
            </field>
            <button sid="nextCase1">
               <xforms:trigger>
                  <xforms:label>Next</xforms:label>
                  <xforms:toggle case="spouseName" 
                  ev:event="DOMActivate"/>
               </xforms:trigger>
            </button>
         </xforms:case>
         <xforms:case id="spouseName" selected="false">
            <field sid="spouseFirstName">
               <xforms:input ref="spouse/firstname">
                  <xforms:label
                     >Enter the first name of your spouse:</xforms:label>
               </xforms:input>
            </field>
            <field sid="spouseLastName">
               <xforms:input ref="spouse/lastname">
                  <xforms:label
                     >Enter the last name of your spouse:</xforms:label>
               </xforms:input>
            </field>
            <button sid="nextCase2">
               <xforms:trigger>
                  <xforms:label>Next</xforms:label>
                  <xforms:toggle case="address" 
                  ev:event="DOMActivate"/>
            </xforms:trigger>
         </button>
         </xforms:case>
         <xforms:case id="address" selected="false">
            <field sid="street">
               <xforms:input ref="address/street">
                  <xforms:label
                     >Enter your street address:</xforms:label>
               </xforms:input>
            </field>
            <field sid="city">
               <xforms:input ref="address/city">
                  <xforms:label
                     >Enter the city you live in:</xforms:label>
               </xforms:input>
            </field>
         </xforms:case>
      </xforms:switch>
   </pane>

The following example shows a pane that displays a web page. The xforms:group provides the content that is printed and a spacer option for defining the size of the display area.

  <pane sid="PANE1">
     <xforms:group>
        <label sid="LABEL1">
          <value>This is printed.</value>
        </label>
        <spacer sid="vfd_spacer">
          <itemlocation>
            <x>220</x>
            <y>160</y>
          </itemlocation>
        </spacer>
    </xforms:group>
    <url>http://example.com/colorPalette.html</url>
  </pane>                 

Usage details

1. In the Designer, a pane item will always expand to contain the items you place within it, regardless of the size setting. In the Viewer and Webform Server, the size of a pane expands or shrinks according to the items it contains; this happens regardless of the specific size that you set for the pane in the Designer.
2. An item that is contained inside a pane can reference sibling items, as well as items outside of that pane. However, an item that is outside of a pane cannot reference items inside the pane.
3. If a pane is contained within an xforms:repeat, then the pane and all items within the pane are duplicated for each row of the table.
4. The next and previous options in the pane determine which items precede and follow the pane in the tab order, but do not affect the tab order within the pane. Instead, the next and previous options within the items in the pane control the tab order within the pane.
5. The first and last options determine where the focus is initially placed when the user tabs into a pane item.
6. If a pane is not visible, then none of the controls in the pane will be visible, regardless of their state of visibility.
7. If a pane does not have a visible option (or if it is empty), then the signed node binding of the xforms:group helps determine visibility.
8. The size of a pane is determined by the size of the items in the pane. As such, the extent setting in the itemlocation option has no affect on the pane's sizing.
9. The padding option allows you to define how much white space is put around the pane item. Useful when putting a Pane around rows in a table. This option lets you minimize empty space between rows.
   Note: 3 pixels are required to draw a border outside the Pane item.
10. Use the layoutflow option to control if the content is displayed vertically or horizontally.
11. The itemprevious is set as follows:
    • The pane refers to the item that precedes the pane in the build order.
    • The first item in the first row of the pane refers to the pane itself.
    • The item that follows the pane in the build order refers to the last item in the last row of the pane.
12. The itemnext is set as follows:
    • The pane itself refers to the first item in the pane.
    • The last item in the pane refers to the item that follows the pane in the build order.
    • The item that precedes the pane in the build order refers to the pane itself.
13. The label option defaults to the xforms:label of the xforms:group within the pane.
14. Do not use itemprevious to compute the location of an item after an pane . Doing so can break signatures, as the items inside panes receive random scope identifiers at runtime. If you sign the form with a compute resolved to a random sid, the compute is locked to that random sid. If you then re-open the form, the items inside the pane are assigned new random sids, which do not correspond with the sid associated with the compute and breaks the signature.