8.1. Folding Item

You can use the Client Framework 2 platform to build complex, application level components. A Folding Item component is an example of such a complex component. The component allows page authors to include hidden content that is displayed when the user selects an action. When folded, only the label, and an optional marker indicating that the component can be opened, are displayed. When unfolded, either the hidden content alone, or the label and content are displayed, usually with a 'close' marker. Users can unfold/fold the component by clicking on the label/marker.

This module explains how to create a Folding Item component using the Client Framework 2 components. The following page contains two Folding Item components. The first one is unfolded when the page is initially loaded. The second component is folded when the page is initially loaded. Users can change the state of the components by clicking on their title bars.

Creating a Folding Item component

The following code defines the first Folding Item component.

<ui:box id="fi-summary-1" class="fi-summary">
  <ui:button>
    <ui:inline id="fi-plus-1" initial-displayed-state="false">+</ui:inline>
    <ui:inline id="fi-minus-1" initial-displayed-state="true">-</ui:inline> Europe <cf2:on
      event="cf2:activate">
      <cf2:param name="disp" property="fi-details-1#displayed"/>
      <cf2:param name="dispM" property="fi-minus-1#displayed"/>
      <cf2:param name="dispP" property="fi-plus-1#displayed"/>
        if(!disp.get()) {
          disp.set(true);
          dispM.set(true);
          dispP.set(false);
        } else {
          disp.set(false);
          dispM.set(false);
          dispP.set(true);
        }
    </cf2:on>
  </ui:button>
  <div style="clear: both"/>
</ui:box>

<ui:box id="fi-details-1" class="fi-details" initial-displayed-state="true">
  <div style="mcs-layout: 'layouts/5x2_cf2t.mlyt'">
    
    <div style="mcs-container: '_1_1'">
      <object src="assets/images/icon_games_37.gif">
        <param name="mcs-transcode" value="false"/>
      </object>
    </div>
    
    <div style="mcs-container: '_1_2'">
      <span class="bTitle">Call to tackle pollution 'role in 50,000 early deaths' </span>
      <mcs:br/>
      <span class="bSubtitle">3/22/10 | ** | 9 comments</span>
    </div>
    
    <div style="mcs-container: '_2_1'">
      <object src="assets/images/ringtones/icon_gen_35-29.gif">
        <param name="mcs-transcode" value="false"/>
      </object>
    </div>
    
    <div style="mcs-container: '_2_2'">
      <span class="bTitle">Yorkshire space enthusiast records Earth using balloon </span>
      <mcs:br/>
      <span class="bSubtitle">3/25/10 | ** | 4 comments</span>
    </div>
    
  </div>
</ui:box>

The following code defines a label and a marker. Users will be able to show/hide the contents of the component by clicking on the label or the marker.

<ui:box id="fi-summary-1" class="fi-summary">
  <ui:button>
    <ui:inline id="fi-plus-1" initial-displayed-state="false">+</ui:inline>
    <ui:inline id="fi-minus-1" initial-displayed-state="true">-</ui:inline> Europe <cf2:on
      event="cf2:activate">
      <cf2:param name="disp" property="fi-details-1#displayed"/>
      <cf2:param name="dispM" property="fi-minus-1#displayed"/>
      <cf2:param name="dispP" property="fi-plus-1#displayed"/>
        if(!disp.get()) {
          disp.set(true);
          dispM.set(true);
          dispP.set(false);
        } else {
          disp.set(false);
          dispM.set(false);
          dispP.set(true);
        }
    </cf2:on>
  </ui:button>
  <div style="clear: both"/>
</ui:box>

The ui:button element defines a button-like control. It contains two ui:inline elements. The ui:inline element with the id attribute set to 'fi-plus-1' contains a plus sign (+). Please note that its initial-displayed-state attribute is set to 'false'. The attribute specifies the initial displayed state of the element. Setting the value of the attribute to 'false' will prevent the element from being displayed when the page is initially loaded. The ui:inline element with the id attribute set to 'fi-minus-1' contains a minus sign (-). Its initial-displayed-state attribute is set to 'true', which means that the element will be displayed when the page is initially loaded. The plus sign indicates that the component is folded; the minus sign indicates that the component is unfolded.
The cf2:on element registers the cf2:activate event on the enclosing ui:button element.

When the user clicks on the label/marker for the first time, the following things will happen:
- The displayed property of the ui:inline element with the id attribute set to 'fi-minus-1' will be changed to 'false', i.e. the minus sign will be hidden. At the same time the displayed property of the ui:inline element with the id attribute set to 'fi-plus-1' will be changed to 'true', i.e. the plus sign will be displayed.
- The displayed property of the ui:box element with the id attribute set to 'fi-details-1' will be changed to 'false', i.e. the contents of the component will be hidden.
The cf2:param elements define the properties, and the JavaScript code is responsible for setting their values.

When the user clicks on the label/marker again, the values of the displayed properties will be changed to the opposite of their current values.

The following code defines the contents that can be shown or hidden. Please note that the initial-displayed-state attribute of the ui:box element is set to 'true', which means that its contents will be displayed when the page is initially loaded.

<ui:box id="fi-details-1" class="fi-details" initial-displayed-state="true">
  <div style="mcs-layout: 'layouts/5x2_cf2t.mlyt'">
    
    <div style="mcs-container: '_1_1'">
      <object src="assets/images/icon_games_37.gif">
        <param name="mcs-transcode" value="false"/>
      </object>
    </div>
    
    <div style="mcs-container: '_1_2'">
      <span class="bTitle">Call to tackle pollution 'role in 50,000 early deaths' </span>
      <mcs:br/>
      <span class="bSubtitle">3/22/10 | ** | 9 comments</span>
    </div>
    
    <div style="mcs-container: '_2_1'">
      <object src="assets/images/ringtones/icon_gen_35-29.gif">
        <param name="mcs-transcode" value="false"/>
      </object>
    </div>
    
    <div style="mcs-container: '_2_2'">
      <span class="bTitle">Yorkshire space enthusiast records Earth using balloon </span>
      <mcs:br/>
      <span class="bSubtitle">3/25/10 | ** | 4 comments</span>
    </div>
    
  </div>
</ui:box>

The second Folding Item component is created in the exact same way. Only the initial-displayed-state attributes are set differently.

<ui:box id="fi-summary-2" class="fi-summary">
  <ui:button>
    <ui:inline id="fi-plus-2" initial-displayed-state="true">+</ui:inline>
    <ui:inline id="fi-minus-2" initial-displayed-state="false">-</ui:inline> World <cf2:on
      event="cf2:activate">
      <cf2:param name="disp" property="fi-details-2#displayed"/>
      <cf2:param name="dispM" property="fi-minus-2#displayed"/>
      <cf2:param name="dispP" property="fi-plus-2#displayed"/>
        if(!disp.get()) {
          disp.set(true);
          dispM.set(true);
          dispP.set(false);
        } else {
          disp.set(false);
          dispM.set(false);
          dispP.set(true);
        }
    </cf2:on>
  </ui:button>
  <div style="clear: both"/>
</ui:box>

<ui:box id="fi-details-2" class="fi-details" initial-displayed-state="false">
  <div style="mcs-layout: 'layouts/5x2_cf2t.mlyt'">
    
    <div style="mcs-container: '_1_1'">
      <object src="assets/images/icon_news_37.gif">
        <param name="mcs-transcode" value="false"/>
      </object>
    </div>
    
    <div style="mcs-container: '_1_2'">
      <span class="bTitle">Ship sunk by Indian navy was a fishing boat, says owner </span>
      <mcs:br/>
      <span class="bSubtitle">9/29/09 | *** | 3 comments</span>
    </div>
    
    <div style="mcs-container: '_2_1'">
      <object src="assets/images/icon_politics_35.gif">
        <param name="mcs-transcode" value="false"/>
      </object>
    </div>
    
    <div style="mcs-container: '_2_2'">
      <span class="bTitle">Militants, pirates may fight over Saudi oil tanker</span>
      <mcs:br/>
      <span class="bSubtitle">9/29/09 | ** | 1 comment</span>
    </div>
    
    <div style="mcs-container: '_3_1'">
      <object src="images/icon_gen_35-23.mimg"/>
    </div>
    
    <div style="mcs-container: '_3_2'">
      <span class="bTitle">Australian government introduces "Fair Work" to parliament </span>
      <mcs:br/>
      <span class="bSubtitle">9/30/09 | **** | 5 comments</span>
    </div>
    
  </div>
</ui:box>

Please compare the code defining the first Folding Item component with the previous code. You should notice that, in the first case, the ui:inline elements are configured in the following way:
```
<ui:inline id="fi-plus-1" initial-displayed-state="false">+</ui:inline>
<ui:inline id="fi-minus-1" initial-displayed-state="true">-</ui:inline>
```
In the second case, the initial-displayed-state properties have the opposite values.
```
<ui:inline id="fi-plus-2" initial-displayed-state="true">+</ui:inline>
<ui:inline id="fi-minus-2" initial-displayed-state="false">-</ui:inline>
```
In other words, in the first case, the '-' sign, indicating that the Folding Item component can be folded, will be displayed when the page is initially loaded, while in the second case the '+' sign, indicating that the Folding Item component can be unfolded, will be displayed.

The same applies to the ui:box elements that contain the details of the components. In the first case, the details will be displayed when the page is initially loaded; in the second case, the details will be initially hidden.
```
<ui:box id="fi-details-1" class="fi-details" initial-displayed-state="true">
```
```
<ui:box id="fi-details-2" class="fi-details" initial-displayed-state="false">
```

Applying transition effects

Effects are visual indicators that an element is changing from one state to another.

The theme contains the following style rules. The first rule associates the 'wipe(top)' effect with the appearance of the element. The second rule associates the same transition effect with the disappearance of the element.

.fi-details:mcs-change(:mcs-concealed, :mcs-displayed) {
  mcs-effect-style: wipe(top);
  mcs-effect-duration: 0.2s;
  mcs-frame-rate: 25hz;      
}

.fi-details:mcs-change(:mcs-displayed, :mcs-concealed) {
  mcs-effect-style: wipe(top);
  mcs-effect-duration: 0.6s;
  mcs-frame-rate: 25hz;      
}

The :mcs-change pseudo-class represents an element whose state has changed from one state to another. The pseudo-class allows page authors to associate transition effects with the change of the state of an element. The states, FROM and TO, are represented as pseudo-classes. Please note that this pseudo-class can only be used with the effect related properties, specifically mcs-effect-style, mcs-effect-duration and mcs-frame-rate, and the following pseudo-classes: :mcs-displayed and :mcs-concealed.
The :mcs-displayed pseudo-class represents an element which is being displayed.
The :mcs-concealed pseudo-class represents an element which is in the concealed state, i.e. when it is not displayed.
The mcs-effect-style property specifies the transition effect to use.

Note:
At present only the 'wipe(top)' effect is supported.
The mcs-effect-duration property specifies the duration in seconds of the effect applied to the element. The default value is 1s.
The mcs-frame-rate property specifies the frequency in Hz that is required when displaying visual effects such as transitions, or scrolling. The default value is 10Hz. The x-client.frame.rate.max device policy sets an overriding maximum limit.

Complete XDIME code

The complete code for the XDIME page follows.

<?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:cf2="http://www.volantis.com/xmlns/2009/07/cf2"
  xmlns:ui="http://www.volantis.com/xmlns/2009/07/cf2/ui"
  xmlns:event="http://www.w3.org/2001/xml-events"
  xmlns:template="http://www.volantis.com/xmlns/marlin-template">
  <head>
    <title>News</title>
    <link rel="mcs:theme" href="/themes/main_cf2t.mthm"/>
    <link rel="mcs:layout" href="/layouts/main_cf2t.mlyt"/>
  </head>
  
  <body>
    
    <div id="title" style="mcs-container: 'title'">
      <div class="glass-bar"/>
      <span>News</span>
    </div>
    
    <div id="content" style="mcs-container: 'content';">
      <div style="mcs-layout: 'layouts/ui_cf2t.mlyt'">
        <div id="ui-content" style="mcs-container: 'ui-content'">
          
          <ui:box id="fi-summary-1" class="fi-summary">
            <ui:button>
              <ui:inline id="fi-plus-1" initial-displayed-state="false">+</ui:inline>
              <ui:inline id="fi-minus-1" initial-displayed-state="true">-</ui:inline> Europe <cf2:on
                event="cf2:activate">
                <cf2:param name="disp" property="fi-details-1#displayed"/>
                <cf2:param name="dispM" property="fi-minus-1#displayed"/>
                <cf2:param name="dispP" property="fi-plus-1#displayed"/>
                  if(!disp.get()) {
                    disp.set(true);
                    dispM.set(true);
                    dispP.set(false);
                  } else {
                    disp.set(false);
                    dispM.set(false);
                    dispP.set(true);
                  }
              </cf2:on>
            </ui:button>
            <div style="clear: both"/>
          </ui:box>
          
          <ui:box id="fi-details-1" class="fi-details" initial-displayed-state="true">
            <div style="mcs-layout: 'layouts/5x2_cf2t.mlyt'">
              
              <div style="mcs-container: '_1_1'">
                <object src="assets/images/icon_games_37.gif">
                  <param name="mcs-transcode" value="false"/>
                </object>
              </div>
              
              <div style="mcs-container: '_1_2'">
                <span class="bTitle">Call to tackle pollution 'role in 50,000 early deaths' </span>
                <mcs:br/>
                <span class="bSubtitle">3/22/10 | ** | 9 comments</span>
              </div>
              
              <div style="mcs-container: '_2_1'">
                <object src="assets/images/ringtones/icon_gen_35-29.gif">
                  <param name="mcs-transcode" value="false"/>
                </object>
              </div>
              
              <div style="mcs-container: '_2_2'">
                <span class="bTitle">Yorkshire space enthusiast records Earth using balloon </span>
                <mcs:br/>
                <span class="bSubtitle">3/25/10 | ** | 4 comments</span>
              </div>
              
            </div>
          </ui:box>
          
          <ui:box id="fi-summary-2" class="fi-summary">
            <ui:button>
              <ui:inline id="fi-plus-2" initial-displayed-state="true">+</ui:inline>
              <ui:inline id="fi-minus-2" initial-displayed-state="false">-</ui:inline> World <cf2:on
                event="cf2:activate">
                <cf2:param name="disp" property="fi-details-2#displayed"/>
                <cf2:param name="dispM" property="fi-minus-2#displayed"/>
                <cf2:param name="dispP" property="fi-plus-2#displayed"/>
                  if(!disp.get()) {
                    disp.set(true);
                    dispM.set(true);
                    dispP.set(false);
                  } else {
                    disp.set(false);
                    dispM.set(false);
                    dispP.set(true);
                  }
              </cf2:on>
            </ui:button>
            <div style="clear: both"/>
          </ui:box>
          
          <ui:box id="fi-details-2" class="fi-details" initial-displayed-state="false">
            <div style="mcs-layout: 'layouts/5x2_cf2t.mlyt'">
              
              <div style="mcs-container: '_1_1'">
                <object src="assets/images/icon_news_37.gif">
                  <param name="mcs-transcode" value="false"/>
                </object>
              </div>
              
              <div style="mcs-container: '_1_2'">
                <span class="bTitle">Ship sunk by Indian navy was a fishing boat, says owner </span>
                <mcs:br/>
                <span class="bSubtitle">9/29/09 | *** | 3 comments</span>
              </div>
              
              <div style="mcs-container: '_2_1'">
                <object src="assets/images/icon_politics_35.gif">
                  <param name="mcs-transcode" value="false"/>
                </object>
              </div>
              
              <div style="mcs-container: '_2_2'">
                <span class="bTitle">Militants, pirates may fight over Saudi oil tanker</span>
                <mcs:br/>
                <span class="bSubtitle">9/29/09 | ** | 1 comment</span>
              </div>
              
              <div style="mcs-container: '_3_1'">
                <object src="images/icon_gen_35-23.mimg"/>
              </div>
              
              <div style="mcs-container: '_3_2'">
                <span class="bTitle">Australian government introduces "Fair Work" to parliament </span>
                <mcs:br/>
                <span class="bSubtitle">9/30/09 | **** | 5 comments</span>
              </div>
              
            </div>
          </ui:box>
          
        </div>
      </div>
    </div>
    
    <div id="footer" style="mcs-container: 'footer'">
      <div class="shadow-bottom-bar"/>
      <div class="glass-bar"/>
      <ul>
        <li>
          <a href="/mcs/projects/examples/cf2/index.xdime">Start Over</a>
        </li>
        <li>
          <a href="/mcs/projects/welcome/welcome.xdime">Home</a>
        </li>
      </ul>
      <div id="copyright">
        <div class="glass-bar"/> &#169; 2011 Antenna Software </div>
    </div>
    
  </body>
</html>

Checklist

Client Framework 2 Components

Name	Purpose
Box	This component can be used to build low level custom components.
Button	A button-like control used by the Client Framework 2.
Inline	Adds extra structure to documents.
cf2:OnEventHandler	Specifies an event handler on a component.
cf2:ui.DynamicProperties#Displayed	Determines whether a component is displayed or not. When the property is set to 'true', the component is in the displayed state. When the property is set to 'false', then the component is in the concealed state, i.e. it is not displayed.

XDIME Elements

Name	Purpose
body	Contains the document's content.
div	A section used to add extra structure to documents. Style sheets can be used to control the presentation.
html	The container for the XDIME 2 document.
li	A list item in an ordered, unordered or navigation list.
link	Defines a link. Multiple links and relationships may be defined for a single document. Refer to the topic entitled Document relationship links for more information.
object	A reference to a media resource. `Object` allows a variety of media resources to be placed on the rendered page. The resource may be specified as an image policy or a device dependent mime type. `Object` also allows the control of media transcoding to ensure the resource will render on the requesting agent. See References to media for details.
span	Inline element used to set a style.
ul	A list of unordered items.
cf2:on	Registers an event handler on a component.
cf2:param	Defines an optional parameter value passed into the handler's JavaScript method.
ui:box	The box component for the Client Framework 2 user interface.
ui:button	A button-like control used by the Client Framework 2.
ui:inline	An inline element for the Client Framework 2 user interface. It is used to add extra structure to documents.