Quickstart: Adding a FlipView (HTML)
[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]
Many apps display a list of items that the user can flip through. These lists might obtain their data from a database, the web, or a JSON data source. Windows Library for JavaScript provides the FlipView control for just this purpose.
.png "A FlipView control.")
Prerequisites
What is a FlipView?
The FlipView is a WinJS control that lets you flip through a collection of items, one at a time. It's great for displaying a gallery of images.
The FlipView gets its data from an IListDataSource. WinJS provides several types of IListDataSource objects:
- You can use a List to create an IListDataSource from an array of data.
- You can use a StorageDataSource to access information about files and directories.
You can also create your own custom data source that connects to some other type of data provider, such as a web service or database. For instructions, see How to create a custom data source.
Creating a simple FlipView
Add references to the WinJS to your HTML file, if they aren't already there.
<!-- WinJS references --> <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet"> <script src="//Microsoft.WinJS.2.0/js/base.js"></script> <script src="//Microsoft.WinJS.2.0/js/ui.js"></script>This example shows the HTML for the default.html file that is generated when you create a new Blank Application project in Microsoft Visual Studio. Note that it already contains references to the WinJS.
<!-- default.html --> <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>FlipViewExample</title> <!-- WinJS references --> <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet"> <script src="//Microsoft.WinJS.2.0/js/base.js"></script> <script src="//Microsoft.WinJS.2.0/js/ui.js"></script> <!-- FlipViewExample references --> <link href="/css/default.css" rel="stylesheet"> <script src="/js/default.js"></script> </head> <body> <p>Content goes here</p> </body> </html>This example uses the light style sheet instead of the dark style sheet, so if you want your app to match these examples, change this reference:
<!-- WinJS references --> <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet">...to this:
<!-- WinJS references --> <link href="//Microsoft.WinJS.2.0/css/ui-light.css" rel="stylesheet">In your HTML file, create a div element and set its data-win-control property to "WinJS.UI.FlipView".
<div id="basicFlipView" data-win-control="WinJS.UI.FlipView" ></div>In the JavaScript code that accompanies your HTML file, call the WinJS.UI.processAll function when your HTML is loaded.
WinJS.UI.processAll();The next example shows the default.js file that accompanies the default.html file created for you when you create a new Blank Application project.
// default.js (function () { "use strict"; var app = WinJS.Application; // This function responds to all application activations. app.onactivated = function (eventObject) { if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) { // TODO: Initialize your application here. WinJS.UI.processAll(); } }; app.start(); })();This example works if you're adding the FlipView to your start page (default.html). If you're adding the FlipView to a Page control, you don't need to call WinJS.UI.processAll because the Page control does it for you. If you're adding the FlipView to your own custom HTML, you can use the DOMContentLoaded event to call WinJS.UI.processAll. For more information about activating your controls, see Quickstart: Adding WinJS controls and styles.
Important: Set the height and width of your FlipView. For a FlipView to render, you must specify its height with an absolute value. Add this CSS to the CSS style sheet for the HTML page that contains the FlipView:
#basicFlipView { width: 480px; height: 270px; border: solid 1px black; }
This code creates an empty FlipView. If you run the app, you'll see an empty control. In the next section, you create some data for the FlipView to display.
Defining your data
Putting the code to create your data source in a separate JavaScript file can make it easier to maintain. In this section, you learn how to create a JavaScript file for your data, how to create a List, and how to use the WinJS.Namespace.define function to make the data accessible to the rest of your app.
Use Visual Studio to add a data file to your project. In the Solution Explorer, right click your project's
jsfolder and select Add > New Item. The Add New Item dialog appears.Select JavaScript File. Give it the name "dataExample.js". Click Add to create the file. Visual Studio creates a blank JavaScript file named dataExample.js.
Open dataExample.js. Create an anonymous function and turn on strict mode.
As described in Coding basic apps, it's a good idea to encapsulate your JavaScript code by wrapping it in an anonymous function, and it's a good idea to use strict mode.
(function () { "use strict"; })();Create an array of data. This example creates an array of objects. Each object has three properties: type, title, and image.
(function () { "use strict"; var dataArray = [ { type: "item", title: "Cliff", picture: "images/Cliff.jpg" }, { type: "item", title: "Grapes", picture: "images/Grapes.jpg" }, { type: "item", title: "Rainier", picture: "images/Rainier.jpg" }, { type: "item", title: "Sunset", picture: "images/Sunset.jpg" }, { type: "item", title: "Valley", picture: "images/Valley.jpg" } ]; })();Note If you're following along with your code, you can change the pictures to files on your local machine, or you can get the pictures by downloading the HTML FlipView control sample (it's not the same sample, but it uses the same images). You can also run the sample without adding the images—it will still run.
Use the array to create a List object.
(function () { "use strict"; var dataArray = [ { type: "item", title: "Cliff", picture: "images/Cliff.jpg" }, { type: "item", title: "Grapes", picture: "images/Grapes.jpg" }, { type: "item", title: "Rainier", picture: "images/Rainier.jpg" }, { type: "item", title: "Sunset", picture: "images/Sunset.jpg" }, { type: "item", title: "Valley", picture: "images/Valley.jpg" } ]; var dataList = new WinJS.Binding.List(dataArray); })();Expose the List by declaring a namespace and adding the List as a public member.
Because the code you just wrote in enclosed in an anonymous function, non of it is publicly accessible. (That's part of the reason why you use the anonymous function: to keep private data private.) For your FlipView to be able to access the List, you need to make it publicly accessible. One way to do this is to use the WinJS.Namespace.define function to create a namespace and add the List as one of its members.
The WinJS.Namespace.define function takes two parameters: the name of the namespace to create, and an object that contains one or more property/value pairs. Each property is the public name of the member, and each value is underlying variable, property, or function in your private code that you want to expose.
This example creates a namespace named DataExample that exposes a public member named itemList that returns your List.
(function () { "use strict"; var dataArray = [ { type: "item", title: "Cliff", picture: "images/Cliff.jpg" }, { type: "item", title: "Grapes", picture: "images/Grapes.jpg" }, { type: "item", title: "Rainier", picture: "images/Rainier.jpg" }, { type: "item", title: "Sunset", picture: "images/Sunset.jpg" }, { type: "item", title: "Valley", picture: "images/Valley.jpg" } ]; var dataList = new WinJS.Binding.List(dataArray); // Create a namespace to make the data publicly // accessible. var publicMembers = { itemList: dataList }; WinJS.Namespace.define("DataExample", publicMembers); })();
You've created a data source that can be accessed by your FlipView. In the next section, you connect the data to the FlipView.
Connecting your data to the FlipView
In the head section of the HTML file that contains your FlipView, add a reference to the data file you just created (dataExample.js):
<head> <meta charset="utf-8"> <title>FlipViewExample</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> <!-- FlipViewExample references --> <link href="/css/default.css" rel="stylesheet"> <script src="/js/default.js"></script> <!-- Your data file. --> <script src="/js/dataExample.js"></script> </head>Use the data you created in the last section to set the FlipView control's itemDataSource property.
The itemDataSource property takes an IListDataSource object. The List object is not an IListDataSource, but it does have a dataSource property that returns an IListDataSource version of itself.
To connect your data, set the FlipView control's itemDataSource property to
DataExample.itemDataList.dataSource:<div id="basicFlipView" data-win-control="WinJS.UI.FlipView" data-win-options="{ itemDataSource : DataExample.itemList.dataSource }"> </div>
Run the app. The FlipView displays the properties and values in the data source:
.png "Displaying the data source contents without a template.")
This isn't quite the look that we want. We want to show just the values of the title field, and we want to show the actual images, not the path to the images. To get the rendering that we want, we need to define a Template. The next step shows you how.
Defining an item template
At this point, the FlipView has the data it needs, but doesn't know how to display it. For that, you need an item template. There are two ways to create a template: you can use markup to define a WinJS.Binding.Template, or you can create a templating function. This example creates a template in markup. (For information about creating a template function, see the itemTemplate property.)
A WinJS.Binding.Template is easy to create: you define the markup that you want to use to display each list item, then you indicate where each data field is displayed.
In your HTML, create a WinJS.Binding.Template control and assign it an ID. This example uses the ID "ItemTemplate".
<div id="ItemTemplate" data-win-control="WinJS.Binding.Template"> </div>Note Your template must be defined before you use it, so add the HTML for our template before the HTML for your FlipView.
WinJS.Binding.Template must have a single root element. Create a div element to serve as a parent for the template's contents.
<div id="ItemTemplate" data-win-control="WinJS.Binding.Template"> <div> </div> </div>Create the markup that the FlipView will produce for each data item it contains. The data you created in the previous section contains an image location, a title, and some text, so create these elements:
- An img element for displaying the picture field.
- An h2 element for displaying the title field.
(This example also adds an extra div element for formatting reasons.)
<div id="ItemTemplate" data-win-control="WinJS.Binding.Template"> <div> <img src="#" /> <div> <h2></h2> </div> </div> </div>Set the data-win-bind attribute on each element that displays data. The data-win-bind attribute uses the syntax:
data-win-bind="propertyName: dataFieldName"
For example, to bind the src property of an img to the "picture" field, use the syntax:
<img data-win-bind="src : picture" />To set multiple properties, you separate them with a semicolon:
data-win-bind="property1Name: dataField1Name; property2Name: dataField2Name"
This example binds the items in the template to their corresponding data fields.
<div id="ItemTemplate" data-win-control="WinJS.Binding.Template"> <div> <img src="#" data-win-bind="src: picture; alt: title" /> <div> <h2 data-win-bind="innerText: title"></h2> </div> </div> </div>To use the item template, set the itemTemplate property of the FlipView to the ID of your item template ("ItemTemplate" in this example).
<div id="ItemTemplate" data-win-control="WinJS.Binding.Template"> <div> <img src="#" data-win-bind="src: picture; alt: title" /> <div> <h2 data-win-bind="innerText: title"></h2> </div> </div> </div> <div id="basicFlipView" data-win-control="WinJS.UI.FlipView" data-win-options="{ itemDataSource : DataExample.itemList.dataSource, itemTemplate : ItemTemplate }" ></div>Now when you run the app, the bound data appears in the list.
.png "A data-bound FlipView.")
Note that there are some formatting issues: the title text doesn't display. The next section shows you how to fix the issue by styling the template.
Styling items
You can use CSS to style your item template. The next example adds some CSS classes to the template you defined in the Defining an item template section.
<div id="ItemTemplate" data-win-control="WinJS.Binding.Template">
<div class="overlaidItemTemplate">
<img class="image" src="#" data-win-bind="src: picture; alt: title" />
<div class="overlay">
<h2 class="ItemTitle" data-win-bind="innerText: title"></h2>
</div>
</div>
</div>
<div id="basicFlipView"
data-win-control="WinJS.UI.FlipView"
data-win-options="{ itemDataSource : DataExample.itemList.dataSource, itemTemplate : ItemTemplate }"
></div>
In the CSS style sheet for your HTML file, add these styles for the template:
#basicFlipView
{
width: 480px;
height: 270px;
border: solid 1px black;
}
/**********************************************/
/* */
/* Styles used in the item template */
/* */
/**********************************************/
.overlaidItemTemplate
{
display: -ms-grid;
-ms-grid-columns: 1fr;
-ms-grid-rows: 1fr;
width: 480px;
height: 270px;
}
.overlaidItemTemplate img
{
width: 100%;
height: 100%;
}
.overlaidItemTemplate .overlay
{
position: relative;
-ms-grid-row-align: end;
background-color: rgba(0,0,0,0.65);
height: 40px;
padding: 20px 15px;
overflow: hidden;
}
.overlaidItemTemplate .overlay .ItemTitle
{
color: rgba(255, 255, 255, 0.8);
}
Here's what the FlipView looks like now:
.png "The styled FlipView.")
Note
Changing the font-family for FlipView navigation buttons will cause buttons to no longer contain the correct glyph.
Changing the orientation of the FlipView
By default, the FlipView uses a horizontal orientation. You can display the FlipView vertically by setting its orientation property to "vertical".
<div id="basicFlipView"
data-win-control="WinJS.UI.FlipView"
data-win-options="{ itemDataSource : DataExample.itemList.dataSource, itemTemplate : ItemTemplate, orientation: 'vertical' }"
></div>
.png "A FlipView with a vertical orientation.")
Adding interactive elements to an item template
The item template can contain most other controls, but it can't contain a ListView or another FlipView.
Normally, when the user interacts with an element, the FlipView captures that interaction and uses it to determine whether the user selected or invoked an item or is panning through items. For an interactive element, such as a control, to receive input, you must attach the win-interactive class to the interactive element or one of its parent elements. That element and its children receive the interaction and no longer trigger events for the FlipView.
When you attach the win-interactive to an element in a item template, be sure that the element doesn't fill the entire item, otherwise the user won't have a way to select or invoke that item.
To add interactive elements to your item template, you must use a templating function instead of a WinJS.Binding.Template. For an example of how to do this, see the HTML FlipView control sample. For more info about templating functions, see the examples in the FlipView.itemTemplate.
Creating a context control
The FlipView exposes methods and events that allow you to create custom controls that give the user an idea of where current item is and alternative mechanisms for navigating the collection. The following image shows a set of styled radio buttons that are kept in sync with the FlipView via the pageselected and pagevisibilitychanged events.
.png "A FlipView with a context control.")
For the code that shows you how to do this, see the HTML FlipView control sample.