WinJS.UI.SemanticZoom object

Article
01/26/2017

Enables the user to zoom between two different views supplied by two child controls. One child control supplies the zoomed-out view and the other provides the zoomed-in view.

Syntax

<div data-win-control="WinJS.UI.SemanticZoom">
     <!-- The control that provides the zoomed-in view goes here. -->
     <!-- The control that provides the zoomed-out view goes here. -->
</div>

var object = new WinJS.UI.SemanticZoom(element, options);

Members

The SemanticZoom object has these types of members:

Constructors
Events
Methods
Properties

Constructors

The SemanticZoom object has these constructors.

Constructor	Description
SemanticZoom	Creates a new SemanticZoom.

Events

The SemanticZoom object has these events.

Event	Description
onzoomchanged	Raised after the control zooms in or out.

Methods

The SemanticZoom object has these methods.

Method	Description
addEventListener Method	Registers an event handler for the specified event.
dispatchEvent	Raises an event of the specified type and with additional properties.
dispose	Releases resources held by this object. Call this method when the object is no longer needed. After calling this method, the object becomes unusable.
forceLayout	Forces the SemanticZoom to update its layout. Use this function when you want to make the SemanticZoom visible again after its style.display property was set to "none".
removeEventListener Method	Removes an event handler for the specified event that the addEventListener method registered.

Properties

The SemanticZoom object has these properties.

Property	Access type	Description
element	Read-only	Gets the DOM element that hosts the SemanticZoom control.
enableButton	Read/write	Gets or a sets a value that specifies whether to display the SemanticZoom zoom-out button. (Not supported on Windows Phone 8.1.)
isDeclarativeControlContainer	Read-only	Gets a value that determines whether any controls contained in a SemanticZoom should be processed separately. This property is always true, meaning that the SemanticZoom takes care of processing its own controls.
locked Property	Read/write	Gets or sets a value that indicates whether SemanticZoom is locked and zooming between views is disabled.
zoomedInItem	Read/write	Gets or sets a mapping function which can be used to change the item that is targeted on zoom in. SemanticZoom
zoomedOut	Read/write	Gets or sets a value that indicates whether the control is zoomed out.
zoomedOutItem	Read/write	Gets or sets a mapping function which can be used to change the item which is targeted on zoom out.
zoomFactor	Read/write	Gets or sets a value that specifies how much scaling the cross-fade animation performs when the SemanticZoom transitions between views.

Remarks

SemanticZoom is used to present two levels of detail for the data or content based on a zoom factor: a zoomed in (detailed) view typically used for presenting individual items and a zoomed out (structured) view for presenting item groups based on metadata. You use two other controls to provide these zoomed-in and zoomed-out views. One control provides the zoomed-in view and the other control provides the zoomed-out view. To use a control with SemanticZoom, it must implement the IZoomableView interface.

The Windows Library for JavaScript provides one control that implements IZoomableView: the WinJS.UI.ListView control. You can also create your own custom controls that implement IZoomableView or augment existing controls to support IZoomableView and use with the SemanticZoom.

Styling the SemanticZoom

CSS classes

To customize the SemanticZoom, you can define your own styles for these Cascading Style Sheets (CSS) classes (defined by the WinJS style sheets):

CSS class	Description
win-semanticzoom	Styles the entire SemanticZoom.
win-semanticzoom-button	(Not supported on Windows Phone 8.1.) Styles the SemanticZoom zoom-out button. The default style positions the button 4px from the right edge and 21px from the lower edge of the SemanticZoomdiv.
win-semanticzoomactive	Styles the active view.
win-semanticzoom-zoomedoutview	(Added in Windows Phone 8.1) Styles the SemanticZoom when the view is zoomed out.
win-semanticzoom-zoomedinview	(Added in Windows Phone 8.1) Styles the SemanticZoom when the view is zoomed in

Setting the height of the SemanticZoom

The SemanticZoom does not dynamically adjust its height to fit your content. For a SemanticZoom to render, you must specify an absolute value for its height. The WinJS style sheets set the SemanticZoom control's height to 400 pixels.

Using placeholders

The user must be able to quickly and smoothly switch between the zoomed-in and zoomed-out views of a SemanticZoom. That means that the SemanticZoom control's child controls shouldn't make the app wait while they load their data. When using the ListView (or a version of the FlipView that you've customized to implement IZoomableView) with the SemanticZoom, use a templating function that creates placeholders when there's a chance that the items might not be available by the time the control comes into view. For more info about using placeholders in item templates, see How to create a templating function for a ListView. If you're using a custom control with the SemanticZoom, implement a progress circle and use placeholders if items might not be available.

Using the SemanticZoom with a vertical list

When you use a ListView that has its layout set to ListLayout as the zoomed-in view of a SemanticZoom, override the win-semanticzoom-button class to reposition the zoom-out button.

Using the SemanticZoom with custom control

You can also create your own custom controls that implement IZoomableView or augment existing controls to support IZoomableView and use with the SemanticZoom.

To use the SemanticZoom with a custom control that has custom touch interactions, add the ms-touch-action class to the control's top level container. This enables it to work properly with touch interactions.

Examples

This example creates a SemanticZoom control that uses two ListView controls to provide its zoomed-in and zoomed-out views.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>semanticZoomExamples</title>

    <!-- WinJS references -->
    <link href="//Microsoft.WinJS.2.0/css/ui-light.css" rel="stylesheet" />
    <script src="//Microsoft.WinJS.2.0/js/base.js"></script>
    <script src="//Microsoft.WinJS.2.0/js/ui.js"></script>

    <link href="semanticZoomExamples.css" rel="stylesheet" />
    <script src="semanticZoomExamples.js"></script>
    <script src="/js/sezoExampleData.js"></script>
</head>
<body>

    <!-- Template for the group headers in the zoomed in ListView -->
    <div id="headerTemplate" 
         data-win-control="WinJS.Binding.Template" style="display: none">
        <div class="simpleHeaderItem">
            <h1 data-win-bind="innerText: title"></h1>
        </div>
    </div>

    <!-- Template for the items in the zoomed in ListView -->
    <div id="mediumListIconTextTemplate" 
         data-win-control="WinJS.Binding.Template" style="display: none">
        <div class="mediumListIconTextItem">
            <img src="#" class="mediumListIconTextItem-Image" 
                 data-win-bind="src: picture" />
            <div class="mediumListIconTextItem-Detail">
                <h4 data-win-bind="innerText: title"></h4>
                <h6 data-win-bind="innerText: text"></h6>
            </div>
        </div>
    </div>

    <!-- Template for the items in the zoomed out 
         ListView of the SemanticZoom -->
    <div id="semanticZoomTemplate" 
        data-win-control="WinJS.Binding.Template" style="display: none">
        <div class="semanticZoomItem">
            <h2 class="semanticZoomItem-Text" 
                data-win-bind="innerText: title"></h2>
        </div>
    </div>

    <!-- SemanticZoom using two ListViews -->
    <div id="semanticZoomDiv" data-win-control="WinJS.UI.SemanticZoom">

        <!-- The zoomed in ListView -->
        <div id="zoomedInListView"
            class="win-selectionstylefilled"
            data-win-control="WinJS.UI.ListView"
            data-win-options="{ 
                    itemDataSource: sezoData.groupedList.dataSource, 
                    itemTemplate: select('#mediumListIconTextTemplate'), 
                    groupDataSource: sezoData.groupedList.groups.dataSource, 
                    groupHeaderTemplate: select('#headerTemplate'), 
                    selectionMode: 'none', 
                    tapBehavior: 'none', 
                    swipeBehavior: 'none' 
                }">
        </div>

        <!-- The zoomed out ListView -->
        <div id="zoomedOutListView"
            data-win-control="WinJS.UI.ListView"
            data-win-options="{ 
                    itemDataSource: sezoData.groupedList.groups.dataSource, 
                    itemTemplate: select('#semanticZoomTemplate'), 
                    selectionMode: 'none', 
                    tapBehavior: 'invoke', 
                    swipeBehavior: 'none' 
                }">
        </div>

    </div>

</body>
</html>

The next example creates the data used by the ListView objects in a separate file named sezoExampleData.js. Add a reference to this file in to your HTML page that creates the ListView.

(function () {
    "use strict";


    // Data used in the ListView for the sample
    var myList = new WinJS.Binding.List([
        { title: "Banana Blast", text: "Low-fat frozen yogurt", picture: "images/60Banana.png" },
        { title: "Banana Blast", text: "Low-fat frozen yogurt", picture: "images/60Banana.png" },
        { title: "Banana Blast", text: "Low-fat frozen yogurt", picture: "images/60Banana.png" },
        { title: "Banana Blast", text: "Low-fat frozen yogurt", picture: "images/60Banana.png" },
        { title: "Lavish Lemon Ice", text: "Sorbet", picture: "images/60Lemon.png" },
        { title: "Lavish Lemon Ice", text: "Sorbet", picture: "images/60Lemon.png" },
        { title: "Lavish Lemon Ice", text: "Sorbet", picture: "images/60Lemon.png" },
        { title: "Lavish Lemon Ice", text: "Sorbet", picture: "images/60Lemon.png" },
        { title: "Marvelous Mint", text: "Gelato", picture: "images/60Mint.png" },
        { title: "Marvelous Mint", text: "Gelato", picture: "images/60Mint.png" },
        { title: "Marvelous Mint", text: "Gelato", picture: "images/60Mint.png" },
        { title: "Marvelous Mint", text: "Gelato", picture: "images/60Mint.png" },
        { title: "Creamy Orange", text: "Sorbet", picture: "images/60Orange.png" },
        { title: "Creamy Orange", text: "Sorbet", picture: "images/60Orange.png" },
        { title: "Creamy Orange", text: "Sorbet", picture: "images/60Orange.png" },
        { title: "Creamy Orange", text: "Sorbet", picture: "images/60Orange.png" },
        { title: "Succulent Strawberry", text: "Sorbet", picture: "images/60Strawberry.png" },
        { title: "Succulent Strawberry", text: "Sorbet", picture: "images/60Strawberry.png" },
        { title: "Succulent Strawberry", text: "Sorbet", picture: "images/60Strawberry.png" },
        { title: "Succulent Strawberry", text: "Sorbet", picture: "images/60Strawberry.png" },
        { title: "Very Vanilla", text: "Ice Cream", picture: "images/60Vanilla.png" },
        { title: "Very Vanilla", text: "Ice Cream", picture: "images/60Vanilla.png" },
        { title: "Very Vanilla", text: "Ice Cream", picture: "images/60Vanilla.png" },
        { title: "Very Vanilla", text: "Ice Cream", picture: "images/60Vanilla.png" },
        { title: "Orangy Orange", text: "Sorbet", picture: "images/60Orange.png" },
        { title: "Orangy Orange", text: "Sorbet", picture: "images/60Orange.png" },
        { title: "Absolutely Orange", text: "Sorbet", picture: "images/60Orange.png" },
        { title: "Absolutely Orange", text: "Sorbet", picture: "images/60Orange.png" },
        { title: "Triple Strawberry", text: "Sorbet", picture: "images/60Strawberry.png" },
        { title: "Triple Strawberry", text: "Sorbet", picture: "images/60Strawberry.png" },
        { title: "Double Banana Blast", text: "Low-fat frozen yogurt", picture: "images/60Banana.png" },
        { title: "Double Banana Blast", text: "Low-fat frozen yogurt", picture: "images/60Banana.png" },
        { title: "Double Banana Blast", text: "Low-fat frozen yogurt", picture: "images/60Banana.png" },
        { title: "Green Mint", text: "Gelato", picture: "images/60Mint.png" }
    ]);

    // Create a grouped list for the ListView from the item data and the grouping functions
    var groupedList = myList.createGrouped(getGroupKey, getGroupData, compareGroups);

    // Function used to sort the groups by first letter
    function compareGroups(left, right) {
        return left.toUpperCase().charCodeAt(0) - right.toUpperCase().charCodeAt(0);
    }

    // Function which returns the group key that an item belongs to
    function getGroupKey(dataItem) {
        return dataItem.title.toUpperCase().charAt(0);
    }

    // Function which returns the data for a group
    function getGroupData(dataItem) {
        return {
            title: dataItem.title.toUpperCase().charAt(0)
        };
    }

    WinJS.Namespace.define("sezoData",
    {
        groupedList: groupedList
    });

})();

The last example defines CSS styles for the SemanticZoom and ListView controls.

/* Template for headers in the zoomed in ListView */
.simpleHeaderItem
{
    width: 50px;
    height: 50px;
    padding: 8px;
}   

/* Template for items in the zoomed in ListView */  
.mediumListIconTextItem
{
    width: 282px;
    height: 70px;
    padding: 5px;
    overflow: hidden;
    display: -ms-grid;
}

    .mediumListIconTextItem img.mediumListIconTextItem-Image 
    {
        width: 60px;
        height: 60px;
        margin: 5px;
        -ms-grid-column: 1;
    }

    .mediumListIconTextItem .mediumListIconTextItem-Detail
    {
        margin: 5px;
        -ms-grid-column: 2;
    }
    
/* Template for items in the zoomed out ListView */
.semanticZoomItem
{
    color: white;
    width: 140px;
    height: 52px;
    overflow: hidden;
    padding: 9px 15px;
    white-space: nowrap;
    display: -ms-flexbox;
    -ms-flex-pack: end;
    -ms-flex-direction: column;
    background-color: rgb(70,23,180);
}
    
/* CSS applied to the SemanticZoom and inherited by both ListViews */
#semanticZoomDiv 
{
    width: 600px;
    height: 300px;
    border: solid 2px rgba(0,0,0,0.13);
}

#semanticZoomDiv .win-container
{
    margin: 5px 10px;
}

For more info, see Quickstart: Adding SemanticZoom controls.

Requirements

Minimum WinJS version	WinJS 1.0
Namespace	WinJS.UI