Creating a gallery

You can present media assets in an organized way, using the Gallery widget to display groups of thumbnails, and the Slideshow widget to display the full-sized images. A slideshow may be used alone or may be associated with a gallery. The content for both widgets is defined separately.

Note:

The Client Framework 1 Sample Application contains several examples illustrating the use of the Gallery and Slideshow widgets.

Visual appearance

The Gallery widget displays thumbnails of items from a specified set. Its appearance, including the number of items being displayed on a single page, can be controlled using XDIME 2 elements.

The Slideshow widget presents one item at a time, and you can specify transition effects to be used when the user switches between items. The Slideshow widget may initially be hidden, and displayed on the user's request.

User interactions

A user previewing the gallery can switch to the next or previous group of items using navigation buttons. In addition, he can select an item from the gallery to be displayed in the associated slideshow. The Slideshow widget may already be visible, or it can be embedded in the Popup widget and appear when requested. Users can pause or resume the slideshow presentation, and go to the next or return to the previous item.

Gallery display

The gallery:gallery element is the display container for the thumbnail images. The items attribute identifies the set of gallery items to be displayed in the gallery, and the gallery:item-display elements provide display placeholders for a group of items.

The optional slideshow attribute contains the identifier of the Slideshow widget to be used. To show slides in a popup you use a slideshow-popup attribute instead. This identifies the Popup widget that will display the slideshow on request. If the slideshow attribute is not specified and the summary element contains a link, then clicking on the element allows users to open the link.

You can use item and page numbers and counts such as gallery:start-item-number and gallery:page-count to show a user's progress through the gallery.

The widget:previous and widget:next elements allow users to navigate to the previous or next group of items.

<?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"
  xmlns:gallery="http://www.volantis.com/xmlns/2006/10/gallery-widget">
  <head>
    <title>Gallery Widget with AJAX</title>
  </head>
  <body>
    <div>
      <gallery:items>
        <widget:load src="http://localhost:8080/mcs/projects/client-app/service/itemgallery"
          when="defer"/>
      </gallery:items>
    </div>
    <table>
      <tr>
        <td>
          <gallery:gallery class="widget" slideshow="slideshow" slideshow-popup="gallery-popup">
            <div>
              <table>
                <tr>
                  <td>
                    <widget:previous>&lt;&lt;</widget:previous>
                  </td>
                  <td>
                    <gallery:item-display/>
                  </td>
                  <td>
                    <gallery:item-display/>
                  </td>
                  <td>
                    <widget:next>&gt;&gt;</widget:next>
                  </td>
                </tr>
              </table>
            </div>
            <div>Displaying items from <gallery:start-item-number/> to <gallery:end-item-number/> of
              <gallery:items-count/></div>
            <div>Page number: <gallery:page-number/> of <gallery:pages-count/></div>
          </gallery:gallery>
        </td>
      </tr>
      <tr>
        <td>
          <widget:popup id="gallery-popup">
            <gallery:slideshow id="slideshow">
              <gallery:item-display/>
              <widget:previous>&lt;&lt;</widget:previous>
              <widget:pause>Pause</widget:pause>
              <widget:play>Play</widget:play>
              <widget:next>&gt;&gt;</widget:next>
              <widget:dismiss>Close</widget:dismiss>
              <div>Displaying item <gallery:item-number/> of <gallery:items-count/></div>
            </gallery:slideshow>
          </widget:popup>
        </td>
      </tr>
    </table>
  </body>
</html>

Slideshow display

The gallery:slideshow element may be embedded statically on the page, or contained in a Popup widget.

If this is a standalone slideshow you need to refer to the gallery:items element with an items attribute.

You use the widget:next and widget:previous elements to provide navigation, and widget:play, widget:pause, and widget:stop elements to control the show.

<widget:popup id="gallery-popup">
  <gallery:slideshow id="slideshow">
    <gallery:item-display/>
    <widget:previous>&lt;&lt;</widget:previous>
    <widget:pause>Pause</widget:pause>
    <widget:play>Play</widget:play>
    <widget:next>&gt;&gt;</widget:next>
    <widget:dismiss>Close</widget:dismiss>
    <div>Displaying item <gallery:item-number/> of <gallery:items-count/></div>
  </gallery:slideshow>
</widget:popup>

Defining content

The gallery:items element specifies a set of items to be displayed, each represented by a gallery:item element. The contained widget:summary element specifies the thumbnail content, and the widget:detail contains the slideshow version.

<gallery:items>
  <gallery:item>
    <widget:summary style="mcs-effect-style:fade">
      <object src="/img1_small.mimg"/>
    </widget:summary>
    <widget:detail style="mcs-effect-style:slide-left">
      <object src="/img1.mimg"/>
    </widget:detail>
  </gallery:item>
  <gallery:item>
    <widget:summary style="mcs-effect-style:fade">
      <object src="/img2_small.mimg"/>
    </widget:summary>
    <widget:detail style="mcs-effect-style:slide-left">
      <object src="/img2.mimg"/>
    </widget:detail>
  </gallery:item>
</gallery:items>

The widget:load element can be used to load content of the gallery from an external source. If the when attribute is set to 'defer', then the items will be loaded when user requests the gallery to display the next item, or block of items. If the when attribute is set to 'onload', all items will be loaded immediately.

<gallery:items>
  <widget:load src="service/itemgallery" when="defer"/>
</gallery:items>

The body of the widget response used to replace existing content can contain only one gallery:items element. The count attribute specifies the total number of items in the gallery. It is required unless items are defined directly on the XDIME page. In such cases it must be unspecified.

It is possible to load a subset of items by specifying URL query parameters. The mcs-start parameter defines the number of the first item to load. The default value is 1. The mcs-end parameter defines number of the last item to load. The default value equals to the total number of items. If the range of requested items exceeds the actual number of items in the gallery, only the existing items will be sent returned.

The request should have the following form.

http://www.mygallery.com?mcs-start=7&mcs-end=8

In this case, response will return a list of two items, together with information that the total number of items is equal to 2.

<?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:widget="http://www.volantis.com/xmlns/2006/05/widget"
  xmlns:response="http://www.volantis.com/xmlns/2006/05/widget/response"
  xmlns:gallery="http://www.volantis.com/xmlns/2006/10/gallery-widget">
  <response:head>
    <response:link rel="mcs:theme" href="/main.mthm"/>
  </response:head>
  <response:body>
    <gallery:items count="2">
      <gallery:item>
        <widget:summary style="mcs-effect-style:fade">
          <object src="/img1_small.mimg"/>
        </widget:summary>
        <widget:detail style="mcs-effect-style:slide-left">
          <object src="/img1.mimg"/>
        </widget:detail>
      </gallery:item>
      <gallery:item>
        <widget:summary style="mcs-effect-style:fade">
          <object src="/img2_small.mimg"/>
        </widget:summary>
        <widget:detail style="mcs-effect-style:slide-left">
          <object src="/img2.mimg"/>
        </widget:detail>
      </gallery:item>
    </gallery:items>
  </response:body>
</response:response>

The summary and detail elements can update their content using AJAX too. The action defining element, i.e. widget:load, widget:refresh or widget:fetch, must be placed inside the widget:block element. Refer to 5.6. More about galleries in the Using the widget library tutorial for further information.

<gallery:items>
  <gallery:item>
    <widget:summary>
      <widget:block>
        <widget:load src="gallery_responses/gallery_summary_1.xdime" when="onload"/>
        <widget:block-content>
          <object src="images/gallery/loading.mimg"/>
        </widget:block-content>
      </widget:block> 
    </widget:summary>
    <widget:detail>
      <widget:block>
        <widget:load src="gallery_responses/gallery_detail_1.xdime" when="onload"/>
      </widget:block> 
    </widget:detail>
  </gallery:item>
<gallery:items>

Supported style properties

The mcs-duration property applied to the gallery:slideshow element defines a time for which single item will be displayed by the Slideshow widget.

The mcs-auto-play property specifies if the slideshow should be automatically started when the XDIME page is loaded. The mcs-slideshow-launch-delay property controls the time, after which the slideshow presentation will be automatically launched, if there is no activity in the Gallery widget.

The mcs-items-order property allows authors to specify if the slideshow should present the items in the normal, reverse or random order. The mcs-repetitions property controls the number of slideshow repetitions.

Effect values that define the appearing and disappearing effects, specified on the widget:summary element will be used by the Gallery widget, while styles specified on widget:detail element will be used by the Slideshow widget.

The mcs-button-style property allows authors to control the styling of the buttons such as widget:previous, widget:next, widget:play, widget:pause, widget:stop. In native mode, the buttons are rendered by the device using its native styling. In custom mode the page author has full control over the styling via an image policy, for example.

<widget:next style="content: 'Next'; mcs-button-style: custom"/>
<widget:next style="content: mcs-component-url('next.mimg'); mcs-button-style: custom"/>

The :mcs-disabled pseudo-class allows you style elements, such as widget:next and widget:play as disabled. For example, widget:next is disabled if the end of the gallery is reached.

Non-client fallback

If the Gallery and Slideshow widgets are not supported on a given device, they will not appear on the page. You will have to prepare alternative XDIME pages for such devices.