Adding an AppBar with commands (HTML)

Article
08/10/2016

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

This article explains how to add an AppBar to your Windows Runtime app using JavaScript. If you use the default styles and markup shown in this example, the commands that you place in the AppBar will be styled appropriately. Both image sprites and font glyphs are supported for the icons of the commands.

(Windows only) See this feature in action as part of our App features, start to finish series : Windows Store app UI, start to finish

Prerequisites

Instructions

1. Create a new project by using the Blank App template

Launch Microsoft Visual Studio.
From the Start Page tab, click New Project. The New Project dialog opens.
In the Installed pane, expand Templates and JavaScript, then click the Store apps template type. Choose the platform that you want to target (Universal Apps, Windows Apps, or Windows Phone Apps) but for this Quickstart, we'll be using Universal Apps.
In the center pane, pick the Blank App (Uinversal Apps) project template (don't click OK yet).
In the Name text box, enter AppBar demo.
Click OK to create the project.

2. Add the AppBar definition to the project

Your AppBar is defined in an HTML file with a corresponding JavaScript file (one for Windows and one for Windows Phone).

As shown below and for each platform (i.e., Windows and Windows Phone), open default.html and replace the automatically generated HTML with the following HTML. The best practice is to create one global AppBar per application and this AppBar should be a direct child of the <body> element. It's also a good idea to place global commands before contextual commands in the DOM in order to get the best layout when people snap your app.

This example adds an AppBar with one left-aligned command and three right-aligned commands with a separator between them.

Windows - default.html

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <title>App_bar_demo.Windows</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>

  <!-- App_bar_demo.Windows references -->
  <link href="/css/default.css" rel="stylesheet" />
  <script src="/js/default.js"></script>
  <script src="/js/appbar.js"></script> <!-- Not part of the stock template. -->
</head>
<body>
  <ol>
    <li>
      To show the AppBar, swipe up from the bottom of the screen, swipe down from
      the top of the screen, right-click, or press Windows&nbsp;Logo&nbsp;+&nbsp;Z.
    </li>
    <li>
      Click or tap one of the following AppBar buttons: <strong>Camera</strong>,
      <strong>Add</strong>, <strong>Remove</strong>, or <strong>Delete</strong>
    </li>
    <li>
      To dismiss the AppBar, click or tap in the application, swipe, right-click,
      or press Windows&nbsp;Logo&nbsp;+&nbsp;Z again.
    </li>
  </ol>
  <!-- BEGINTEMPLATE: Template code for an AppBar -->
  <div id="appBar" data-win-control="WinJS.UI.AppBar" data-win-options="">
    <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{id:'cmdAdd', label:'Add', icon:'add', section:'primary', tooltip:'Add item'}"></button>
    <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{id:'cmdRemove', label:'Remove', icon:'remove', section:'primary', tooltip:'Remove item'}"></button>
    <hr data-win-control="WinJS.UI.AppBarCommand"
        data-win-options="{type:'separator',section:'primary'}" /> <!-- SEPARATOR NOT AVAILABLE ON PHONE prior to WinJS 4.0 -->
    <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{id:'cmdDelete', label:'Delete', icon:'delete', section:'primary', tooltip:'Delete item'}"></button>
    <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{id:'cmdCamera', label:'Camera', icon:'camera', section:'secondary', tooltip:'Take a picture'}"></button>
  </div>
  <!-- ENDTEMPLATE -->
  <div id="statusMessage"></div>
</body>
</html>

Caution The following block of sample code is valid only for Windows Phone through version 2.1. When using WinJS 4.0 and later, the correct approach is to use the same HTML code for the AppBar for both Windows and Windows Phone apps.

Windows Phone 2.1 only - default.html

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <title>App_bar_demo.WindowsPhone</title>

  <!-- WinJS references -->
  <!-- At runtime, ui-themed.css resolves to ui-themed.light.css or ui-themed.dark.css
  based on the user’s theme setting. This is part of the MRT resource loading functionality. -->
  <link href="/css/ui-themed.css" rel="stylesheet" />
  <script src="//Microsoft.Phone.WinJS.2.1/js/base.js"></script>
  <script src="//Microsoft.Phone.WinJS.2.1/js/ui.js"></script>

  <!-- App_bar_demo.Phone references -->
  <link href="/css/default.css" rel="stylesheet" />
  <script src="/js/default.js"></script>
  <script src="/js/appbar.js"></script> <!-- Not part of the stock template. -->
</head>
<body class="phone">
  <p>
    Tap the Add, Remove, or Delete AppBar button, or swipe the ellipsis and tap the Camera AppBar button.
  </p>
  <!-- BEGINTEMPLATE: Template code for an AppBar -->
  <div id="appBar" data-win-control="WinJS.UI.AppBar" data-win-options="">
    <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{id:'cmdAdd', label:'Add', icon:'add', section:'primary', tooltip:'Add item'}"></button>
    <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{id:'cmdRemove', label:'Remove', icon:'remove', section:'primary', tooltip:'Remove item'}"></button>
    <!-- <hr data-win-control="WinJS.UI.AppBarCommand"
        data-win-options="{type:'separator',section:'primary'}" /> SEPARATOR NOT AVAILABLE ON PHONE -->
    <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{id:'cmdDelete', label:'Delete', icon:'delete', section:'primary', tooltip:'Delete item'}"></button>
    <button data-win-control="WinJS.UI.AppBarCommand"
            data-win-options="{id:'cmdCamera', label:'Camera', icon:'camera', section:'secondary', tooltip:'Take a picture'}"></button>
  </div>
  <!-- ENDTEMPLATE -->
  <div id="statusMessage"></div>
</body>
</html>

Hh465309.wedge(en-us,WIN.10).gif Add the Appbar.js file

In Solution Explorer, right-click the js folder, point to Add, and click New Item.
In the Installed pane, expand JavaScript, click JavaScript File in the center pane of the dialog.
In the Name text box (near the bottom of the dialog box), enter Appbar.js.
Click Add to create the file and add it to the project.

Open Appbar.js (if necessary) and add the following code.

(function () {
  "use strict";

  WinJS.UI.Pages.define("default.html", {
    ready: function (element, options) {
      // Use element.querySelector() instead of document.getElementById() to ensure that the correct default.html page is targeted:
      element.querySelector("#cmdAdd").addEventListener("click", doClickAdd, false);
      element.querySelector("#cmdRemove").addEventListener("click", doClickRemove, false);
      element.querySelector("#cmdDelete").addEventListener("click", doClickDelete, false);
      element.querySelector("#cmdCamera").addEventListener("click", doClickCamera, false);
    }
  });

  // Command button functions
  function doClickAdd() {
    WinJS.log && WinJS.log("Add button pressed", "status");
  }

  function doClickRemove() {
    WinJS.log && WinJS.log("Remove button pressed", "status");
  }

  function doClickDelete() {
    WinJS.log && WinJS.log("Delete button pressed", "status");
  }

  function doClickCamera() {
    WinJS.log && WinJS.log("Camera button pressed", "status");
  }

  WinJS.log = function (message, messageType) {
    var statusDiv = document.getElementById("statusMessage"); // For a multi-page app, always ensure that each element ID is unique (across all pages).

    if (statusDiv && messageType === "status") {
      statusDiv.innerText = "STATUS: " + message;
    }
  };
})();

The Appbar.js file is injected into the two default.html files through their <script src="/js/appbar.js"></script> markup.

3. Developer Notes

You can only use AppBarCommands in an AppBar. For a list of icons to use, see AppBarIcon enumeration.
AppBar is a light dismissible overlay, which means it will always cover some part of the screen.
AppBar, like all light dismissible overlays, must always be a direct child of the <body> element.
To mitigate the nature of an AppBar overlay to cover other screen content, reserve space at the top or bottom of the screen for the closed AppBar. In this way, only the opened AppBar will cover other content.
The height of the closed AppBar can be controlled with its closedDisplayMode property.
The top or bottom position of the AppBar is controlled by its placement property.

Summary

In this quickstart you added an AppBar to your application.

WinJS.UI.AppBar

WinJS.UI.AppBarCommand

AppBarIcon

Share via

Adding an AppBar with commands (HTML)

Prerequisites

Instructions

1. Create a new project by using the Blank App template

2. Add the AppBar definition to the project

3. Developer Notes

Summary

Additional resources

Share via

Adding an AppBar with commands (HTML)

Prerequisites

Instructions

1. Create a new project by using the Blank App template

2. Add the AppBar definition to the project

3. Developer Notes

Summary

Related topics

Additional resources