Oct
1
2012

CSS3 for Windows Store Apps: Animations

CSS3 has brought much goodness to the web developer community.  The feature that potentially steals the show is CSS3 Animations – which can also be used when developing applications for the Windows Store via JavaScript.

If you are not familiar with animations, the name itself is practically self-explanatory.  Animations can deliver very appealing “eye-candy” in a variety of ways including object movement, resizing, transforming, fading, style changes, and much more.  Because animations have been around awhile, there is plenty of information out there to help you get started, such as the animations topic at the IE 10 Guide for Developers and Hands On: Animations on IE Test Drive.  Our focus here is more on how to use animations in the context of writing apps for the Windows Store.

Animations Simplified

A chronic worry when developing content for the web is how our creative work will render in multiple browsers.  For example, the following CSS rules define an animation for bringing an element in from above the screen:

@-webkit-keyframes drop-in {
    0%   {top: -100px;}
    100% {top: 0px;}
}
@-moz-keyframes drop-in {
    0%   {top: -100px;}
    100% {top: 0px;}
}
@-o-keyframes drop-in {
    0%   {top: -100px;}
    100% {top: 0px;}
}
@keyframes drop-in {
    0%   {top: -100px;}
    100% {top: 0px;}
}
#message {
             position: relative;
    -webkit-animation: drop-in 1s forwards;
       -moz-animation: drop-in 1s forwards;
         -o-animation: drop-in 1s forwards;
            animation: drop-in 1s forwards;
}

All of the rules above are reduced to the following when developing apps for the Windows Store:

@keyframes drop-in {
    0%   {top: -100px;}
    100% {top: 0px;}
}
#message {
     position: relative;
    animation: drop-in 1s forwards;
}

Why so much reduction?  When writing Windows Store apps, we are not worried about supporting multiple browsers.  Whatever standards work for IE 10 are all we need.  Granted, if you used the previous rules with all the vendor prefixes while creating an app - no error would occur, they would just be ignored.

Playing Animations

Animations are triggered as soon as they are defined.  In the previous example, as soon as the page with the element with and ID of “message” was navigated to, the animation was triggered.  Animations can be triggered from code as well.  Consider the following example:

@keyframes drop-in {
    0%   {top: -100px;}
    100% {top: 0px;}
}
.animate-drop-in {
    animation: drop-in 1s forwards;
}
#message {
     position: relative;
}

The rules above introduced a slight change from what we observed previously – the animation was moved to a class named “animate-drop-in”.  Assuming the element with an ID of “message” is not defined with the new class name, the animation will not occur.  However, we can trigger the animation in code as seen here:

message.onclick = function () {
    message.classList.toggle("animate-drop-in");
}

The click event handler for the “message” element toggles the class name.  Once the app sees the element is assigned to an animation (which is what the new class does), it triggers the animation.  The toggle method of classList returns a boolean value based on whether it added (true) the class name or removed (false) it.

If needed, you can respond to three events related to animations.  Here is the syntax for defining the handlers for each:

// animation started
message.addEventListener("animationstart", function (arg) { });

// animation iteration completed
// applies only when animation-iteration-count > 1
message.addEventListener("animationiteration", function (arg) { });

// animation ended
message.addEventListener("animationend", function (arg) { });

The above event handlers are handy and can allow a chain of complex animations.  For example, in the event handler for when an animation ends, you can add code to trigger a completely new animation.

Animations vs. Transitions

A close relative to animations is CSS3 Transitions, and those are covered in another post entitled CSS3 for Windows Store Apps: Transitions.  Since both of these technologies offer “animation” as the effect, you might wonder when to use one or the other.  With that in mind, take the following in consideration when trying to decide which is best:

Animations
  • Effect is played as soon as animation is defined, or programmatically
  • Multiple stages are possible, allowing more complex animations
Transitions
  • Effect is triggered when a targeted property value changes, usually due to a state change such as when a :hover is defined.  A targeted property value changed in code will also trigger a transition.
  • Syntax is much simpler, thus, effect is usually simpler than what can be done with animations.

Another point to think about is what the intent of each technology is.  Transitions (as the name implies) are really intended to provide a nice visual effect when something is changing state.  Animations can be used for anything pertaining to the logic of the application.

With Great Power…

Animations offer a great way to enhance the user experience.  However, too much of a good thing can become an annoyance. So be judicious with your implementations of animations.

It is an exciting time to be a developer with web skills.  Harness what you know and use it to great some great applications for the Windows Store.  Be sure to take advantage of all the resources available at Generation App!

    Copyright © Microsoft Corporation. All rights reserved.
    The code provided in this post is licensed under the Microsoft Public License (Ms-PL).
Oct
1
2012

CSS3 for Windows Store Apps: Transitions

CSS3-LogoWindows 8 brings in a new era of opportunity for the web developer/designer in that applications in the Windows Store can be written with “web” technologies such as HTML5, JavaScript, and CSS3. Creating a compelling user experience is an important aspect of a successful app, and CSS3 is a fantastic way to reach that objective.  This post will specifically address a great way to enable fast and fluid interactions in your app by using CSS3 Transitions.

If you haven’t been using transitions or know what they even do, then let’s start with a quick description:  Transitions allow content on the screen to change from one visual state to another in a gradual, animated way.  To learn more about the basics of transitions, check out the Transitions topic at the IE 10 Guide for Developers, and play with the Hands On: transitions on IE Test Drive.  The focus here will assume you know the fundamentals of transitions and want to how to use them when developing apps for the Windows Store.

Transitions from Web to App

Will you need to define transitions differently for apps than for web pages?  Technically, the answer is no. But you may not need to work so hard. For example, consider the following CSS rule:

.transit {
  -webkit-transition: all 0.4s;  
     -moz-transition: all 0.4s; 
       -o-transition: all 0.4s;  
          transition: all 0.4s; 
}

When developing for the web, we worry about web things – such as supporting multiple browsers. This is not a worry when developing an app for the Windows Store. This means you don’t have to riddle your CSS with all the vendor prefixes as seen above.  Therefore the above rule is reduced and far more simple to read and manage as seen here:

.transit {
   transition: all 0.4s; 
}

When a transition is defined, it specifies what properties are targeted for animation and for how long.  In the example above, the all keyword means all animatable properties.  A transition is triggered when any targeted property value changes. A common scenario where values are changed is when using CSS pseudo classes such as :active, :checked, :disabled, :enabled, :focus, :hover, :invalid, and :valid are in play.  Hovering is one of the most common uses of transitions, as seen here:

.box {
   background-color: #FFFFFF;
         transition: background-color 1s;
}

.box:hover {
   background-color: #FF0000;
}

The above example fades from white to red and smoothly back again when hovering.  Although hover effects are appealing, keep in mind that Windows 8 is an operating system designed to fully embrace touch screen devices.  Hovering works well with a mouse, but not with a finger.  One possible way to deal with this is seen here:

.box {
   background-color: #FFFFFF;
         transition: background-color 1s;
}

.box:hover, .box:active {
   background-color: #FF0000;
}


The subtle change above is adding the :active pseudo class if the targeted element is pressed down.  This may not be practical in some circumstances, but it at least involves use touch devices when using you app.

Transitions in View States

Another way transitions are triggered is by use of media queries.  Windows 8 applications can run in multiple layouts, and media queries can respond to layout changes by responding to the view state.  Here is an example of a style sheet shell with media queries for each supported view state:

/* shared css rules go here */

/* media queries for adapting to layout changes */
@media (-ms-view-state: filled) { }
@media (-ms-view-state: fullscreen-landscape) { }
@media (-ms-view-state: fullscreen-portrait) { }
@media (-ms-view-state: snapped) { }

It is useful to know that transitions can be triggered by layout changes because proper use of them can enhance the fluidity of the application.  For example, a switch to a snapped layout might require a change in font size.  With just a subtle transition, you can get the effect of a graceful move to snapped view and back.  This is demonstrated in the following CSS rules:

.subheader {
     /* recommended subheader size */
     font-size : 20pt;
    font-family: 'Segoe UI Light';
          color: rgba(255,255,255,1.0);

     /* subtle shrink|grow effect */
     transition: font-size ease 0.3s;
}

@media (-ms-view-state: snapped) {
    .subheader {
        /* recommended subheader size for snapped */
        font-size: 11pt;
    }
}

When the rules are implemented above, a switch in the application to a snapped position will create a simple shrink effect.  When switching out of snapped view, the text quickly grows.  Careful use and experimentation can lead to a polished user experience.

Transitions in Code

While changes to targeted properties of a transition can be defined in the CSS rules, another way to make property changes programmatically through JavaScript.

Transitions are always timed.  One way to interact with a transition in code is to respond to the transitionend event when it is complete.  To demonstrate, first look at the following CSS rule:

.demo-transition-end {
    transition: all 4s;
}

.demo-transition-end:active {
        background-color: #FF0000;
               transform: rotate(360deg);
}

Now here is an example of code that responds to an element on the page that is the target of a CSS transition rule above:

var box = document.querySelector("#box");
box.addEventListener("transitionend",
    function (args) {
        if (args.elapsedTime < 4) {
            box.innerText = "Keep Pressing!";
        }
    }
);

In the code above, an anonymous function is used as the event handler when the transition ends.  Note that the argument supplied to the function has an elapsedTime property, allowing you to determine how long the transition lasted.  Because the transition is triggered by the :active pseudo class, it will only reach 4 seconds if the user continues to press down on the element.  The code above detects the user let go too soon, and changes the text of the element to encourage the user to keep pressing.

To continue with this example, a new class rule will be added:

.vanish {
    transition-delay: 1s;
           transform: scale(0.01);
             opacity: 0.01;
}

Now an else clause will be added to the event handler, so that the complete code now looks like this:

var box = document.querySelector("#box");
box.addEventListener("transitionend",
    function (args) {
        if (args.elapsedTime < 4) {
            box.innerText = "Keep Pressing!";
        } else {
            box.innerText = "Let Go...";
            box.classList.add("vanish");
        }
    }
);

The code now responds if the transition reached a full 4 seconds.  If that happens, it changes the text of the element to “Let Go…”.  It also calls on the element’s classList property, and adds a new class named vanish.  The addition of the class rule will invoke another transition that will make the element shrink and disappear in 1 second.

The classList property allows you to easily change the the state of the class attribute, which will invoke a transition if any targeted property values change.  You can use classList for adding, removing, inspecting, or toggling class names in the attribute.  You can also simply change any of the elements style property values directly to also invoke a transition.

Transitions Beyond

Fans of CSS3 transitions will enjoy knowing that such powers are easily tapped when developing Windows Store apps with JavaScript.  You should also be aware that the WinJS.UI.Animation API contains methods for transitioning content as well.

Have fun coding, and be sure to benefit from all the resources available to you at Generation App!

    Copyright © Microsoft Corporation. All rights reserved.
    The code provided in this post is licensed under the Microsoft Public License (Ms-PL).
Sep
27
2012

JavaScript for Windows Store Apps: Error Handling

Are you confident you are writing your JavaScript code error free?  Do you wonder if traditional JavaScript error handling techniques still apply when developing for Windows Store apps?  Does the Windows Library for JavaScript provide additional support for error handling?  Do you deal with errors differently when writing asynchronous code?  This entire post is dedicated to addressing these questions!

To Err is Human

Let’s be clear – if you were perfect and could write code that never fails, you would not need to read any further. For the rest of us (which is all of us), we must acknowledge that errors very often creep into code.  Furthermore when developing with a language that is not strongly-typed such as JavaScript, there is potential for even more errors.  Why? Consider the following code:

var x = 4;

// somewhere else in code...
x = "four";

The above code is valid.  It showcases the dynamic nature of the language. However, it also illustrates the potential confusion as to what the variable x is. Any misuse of x based on assumptions could lead to buggy behaviors.  One way to minimize these kind of issues is to be consistent with variable assignments with regard to inferred type. In other words, if a variable is assigned to a string, keep it a string.

Syntax errors are typically reported through Visual Studio when running the application in debug mode.  However, the error message may not clearly state what is needed for correction.  For example, observe the following syntax error:

varr x = 4;

Isolated from all other lines of code, it is easy to see that the keyword var was misspelled. Yet the IDE reports the error at runtime this way:

javascript critical error

An entry level scripter could debate that there is a ‘;’ at the end of the line, and rationalize the error message itself is erroneous.  The moral of the story here is to examine the complete line of code and surrounding context for discrepancies when the reported error message is not clear.

For web developers who are bringing their JavaScript skills over to Windows Store app development, the use of try…catch…finally statements are fully supported and should be used when attempting to execute any line of code that is conditional to a successful outcome – such as accessing external resources.

Mistrust is a Virtue

I find it a little humorous that the uninitialized use of WinJS.log (a method for logging error information among other things) will cause an error to be thrown at runtime.  The log method can be initialized with WinJS.Utilities.startLog (for logging to the JavaScript console) or assigned to a custom method with logging behaviors defined by the developer.  A straight call to the log method without initializing will cause following:

JavaScript runtime error: Object doesn't support property or method 'log'

Of course, when the log method is initialized - no errors are reported.  However, consider a scenario where settings in the application determine whether the log method will be initialized or not.  In that case, what is a safe way to call the log method?  Some might create a global variable that could be used in an if statement to see if logging is enabled before every call.  That will work, but there is another way.  Consider the following code:

WinJS.log("Risky", "demo", "info");
WinJS.log && WinJS.log("Safer", "demo", "info");

The second line of code is “safer” because it starts with a check to see if the log exists.  The term “safer” is used instead of “safe” because by saying log “exists” what that really equates to is that it is not one of the following: null, undefined, an empty string, or a numeric value of zero.  Even so, it is still safer to use the logical && operator (no if statements needed) because it will exit the statement immediately when a false value is returned.

There is another technique using the || operator which can help reduce errors by producing a default value if one is not provided.  In the following code, the name parameter is given a value if none were already assigned:

function echoName(name) {
    name = name || "John Doe";
    return name.toUpperCase();
}

The above code will produce the following output:

echoName();             // JOHN DOE
echoName("M Palermo");  // M PALERMO

So far so good, but what if the following call is made:

echoName(4);

Passing in a non-string value causes the following error:

JavaScript runtime error: Object doesn't support property or method 'toUpperCase'

To prevent unwanted errors like this, there needs to be a guarantee that the method is safe to call. One way to do so is by using an approach mentioned previously - as seen here:

if (name && name.toUpperCase) {
    // safely call name.toUpperCase();
}

At other times it may be more preferable to simply confirm what type it is.  A common way to accomplish this is to use the typeof operator which returns a string declaring what the underlying type is as seen here:

var x;
(typeof x === 'undefined') // true

x = 4;
(typeof x === 'number')    // true

While typeof performs as expected in most cases, there are other times it may resolve types different than we could, as seen here:

(typeof 'abc' === 'string')             // true
(typeof new String("abc") === 'string') // false – type is object

In order to determine the actual type value, consider implementing a helper function like the one demonstrated here:

function isTypeOf(o,t) {
    if (t && t.charAt && t.charAt(0)) {
        return (Object.prototype.toString.call(o) === "[object " + t + "]");
    } else {
        throw new WinJS.ErrorFromName("args", 
            "'t' required and must be a string.");
    }
}


isTypeOf("abc", "String");             // true
isTypeOf(new String("abc"), "String"); // true
isTypeOf(4);                           // error thrown

The isTypeOf function first checks to see if the t parameter has a value, that the value has a charAt method, and that a call to charAt(0) will not return an empty string. If all conditions are true, the function returns a value based on the comparison of t and the type exposed from Object.prototype.toString.call.  Note that if the t parameter is not provided or not a string, an error is thrown using the WinJS.ErrorFromName factory method which is an easy way to create an error object based on name (error type or category) and message.

So why throw an error?  Doesn’t that defeat the purpose of preventing problems in the first place?  In the above example, the error is thrown from inside a helper function. Because this function could end up in a reusable library, it is a methodology for communicating it is being misused to application level code.  With that understanding, you will likely spend far more time handling errors in the application level code vs. throwing them.

The main message up to this point is to take preemptive strikes in your code to minimize errors as much as possible.  Now what about the errors that went unhandled?

Leave Nothing Unhandled

For all the unknown errors that could happen in your application, there is a simple way to catch them all in one place. The WinJS.Application object has an onerror event that traps all unhandled errors in one place.  Because error could happen at any time, this should be hooked to an event handler as soon as possible in the application lifetime.  Most of the JavaScript project templates for the Windows Store contain a default.js file where application initializing occurs.  Near the top of that file, you can add an event listener for unhandled application errors like seen here:

(function () {
    "use strict";
    
    WinJS.Binding.optimizeBindingReferences = true;

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

    app.addEventListener("error", function (err) {
        var md = Windows.UI.Popups.MessageDialog;
        var msg = new md(err.detail.message, "Ooops!");
        msg.showAsync();
        // return true; // only if error is handled
    });

    [remaining code...]

})();

If an unhandled error happens anywhere in the application, the above listener function gets called.  A message is displayed to the user indicating the details of what has occurred, and then the app stops. The app terminates because the error is still considered unhandled. Returning true from the error handler communicates to the system that the error has been handled and is ok to continue.

Unhandled errors can also be caught at the page level while the page is processing.  This is especially easy to do when using WinJS.UI.Pages.  The following code is an example of how to add an error event listener for the PageControl instance within the define method:

WinJS.UI.Pages.define("/pages/errors/errors.html", {
 
    error: function (err) {
        WinJS.log && WinJS.log(err.message, "demo", "error");
    },

    [remaining code...]

});

It is worth repeating that this event only fires if an unhandled error occurs during the initial processing of the page. Therefore, unhandled errors that occur in after the processing of a page (in a click event for example) will be directed up to the application level for inspection.

When Promises are Broken

Promises allow for asynchronous code, and because this introduces it’s own level of complexity, it is important to know how to handle errors when using them. In order to appreciate the different options available, consider the following example of a custom promise:

function doAsync(msg, limit) {
    return new WinJS.Promise(
        // c complete, e error, p progress
        function (c, e, p) {
        msg = msg || "no-msg";
        limit = limit || 3;
        var seconds = 0; 
        var iId = window.setInterval(function () {
            try {
                seconds++;
                if (msg === "fail") {
                    throw new WinJS.ErrorFromName(
                        "promise", "Muhahaha!");
                }
                p && p(msg + ": " + seconds.toString());
                if (seconds > limit) {
                    window.clearInterval(iId);
                    c && c(msg);
                }
            } catch (ex) {
                window.clearInterval(iId);
                e && e(ex);
            }

        }, 1000); // repeat every second, stop at limit
    });
}

The doAsync function defined above is a custom promise.  When called, it allows a message (provided into the function via the msg parameter)  to be used after a number of seconds (determined by the limit parameter) passes by.  When the time limit is reached, the “complete” function(represented by c parameter) is called.  A “progress” function (represented by p parameter) is called every second, allowing the application to potentially update the UI.  And if any errors occur, the catch block passes the error into an “error” function (represented by e parameter).  If the value of msg equals “fail”, an error is thrown.

The following code demonstrates all the helper methods that will be used when calling the doAsync function:

function doComplete(msg) {
    WinJS.log && WinJS.log(msg + ": complete", "demo", "info");
}

function doProgress(msg) {
    WinJS.log && WinJS.log(msg, "demo", "info");
}

function doError(err) {
    var msg = "undefined error";
    if (err) {
        msg = err.detail;
        if (!(msg && msg.message))
            msg = err.message || "err type unknown";
    }
    WinJS.log && WinJS.log(msg, "demo", "error");
}

Each function calls on WinJS.log  to display data. Now here is the code that brings them all together:

doAsync("promise", 4) // doError not called
    .then(doComplete, doError, doProgress);
    // final call was to doComplete function

doAsync("fail", 4) // doComplete not called
    .then(doComplete, doError, doProgress);
    // final call was to doError function

In each call to doAsync above, a message is passed in, and the duration of the asynchronous call will be limited to 4 seconds.  Each second that ticks by will cause the doProgress function to be called. If all goes well when the 4 seconds are up, the doComplete function is called.  However, if the promise encounters an error, the doError function is called instead.

Promises can be chained together to allow one asynchronous call to invoke the next when completed.  When chaining promises together, put the error handler only in the final link of the chain – the done method.  Here is an example of chaining promises using the doAsync function:

doAsync("chain(1)", 4)
    .then(function (msg) {
        doComplete(msg);
        return doAsync("fail", 4);
    }, null, doProgress)// null passed in for error
    .then(function (msg) {
        doComplete(msg);
        return doAsync("chain(2)");
    }, null, doProgress)// null passed in for error
    .done(null, doError);
    // doError only needed in done method

In the promise chain above, when “chain(1)” is complete it calls on “fail”.  Since “fail” will cause an error to be thrown, “chain(2)” is never called, and processing is directed to the doError function passed into the done method of the chain. 

Promises can also be joined together too.  This allows multiple asynchronous calls simultaneously, but allowing a method to be called when all the joined promises complete.  When handling errors in this scenario, do the following:

var promises = [];
var i = 0;
// each promise has an error handler
promises[i++] = doAsync("2seconds", 2)
    .then(doComplete, doError);
promises[i++] = doAsync("fail", 8)
    .then(doComplete, doError);
promises[i++] = doAsync("3seconds", 3)
    .then(doComplete, doError);
// join promises
WinJS.Promise.join(promises)
    .done(function () {
        doProgress("all promises completed");
    }, doError);

Unlike chaining, joined promises should have their own error handlers.  If a failure happens in one of the promises, it will not stop the others in the join.

On a final note regarding promises, an error handler can be attached to WinJS.Promise.onerror. Do this as a safety net in addition to the methodologies covered so far.

End Gracefully

In summary, remember these useful guidelines and tips while you are writing your Windows Store app with JavaScript:

  • Errors happen – even in your code.
  • Error messages can be vague, so examine the context of suspicious code!
  • Trusting that your code should work is a bad idea.
  • Avoid common pitfalls by implementing a good type-checking strategy.
  • Handle the unhandled at the application level and page level.
  • Use error handlers appropriately when dealing with promises.

If you have not done so already, make sure you are getting all the latest resources by creating a profile at Generation App!!!

    Copyright © Microsoft Corporation. All rights reserved.
    The code provided in this post is licensed under the Microsoft Public License (Ms-PL).
Sep
18
2012

Microsoft DevRadio: Branding Your App

To play video, hover above and press play button.

Abstract: win8genapp30
What are some simple ways you can make your application's tile look awesome? Would you like to add a custom splash screen? Check out this episode from Michael Palermo

Next Steps:
Step #1 – Download Windows 8 and Windows 8 SDK
Step #2 – Download Visual Studio Express for Windows 8
Step #3 – Start building your own Apps for Windows 8

Subscribe to our podcast via iTunes, Zune, or RSS

If you're interested in learning more about the products or solutions discussed in this episode, click on any of the below links for free, in-depth information:

Websites:

Developing for Windows 8 in 1/2 the time!

Virtual Labs:

    Copyright © Microsoft Corporation. All rights reserved.
    The code provided in this post is licensed under the Microsoft Public License (Ms-PL).
Sep
12
2012

Microsoft DevRadio: Writing Code When the App Starts

To play video, hover above and press play button.

Abstract: win8genapp30
When does an application start in a blank and navigation template and where can you start writing your code for your app? Tune in for this helpful how-to from Michael Palermo

Next Steps:
Step #1 – Download Windows 8 and Windows 8 SDK
Step #2 – Download Visual Studio Express for Windows 8
Step #3 – Start building your own Apps for Windows 8

Subscribe to our podcast via iTunes, Zune, or RSS

If you're interested in learning more about the products or solutions discussed in this episode, click on any of the below links for free, in-depth information:

Websites:

Videos:

Virtual Labs:

    Copyright © Microsoft Corporation. All rights reserved.
    The code provided in this post is licensed under the Microsoft Public License (Ms-PL).
Aug
29
2012

JavaScript for Windows 8 Apps: How to Access the User’s Display Name

Need to know the display name of the user currently logged in to Windows 8?  The task is easy!

To demonstrate, I created a new “Blank App” JavaScript project in Visual Studio 2012.  In the default.html file, I replaced the contents of the <body> tag with the following:

<body>
    <h1 id="displayName">(to be replaced by user's display name)</h1>
    <script>
        Windows.System.UserProfile.UserInformation.getDisplayNameAsync().then(
            function (name) {
                document.querySelector("#displayName").textContent = name;
            }
        );
    </script>
</body>

When I run the application, my <h1> contents contain my display name.

SNAGHTML6b4d0e

Of course the JavaScript code above could be used in an external .js file as well.

    Copyright © Microsoft Corporation. All rights reserved.
    The code provided in this post is licensed under the Microsoft Public License (Ms-PL).
    Copyright © Microsoft Corporation. All rights reserved.
    The code provided in this post is licensed under the Microsoft Public License (Ms-PL).
Aug
24
2012

How to Use iFrames in WinRT Apps

SNAGHTML25abaef5Did you know you could use iFrames in WinRT apps developed using JavaScript?  Is this suppose to be exciting?  Why would you care?  For the answers, follow along as I take a journey of discovery attempting to add live Twitter feeds to my app.

To set the stage for what I want to do, you must first understand what a Twitter Widget is.  The folks at Twitter have made it real easy for web developers to create a custom, dynamic section of a web site to display tweets based on a user, a search, favorites, or a list.  Once I know my tweet criteria, I can customize the appearance, dimensions, and other relevant options.  When I am done with all my customizations, I can grab the code that will make the magic happen on my web site.  Um… but I want this in my WinRT app.  Will it work?  Lets find out.

I will choose to create a Twitter Search Widget.  Here is a screen capture of my criteria:

SNAGHTML25bbc55e

Once I click the [Finish & Grab Code] button, I see the following:

SNAGHTML25be0be3

Now I will add this code to my project in Visual Studio 2012.  I have just created this project using a blank template. In the default.html file, I will add the Twitter widget code I created above.  Here is what my markup looks like:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>HowTo_IFrames</title>

    <!-- WinJS references -->
    <link href="//Microsoft.WinJS.1.0/css/ui-dark.css" rel="stylesheet" />
    <script src="//Microsoft.WinJS.1.0/js/base.js"></script>
    <script src="//Microsoft.WinJS.1.0/js/ui.js"></script>

    <!-- HowTo_IFrames references -->
    <link href="/css/default.css" rel="stylesheet" />
    <script src="/js/default.js"></script>
</head>
<body>
    <p>Content goes here</p>
    <script charset="utf-8" 
            src="http://widgets.twimg.com/j/2/widget.js"></script>
    <script>
            new TWTR.Widget({
            version: 2,
            type: 'search',
            search: '#win8appdev',
            interval: 30000,
            title: 'Windows 8 Developers',
            subject: '#win8appdev',
            width: 250,
            height: 300,
            theme: {
                shell: {
                    background: '#8ec1da',
                    color: '#ffffff'
                },
                tweets: {
                    background: '#ffffff',
                    color: '#444444',
                    links: '#1985b5'
                }
            },
            features: {
                scrollbar: false,
                loop: true,
                live: true,
                behavior: 'default'
            }
        }).render().start();
    </script>
</body>
</html>

Will it be that simple?  Unfortunately no.  When I attempt to run the application, I get the following error:

SNAGHTML25cae34d

It may not be obvious by the error message what the real issue is.  The reason why ‘TWTR’ is undefined is due to the following script not being executed:

<script charset="utf-8"             
        src="http://widgets.twimg.com/j/2/widget.js"></script>

Why did the script not execute?  Because my default.html page is considered local in context to my application.  The only way an external script would be allowed to execute is if it was executed in a web context.  Well who decided those rules?  Perhaps a better question for now is – How do I know if I am in local context or web context?

Any HTML file that is physically part of a project is considered as local in context. The converse to this is any HTML that resides externally or is remote to a project is considered to be in web context.  How can I execute HTML remotely in my WinRT app?

Using iFrames

I can use an iframe in my HTML to point to an external web page.  To demonstrate, I will remove the script I added to my default.html page (we will return to that code later), and replace the contents of the body tag with the following:

<h1>iFrame Demo</h1>
<iframe src="http://www.palermo4.com"
        width="900"
        height="600">
</iframe>

When I run my application now, this is what I see:

image

If this is all I do, I essentially have a “browser” to my site within my app.  I could also change the source of the iFrame from anchor tags as seen with the following revisions:

<h1>iFrame Demo</h1>
<div>
    <a href="http://palermo4.com" target="framed">Palermo4</a> 
    <a href="http://codefoster.com" target="framed">Codefoster</a>
</div>
<iframe name="framed" width="900" height="600">
</iframe>

This will cause the iFrame to load the respective href value once either of the anchor tags are clicked.

Recommended:  Create an HTML file in the root directory of your project named
msapp-error.html.  This file will be loaded automatically in the iframe when errors occur due source resources not loading or not found!

Now returning to my original objective, I would like to see the code I grabbed from Twitter work in my app still.  I have an idea!  I will take Twitter widget code and put in in a new HTML file in my project.  I will name the file twitterframe.html, and create it in the root project directory.  Here is the contents of that file:

<!DOCTYPE html>
<html>
    <head>
        <title></title>
    </head>
    <body>
        <script charset="utf-8" 
                src="http://widgets.twimg.com/j/2/widget.js">
        </script>
    <script> 
        new TWTR.Widget({
            version: 2,
            type: 'search',
            search: '#win8appdev',
            interval: 30000,
            title: 'Windows 8 Developers',
            subject: '#win8appdev',
            width: 250,
            height: 300,
            theme: {
                shell: {
                    background: '#8ec1da',
                    color: '#ffffff'
                },
                tweets: {
                    background: '#ffffff',
                    color: '#444444',
                    links: '#1985b5'
                }
            },
            features: {
                scrollbar: false,
                loop: true,
                live: true,
                behavior: 'default'
            }
        }).render().start();
    </script>
    </body>
</html>

Now I will return to default.html, and modify the contents within the body tags as follows:

<h1>iFrame Demo</h1>
<iframe src="/twitterframe.html" width="300" height="400">
</iframe>

Will I get my desired output?  Can I trick the iframe to run a page in local context but treat it like it is in web context?  Not the way I am doing it.  When I run my application, I get the same error I received earlier.  However, I was on the right track of thinking.  By using a special moniker preceding the URL, I can ask for the local page to be executed in a web context.  Here is the syntax for that:

<iframe src="ms-appx-web:///twitterframe.html" 
        width="300" height="400">
</iframe>

By adding ms-appx-web:/// before my local page name, I am informing my application to run it in a web context. This crucial step gives me exactly what I want, as seen here:

image

Hooray!  I got my Twitter search widget to work in my WinRT app!  Think of the possibilities with any other social meshing sites or mapping tools!

By the way, you can govern what is allowed to happen in the iFrame by setting the sandbox attribute.  IntelliSense reveals self-describing features:

SNAGHTML261ce5af

I hope you enjoy developing Windows 8 applications with JavaScript and HTML5!  For more resources, be sure to sign up for Generation App! Your idea. Your app. 30 days.

Cheers!

    Copyright © Microsoft Corporation. All rights reserved.
    The code provided in this post is licensed under the Microsoft Public License (Ms-PL).
    Copyright © Microsoft Corporation. All rights reserved.
    The code provided in this post is licensed under the Microsoft Public License (Ms-PL).
Aug
16
2012

Microsoft DevRadio: Adding HTML5 Content

To play video, hover above and press play button.

Abstract: win8genapp30
Michael Palermo is back for today’s show as he shows us how to add simple HTML5 content in Visual Studio  to develop an app for Windows 8.

Next Steps:
Step #1 – Download Windows 8 Release Preview and Windows 8 SDK
Step #2 – Download Visual Studio Express for Windows 8
Step #3 – Start building your own Metro Style Apps for Windows 8

Subscribe to our podcast via iTunes, Zune, or RSS

If you're interested in learning more about the products or solutions discussed in this episode, click on any of the below links for free, in-depth information:

Websites:

Blogs & Articles:

Videos:

Virtual Labs:

    Copyright © Microsoft Corporation. All rights reserved.
    The code provided in this post is licensed under the Microsoft Public License (Ms-PL).

Resources

Archives

Team Blogs

Download OPML file OPML