WinJS on Windows Phone 8.1

This post was written by Josh Rennert, Program Manager, Windows Ecosystem & Frameworks team

There were two big announcements involving Windows Library for JavaScript (“WinJS”) this year at //build 2014. One revealed MS Open Technology’s work to make WinJS cross-platform and open source. Developers are now able to bring the personality of Windows apps to other browsers and devices. For more information, check out Maria Kang’s post.

The second highlighted the release of WinJS version 2.1. With Windows Phone 8.1, we are proud to announce that the WinJS is now available on Phone.

WinJS 2.1 tailors the features of WinJS 2.0 (for Windows Apps) to fit the Windows Phone experience. We also added new controls and lit up new capabilities unique to Phone without sacrificing performance on low-end form factors.

Porting your existing Windows Store app is simple and painless, giving you a great opportunity to expand your reach onto Windows Phone. By using the same familiar languages and technologies, you can share resources between your Windows and Windows Phone apps. Source code, images, localization and other data—placing these files in one central location reduces the cost and effort in lieu of creating two separate, platform-specific apps. This is the cornerstone behind universal Windows apps, recently announced in David Treadwell’s talk from the Day 1 keynote.

Visual Studio provides us with three sets of templates: Windows Apps, Windows Phone Apps, and Universal Apps. While the first two will specifically target each form factor, with the third you can potentially write once and still cater to both. Developers can build compelling native apps across both platforms.

In this blog post, we will discuss the differences in design and feature sets, and point to additional resources regarding this exciting step forward.

Pivot

The Phone possesses a different model of app interaction than you would normally see on a PC or tablet device. Its user interface enjoys controls which do not currently exist in WinJS 2.0. Thus, for version 2.1 we introduced the Pivot control.

The full-screen container provides a quick way to navigate between different views, such as the ListView shown above. Those familiar with the Hub control will recognize the similarities both in its visual appearance and in its API. Indeed, it is even possible to find and replace the API names between the Hub and Pivot controls for most cases. The Pivot is a powerful control that can help produce the outstanding experiences users have come to expect in a Windows Phone app.

Visit the Quickstart: Using a pivot control for layout and navigation article for more information.

Adaptive controls

This Phone form factor introduces many challenges that may cause you to rethink the way your app looks and feels. A Windows device accommodates a vast array of screen sizes, ranging from small tablets to large monitors, whereas a Windows Phone device generally does not exceed five or six inches. Additionally, a Windows device may have a variety of input methods, including mouse and keyboard, whereas a Windows Phone device will use touch exclusively.

We have tried to minimize the work that is needed for your app to adapt across all devices, which typically amounts to minor adjustments in layout and visuals. WinJS automatically adapts its controls to match the Phone’s overall user interface and personality, so the majority of your markup will remain the same.

We have also updated our style sheets to complement the new design paradigms, with controls matching the Phone experience right out of the box. You can take advantage of the device’s excellent customization options and have your app match the user theme or accent coloring.

Here are a couple examples.

App bar

The App bar on Phone is always visible in some fashion. There are two closed states, minimal (below left) and compact (the default, below right). In the minimal state, no buttons are visible apart from the ellipsis on the right side. In the compact state, up to four buttons are visible at any one time.

Tapping or dragging the ellipsis will expand the drawer and animate the control to its open state, shown below. The App bar reveals the labels of the three primary buttons, as well as a menu of additional commands.

Screen real estate seldom poses an issue in a Windows Store app. Consider the first scenario of the HTML AppBar control sample on a Windows device:

The Camera button is separated from the primary commands along the width of the page. The ample resolution allows App bar commands to be broken up into two sections. Setting the section property to 'global' will affix a command to the right margin, while 'selection' will affix a command to the left margin.

On the other hand, in a Windows Phone app, screen real estate is at a premium. The prior images reveal the Camera button is moved to the secondary list of commands, hidden from view until the drawer has been expanded. The 'global' value now corresponds with the primary commands, and 'selection' with the secondary commands.

Lastly, screen orientation is more of a factor on a smaller device. On a Windows tablet or PC, the App bar remains pinned to the bottom of your perspective, regardless if the device is in landscape or portrait mode. On your Windows Phone, however, the App bar will remain pinned to the bottom of the physical device. Depending on which direction you rotate, the bar may appear on the left or right side of your screen, with the icons and text oriented appropriately. No work is needed to achieve this look and functionality—the control will automatically adapt as appropriate.

For more information, refer to the documentation for the WinJS.UI.AppBar object.

Intrinsic controls

In order to maximize the use of space, a text input on Phone stretches to match the width of its parent. As long as the width is not forced, this behavior will take place by default.

Upon device rotation, the text box will properly resize to fill the remainder of the screen.

The slider, select, and toggle switch controls also exhibit this flex-width behavior.

Noteworthy changes

While the Phone introduces new controls that do not exist on Windows, there are some Windows controls that do not fit the overall design on Phone.

Flyout, Menu, NavBar, SearchBox, SettingsFlyout, and Tooltip do not make sense in a Windows Phone app. Likewise, BackButton is no longer needed, as there is now a back button built into the hardware. Consequently, these controls are not available in WinJS 2.1.

With that being said, there are mitigations for each unsupported control. See WinJS API changes for Windows Phone 8.1 for a complete list of API deprecations, functional changes, and optimizations.

It is worthwhile to point out that the HTML platform on Windows Phone does not support a few HTML elements that are supported on Windows. These are the context menu, message dialog, and simple tooltip. Similarly, the file upload and progress ring controls work, but are not officially supported.

Making your app universal

Adopting WinJS 2.1 in a Windows Phone app should feel seamless and familiar with work you have done in a Windows Store app with WinJS 2.0. The primary differences between versions are all about the controls, as befits the deltas between the Windows Phone and Windows user interfaces. Beyond that, the core capabilities and utilities of WinJS are identical, streamlining the development of universal apps for Windows to reach customers across devices.

Additional resources

You can learn more about WinJS on Phone from Paul Gusmorino’s Build talk, What’s new in WinJS: Windows Phone and the road ahead: https://channel9.msdn.com/Events/Build/2014/2-506

Josh Williams and Ryan Salva also gave a full coding demonstration for universal apps in Build a Converged Phone and PC App using HTML and JavaScript: http://channel9.msdn.com/Events/Build/2014/2-540

More help can also be found through the following links:

· Porting a Windows Runtime app using JavaScript to Windows Phone

· WinJS API changes for Windows Phone 8.1

· Try WinJS

· WinJS on GitHub

· WinJS Dev Center

· Building Windows Phone 8.1 Apps in HTML (Visual Studio Blog)

Also be sure to check out the new Phone and converged, universal samples:

· HTML AppBar control sample

· HTML ListView essentials sample

· HTML Pivot control sample

· HTML scrolling, panning, and zooming sample

Continue reading...