Quickstart: Adding an app bar with custom content (HTML)

Applies to Windows and Windows Phone

You can add an app bar with custom content to your Windows Store app using JavaScript. The AppBar control and the AppBarCommand controls it contains can be customized in a variety of ways: you can add custom HTML content, create flyouts, insert toggle commands, and much more.

Note  If you want to create a persistent nav bar for your app, use the NavBar control instead. For more info about how to create a nav bar, see Quickstart: Adding a nav bar and back buttons.

Prerequisites

Instructions

Create a new project by using the Blank App template

  1. Start Microsoft Visual Studio.

  2. From the Start Page tab, click New Project. The New Project dialog opens.

  3. In the Installed pane, expand Templates and JavaScript, and click the Windows Store app template type. The available project templates for JavaScript are displayed in the center pane of the dialog.

  4. In the center pane, pick the Blank App project template.

  5. In the Name text box, type Custom AppBar demo.
  6. Click OK to create the project.

2. Add the bar control and customize its commands

An AppBar control with its layout property set to "commands" can contain only AppBarCommand controls as its children—anything other than an AppBarCommand control within the AppBar raises an exception. The "commands" value is the default setting for the AppBar.layout property.

Note  You can put any HTML in the app bar if you set the AppBar.layout to "custom". However, an AppBar control using a "custom" layout doesn’t have the full built-in app bar functionality available to an AppBar using the "commands" layout.

Thus, you customize the app bar through customizable app bar commands. You can change the type of an AppBarCommand control by using its type property. Only certain HTML elements can host some app bar command types.

The AppBarCommand.type property takes one of five values:

  • button—The default value for the type. It defines a standard button and can be applied only to a <button> element.
  • flyout—Creates a button that reveals an HTML fragment adjacent to it (a flyout). To create a flyout AppBarCommand, specify the type as "flyout" and set its flyout property. The flyout property must reference a defined Flyout control. Only a <button> element can host a flyout AppBarCommand.
  • toggle—Creates a button that can be selected or cleared. When the button is selected, the colors of the icon of the AppBarCommand are reversed (black to white and white to black, for example). Only a <button> element can host a toggle AppBarCommand.
  • separator—Creates a horizontal line in the AppBar, to create a visual separation between other AppBarCommand controls. Only an <hr/> element can host a separator AppBarCommand.
  • content—Creates an AppBarCommand that can host other HTML markup inside it. The hosted markup can include text, <input> tags, and even a subset of Windows Library for JavaScript (WinJS) controls. Only a <div> element can host a content AppBarCommand.

You can create AppBar and AppBarCommand controls declaratively in HTML or at run time by using JavaScript. This example creates the app bar declaratively in the HTML markup of default.html. The example contains seven AppBarCommand controls.

Hh780658.wedge(en-us,WIN.10).gifTo add a custom app bar

  1. In Solution Explorer, open the default.html file from the root of the solution.
  2. Replace the markup inside the <body> tags with the following markup.
    
    <div data-win-control="WinJS.UI.AppBar"
        data-win-options="{
            placement: 'bottom',
            layout: 'commands'
        }">
        <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{
                id: 'default'
                icon: 'placeholder',
                label: 'Button',
                type: 'button'
        }">
        </button>
        <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{
                id: 'flyout', 
                icon: 'volume', 
                label: 'Volume', 
                type: 'flyout',
                flyout: select('#volumeFlyout')}">
        </button>
        <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{
                id: 'toggle', 
                icon: 'filter', 
                label: 'Filter', 
                type: 'toggle'}">
        </button>
        <hr data-win-control="WinJS.UI.AppBarCommand" data-win-options="{ type: 'separator' }"/>
        <div data-win-control="WinJS.UI.AppBarCommand" data-win-options="{ type: 'content' }">
            <p>You can include a wide variety of HTML inside of a 'content' AppBarCommand, <br/>
            including HTML and some WinJS controls.</p>
        </div>
        <div data-win-control="WinJS.UI.AppBarCommand" data-win-options="{ type: 'content' }">
            <div id="itemContainer"
                 data-win-control="WinJS.UI.ItemContainer">
                <h3>Item Container</h3>
            </div>
        </div>
    </div>
    <div id="volumeFlyout"
         data-win-control="WinJS.UI.Flyout">
        <h3>Volume</h3> <input type="range" />
    </div>
    
    
    

Summary

In this quickstart you added an app bar with custom buttons to your app.

This article does not describe how to create a nav bar. To learn how to create a nav bar, see Quickstart: Adding a nav bar and back buttons.

Related topics

WinJS.UI.AppBar
WinJS.UI.AppBarCommand.type
WinJS.UI.AppBarCommand.flyout
Quickstart: Adding a flyout

 

 

Show:
© 2014 Microsoft