Part 1: Create a "Hello, world" app (Windows Store apps using JavaScript and HTML)

Applies to Windows only

This tutorial teaches you how to create a simple "Hello, world" app using Javascript and HTML. It's the first tutorial in a series of 5 that teach you what you need to know to build apps.

In this tutorial, you learn how to:

  • Create a new project
  • Add HTML content to your start page
  • Handle touch, pen, and mouse input
  • Switch between the light and dark style sheets
  • Create your own custom styles
  • Use a Windows Library for JavaScript control

We show you how to create an app using HTML, JavaScript, and CSS.

Tip  

If you want to skip the tutorial and go straight to the code, see Getting started with JavaScript: Complete code for the tutorial series.

Before you start...

  • To complete this tutorial, you need Windows 8.1 and Microsoft Visual Studio Express 2013 for Windows. To download them, see the Downloads page.
  • You also need a developer license. For instructions, see Get a developer license.

Step 1: Create a new project in Visual Studio

Let's create a new app named HelloWorld. Here's how:

  1. Launch Visual Studio Express 2013 for Windows.

    The Visual Studio Express 2013 for Windows start screen appears.

    (Going forward, we refer to Visual Studio Express 2013 for Windows as just "Visual Studio".)

  2. From the File menu select New Project.

    The New Project dialog appears. The left pane of the dialog lets you pick the type of templates to display.

  3. In the left pane, expand Installed, then expand Templates, then expand JavaScript, then expand Store Apps and select the Universal Apps category. The dialog's center pane displays a list of universal project templates for JavaScript. The Universal App template allows you to quickly develop an app for the both Windows and Windows Phone at the same time.

    The New Project window

    For this tutorial, we use the Blank App template. This template creates a minimal app that compiles and runs, but contains no user interface controls or data. We'll add controls and data to the app over the course of these tutorials.

  4. In the center pane, select the Blank App template.
  5. In the Name text box, enter "HelloWorld".
  6. Click OK to create the project.

    Visual Studio creates your project and displays it in the Solution Explorer.

    The Soution Explorer for the  HelloWorld project

You'll notice three projects have been created for you: HelloWorld.Phone, HelloWorld.Store, and HelloWorld.Shared. The

The Windows and Phone projects each contain a number of files:

  • A manifest file (package.appxmanifest) that describes your app (its name, description, tile, start page, splash screen, and so on) and lists the files that your app contains.
  • An images folder, which contains a set of logos to represent your app on the device (logo.png and smalllogo.png), an image to represent your app in the store (storelogo.png), and a splash screen to show while your app is starting (splashscreen.png).
  • CSS and code files for the WinJS (inside the References folder).
  • A start page (default.html).

The shared project currently holds a single folder, js, which contains the JavaScript file default.js. This file loads when your app starts and is shared between the two default.html files in the Windows and Phone projects.

These files are essential to all apps. Any project that you create in Visual Studio contains them.

Step 2: Launch the app

At this point, we created a very simple app. If you want to see what it looks like, press F5 to build, deploy, and start your app. A default splash screen appears first. The splash screen is defined by an image (splashscreen.png) and a background color (specified in our app's manifest file). We don't cover it here, but it's easy to customize your splash screen. (To find out how, see Adding a splash screen.)

The splash screen disappears, and then our app appears. It contains a black screen with the text "Content goes here".

Our HelloWorld app

On Windows, there is no button or command to close the app. To close the app, slide from the top edge toward the bottom edge of the screen or press Alt-F4. Go to the Start screen; notice that deploying the app adds its tile to the last group on the Start screen. To run the app again, tap or click its tile on the start screen or press F5 in Visual Studio to run the app in the debugger.

By default, Microsoft Visual Studio starts with the Windows Store app selected for debugging. However, with the Universal App template, it is easy to switch to the Phone version of your app. Simply right-click the Windows Phone 8.1 solution in Visual Studio and select Set as startup project. Then click F5 again to launch your app using the Windows Phone emulator.

Our HelloWorld app

When you are finished previewing the app (which should look very similar to its Windows counterpart), you can close it either by clicking the Stop symbol in the Visual Studio menu bar, or by holding down the back button on the Windows Phone emulator and selecting the "X" symbol in the upper-right hand corner.

Neither app does much yet but congratulations — you've built your first app!

Step 3: Modify your start page

One of the files that Visual Studio created for us in each project is default.html, our app's start page. When the app runs, it displays the content of its start page. The start page also contains references to the app's code files and style sheets. Here's the start page that Visual Studio created for us in the Windows project:


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

    <!-- HelloWorld references -->
    <link href="/css/default.css" rel="stylesheet" />
    <script src="/js/default.js"></script>
</head>
<body>
    <p>Content goes here</p>
</body>
</html>

Let's add some new content to your default.html file. Just as you would add content to any other HTML file, you add your content inside the body element. You can use HTML5 elements to create your app (with a few exceptions). That means you can use HTML5 elements like h1, p, button, div, and img.

Hh986964.wedge(en-us,WIN.10).gifTo modify our start page

  1. Replace the existing content in the body element with a first-level heading that says "Hello, world!", some text that asks the user's name, an input element to accept the user's name, a button, and a div element. Assign IDs to the input, the button, and the div .

    
    <body>
        <h1>Hello, world!</h1>
        <p>What's your name?</p>
        <input id="nameInput" type="text" />
        <button id="helloButton">Say "Hello"</button>
        <div id="greetingOutput"></div>
    </body>
    
    
  2. Run the app.

    Our HelloWorld app, with new content

    You can write in the input element, but right now, clicking the button doesn't do anything. Some objects, such as button, can send messages when certain events occur. These event messages give you the opportunity to take some action in response to the event. You put your code to respond to the event in an event handler method.

    In the next steps, we create an event handler for the button that displays a personalized greeting. We add our event handler code to our default.js file.

Step 4: Create an event handler

When we created our new project, Visual Studio created a /js/default.js file for us. This file contains code for handling your app's lifecycle, a concept that we explain in Part 2: Manage app lifecycle and state. It's also where you write additional code that provides interactivity for your default.html file.

Open the default.js file.

Before we start adding our own code, let's take a look at the first and last few lines of code in the file:



(function () {
    "use strict";

     // Omitted code 

 })(); 

You might be wondering what's going on here. These lines of code wrap the rest of the default.js code in a self-executing anonymous function.

Now that you know what it does, you're probably wondering why we wrap our code in a self-executing anonymous function. It's because this makes it easier to avoid naming conflicts or situations where you accidently modify a value that you didn't intend to. It also keeps unnecessary identifiers out of the global namespace, which helps performance. It looks a little strange, but it's a good programming practice.

The next line of code turns on strict mode for your JavaScript code. Strict mode provides additional error checking for your code. For example, it prevents you from using implicitly declared variables or assigning a value to a read-only property.

Take a look at the rest of the code in default.js. It handles your app's activated and checkpoint events. We go into more detail about these events later. For now, just know that the activated event fires when your app starts.

Let's define an event handler for your button. Our new event handler gets the user's name from the nameInput input control and uses it to output a greeting to the greetingOutput div element that you created in the last section.

Using events that work for touch, mouse, and pen input

You don’t need to worry about the differences between touch, mouse, and other forms of pointer input. You can just use events that you know, like click, and they work for all forms of input.

Tip   Your app can also use the new MSPointer* and MSGesture* events, which work for touch, mouse, and pen input and can provide additional info about the device that triggered the event. For more info, see Responding to user interaction and Gestures, manipulations, and interactions.

Let's go ahead and create the event handler.

Hh986964.wedge(en-us,WIN.10).gifTo create the event handler

  1. In default.js, after the app.oncheckpoint event handler and before the call to app.start, create a click event handler function named buttonClickHandler that takes a single parameter named eventInfo.
    
        function buttonClickHandler(eventInfo) {
     
        }
    
    
  2. Inside our event handler, retrieve the user's name from the nameInput input control and use it to create a greeting. Use the greetingOutput div to display the result.
    
        function buttonClickHandler(eventInfo) {
            var userName = document.getElementById("nameInput").value;
            var greetingString = "Hello, " + userName + "!";
            document.getElementById("greetingOutput").innerText = greetingString; 
        }
    
    

We added our event handler to default.js. Now we need to register it.

Step 5: Register the event handler when our app launches

The only thing we need to do now is register the event handler with the button. The recommended way to register an event handler is to call addEventListener from our code. A good place to register the event handler is when our app is activated. Fortunately, Visual Studio generated some code for us in our default.js file that handles our app's activation: the app.onactivated event handler. Let's take a look at this code.



    var app = WinJS.Application;
    var activation = Windows.ApplicationModel.Activation;

    app.onactivated = function (args) {
        if (args.detail.kind === activation.ActivationKind.launch) {
            if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
                // TODO: This application has been newly launched. Initialize
                // your application here.
            } else {
                // TODO: This application has been reactivated from suspension.
                // Restore application state here.
            }
            args.setPromise(WinJS.UI.processAll());
        }
    };

Inside the onactivated handler, the code checks to see what type of activation occurred. There are many different types of activations. For example, your app is activated when the user launches your app and when the user wants to open a file that is associated with your app. (For more info, see Application lifecycle.)

We're interested in the launch activation. An app is launched whenever it is not running and then a user activates it.



    app.onactivated = function (args) {
        if (args.detail.kind === activation.ActivationKind.launch) {


If the activation is a launch activation, the code checks to see how the app was shut down the last time it ran.




            if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
                // TODO: This application has been newly launched. Initialize
                // your application here.
            } else {
                // TODO: This application has been reactivated from suspension.
                // Restore application state here.
            }


Then it calls WinJS.UI.processAll.




            args.setPromise(WinJS.UI.processAll());           
        }
    };

It calls WinJS.UI.processAll regardless of whether the app had been shut down in the past or whether this is the very first time it's being launched. The WinJS.UI.processAll is enclosed in a call to the setPromise method, which makes sure the splash screen isn't taken down until the app's page is ready.

Tip  The WinJS.UI.processAll function scans your default.html file for WinJS controls and initializes them. So far, we haven't added any of these controls, but it's a good idea to leave this code in case you want to add them later. To learn more about WinJS controls, see Quickstart: Adding WinJS controls and styles.

A good place to register event handlers for non-WinJS controls is just after the call to WinJS.UI.processAll.

Hh986964.wedge(en-us,WIN.10).gifTo register your event handler

  • In the onactivated event handler in default.js, retrieve helloButton and use addEventListener to register our event handler for the click event. Add this code after the call to WinJS.UI.processAll.

    
        app.onactivated = function (args) {
            if (args.detail.kind === activation.ActivationKind.launch) {
                if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
                    // TODO: This application has been newly launched. Initialize
                    // your application here.
                } else {
                    // TODO: This application has been reactivated from suspension.
                    // Restore application state here.
                }
                args.setPromise(WinJS.UI.processAll());
    
                // Retrieve the button and register our event handler. 
                var helloButton = document.getElementById("helloButton");
                helloButton.addEventListener("click", buttonClickHandler, false);
    
            }
        };
    
    

Here's the complete code for our updated default.js file:


// For an introduction to the Blank template, see the following documentation:
// http://go.microsoft.com/fwlink/p/?linkid=232509
(function () {
    "use strict";

    var app = WinJS.Application;
    var activation = Windows.ApplicationModel.Activation;

    app.onactivated = function (args) {
        if (args.detail.kind === activation.ActivationKind.launch) {
            if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
                // TODO: This application has been newly launched. Initialize
                // your application here.
            } else {
                // TODO: This application has been reactivated from suspension.
                // Restore application state here.
            }
            args.setPromise(WinJS.UI.processAll());

            // Retrieve the button and register our event handler. 
            var helloButton = document.getElementById("helloButton");
            helloButton.addEventListener("click", buttonClickHandler, false);
        }
    };

    app.oncheckpoint = function (args) {
        // TODO: This application is about to be suspended. Save any state
        // that needs to persist across suspensions here. You might use the
        // WinJS.Application.sessionState object, which is automatically
        // saved and restored across suspension. If you need to complete an
        // asynchronous operation before your application is suspended, call
        // args.setPromise().
    };

    function buttonClickHandler(eventInfo) {

        var userName = document.getElementById("nameInput").value;
        var greetingString = "Hello, " + userName + "!";
        document.getElementById("greetingOutput").innerText = greetingString;
    }

    app.start();
})();

Run the app. When you enter your name in the text box and click the button, the app displays a personalized greeting.

A personalized greeting from our HelloWorld app

Note  If you're curious as to why we use addEventListener to register our event in code rather than setting the onclick event in our HTML, see Coding basic apps for a detailed explanation.

Step 6: Style our start page

It's easy to customize the look and feel of your app. Apps let you use Cascading Style Sheets, Level 3 (CSS3), much like you would for a website.

The default.html that Visual Studio created for us contains a reference to the WinJS style sheet:



    <!-- WinJS references -->
    <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet" />


What does this style sheet do? Quite a bit! It provides these benefits:

  • A set of styles that automatically give our app the modern Windows look and feel. Just including the style sheet will make our controls look great and they'll work with touch-based displays, too.
  • Automatic support for high-contrast modes. These styles were designed with high-contrast in mind, so when our app runs on a device in high-contrast mode, it displays properly.
  • Automatic support for other languages. The WinJS style sheets automatically select the correct font for every supported language. You can even use multiple languages in the same app and they are displayed properly.
  • Automatic support for other reading orders. It automatically adjusts HTML and WinJS controls, layouts, and styles for languages that read from right to left.

By default, each HTML page in your project contains a reference to the dark style sheet. The WinJS also provides a light style sheet. Let's try it out and see what it looks like.

Hh986964.wedge(en-us,WIN.10).gifTo switch to the light style sheet

  1. In your default.html file, replace the reference to the dark style sheet:
    
    
        <!-- WinJS references -->
        <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet" />
    
    
    

    With this one:

    
    
        <!-- WinJS references -->
        <link href="//Microsoft.WinJS.2.0/css/ui-light.css" rel="stylesheet" />
    
    
    
  2. Run your app. It now uses the light style sheet.

    Our HelloWorld app with the light style sheet

Which style sheet should you use? Whichever one you want. For apps that mostly display images or video, we recommend using the dark style sheet, and for apps that contain a lot of text, we recommend using the light style sheet. (If you're using a custom color scheme, use the style sheet that goes best with your app's look and feel.)

Creating your own styles

If you want to customize the look and feel from your app, you don't have to throw out the WinJS styles and start over from scratch. It's easy to make incremental changes by overriding the styles you want to change.

In fact, it's better to override the WinJS styles rather than creating your own. When your app runs in high-contrast mode, any changes to the colors in the default styles are automatically overridden by a color scheme that supports high-contrast.

You can override any style in the default style sheet by creating your own style sheet and including it after the WinJS style sheet. The Blank App template does this for you. It creates a style sheet named default.css that you can use to create your own styles.



    <!-- 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>

    <!-- HelloWorld references -->
    <link href="/css/default.css" rel="stylesheet" />
    <script src="/js/default.js"></script>


Let's create some of our own styles.

  1. First, lets add some div elements and classes to our HTML to make it easier to style.
    1. In Visual Studio, open the default.html file.
    2. Set your page header's class attribute to "headerClass". Create a div element and use it to contain your page's main content. Give it a class setting of "mainContent".
      
      
      <body>
          <h1 class="headerClass">Hello, world!</h1>
          <div class="mainContent">
              <p>What's your name?</p>
              <input id="nameInput" type="text" />
              <button id="helloButton">Say "Hello"</button>
              <div id="greetingOutput"></div>
          </div>
      </body>
      
      
      
  2. Now lets define our styles. Open the default.css file.

    Right now it's mostly blank:

    
    body {
    }
    
    
    
  3. According to Layout out an app page, the heading has a top margin of 45 pixels and a left margin of 120 pixels. The content area also has a left margin of 120 pixels, a top margin of 31 pixels, and a bottom margin of 50 pixels.

    Define the headerClass and mainContent classes and set their margins to follow these guidelines. Also, create a style for the greetingOutput div that sets its height to 20 pixels and its bottom margin to 40 pixels.

    
    
    body {
    }
    
    .headerClass {
        margin-top: 45px;
        margin-left: 120px; 
    }
    
    .mainContent {
        margin-top: 31px;
        margin-left: 120px;
        margin-bottom: 50px; 
    }
    
    #greetingOutput {
        height: 20px; 
        margin-bottom: 40px;
    }
    
    
  4. Run the app. Notice the change in spacing.

    The Hello, world app, with margins

Apps support CSS3, so there's a lot you can do to customize your app. (For more info about styling your app, see Quickstart: Styling controls.)

Step 7: Add a Windows Library for JavaScript control

In addition to standard HTML controls, your apps can use any of the new controls in the WinJS, such as the WinJS.UI.AppBar, WinJS.UI.FlipView, WinjS.UI.ListView, and WinJS.UI.ToggleSwitch controls. These controls offer an easy way to include common features in your apps that would normally require a lot of complicated CSS and JavaScript code to implement.

Unlike HTML controls, app controls don't have dedicated markup elements: you can't create a ToggleSwitch control by adding a <toggleswitch /> element, for example. To add a WinJS control, you create a div element and use the data-win-control attribute to specify the type of control you want. To add a ToggleSwitchRating control, you set the attribute to "WinJS.UI.ToggleSwitch".

Let's add a ToggleSwitch control to our app.

  1. In your default.html file, add a label and a ToggleSwitch control after the greetingOutput div.

    
    
    <body>
        <h1 class="headerClass">Hello, world!</h1>
        <div class="mainContent">
            <p>What's your name?</p>
            <input id="nameInput" type="text" />
            <button id="helloButton">Say "Hello"</button>
            <div id="greetingOutput"></div>
            <div id="toggleSwitchControlDiv" data-win-control="WinJS.UI.ToggleSwitch">
            </div>
        </div>
    </body>
    
    
    

    For the ToggleSwitch to load, your page must call WinJS.UI.processAll. Because our app is using one of the Visual Studio templates, our default.js already includes a call to WinJS.UI.processAll, as described earlier in Step 5, so you don't have to add any code.

  2. Run the app. Notice the new ToggleSwitch control.

    The Hello, world app, with a Windows Library for JavaScript control

Right now, clicking the ToggleSwitch control switches the selection between on and off, but it doesn't do anything else. Let's use an event handler to do something when the user changes the rating.

Step 8: Register an event handler for a Windows Library for JavaScript control

Registering an event handler for a WinJS control is a little different than registering an event handler for a standard HTML control. Earlier, we mentioned that the onactivated event handler calls WinJS.UI.processAll method to initialize WinJS in your markup. The WinJS.UI.processAll is enclosed in a call to the setPromise method.



            args.setPromise(WinJS.UI.processAll());           


If ToggleSwitch were a standard HTML control, you could add your event handler after this call to WinJS.UI.processAll. But it's a little more complicated for a WinJS control like our ToggleSwitch. Because WinJS.UI.processAll creates the ToggleSwitch control for us, we can't add the event handler to ToggleSwitch until after WinJS.UI.processAll has finished its processing.

If WinJS.UI.processAll were a typical method, we could register the ToggleSwitch event handler right after we call it. But the WinJS.UI.processAll method is asynchronous, so any code that follows it might run before WinJS.UI.processAll completes. So, what do we do? We use a Promise object to receive notification when WinJS.UI.processAll completes.

Like all asynchronous WinJS methods, WinJS.UI.processAll returns a Promise object. A Promise is a "promise" that something will happen in the future; when that thing happens, the Promise is said to have completed.

Promise objects have a then method that takes a "completed" function as a parameter. The Promise calls this function when it completes.

By adding your code to a "completed" function and passing it to the Promise object's then method, you can be sure your code executes after WinJS.UI.processAll is complete.

  1. Let's output the rating value when the user selects a rating. In your default.html file, create a div element to display the rating value and give it the id "ratingOutput".
    
    
    <body>
        <h1 class="headerClass">Hello, world!</h1>
        <div class="mainContent">
            <p>What's your name?</p>
            <input id="nameInput" type="text" />
            <button id="helloButton">Say "Hello"</button>
            <div id="greetingOutput"></div>
            <label for="ratingControlDiv">
                Rate this greeting: 
            </label>
            <div id="ratingControlDiv" data-win-control="WinJS.UI.Rating">
            </div>     
            <div id="ratingOutput"></div>
        </div>
    </body>
    
    
    
  2. In our default.js file, create an event handler for the Rating control's change event named ratingChanged. The eventInfo parameter contains a detail.tentativeRating property that provides the new user rating. Retrieve this value and display it in the output div.

    
    
        function ratingChanged(eventInfo) {
    
            var ratingOutput = document.getElementById("ratingOutput");
            ratingOutput.innerText = eventInfo.detail.tentativeRating; 
        }
    
    
    
  3. Update the code in our onactivated event handler that calls WinJS.UI.processAll by adding a call to the then method and passing it a completed function. In the completed function, retrieve the ratingControlDiv element that hosts the Rating control. Then use the winControl property to retrieve the actual Rating control. (This example defines the completed function inline.)

    
                args.setPromise(WinJS.UI.processAll().then(function completed() {
    
                    // Retrieve the div that hosts the Rating control.
                    var ratingControlDiv = document.getElementById("ratingControlDiv");
    
                    // Retrieve the actual Rating control.
                    var ratingControl = ratingControlDiv.winControl;
    
                    // Register the event handler. 
                    ratingControl.addEventListener("change", ratingChanged, false);
    
                }));
    
    
  4. While it's fine to register event handlers for HTML controls after the call to WinJS.UI.processAll, it's also OK to register them inside your completed function. For simplicity, let's go ahead and move all our event handler registrations inside the then event handler.

    Here's our updated onactivated event handler:

    
        app.onactivated = function (args) {
            if (args.detail.kind === activation.ActivationKind.launch) {
                if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
                    // TODO: This application has been newly launched. Initialize
                    // your application here.
                } else {
                    // TODO: This application has been reactivated from suspension.
                    // Restore application state here.
                }
                args.setPromise(WinJS.UI.processAll().then(function completed() {
    
                    // Retrieve the div that hosts the Rating control.
                    var ratingControlDiv = document.getElementById("ratingControlDiv");
    
                    // Retrieve the actual Rating control.
                    var ratingControl = ratingControlDiv.winControl;
    
                    // Register the event handler. 
                    ratingControl.addEventListener("change", ratingChanged, false);
    
                    // Retrieve the button and register our event handler. 
                    var helloButton = document.getElementById("helloButton");
                    helloButton.addEventListener("click", buttonClickHandler, false);
    
                }));
    
            }
        };
    
    
  5. Run the app. When you select a rating value, it outputs the numeric value below the Rating control.

Note  This section and the last one just touched on what you need to know to start using WinJS control. To learn more and to see a list of controls, see Quickstart: Adding WinJS controls and styles.

Summary

Congratulations, you're done with the tutorial! You learned how to add content to anapp. You also learned how to add interactivity and how to style the app.

Download the sample

Did you get stuck, or do you want to check your work? If so, download the Getting started with JavaScript sample.

Next steps

In the next part of this tutorial series, you learn more about how the app lifecycle works and how to save your app's state. Go to Part 2: Manage app lifecycle and state.

Related topics

Getting started with JavaScript: Complete code for the tutorial series
Programming Windows 8 Apps with HTML, CSS, and JavaScript (ebook)

 

 

Show:
© 2014 Microsoft. All rights reserved.