The fixes described here may or may not apply to other third party frameworks (besides Ionic, AngularJS, and WinJS), but they are probably a good place to start if you are running into issues.

The issues I've seen involve the following:

• App fails to load correctly or CSS is not applied
• Failure of partial pages to load in multi-page apps
• Expired certificate error

I expect some of these issues to be resolved shortly (e.g., the certificate issue), but community samples in particular are not likely to include these fixes soon.

Update the Shim

When you target Windows and Windows Phone 8.1 from a Cordova app, you may need to use the JavaScript Dynamic Content shim to enable support for some third party libraries, like Ionic, as a workaround for code that Windows flags as unsafe. In fact, the shim is included in the sample apps and the Blank App template. However, you will need to get an updated version of the shim and copy the code into winstore-jscompat.js, or your app may not work correctly. In the Ionic sample I tested, the older version of the shim was dynamically emitting <head> and <a> elements that prevented Ionic CSS from being applied. (In addition, this issue prevents the current AngularJS ToDoList sample app from working on Windows 8.1**.)

**Note: If you want to target Windows Phone 8.1 (recommended) using the ToDoList samples to get started, you will need to update the app as a CTP3 project.

Fix URL Prefixes (multi-page AngularJS apps)

Also, when you are using the AngularJS routing module (Ionic starter templates often use this module as well), you may need to include a call to aHrefSanitizationWhitelist. Typically, you include this in app.js or wherever you are calling your module configuration code:

    $compileProvider.aHrefSanitizationWhitelist(/^\s*(https?|ftp|mailto|file|ghttps?|ms-appx|x-wmapp0):/);

    $compileProvider.imgSrcSanitizationWhitelist(/^\s*(https?|ftp|file|ms-appx|x-wmapp0):|data:image\//);

If you don't include this code, your links may be flagged as unsafe by AngularJS, and partial pages may not load (On Windows, you may see a prompt asking whether to look for an app on the Store). For one example of using this code, see the Ionic SideMenu Starter template.

Update your Windows Certificate

If you start with the Blank App Cordova template in Visual Studio (or a community sample), you will also run into a Cordova bug caused by an expired certificate for Windows and Windows Phone 8.1. This bug is documented here and the fix is to include the provided temporary certificate either in /res/native/windows (Visual Studio 2015) or in /res/cert/windows8 (Visual Studio 2013 Update 4).

WinJS Compatibility Bug

Lastly, if you are using WinJS and some third party libraries like jQuery, you may run into this navigation issue. The fix has been checked into WinJS, but at present you will need to build your own version of WinJS to get the updated versions of ui.min.js and base.min.js.

Hopefully, these tips will help you get up and running!

Out of the box, the Multi-Device Hybrid Apps extension for Visual Studio includes only the Blank template. I took one of the more popular Windows Store templates, the Navigation App template, and ported it to Cordova. This template is available here. In this post, I thought I'd share what I learned in that process.

Before going through the porting process, you can evaluate your app for the likely ease, or difficulty, of making it work in Cordova. Here are some of the main considerations:

• Are there a lot of calls to Windows Runtime APIs? Cordova in VS supports the WinJS APIs, but native Windows Runtime APIs (Windows.* namespace) won't work in a Cordova app. For app lifecycle code and a few other common events, Cordova has APIs that you can use instead. For other native code, you may need to use a Cordova plugin to replace the native APIs, and code your app using the plugin's interface (JavaScript APIs).
• If you need to use a Cordova plugin for access to native APIs (for example, Geolocation or Camera APIs), check whether the feature is supported in a core plugin or a third-party plugin. Core plugins typically support all the most common target platforms; in third-party plugins, platform support varies. If plugin support is not already available for the native feature, work will be required to create a custom plugin (or to extend an existing plugin) before your app will work in Cordova. Creating a custom plugin will involve writing native code for the platform(s) that you are going to support.
• Are you using any third-party frameworks besides WinJS? Some frameworks may have incompatibilities with specific platforms or with Cordova.

The main steps involved in porting your app to Cordova:

1. Create your project using a Multi-Device Hybrid App sample app that uses WinJS.
2. Open it in VS, manually copy over your code, and get rid of any sample code that you don't need.
3. Update the app lifecycle code to use Cordova events.
4. Rewrite code that requires the use of a plugin.
5. Test the CSS in the various emulators. Use the merges folder for platform-specific CSS, if necessary.
6. Update images in platform resource files.

1. Create your project using a Multi-Device Hybrid App sample

Instead of using the Blank template included with Cordova, start with one of these sample apps; the apps listed here simplify the setup of the open source WinJS. A custom PowerShell script in the project file will automatically download and include WinJS when you build the project.

• Cordova Navigation Template (WinJS). This is a port of the Windows Store Navigation App template, and provides a simple multi-page app with page animations and Back button support. It includes the Windows Store navigator.js file.
• ToDoList sample using WinJS. This sample provides local storage using HTML5 Web Storage, cloud-storage using Azure Mobile Services, and geolocation using Bing Maps. Note that this sample uses TypeScript out of the box.

2. Manually copy your HTML, JavaScript, and CSS code, and get rid of sample code you don't need

No shortcuts here, but it's not hard for smaller apps. Cordova uses an index.html file instead of default.html. If you use the out-of-the-box Cordova project structure, you will naturally need to update script and internal URI references;  for example, in calls to WinJS.Navigation.navigate.

3. Update the app lifecycle code

The app lifecycle code in a Windows Store app likely includes one or more calls to Windows Runtime APIs. You need to replace these with Cordova APIs, such as the deviceready event handler. Here is an example of app lifecycle code from the Cordova Navigation Template. This code eliminates the need to call the Windows.ApplicationModel.Activation API.

(function () {
    "use strict";

    var app = WinJS.Application;
    var nav = WinJS.Navigation;
    var sched = WinJS.Utilities.Scheduler;
    var ui = WinJS.UI;

    document.addEventListener("deviceready", onReady, false);
    document.addEventListener("resume", onResume, false);

    function onReady() {
        // Handle the deviceready event.
        initialize();
    }
    function onResume() {
        // Handle the resume event
    }

    function initialize() {

        nav.history = app.sessionState.history || {};
        nav.history.current.initialPlaceholder = true;

        // Optimize the load of the application and
        // while the splash screen is shown,
        // execute high priority scheduled work.
        ui.disableAnimations();
        var p = ui.processAll().then(function () {
            return nav.navigate(nav.location || Application.navigator.home, nav.state);
        }).then(function () {
            return sched.requestDrain(sched.Priority.aboveNormal + 1);
        }).then(function () {
            ui.enableAnimations();
        });

    }

})();

4. Rewrite code that requires use of a plugin

If your app requires extensive use of one or more plugins, this step will likely involve the most work. If it requires only plugins that already work on all target platforms, especially the core plugins, comparatively less work will be required.

To support certain types of changes you made to the package.manifest file in the new app (before you ported it), you may have to use a plugin.
Cordova provides some handy APIs for a few events such as backbutton. If you can use these events instead of native APIs, you don't need to use a plugin. For more info, see Events.

5. Test and update the CSS

You're in the web developer world now! You will need to test your app on the different platforms and deal with browser differences in CSS implementations. Fortunately, WinJS should handle most of this, but there are exceptions. For example, Webkit-based browsers (Android, iOS) don't currently support the CSS3 grid layout, so you may need to use a flexbox in your app instead.

The Ripple Emulator will provide quick and easy testing of layout and CSS on Android and iOS. But, of course, to really verify your app you will need to do testing on platform emulators and devices.

The best practice for handling differences in display size (and orientation changes) is to use @media rules. For example, the following CSS applies to display sizes <500 px in width. Here, you override margin values for the .fragment header CSS selector.

@media (max-width:499px) {
    .fragment header[role=banner] {
        margin-left: 15px;
        margin-right: 30px;
    }
}

If necessary, use the merges folder to provide platform-specific CSS values. Cordova recommends using an overrides.css file for this purpose. When you use overrides, you should include an empty overrides.css in the project's css folder.

WinJS provides ui-dark.css and ui-light.css as style templates. You will need to decide which one provides the look you want in your app and whether you want the app to look the same on all platforms. If not, you will need to decide how much extra effort you want to invest to make the app look like a native app on all target platforms.

6. Update images in platform resource files

Android and iOS include device-specific files for the splashscreen and icons. The sample apps include these files, but the art will need to be updated for your app.

Finally -- Test, package, and publish

Packaging and publishing is platform-specific. For more info, see the documentation.

VS for Multi-Device Hybrid Apps doesn't support debugging Windows Phone targets in the current release (but that is coming, I'm told). So, if you're porting from a Windows Store app, you may choose to test, package, and publish for Windows Phone using your native Windows Store project (requires Windows 8.1 for phone support).

By that I mean that I don't use regular expressions very often and so I often get them wrong. When I want to write a complex regex, I find myself consulting the docs extensively and/or using a regex validation tool to figure out how to write the regex I need to get the results I want.

To help me (and developers like me), my teammates put together this handy downloadable guide to .NET regular expressions. You can download the guide as a .pdf or a .doc and it’s in brochure format. The idea is that you can either save the file to your computer, or if you want to print it out, you can fold it into a neat brochure. You can see a snippet of the brochure below:

This brochure format is something new we're exploring and we'd love to hear what you think. However, we mostly hope you will find this useful when you are writing regular expressions.

Being a JavaScript enthusiast, and also assigned to the language, I'm most excited
about the fact that you can now use HTML and JavaScript for Windows Phone.
Cool. Being able to do it in a single VS solution using shared code is gravy.

I ported my JSON Web reader app to a universal app template
in Visual Studio 2013 Update 2 (required). This solution targets both Window 8.1
and Windows Phone 8.1. You can check out that app here:

• JSON Web reader that uses the Hub/Pivot template

To get Visual Studio 2013 Update 2, which includes the Phone Emulator, and to get general info
about universal apps, go here:

• Building universal apps

To use the Phone Emulator, you need a machine with second level address translation (SLAT). For more info, go here:

• Windows Phone Emulator system requirements

For info about the templates, go here:

• JavaScript project templates
• C#/VB/C++ project templates

For info on porting a Windows Store app to the phone
(JavaScript emphasis), go here:

• Porting apps from Windows to Windows Phone

Besides the JSON Web Reader, I've worked on porting various other test samples to Phone. In most cases, I've been pleasantly surprised how easy it is. There are a number of controls that aren't cross-platform, which require more work. But generally, most of the extra work is around coding for different display sizes. Typically, you will use different HTML files for each platform (Phone and Windows have a separate project and app package within the shared solution), but you can use the same JavaScript code. In JavaScript code, you can test whether a feature is available before using it, or call WinJS.Utilities.isPhone to check your platform target. See the above links for more details.

The app uses a combination of 3D and 2D technologies to provide 3D effects without the development cost of creating full 3D models, such as you might use if you are writing WebGL or DirectX apps.

Currently, the app is implemented for Windows Store. There is not much Win8-dependent platform code, however, so I may port it to IE in a update in the near future.

Check out the sample here

Here is an illustration showing the chessboard in mid-rotation:

 Goals

The main goal of this app is to simulate playing on a real chess board against an actual person, in which touch-based interaction with the board & chess pieces is preferable to a mouse and feels natural (though a mouse also works). The more specific goals of this app are to demonstrate:

• 3D perspective-transforms and rotations on the chess board. This uses CSS3 for hardware-accelerated 3D animations.
• Board rotations using a hybrid of HTML5 and CSS3. During a rotation, the use of HTML5 <canvas> overlay for the chess pieces moves expensive calculations off the UI thread (to the GPU). The pieces are animated using tracking points on the transformed coordinate plane (the chess board, which is itself rotated using CSS3).
• Adding, moving, capturing, and removing pieces using CSS3.
• Use of requestAnimationFrame for performance-optimized repaints, also used during board rotations.
• Resetting/rescaling of board and pieces for changes in display size.
• Row & column detection.
• Sound effects (when capturing a piece).
• Dynamically updating CSS3 @keyframes rules. Importantly, this allows the use of relatively few @keyframes rules to apply to many different pieces with many different values.
• Consistent handling of app state to support different game modes (Start/Play, Add/Remove, Spin, Reach-thru).

This app does NOT demonstrate:

• Big Blue style AI (it's a two-player game).

Possible future enhancements:

• Restricting moves of the chess pieces to legal moves (the simulation is closer to a real chess board, in which you can move pieces wherever you want. The simulation does include capturing pieces, however). Since the app already does row and column detection, enforcement of legal moves is a possible future enhancement.
• A complete set of chess pieces. Unlike the 3D board, the pieces are 2D artwork that simulate 3D, and I just needed enough pieces to demonstrate all the concepts working. The supported pieces include: all black and white pawns, black and white knights, black and white bishops, and a white queen. (Sorry, no rooks and kings!)
• Enforcement of player turns. I did not implement support for playing on two different screens at the same time, involving a web service. That is an option for extending the app.
• Running in a browser outside the context of Windows Store. There is very little WinJS (Win8)-dependent code in this app, but I need to do an additional update to make it available as a Web-only app.
• Maintenance of app state after termination.

Links to More Info:

Check out the sample here

My other blog posts about the animation technologies (see Part II if you want more an intro to animations):

• Part I: Using JavaScript to set @keyframes in CSS animations
• Part II: Running multiple CSS3 and HTML5 animations

Tool-related documentation that was helpful:

• The HTML UI Responsiveness profiler was a critical tool to test the effect of board rotations on CPU and visual throughput. For that documentation, see this topic and the associated Walkthrough.
• The DOM Explorer was essential for comparing expected element values with actual element values. For more info, go here.
• To check your own app for memory leaks, use the JavaScript memory analyzer.

Here’s a 5-minute video tour of what the app does.

[View:https://www.youtube.com/watch?v=8qZ6X14JzMw]

This sample shows off tons of C++ and Windows 8.1 goodness, such as how to:

• combine C++, C++/CX, XAML, and DirectX.
• perform work in the background to keep your app running smoothly.
• render 3D content from the app on the live tile and other places in the app.
• use secondary tiles.
• use pixel shaders to create effects that run on both Intel and ARM-based devices.
• work with app bars.
• work with the GestureRecognizer.
• use Semantic Zoom.
• use the Search contract.
• download and cache images for later use.
• use the Settings flyout.
• create a basic logger to display diagnostic messages on the UI.

I'm working to add more detailed info about how the app works in the Documentation area. Be sure to check back for the latest updates. 

There’s also plenty of opportunity to improve the app and add features. Check out the Issues tab for some starter ideas.

Whether you're an established DirectX programmer or a C# and XAML developer interested in learning how to leverage the power of C++ and DirectX to differentiate your app, I hope you find this project useful. I look forward to hearing your feedback in the Discussions area.

Happy coding! 

The game I'm working on is a board game with a few 3D elements and (mostly) 2D elements that mimic 3D. I decided to implement the game using CSS3 transforms. In addition to CSS3, I also used the animation timing function, requestAnimationFrame, which is associated with the HTML5 specs. At the moment, I'm rendering one set of 2D game piece elements in a parent DIV element, which overlays the game board, but after I finish code optimization and performance testing, I may move the overlay containing the game pieces to an HTML5 <canvas> object.

Updated info, 2/19/2014: Check out the completed sample (Windows Store version)

When I started coding the animated components, I tried to think about user experience (UX) first before choosing a methodology for a particular animation. For UX, the main considerations were:

• Should touch/click or button click invoke an animation, or will the app initiate the animation itself?
• Should the animation complete every time it runs, or can it be canceled?
• Does the animation need to support different values for multiple DOM elements?

In your own coding, the answers to these questions can help you decide whether to start a particular animation using CSS pseudo-classes (focus, hover), by simply resetting animations in your JavaScript code, or by using requestAnimationFrame.

A few words about animation technologies

CSS3 allows you to perform animations using DOM element properties. If you use HTML5 or WebGL instead, your app will likely involve more development time but will typically result in the best performance. If your app requires lots of complex computations for positioning elements, plan on using HTML5 <canvas> or WebGL. In that scenario, you may want to skip to the last section, "Using requestAnimationFrame to start an animation."

If your animations follow predictable patterns, CSS3 may work great, and these animations will get hardware-accelerated. In addition, if you are moving lots of DOM elements around the screen using left and top CSS style properties (not CSS3), you will need to keep a close eye on perf.

Using focus and hover events to start an animation

You can initiate CSS3 animations by implementing pseudo-classes such as focus and hover on specific elements. hover isn't much use in a touch-centric app, so after a few tests I stopped using it. The focus event was more intriguing.

To use focus (or hover), create an animation in your CSS. The following example shows a rotate animation around the Z-axis.

  @keyframes rotate {
      from {
          transform: rotateZ(0deg);
      }
      to {
          transform: rotateZ(180deg);
      }
  }

To use this animation, set the animation properties on the associated DOM element in your CSS or in your JavaScript code. Here's an example of CSS:

  animation-duration: 6s;
  animation-fill-mode: forwards;
  animation-timing-function: ease-in-out

Then include the hover or focus event selector and the animation-name property. (I've shown both event selectors here.)

  #inner:focus {
      animation-name: rotate;
  }
  #outer:hover {
      animation-name: rotate;
  }

You can let the user start the animation by touch or click, or just call someFocusableElement.focus() in your code.

There are a few UX considerations to manage when using focus.

• Your animation gets canceled as soon as something else receives focus.
• You may not always want the user to decide which element receives focus.

The easiest way to manage these issues is to enable and disable pointer events on different elements. If you start an animation using focus and you want it to finish, disable pointer events on the other UI elements until the animation completes.

To disable pointer events on a set of elements:

  var children = wrapperElem.children;
  var len = children.length;
  for (var i = 0; i < len; i++) {
      children[i].style.pointerEvents = "none";
  }

To re-enable pointer events, use this value:

  children[i].style.pointerEvents = "visiblePainted";

If you need user-initiated animations but don't want to disable events on the other elements, use handlers for events like mouseup, mousedown, or focus in your code, and then use a different method to start the animation (see the following sections). In this scenario, you will of course need to remove the focus rule from your CSS code.

Changing the animation values to start an animation

When you change the animation values for an element, you start the animation. Depending on the new values, this will appear either as a restart or an update. For your animation to appear smooth, the starting CSS3 transform properties (like translate, rotate, scale, and opacity) must match the end properties of the previous animation. To incrementally change animation values that are different for each element in a set of DOM elements, you can dynamically change the @keyframes rule.

A very simple way to control animation using JavaScript is to create two or more @keyframes rules for an element. Then, when you want to start a new animation, just change the animation-name property from one rule to the other (you first reset duration, etc. in JavaScript).

  elem.style.animationName = exitPiece;

For example, I use the following rules for game elements in my board game app: enterPiece when a game piece is added, and exitPiece when a game piece is removed. Here is the CSS:

  @keyframes enterPiece {
      from {
          transform: translateY(-150px) scale(.5);
          opacity: 0;
      }
      to {
          transform: translateY(0px) scale(1);
          opacity: 1;
      }

  }

  @keyframes exitPiece {
      from {
          transform: translateY(0px) scale(1);
          opacity: 1;
      }
      to {
          transform: translateY(-150px) scale(.5);
          opacity: 0;
      }
  }

If you want to support additional behavior (for example when a game piece gets captured), you can create additional rules.

Using requestAnimationFrame to start an animation

The performance-optimized requestAnimationFrame function has replaced setTimeout and setInterval as the function of choice for timer-based animations. The callback function you pass to requestAnimationFrame gets called only when the browser is about to repaint the screen, so there are no wasted code cycles.

requestAnimationFrame is critical for independently adjusting values that need to be different for each member of a set of animated DOM elements. This function is used in loop-based HTML5 <canvas> apps, but you can also use it for simple manipulations of CSS properties like top and left. (If you want to benefit additionally from hardware acceleration, use requestAnimationFrame with HTML5 <canvas>, with WebGL, or potentially with some CSS3 properties values set in JavaScript.)

Note: If you are resetting lots of DOM elements using left and top properties, you will need a tool to help test perf. In Windows Store apps and web apps, use the HTML UI Responsiveness profiler. The same profiler is available in F12 tools for IE11. The profiler is easy to use and provides good feedback on CPU utilization and frame rate. If there are perf issues, you may need to switch to a <canvas> implementation.

You call requestAnimationFrame like this:

  var requestId = window.requestAnimationFrame(animFrame);

You must be sure to cancel the animation callback when your animation is complete:

  window.cancelAnimationFrame(requestId);

For a loop-based game, you cancel the animation callback when the game ends. In my game, I cancel it in a setTimeout timer with a delay value that equals the animation-duration.

Note: To take action either at the beginning or at the end of an animation, you can use setTimeout or events like MSAnimationStart and MSAnimationEnd.

Here is the essential code for the animation frame callback loop. It includes a recursive call to requestAnimationFrame.

  function animFrame(args) {
      // Manipulate DOM elements

      requestId = window.requestAnimationFrame(animFrame);
  }

Within the animation frame callback function, I get the current top and left coordinates of my DOM elements using getBoundingClientRect() (a very handy API for games, at least for IE and Windows Store, especially when working with a transformed coordinate plane), and then reset those values. The code here is truncated for readability.

  function animFrame(args) {

      gameObjects.forEach(function(piece) {

          // Get and manipulate DOM elements, or use cached elements.
          // point may be an element on a transformed coordinate plane,
          // or you might use the current element (piece),
          // depending on your app.
          // NOTE: The WinJS call is Windows Store only, so for IE
          // you need to use a different method to get the position
          // of the parent element.
          var pos = WinJS.Utilities.getPosition(point.parentElement);

          var topRect = Math.round(point.getBoundingClientRect().top);
          var leftRect = Math.round(point.getBoundingClientRect().left);

          // pos.top and pos.left are offsets of the parent element.
          piece.style.top = topRect - pos.top - piece.clientHeight + "px";
          piece.style.left = leftRect - pos.left + "px";

      });

      requestId = window.requestAnimationFrame(animFrame);
  }

As noted previously, the style and rendering of top and left values here are not running on the GPU. To to do that, make <canvas> the parent element and use methods available in <canvas> to draw the pieces.

Although you can combine a CCS3 animation with the animations produced in the callback function, you typically just need to run the CSS3 animation once for each DOM element (not once for each frame) in a complete animation cycle. For example, I combine a CSS3 scale transform with the top/left animations in the previous code, but this code is not contained in the animation callback function. The important aspect here is the dynamic setting of an @keyframes rule to adjust scale individually for each game element. For more information, see my earlier post.

  // Get currentScale and targetScale values for each DOM element.
  cssRuleAdjustScale.deleteRule("0");
  cssRuleAdjustScale.deleteRule("1");

  cssRuleAdjustScale.appendRule("0% { transform: " + currentScale + "; }");
  cssRuleAdjustScale.appendRule("100% { transform: " + targetScale + "; }");

  piece.style.animationDuration = "5.5s";
  piece.style.animationName = "adjustScale";

When the app is finished, I'll upload the full sample and post a link here. If you have time to look at it then, please send me some feedback!

Updated info, 2/19/2014: Check out the completed sample (Windows Store version)

Despite a few hiccups, CSS3 development has been pretty fast–which is an advantage of the technology vs. using the HTML5 <canvas> (note that <canvas> also has a lot of advantages, especially for games with a large number of independent objects). However, I thought I'd talk about a couple of areas where I got tripped up a bit using CSS3. In this post, I'll talk about the need to dynamically manipulate the @keyframes rule using JavaScript.

Basic CSS3 animations are pretty straightforward. You create your DOM elements, declaratively or otherwise, and specify a few animation properties. And then you create a set of one or more @keyframes
rules to handle the actual animations.

Here is some of the CSS code for an HTML element representing a game object. We'll say it's for a DIV element containing an image (<div id="piece"></div>). The animation-name rule specifies the @keyframes "enterPiece" rule.

  #piece {

      position: absolute;

      animation-duration: 1.5s;

      animation-fill-mode: forwards;

      animation-name: "enterPiece"

  }

Here is the CSS code for the @keyframes "enterPiece" rule. @keyframes allows you to specify beginning/end states and anything in between (such as what the animation should look like when 50% complete). In this example, I just set the beginning/end states.

  @keyframes enterPiece {

      from {

          transform: translateY(-150px) scale(1);

          opacity: 0;

      }

      to {

          transform: translateY(0px) scale(1);

          opacity: 1;

      }

  }

This is all pretty straightforward. The animation for the game object moves the object from a relative starting position of -150px to 0px, and changes the opacity from 0 to 1 while moving it this distance. (I include a scale value for informational purposes but I won't be using it—I'll be setting that value dynamically.)

Here's code to set some of these animation values in JavaScript: In this code, we set the animation duration, fill mode, and the animation name ("enterPiece", again), which specifies the same @keyframes code in CSS. In this case, we're doing it for a new element that we're about to add to the DOM.

  newNode.style.animationDuration = "1.5s";

  newNode.style.animationFillMode = "forwards";

  newNode.style.animationName = "enterPiece";

As I tested my code, I realized I would need to set different scale values for each piece, due to the use of a 3D perspective. This was a little trickier to do in JavaScript, because animated transform values such as scale, translate, and rotate belong to the harder to access @keyframes rule. I refused to create a bunch of extra @keyframes rules in the CSS**. Instead, after some investigation, I was able to obtain the rule using the following code, which iterates through the stylesheets to get the rule I wanted.

**requestAnimationFrame is another way to go. More on this in a later post.

Note:  If you don't need to show these values changing within an animation, you can just include them in CSS code, for example, like this: transform: rotateX(180deg).

  var cssRule;

  // Returns a reference to the specified CSS rule(s).

  function getRule() {

      var rule;

      var ss = document.styleSheets;

      for (var i = 0; i < ss.length; ++i) {

          // loop through all the rules!

          for (var x = 0; x < ss[i].cssRules.length; ++x) {

              rule = ss[i].cssRules[x];

              if (rule.name == "enterPiece" && rule.type

                      == CSSRule.KEYFRAMES_RULE) {

                  cssRule = rule;

              }

          }

      }

  }

To make sure I'm not getting the wrong CSS rule, I check the type, which needs to be CSSRule.KEYFRAMES_RULE, and I check the name. It's best to run this code during app initialization, and cache any rules which you need to modify in JavaScript.

Note: For non-IE browsers, check current recommendations for using the CSSRule.KEYFRAMES_RULE.

Once I had the right rule, I had to change it. The API documentation led me to think that I should use insertRule, but some testing indicated otherwise. Instead, I used appendRule along with deleteRule.

First, I needed to clear out the current rule values. To use deleteRule, you must pass an index to indicate which part of the existing rule to delete. An index of 0 indicates the from portion (that is, the "0%" portion) of the rule. Once I deleted the rule parts, I replaced them using appendRule, and here I passed in my dynamically set scale values.

  cssRule.deleteRule("0");

  cssRule.deleteRule("1");

  cssRule.appendRule("0% { transform: translateY(-150px) "

      + scale +"; opacity: 0; }");

  cssRule.appendRule("100% { transform: translateY(0px) "

      + scale + "; opacity: 1; }");

And this worked!

In Part II of this series, I talk about running multiple animations and using requestAnimationFrame. I'll share the full code when it's closer to final state.

For my game, I want to create a 5x5 grid of buttons that are bound to a list of letters that display a character value and a point value. Something like this:

I was surprised that there wasn’t more examples of how to display a bunch of bound buttons in a grid, as this seems to be a pretty common scenario. I was also surprised at how quickly I was deep into setting styles, data templates and control templates, so I thought I would share how I created my UI.

The Data

Since I need to display letters, I created a simple letter object that stores a character value, a base point value (my game increments the points during play), and a count for how many of each letter are contained in my list.

   1:  

   2: public class Letter

   3: {

   4:     public Char Character { get; set; }

   5:     public int BaseValue { get; set; }

   6:     public int Count { get; set; }

   7: }

In my code behind, I created a property on my Page named LetterList, which is an ObservableCollection of letters. I set the list as my data context for the Page.

   1: this.DataContext = LetterList;

So I had my data, I just needed to figure out the UI.

Changing the appearance of the default Button

Out of the box, a Windows Phone button looks like this.

I wanted something like this:

I needed a couple of changes for the button to look how I want.

1. The border needs to move closer to the actual edge of the button (I am pretty sure this violates some style rule, but that’s what I wanted)
2. The letter character should display in the center, in a large font, and the point value for the character to the lower right of the letter character.

I thought Changing #2 was easy. I created a DataTemplate for Button that set the set the Content property to a StackPanel and the StackPanel contains two TextBlock controls, one to display the character value, and one to display the point value.

But there is some layering here that is a little tricky.

• A DataTemplate is a reusable resource that sets the structure for the data it contains. That said; you can also apply a style to the data in the template, which I did, to establish the height and width for the button, and the color and thickness of the button border.
• I discovered that I needed to alter the ControlTemplate to change the border Margin, and therefore display the border at the outside edge of the button. This property is a dependency property but it is not template-bound, meaning I can’t set it directly and have it override the default property like I did with the border color and thickness.
• The control template is a property of the Style. There is probably a good reason for this, in the sense that the original button author did not want me messing with the border margin of a button, but I want to show you how to do it regardless. This article describes the basics of dependency properties and value precedence if you want some more information.

In summary, this means I need to set the control template in the style, which is set in the data template. Got that?

I remembered how to do all the DataTemplate stuff. I create two text block controls, set their font size and text alignment how I want and bind them to the letter character and value. I also set the style to my custom style, which I’ll show a bit later. Here’s how my data template looks:

   1: <DataTemplate x:Name="buttonTemplate" >

   2:     <Button Style="{StaticResource LetterButton}" Click="Button_Click_1" >

   3:         <Button.Content>

   4:             <StackPanel  Orientation="Horizontal">

   5:                 <TextBlock Text="{Binding Character}"  TextAlignment="Left" 

   6:                    VerticalAlignment="Top" HorizontalAlignment="Left" FontSize="35" >

   7:                 </TextBlock> 

   8:                 <TextBlock Text="{Binding BaseValue}" TextAlignment="Right" 

   9:                   FontSize="15"  VerticalAlignment="Bottom" HorizontalAlignment="Right"/>

  10:             </StackPanel>

  11:         </Button.Content>

  12:     </Button>

  13: </DataTemplate>

Next I needed to tackle the control template, which frankly intimidated me. The control template contains the entire visual tree for a control, and usually trying to create one that contains all of the behavior the original control author included is difficult. Imagine my happy surprise when I discovered how easy it is to change a control template in Visual Studio these days. I selected my button, right clicked and saw the following menu choices.

I chose to edit a copy of the template and simply adjusted the property that I cared about, the Margin for the border.

Following is my control template, style and data template. I’ve omitted most of the control template, just showing the portion I modified. You’ll see that most of the properties of the ButtonBackground border are specified as TemplateBinding, which exposes them to be set locally.

You will also see that the Style contains and sets the ControlTemplate, and the DataTemplate sets the Style.

   1: <ControlTemplate x:Key="ButtonBaseControlTemplate1" TargetType="ButtonBase">

   2:     <Grid>

   3:   

   4:        <!--Unchanged portions omitted for brevity-->

   5:         <Border x:Name="ButtonBackground" 

   6:             BorderBrush="{TemplateBinding BorderBrush}" 

   7:             BorderThickness="{TemplateBinding BorderThickness}" 

   8:             CornerRadius="4" Background="{TemplateBinding Background}" Margin="0" >

   9:             <ContentControl x:Name="ContentContainer" 

  10:             Foreground="{TemplateBinding Foreground}" 

  11:             HorizontalContentAlignment="{TemplateBinding HorizontalContentAlignment}" 

  12:             VerticalContentAlignment="{TemplateBinding VerticalContentAlignment}" 

  13:             Padding="{TemplateBinding Padding}" Content="{TemplateBinding Content}" 

  14:             ContentTemplate="{TemplateBinding ContentTemplate}"/>

  15:         </Border>

  16:     </Grid>

  17: </ControlTemplate>

  18: <Style TargetType="Button" x:Name="LetterButton" >

  19:     <Setter Property="Template" Value="{StaticResource ButtonBaseControlTemplate1}" />

  20:     <Setter Property="Height" Value="88" />

  21:     <Setter Property="Width" Value="88" />

  22:     <Setter Property="BorderBrush" Value="White" />

  23:     <Setter Property="BorderThickness" Value="3" />

  24: </Style>

  25:  

  26: <DataTemplate x:Name="buttonTemplate" >

  27:     <Button Style="{StaticResource LetterButton}" Click="Button_Click_1" >

  28:         <Button.Content>

  29:             <StackPanel  Orientation="Horizontal">

  30:                 <TextBlock Text="{Binding Character}"  TextAlignment="Left" 

  31:                    VerticalAlignment="Top" HorizontalAlignment="Left" FontSize="35" >

  32:                 </TextBlock> 

  33:                 <TextBlock Text="{Binding BaseValue}" TextAlignment="Right" 

  34:                   FontSize="15"  VerticalAlignment="Bottom" HorizontalAlignment="Right"/>

  35:             </StackPanel>

  36:         </Button.Content>

  37:     </Button>

  38: </DataTemplate>

Using WrapPanel to get the look of a Grid

My button looks good, so the next step is to lay it out in a grid, and bind it to my list of letters. I first tried a Grid layout, but I couldn’t get my data binding to work properly. I was pretty sure the buttons needed to be displayed in some type of list control to get the data binding right. ListBox appeared to be the control I needed, but I didn’t know how to display a ListBox so it looked like a grid.

I poked around and discovered the WrapPanel control in the Windows phone toolkit, which is available through NuGet.

The layout for the ListBox is also a little tricky. In order for my ListBoxItems to display correctly, I needed to set the ItemTemplate, which determines the visual structure of each ListBoxItem contained in the ListBox, to the data template I showed previously. This mean each list box item will have contain a button, which in turn contains two text blocks with my letter character and point value.

Finally, to layout my items in a grid-like way, I set the ListBox.ItemsPanelTemplate to a WrapPanel. The ItemsPanelTemplate property determines the layout of each item in the ListBox control.

I turned off scrolling on my ListBox, by setting the ScrollViewer.VerticalScrollBarVisibility property to disabled so just my 5x5 grid displays on the screen.

My XAML for the ContentPanel of my phone page looks like this:

   1: <Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0" ShowGridLines="True" >

   2:         <ListBox Height="440"  Name="ButtonList" 

   3:            ItemsSource="{Binding}"

   4:            ItemTemplate="{StaticResource buttonTemplate}" 

   5:            ScrollViewer.VerticalScrollBarVisibility="Disabled">

   6:             <ListBox.ItemsPanel>

   7:                 <ItemsPanelTemplate>

   8:                     <toolkit:WrapPanel Width="440"  />

   9:                 </ItemsPanelTemplate>

  10:             </ListBox.ItemsPanel>

  11:         </ListBox>

  12: </Grid>

And finally, when I ran my app, I saw success:

I am sure this code will continue to evolve as I create my app, but for now, I am happy with the progress I’ve made.

The Hub template sample app (JavaScript only, at present) demonstrates how to customize the data model in the Hub template to support asynchronous data (the app grabs images and text from a public Web service).

Here's a few other things that the sample app shows:

• How to implement data binding for the template's <img> elements and ListView controls.

• How to handle user-initiated requests for new data.

• How to process JSON data obtained from a Web service.

• How to add a progress indicator.

The app retrieves public photos and data available on Flickr using the Flickr public Web feed. You can replace this easily with another JSON, RSS, or Atom feed. The grouping of data is for demonstration purposes, and is somewhat arbitrary (the first five images are used for Hub template <img> elements, the rest are used ListView controls), but this can be easily modified to support data that is inherently group-based.

Note: Because the globalized string resources can be easily replaced, the sample app leaves these strings unmodified.

Link:

Hub template sample with asynchronous data