Adding an AppBar with custom content (HTML)

  • Article

[ 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 ]

You can add an AppBar with custom content to your Windows 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

1. 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

You can customize the AppBar through customizable AppBar commands. You can change the type of an AppBarCommand control by using its type property. Only certain HTML elements can host some AppBar 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 AppBar declaratively in the HTML markup of default.html. The example contains seven AppBarCommand controls.

Hh780658.wedge(en-us,WIN.10).gifTo add custom content to AppBar

  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'
    }">
    <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 AppBar 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.

WinJS.UI.AppBar

WinJS.UI.AppBarCommand.type

WinJS.UI.AppBarCommand.flyout

Quickstart: Adding a flyout