Hiding and showing content

You can use the Folding Item widget to include hidden content that is displayed when the user selects an action. This content may be downloaded with the initial page, or the download may be deferred until the item is opened - improving page rendering performance.

Visual appearance

When folded, only the label, and a marker indicating that the item can be opened, are displayed. When unfolded, either the hidden content alone, or the label and content are displayed, usually with a 'close' marker.

Note:

The unfolding of the item results in the content with the widget moving to make space for the unfolded item. Folding makes the content move to reclaim the space. The process of folding and unfolding may use transitions.

User interactions

Users can unfold an item by clicking on the label/marker or giving it focus. To fold the item the user can click on the label/marker or remove focus from it or the expanded content. If the label is not to be displayed when the item is unfolded, then a special link is required in the item content. Both unfolding and folding actions can also be called using JavaScript.

XDIME 2 elements

The widget:folding-item defines a widget. widget:summary provides the label of the widget. Clicking the widget:summary label displays the widget:detail, which is initially hidden.

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/2002/06/xhtml2"
  xmlns:widget="http://www.volantis.com/xmlns/2006/05/widget">
  <head>
    <title>widget:folding-item</title>
  </head>
  <body>
    <widget:folding-item>
      <widget:summary>List of cities</widget:summary>
      <widget:detail>
        <ul>
          <li><a href="http://www.ankara-bel.gov.tr">Ankara</a></li>
          <li><a href="http://www.berlin.de">Berlin</a></li>
          <li><a href="http://www.budapest.hu">Budapest</a></li>
          <li><a href="http://www.krakow.pl">Cracow</a></li>
        </ul>
      </widget:detail>
    </widget:folding-item>
  </body>
</html>

The default mode of operation for Folding Item widget is to deliver the folded part of the item in the initial page load. However, you can specify that the item is loaded dynamically when the item is unfolded. The request occurs only the first time the unfold operation occurs. Once loaded, the item content is not requested again unless the page has been reloaded. See Load, refresh and fetch actions for details.

The widget:load element provides a way for the Folding Item widget to load its content on demand.

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/2002/06/xhtml2"
  xmlns:mcs="http://www.volantis.com/xmlns/2006/01/xdime/mcs"
  xmlns:template="http://www.volantis.com/xmlns/marlin-template"
  xmlns:widget="http://www.volantis.com/xmlns/2006/05/widget">
  <head>
    <title>Folding Item Widget with AJAX</title>
    <link rel="mcs:theme" href="/themes/main.mthm"/>
    <link rel="mcs:layout" href="/layouts/main.mlyt"/>
  </head>
  <body>
    <template:apply href="templates/demo-main.xdtpl">
      <template:binding name="title" value="Folding Item w/AJAX"/>
      <template:binding name="content">
        <template:complexValue>
          <div class="widget">
            <widget:folding-item>
              <widget:summary>Ankara</widget:summary>
              <widget:detail>
                <widget:load src="service/folding-item?itemId=Ankara"/>
              </widget:detail>
            </widget:folding-item>
            <widget:folding-item>
              <widget:summary>Beograd</widget:summary>
              <widget:detail>
                <widget:load src="service/folding-item?itemId=Beograd"/>
              </widget:detail>
            </widget:folding-item>
            <widget:folding-item>
              <widget:summary>Cracow</widget:summary>
              <widget:detail>
                <widget:load src="service/folding-item?itemId=Cracow"/>
              </widget:detail>
            </widget:folding-item>
            <widget:folding-item>
              <widget:summary>Vienna</widget:summary>
              <widget:detail>
                <widget:load src="service/folding-item?itemId=Vienna"/>
              </widget:detail>
            </widget:folding-item>
            <widget:folding-item>
              <widget:summary>Zagreb</widget:summary>
              <widget:detail>
                <widget:load src="service/folding-item?itemId=Zagreb"/>
              </widget:detail>
            </widget:folding-item>
          </div>
        </template:complexValue>
      </template:binding>
    </template:apply>
  </body>
</html>

The service response must have the following form. See Widget response structure for more information.

<?xml version="1.0" encoding="UTF-8"?>
<response:response xmlns="http://www.w3.org/2002/06/xhtml2"
  xmlns:mcs="http://www.volantis.com/xmlns/2006/01/xdime/mcs"
  xmlns:response="http://www.volantis.com/xmlns/2006/05/widget/response">
  <response:head>
    <response:link rel="mcs:theme" href="/main.mthm"/>
  </response:head>
  <response:body>
    <response:folding-item>
      <div>Weather conditions in <a href="http://www.wien.gv.at/">Vienna</a>: 22°C,
        chance of thunderstorms</div>
   </response:folding-item>
  </response:body>
</response:response>

The optional ref attribute contains a reference to an anchor element on the page. Please note that the value of the attribute must be prefixed with '#'. When the user unfolds the widget, the page will be scrolled to the selected element. This allows, for example, to easily display the contents of the newly unfolded widget, when the widget is placed at the end of the page.

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/2002/06/xhtml2"
  xmlns:widget="http://www.volantis.com/xmlns/2006/05/widget">
  <head>
    <title>widget:folding-item</title>
  </head>
  <body>
    <div>
      <a id="myF1Locator"></a>
      <widget:folding-item ref="#myF1Locator">
        <widget:summary>List of cities</widget:summary>
        <widget:detail>
          <ul>
            <li><a href="http://www.ankara-bel.gov.tr">Ankara</a></li>
            <li><a href="http://www.berlin.de">Berlin</a></li>
            <li><a href="http://www.budapest.hu">Budapest</a></li>
            <li><a href="http://www.krakow.pl">Cracow</a></li>
          </ul>
        </widget:detail>
      </widget:folding-item>
    </div>
  </body>
</html>

Supported style properties

If you set the mcs-initial-state property on the widget to 'inactive' the content will be hidden, whereas an 'active' setting will display it unfolded. The mcs-toggle-event property describes the event that unfolds the content, with values 'focus' or 'click'.

The :mcs-unfolded psuedo-class, and the ::marker pseudo-element set the style for folded/unfolded markers, i.e. all styles assigned to widget|summary::marker will be applied to a folded marker, and all styles assigned to widget|summary:mcs-unfolded::marker will be applied to an unfolded marker.

The standard float property associated with the ::marker pseudo element controls the position of the marker. If float is set to 'none', or 'left' then the marker is aligned to left, and placed before the summary. If float is set to 'right', then the marker is aligned to right.

Note:

The following expression, widget:summary:mcs-unfolded {display: none}, hides the summary when widget is in unfolded state.

Non-client fallback

If the device does not support the Folding Item widget, then the list of folding items will be rendered as a definition list (dl), so that both title and data will be visible.