I created an integration to do just that, and used it as an opportuniy to do a little development in .NET Core. You can find exist-spoon on my GitHub page.

The exist.io API is simple to work with. The only tricky part was implementing the OAuth authenticaiton flow on a console app. OAuth requires you to serve a page where the user’s browser will be redirected after completing the authorization. This page accepts the token provided by the parter (exist.io in this case).

There is no HttpListener in .NET Core, so I started from the web application skeleton and stripped everything down as much as possible. As usually happens with async work, I wrote way too many Task<T> and awaits before arriving at the final, simpler structure. I punted on the TDL file format and used a simple regex to parse out when a task has DONEDATE equal to today.

The tool isn’t too complicated, but it’s gotten my juices flowing after a while without working on personal projects. It was cool to get a shoutout from one of exist.io’s creators (Hi Josh!) too.

Scenario

This authentication method applies to the following scenario:

• Azure Mobile Services is set up for Social Authentication. See here for instructions.
• Users authenticate on the client (browser) side using the Azure Mobile Services JavaScript SDK. The latest SDK at the time of this writing is version 1.1.3, and can be found here.
• You have ASP.NET Web API services that you want to expose only to users who have authenticated with Azure Mobile Services.

Normally we are authenticating users on the same system that issues credentials - think standard ASP.NET membership stuff. In this case, our Web API system needs to trust credentials issued by a third party.

Method

Here is a quick refresher on login with Azure Mobile Services:

1
2
3
4
5
6
7
8
9
10
11

var zumoUrl = "https://your-zumo-service.azure-mobile.net";
var zumoKey = "your-zumo-application-key";
var client = new WindowsAzure.MobileServiceClient(zumoUrl, zumoKey);

// options are facebook, twitter, microsoft, or google.
// you must set up each provider in the azure management portal.
client.login("facebook").then(function() {
  alert('login succeeded');
}, function(error) {
  alert(error);
});

When a user successfully logs in with Azure Mobile Services, the client.currentUser field is set. This in turn exposes a mobileServiceAuthenticationToken field, which is a JSON Web Token (JWT). JWT is an emerging standard for representing authentication information. It is used by many OAuth implementations, including Azure Mobile Services.

In order to verify that users have truly authenticated with Azure Mobile Services, we will rely on a ”shared secret” known only to Azure Mobile Services and to us. The JWT issued to the user is cryptographically signed by Azure Mobile Services using the Master Key unique to our service instance. We have access to this key via the management portal, and we can use it in our Web API code to verify that a JWT was truly issued and signed by our Azure Mobile Services instance.

Here’s a quick diagram that sums it up:

The standard for a client to present a JWT for authentication to a server is to set the request’s Authorization header to “Bearer ” where is the actual Base64-encoded JSON Web Token. MyVote is using AngularJS, so I set up an HTTP interceptor to set the header on every request:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

MyVote.App = angular.module('MyVoteApp', ['ngRoute', 'ngResource']);

MyVote.App.factory('zumoAuthInterceptor', function () {
    return {
        request: function (config) {
            if (Globals.zumoUserKey) {
                config.headers['Authorization'] = 'Bearer ' + MyVote.Services.AuthService.zumoUserKey;
            }
            return config;
        }
    };
});

MyVote.App.config([
    '$routeProvider', '$httpProvider',
    function ($routeProvider, $httpProvider) {
        $httpProvider.interceptors.push('zumoAuthInterceptor');
        // -- snip -- other config stuff here -- //
    }
]);

On the server side, authentication is implemented in Web API via a delegating handler. The process begins here:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
{
    // browser sends OPTIONS requests to check CORS and will not include Authorization header
    // allow these requests to flow through with the response from the CORS handler
    if (request.Method != HttpMethod.Options)
    {
        string token;
        if (TryRetrieveToken(request, out token))
        {
            try
            {
                var jwt = new JsonWebToken(token, new Dictionary<int, string> 0);
                jwt.Validate(validateExpiration: true);

                MyVoteAuthentication.SetCurrentPrincipal(new MyVotePrincipal(jwt.Claims.UserId));
            }
            catch (JsonWebTokenException)
            {
            }
        }
    }
    return base.SendAsync(request, cancellationToken);
}

In the SendAsync override, we attempt to validate the JWT. If it is valid, we call MyVoteAuthentication.SetCurrentPrincipal which sets HttpContext.Current.User. This allows us to simply add the [Authorize] attribute to Web API controllers or actions where we want to require Azure Mobile authentication. Note the _masterKey field that is included in the JsonWebToken contructor call. This is the Azure Mobile Services Master Key (shared secret) that we trust as the cryptographic signer of valid JWTs.

The relevant bit inside JsonWebToken that validates the signature follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

private void ValidateSignature()
{
    // Derive signing key, Signing key = SHA256(secret + "JWTSig")
    byte[] bytes = _UTF8Encoder.GetBytes(_signatureKey + "JWTSig");
    byte[] signingKey = _Sha256Provider.ComputeHash(bytes);

    // UFT-8 representation of the JWT envelope.claim segment
    byte[] input = _UTF8Encoder.GetBytes(_envelopeTokenSegment + "." + _claimsTokenSegment);

    // calculate an HMAC SHA-256 MAC
    using (var hashProvider = new HMACSHA256(signingKey))
    {
        byte[] myHashValue = hashProvider.ComputeHash(input);
        string base64UrlEncodedHash = Base64UrlEncode(myHashValue);
        if (base64UrlEncodedHash != Signature)
            throw new JsonWebTokenException("Signature does not match.");
    }
}

I borrowed liberally from the Windows Live SDK sample for this. There is one gotcha - the JWT spec indicates that a claims “exp” member should be expressed as a double, but Azure Mobile Services uses an integer.

You can find all of the JWT authentication-related code in the MyVote GitHub repository, in the MyVote.AppServer.Auth namespace.

WARNING: Do not expose your Azure Mobile Services Master Key! For example, DON’T put the key in appSettings in your Web.config and then host your code on GitHub. You should rely on the secure configuration facility supplied by your hosting environment. If your Web API is hosted in Azure via Web Sites or Cloud Services, you can securely set appSettings values from within the management portal.

From backend to user experience

Magenic has created a unique conference experience where the sessions build on one another to tell the whole story of building a modern application from start to finish. The common thread that ties the sessions together is the creation of a single application platform (a polling app called “MyVote”) delivered on diverse clients: Web, iOS, Android, Windows 8 (WinRT), and Windows Phone. The backend is all Azure - SQL and a Web API Cloud Service. The entire development effort was distributed, using Git on Visual Studio Online.

The Magenic team who delivers the conference talks are the same folks who developed the apps. All of the talks emphasize the architecture/design perspective: choosing the right components and patterns for reliable, predictable, successful dlivery. The conference program begins with sessions focused on solution architecture and the backend, follows with development of the various clients, user experience design, and touches on process and tooling around distributed development. We also do a deep-dive workshop on the last day where we dig into the actual nuts and bolts of implementation.

My talk: HTML5/JavaScript application development

My talk is about the development of an HTML5 “smart client” app. It is a Single Page App (SPA) developed with AngularJS, TypeScript, and Razor. I describe the benefits of taking an app the web, selection of a JavaScript application framework, architecture of the app components, testing, and cross-cutting concerns. I am really excited about this combination of technologies: AngularJS provides an “opinionated” framework that is very discoverable, and the combination of TypeScript and Razor templating allows us to extend the type-safety of .NET out into the client.

Next time…

We’re bringing the show to Vegas on March 10-14. We’ve added some features to the apps, and updated them to keep pace with advancements in their various platforms. Hope to see you there!

If your company does ASP.NET development and you are interested in learning how to leverage Responsive Web Design, I would be happy to bring my show on the road. Email me: aidanr (at) magenic.com.

For this release, I have created two binary packages - one targeted at the TFS2010 API and another for the TFS2012 API. My error tracking system has been regularly emailing me reports from users who do not have the TFS2010 client assemblies installed, and a few discussions have cropped up in CodePlex reporting some TFS2012 formatting issues. I’m hoping this resolves both problems.

Visit the project at CodePlex and pick up either the TFS2010 or TFS2012 release.

Delete HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\12.0_Config\MainWindowFrameControls\{F66FBC48-9AE4-41DC-B1AF-0D64F0F54A07}.

Defining Responsive

In the context of Responsive Web Design, the term “responsive” is the opposite of “prescriptive.” You’ve probably heard arguments against prescriptive approaches to language and grammar. Language and meaning are organic, evolving things that are constantly being re-created by their users. Prescriptivism in language does not account for its evolution, and can ignore the context and needs of its users. We have experienced “Prescriptive Web Design” from the dawn of the web, in the form of “best viewed in Netscape 4.0.3 on a 800 x 600 monitor at 16-bit color depth.” The modern variation is a placeholder page replacing desired content with “sorry, this page not formatted for mobile devices” How short-sighted, to actually hide content from valuable eyeballs? Responsive Web Design is decidedly not prescriptive.

Responsive Web Design is a set of techniques that allow our pages to adapt to the capabilities of the client. Client, in this case, being both the electronic and human consumer of our content. The goal is to ensure that our content can be comfortably and accessibly consumed by as many devices and people, of varying capabilities, as possible.

These techniques respond to

• Browser capabilities (HTML5, native audio/video, CSS3, plugins)

• Device capabilities (geolocation, resolution, input methods)

• User capabilities (vision, hearing)

• Viewport (media type, resolution, density, orientation)

Prescriptive designs enforce requirements on the client: they require certain screen sizes, input devices, or plugin support to fully render content. Responsive designs inquire about the capabilities of the client and put forth the best possible experience given those capabilities. They are as functional as possible in limited scenarios and enhance the experience as capabilities increase.

Why?

Why use responsive techniques? The sweet spot for RWD is a balance of development effort and reach: responsive design techniques will get your content in front of the most eyeballs, in a usable form, the the least effort. This form may not be optimal for every client scenario, but the aim is to find an appropriate compromise where required, and to take advantage of advanced capabilities where possible.

Consider the polar approaches:

• The cheapest option is to design only for desktop and cross your fingers for mobile users. Desktop clients less restrictive and therefore simpler to target.

• The most expensive option is to implement separate designs for phone, tablet and desktop (potentially even developing native mobile clients.) You will deliver the most optimal experience for each device, at greatly increased cost of development and maintenance.

Beyond the cost-reach compromise, RWD provides several other benefits:

• Consistency: Delivery of a consistent experience across devices. Styling, navigation, and user experience will be familiar and aid users who arrive at your site using different clients at different times. There is a single set of markup and CSS to maintain, reducing the chance of styles “evolving apart” over time.

• Value First: RWD forces you to first examine the value of the content being delivered, then decide how to present it. The tendancy when designing for a single platform can be to dive into Lorem Ipsum wireframes before content is fully realized. A content-first approach results in a design that exists purely to support the maximum transmission of the value of content; wireframe-first approaches can result in designs with vestigial features that distract from content value.

Responsive design is about delivering the greatest possible user joy regardless of the access method. It is not a dogma or a recipe, it’s more of a mindset that is focused on experience first.

Why Not?

Responsive techniques are not useful or cost-effective for all applications. When the client capabilities are fully controlled, it is not necessary to design for multiple clients. Enterprise applications being deployed across known devices are the most common scenario here. Solutions that require specific interaction modes may not benefit from RWD, for example, interactions that are simply not possible on a touch device.

History

Here is a brief timeline of some influential articles that have led to the current state of thinking on Responsive Web Design:

• John Allsopp - A Dao of Web Design: Letting go of control in favor of accepting and adapting to client differences.

• Ethan Marcotte - Responsive Web Design: Original articulation of the principles.

• Jason Grigsby - CSS Media Query for Mobile is Fool’s Gold: First major rebuttal, warning that bandwidth suffers - additional HTML, CSS, and (potentially) JavaScript to render on a smaller screen with more code. Important for pivoting the discussion toward general adaptability away from a mobile “silver bullet.”

• Luke Wroblewski - Mobile First: Refinement of responsive design approach working from most-constrained to least.

Core Techniques

The original Responsive Web Design article defined the approach as being composed of three techniques: a Fluid Grid, Media Queries, and Flexible Images. Thinking in these areas has evolved a bit since the original article – here are some thoughts on each of the original techniques:

• Fluid Grid (Adaptive Grid) The original article names it “fluid,” but this has come to mean proportional, which is not strictly required. An adaptive grid (and an adaptive layout in general) provides a framework for adjusting presentation to window sizes, resolutions, and screen densities. The earliest fluid layouts were focused on achieving proportional columns using CSS (a technique that was trivial using the common table-based layouts at the time). Further developments of adaptive layout are more focused on typography, especially given the emergence of high-density displays that make pixel- and point-sizing less reliable. A fully-fledged adaptive grid framework (potentially combined with a pre-defined base style set) can be a nice productivity boost.

• Media Queries The media query is a CSS3 feature that allows you to target CSS rules at specific ranges of window or screen size. The most common application of media queries in RWD is for adjusting the layout by repositioning or hiding certain elements as the available space is reduced.

• Flexible Images (Adaptive Media) The original article focuses on flexibly sizing and positioning images for smaller screen dimensions and lower bandwidth. Further thinking in this area has included selectively loading smaller image files in lower-bandwidth scenarios. With the addition of HTML5 Video and Audio capabilities, these media types should be considered as well.

It is absolutely not essential to use all of these techniques in every web design effort. These primary techniques form the foundation of RWD thinking, and many additional techniques have been developed along the way. There is a toolbox available, and you can choose the appropriate tools for each job.

Grid Systems

Grid System Rationale

Many responsive sites rely on a grid system for layout. Abstracting the foundation of the layout provides a clean, consistent framework for positioning site components. A grid can be defined as a horizontal sectioning of the canvas in to columns and gutters. Content lives in columns, and gutters provide whitespace between them. Grids help us think about design, and they help users engage with your content. You can compare a CSS grid to the “snap to grid” function provided in form designer and presentation software: it provides convenient, consistent alignment and spacing for the elements on a page.

Several frameworks and generators exist that provide grid systems. They fall into four basic categories:

• Fixed: the container width is set to a fixed width, and the column count, column width, and gutter width are set to fixed fractions of the container. Column spanning is possible, but the container will never resize with the window.

• Responsive: a set of media queries provides a progressive step-down of container width, column count, column width, and gutter width.

• Fluid: the column count is fixed; container width, column width, and gutter width are percentages of the canvas.

• Fluid + Responsive: media queries set the container width and column count; within each breakpoint, column and gutter widths are proportional.

Grid System Framework Comparison

There are dozens of CSS grid frameworks available, at varying degrees of complexity, maturity, and compatibility. This list selects some notable popular frameworks that focus on different use cases, roughly ordered from simplest to more fully-featured. New ones are constantly being released that build on principles developed in those that came before.

Some additional notes on the grid frameworks:

• 960gs The granddaddy. A good starting point to understand the concepts to launch you toward rolling your own. Viable for sites that are likely to have only desktop traffic. Consider 1140 grid given rise of wider screens.

• Skeleton Relatively minimal and easily customizable. Provides a layout skeleton (output) and CSS skeleton (source) with reset/sane defaults /media-query breakpoints for you to customize. Has not been maintained in a while (lots of open Github issues) - the dmur fork is more active.

• Bourbon Neat Relies exclusively on Sass mixins - no classes applied to markup. Extremely customizable.

• Responsive.gs Enforces border-box box-sizing model on all elements.

• Bootstrap Probably the best-known (or at least most buzzed-about) client-side framework available. A complete suite of layout, styling, and input/interactivity tools. Tends to leave a recognizable stamp on the appearance of the site.

Note that responsive features rely on media queries - grids with responsive features will serve either the desktop or mobile view to <= IE8 depending on whether they are “mobile first” or “desktop first.” JavaScript polyfills may be leveraged to extend back-compatibility to earlier browsers than those targeted by the framework.

It can be difficult to adapt an existing project to use a CSS framework - the framework may rely on certain style reset features, typographic assumptions, box-model settings, or other styling techniques that are not compatible with the existing codebase. Even for new work, adoption of a framework can assert a certain identifiable look and feel (for example, the Bootstrap buttons and navbar). It is worth spending time customizing the base style to ensure unique branding. This will often require you to learn at least the basics of a CSS preprocessor tool like LESS or Sass.

Grid System Demo

A page demonstrating the responsive.gs grid system can be found here: DEMO. View the page on a mobile device and/or experiment with resizing the browser window.

Responsive.gs provides a very lightweight framework purely focused on grid layout; it does not enforce any look-and-feel on the site. The framework applies the box-sizing: border-box CSS rule to all elements, enabling a simpler sizing model. This rule makes it easier to calculate sizing in layouts: it changes the box size calculation to include padding and border in the overall height and width of a box. Due to this low-level rule, adoption of responsive.gs into an existing layout could result in some painful size adjustments. However, you’ll find that starting fresh with this rule applied can make layout size calculations much more intuitive.

The framework is proportionally fluid at widths above 768px, while all columns stack vertically at 100% width on smaller screens. It’s very simple to lay out columns with responsive.gs: apply the row class to define a full-width row, then use the col and span_* classes to set proportional column widths within the row.

1
2
3
4
5

<section class="row">
  <article class="col span_6 bg4"><h3>col span_6</h3><img class="left-quarter" src="http://fillmurray.com/200/300"><p>Column 1.</p></article>
  <article class="col span_6 bg3"><h3>col span_6</h3><p>Column 2.</p></article>
  <article class="col span_4 bg2"><h3>col span_4</h3><p>Column 3.</p></article>
</section>

Compatibility notes: Because the box-sizing rule is not supported on IE7 or lower, a polyfill (for inclusion using conditional comments) is provided. The framework is “mobile first”, in that all columns are laid out to 100% width in the base style, then set to proportional widths within a media query. This means that users of IE8 and below will receive the mobile experience.

Media Queries

Media queries are mostly about width, width, width. We generally assume that our layouts are equal to the width of the browser window and that they can be infinitely long. Thank goodness we aren’t working with fixed-height pages! Everyone expects to scroll vertically when viewing a page, and the mouse wheel convention is to scroll the page vertically. There are some clever / artistic layouts that scroll horizontally, but these can be difficult for users to “grok” initially, and should only be used for specialized content and audiences. (A media query can reference height, and there are some interesting cases where that can be useful described here.)

Given that the primary constraint on our designs is the width of the page, it’s very useful to be able to write width-aware CSS rules. When there is room, allow elements to be positioned next to one another horizontally. When there isn’t, reposition elements into a vertical flow, remove non-essential elements, and/or provide methods for the user to toggle the visibility of lower-priority elements.

Selecting Breakpoints

The horizontal width where a media query changes the layout is referred to as a “breakpoint.” There are many references that attempt to provide the screen dimensions of popular devices, which one could adopt for layout breakpoints. This approach is not workable, because the device landscape is constantly changing - it would result in an explosion of difficult-to-maintain rules, and bloat the size of the CSS transmitted to the browser.

Here is an overview of a workflow that can help identify the most appropriate breakpoints for an application:

• CONTENT is king. It’s not possible to select and design around a set of device-based breakpoints. CSS will be heavy and under-performing, and compromises will be made to “fit in the box.” It’s better to evaluate your content and think in general terms about presenting it in “big,” “middle,” and “small” contexts.

• Start at a size near your initial wireframe target, and start resizing until things start looking “wrong”

• Set a breakpoint with some breathing room before things go haywire, then apply rules to fix the layout in the “wrong side”

• Repeat this exercise moving inward and outward until unreasonably small and large

• Three sizes, small /medium / large, represent a maintainable sweet-spot

Additional considerations for media query breakpoints:

• Line length is important. On wider layouts, it may be useful to set max-width to a comfortable reading length and allow margins to increase as the viewport grows wider. In browsers that support it, CSS3 multi-column can allow content to flow to multiple columns and avoid whitespace in wider scenarios.

• Scaling widths out in ems proportionally to a base-font em ensure your design renders consistently across operating systems with missing fonts, user-selected fonts, zooms, and display densities.

• Knowledge of common device widths is useful (along with testing the site on biggest-marketshare devices), but creating a layout appropriate to the content is most important of all.

• iOS reports portrait device-width and device-height regardless of orientation (use orientation in query to differentiate)

Size, Move, Hide, Replace, or Transform?

There are many options available for style specializations inside a media query. This list defines the most common techniques:

• Size: Shrink box and / or font

• Move: Reposition an element (most commonly moving horizontally laid out columns to vertically stacked)

• Hide: Remove entirely

• Replace: Provide the same function in a smaller package (common example – list of navigation links collapsed to navigation menu menu)

• Transform: Maintain the same markup, but change its initial presentation (e.g. collapsing a context box into an accordion)

Selection of the most appropriate technique depends on several factors:

• Semantics of the element / component

• May descend from size > move > hide at cascading breakpoints

• Remember that the most-important content should come first in markup for accessibility and SEO (see grid system push / pull classes)

The Mobile Viewport

In order to effectively leverage media queries for mobile devices, it is necessary to include the viewport meta tag in the head of the page, like so:

<meta name="viewport" content="width=device-width" />

This instructs the mobile browser to treat device pixels as CSS pixels, that is, for the physical and virtual dimensions of the screen to be the same. (This is a bit of an oversimplification, since multiple high-density display pixels are sometimes treated as a single virtual device pixel. See A Tale of Two Viewports for an excellent explanation.) When the viewport tag is not present, most mobile browsers will effectively “zoom” a larger virtual viewport into the smaller physical device viewport, by treating a device pixel as multiple CSS pixels. When mobile devices first became capable of browsing the web, this behavior was necessary to provide enough space to lay out pages designed exclusively for the desktop. Users employ the “double-tap zoom” gesture to focus on portions of the page.

The viewport meta tag allows us to instruct the browser how to treat the Layout Viewport relative to the Visual Viewport. Let’s examine the differences between the Layout Viewport and the Visual Viewport.

Layout Viewport

• CSS pixels available to layout

• Resize of a Desktop browser window resizes the Layout Viewport and causes a reflow

  • The Mobile Layout Viewport is set at the initial load and does not change

  • Mobile devices play some extra tricks with text wrapping - divs will lay out correctly, but the wrap point may be adjusted based on double-tap zoom size; text may re-wrap on zoom as well.

Visual Viewport

• The Visual Viewport is the CSS pixel dimension of the visible area of the page

• Resize of a Desktop browser window resizes the Visual Viewport

• Mobile zoom resizes the Visual Viewport

Additional notes on the viewport meta-tag:

• Controls the layout viewport

• Determines the number of device pixels per CSS pixel at zoom = 1

• 99% of the time, use the tag

• For most modern devices, the default iOS and Android layout viewport width is 980 CSS pixels, with initial scale set to match the visual viewport

• The content attribute is comma-separated

  • Width = [px|device-width]. Device width is “screen width in CSS pixels at 100% zoom”

  • Height – little-used

  • Initial-scale = device pixel multiplier

  • Maximum-scale = device pixel multiplier

  • User-scalable = [true|false]. Whether to allow the user to scale. Think very carefully before limiting this.

  • CSS 2.1 recommends that CSS pixels correlate to one 96dpi pixel at arms’ length; initial-scale=1 requests this

• IE10 on Windows 8 ignores the viewport meta tag in snapped view. You need the following CSS declaration:

1
2
3

@-ms-viewport {
    width: device-width;
}

Tangent: ASP.NET MVC Technique - Server-side mobile refinement

This topic is not directly related to media queries, but can be used in conjunction with them to achieve comfortable layout and bandwidth reduction while maintaining a single page of markup. It is important to remember that content hidden with display: none is still downloaded. The idea behind the following technique is to remove a component from the layout flow using a media query, and apply server-side processing to entirely eliminate its content from the payload.

Here is an overview of the steps involved:

• Add the NuGet package from 51Degrees.mobi for better device detection. Inclusion of this package causes the Request.Browser.IsMobileDevice property to be set for each request, detecting a much broader range of devices than the out-of-box behavior.

• An alternative is the DetectMobileBrowsers.com regex for simple useragent-based detection.

• In your server-side markup (.aspx or .cshtml), wrap the component you wish to hide from mobile devices as follows:

1
2
3
4
5
6
7
8
9
10

@if (!Request.Browser.IsMobileDevice) {
  <section class="sidebar">
      <p>Check out my twitter feed:</p>
      <ul>
          <li>Post 1</li>
          <li>Post 2</li>
          <li>Post 3</li>
      </ul>
  </section>
}

• Implement a media query to flow the remainder of the layout into the previously-occupied space.

• When Output Caching is in use, ensure the mobile and non-mobile variations of the page are cached separately. Include the attribute [OutputCache(Duration = 60, VaryByCustom = "Mobile")] on each controller action that relies on this technique. Provide the custom cache key by overriding GetVaryByCustomString in Global.asax.cs:

1
2
3
4
5
6
7

public override string GetVaryByCustomString(System.Web.HttpContext context, string custom)
{
    if (custom != "Mobile")
        return null;

    return context.Request.Browser.IsMobileDevice.ToString();
}

• Depending on the nature of the content, you may wish to provide a way for the user to asynchronously request it after the initial page load.

You can see this technique in action here: DEMO. View the source of the page from a mobile device (or with a mobile user agent string) to verify that the sidebar is not transmitted. On desktop devices, the sidebar is included and hidden/shown as the page width changes.

Adaptive Media

In Marcotte’s original article, the only medium considered for adaptability was the image. Modern sites deliver images, video, and audio to devices of varying capabilities. The following sections describe responsive techniques for dealing with all three.

A page demonstrating many of the following techniques is available here: DEMO.

Responsive Images

We must consider layout and bandwidth when planning a responsive approach for images. Here are some notes on responsive image techniques:

• Scaling: Basic image scaling can be accomplished with width: 100% and max-width CSS properties. IE7 may require a polyfill depending on other CSS properties in use.

• Cropping: At media query breakpoints, set negative margins with overflow: hidden to avoid shrinking the image and

• Swap/Omit: On the server side, alternative image href may be set in markup, or images may be omitted when a mobile browser is detected. An HTTP handler may be employed to dynamically scale images according to user agent. Client-side techniques for selecting images according to page size exist, but there is no silver bullet - most of these techniques will result in multiple image downloads or suffer from very un-semantic (and potentially non-accessible) markup.

• SVG: Scalable Vector Graphics images have the benefit of full-fidelity scaling with a single file. Internet Explorer introduced SVG support in IE9, so a fallback is required for earlier IE versions. As with most “swap” techniques, it’s important to monitor network traffic and avoid transmission of both files, when possible, or to employ a server-side approach.

Be sure to choose the correct image format. PNG works best for logos and vectors, JPEG for photos and other realistic images. GIF should rarely be used, though can be effective for <= IE6 as a work around for PNG transparency. Losslessly optimize your PNG images - this can reduce size by a surprising amount (see PngGauntlet for example).

Responsive Video

HTML5 introduced full video support, which modern browsers all handle. HTML5 video is generally more performant and less buggy than relying on plugin-based approaches. It is necessary, though, to provide a fallback for older browsers - the goal with video is a balance of performance and compatibility.

• Supply VP8- and H.264-encoded files and you will cover nearly all user agents

• Omitting the type from the final source will cause most browsers to check the metadata to determine if it can be played. Bandwidth / accessibility tradeoff.

• One could use the little-known media attribute to serve smaller files to smaller devices, although at the time of this writing it appears this attribute may be dropped.

• IIS NOTE: need to add mime types for video, or IIS will return a 404.3. See Web.config section system.webserver\staticContent\mimeMap.

• Within the video tag, below the sources, include a flash fallback and video download link (for users without flash).

• Use JavaScript and/or HTTP module and user agent detection to serve appropriate codec and filesize

• Good resources:

  • Mark Pilgrim’s excellent, very in-depth (though getting out-of-date) guide: http://diveintohtml5.info/video.html

  • Concise, easy to read guide from JWPlayer: http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/22644/using-the-html5-video-tag/

  • FlowPlayer is a pre-packaged, responsive, broadly compatible option.

  • Nice tool for generating markup: Video for Everybody

Don’t discount the option of hosting the video externally (Vimeo, Youtube) and IFRAMEing in a player – they’ve solved the cross-browser issues and will take bandwidth & connection pressure off your server.

Flexible video sizing:

• For the <video> tag, you can rely on width: 100% and max-width with height: auto to flexibly resize video while maintaining aspect ratio.

• Flash and IFRAMEs have issues – can’t automatically set height to preserve the aspect ratio. Thierry Koblentz “Creating Intrinsic Ratios for Video” to the rescue - post.

  • Set a wrapper DIV with relative position, zero height, and bottom-padding representing the aspect radio (e.g. 56.25% == 16:9)

  • Set an inner div absolutely positioned with 100% width and height

  • This technique has issues in IE7 and below – use a conditional style sheet

Responsive Audio

Techniques for audio largely follow those for video, except that layout adjustment is not really a concern. Rely on the HTML5 audio tag with fallbacks, and provide download links for users without plugin support. On the server side, consider serving files encoded to lower bit rates when mobile devices are detected.

Other Considerations

Now that we have covered the the three primary categories of responsive web design techniques, let’s briefly visit some related considerations.

Forms

Forms must provide a usable mobile layout and be touch-friendly. The following are important points to consider for responsive forms:

• Note the “field zoom” feature of many mobile browsers. When an input field is focused, the browser will zoom the viewport to the width of the field.

  • This makes top-aligned labels better, otherwise the label or field may be cut off.

  • Set input, textarea { font-size: 1em } to avoid extra zoom on iDevices – lower font sizes will introduce additional zoom

• Touch-friendly

  • Sizing (finger targets): extra padding on inputs, and larger label targets for radio and checkbox controls.

  • Click versus Touch events: there is a delay between the initial touch event and final click event, during which the browser is waiting for a potential gesture. If you know that a given control has no gesture interaction, you can trigger interactions from the touch event, resulting in faster response. This can be difficult to implement reliably - see FT Fastclick for a solid implementation.

• Input Types

  • HTML5 introduces new values for the input element’s type attribute. Mobile browsers key off this attribute to provide the most appropriate keyboard layout for the type (e.g. email type results in keyboard with @ symbol).

  • Some desktop browsers implement some native validation and specialized input controls for certain input types. This may not be desired - the form element’s novalidate attribute can prevent native validation, and CSS can be used to prevent browser-substituted controls.

Typography

The trend is toward more minimal interfaces that place typography in the forefront. The increased prevalence of high-density displays makes the display of beautiful type accessible to a greater number of users. Consider the following points related to typography:

• The user (or at least platform developer) has already specified his / her preferred default font size. Rather than overriding this, we should respect it as a base and scale from there.

• New “retina”-class devices and high density displays can make pixel sizing unreliable. The future of the “pixel” is uncertain - em should be the default sizing unit, unless you have a really good reason to use pixels.

• On higher-density displays, you may wish to increase font weight to achieve a uniform result across displays. Antialiasing on lower-density displays results in greater perceived weight given the same font on a higher-density display.

• On standard-density displays, serif fonts below 12px are not sharp enough. But you should be over 12px anyway.

• Good Metrics

  • Font size: bigger than you think. Hold a book or magazine at a comfortable distance and compare.

  • Contrast: ratio font color to background brightness. Steer clear of full black (looks like a “hole”) and full white.

  • Line Height: for text, 140% of font size is a good general rule, but depends on face (ascender/descender ratio to x-height and “blackness”). In CSS, use proportional line-height notation (e.g. font: Arial 1em/1.44) with no units.

  • Line Length (measure): From 45 to 75 characters is good balance of ease in tracking to next line versus not having to do it too often. When browsers support it, you can use CSS3 column count when the view gets very wide. You can leave width “on the table” and set a max-width. Ensure text blocks have good height in proportion to width.

  • Spacing: Headings can often use more vertical padding to breathe

• Gotchas

  • Note that when using fluid (proportional) layout techniques, you give up some control over line length

  • Web Font browser quirks and format support (use Font Squirrel)

  • When serving locally, apply correct mimetype to web fonts

Conclusion

Responsive Web Design has been around for several years, and has been gathering steam since its introduction. There is no “one size fits all” approach for cross-device sites - careful evaluation and application of the available techniques is required. Good luck on your projects!

Removing existing tooltips

In the site I am working with, the custom tooltips must be displayed for an ASP.NET control that has its own tooltip implementation. This means that when the page is initially rendered, the title attribute is already set on the items where I need custom tooltips. This means I need to remove the title attribute but preserve its text for displaying later in my custom tooltip. There is an other wrinkle, in that the site is displayed in Internet Explorer’s quirks mode, which means the alt attribute will also display a browser tooltip on hover. I needed to remove the alt attribute as well, to avoid “double tooltips” with my custom tooltip and the browser tooltip being displayed simultaneously.

Here’s a snippet illustrating the technique:

1
2
3
4
5

$map.children('area').each(function() {
  var $area = $(this);
  $area.attr('data-customtooltip', $area.attr('title'));
  $area.removeAttr('alt title');
})

The control uses an image map to provide tooltip and interactive functions. I get a jQuery object for the map, then iterate is children. The title attribute is copied to a data-customtooltip attribute, and the alt and title attributes are removed to prevent display of the native browser tooltip.

Displaying and positioning the custom tooltip

The next piece of the puzzle is displaying a custom tooltip when the mouse is over an area. I include the following HTML in the master layout page:

1
2
3
4
5
6
7

<div
  id="tooltip"
  style="
    position: fixed;
    z-index: 999;
    display: none;">
</div>

This creates a div that is initially invisible and detached from the overall page layout. Of course, the div is also styled to fit with the site’s overall theme.

Back in the JavaScript, I hooked the mouseenter event to set the tooltip text and then display the hidden div. Initially, I simply positioned the div below and to the left of the mouse pointer. Unfortunately, this naive positioning technique falls down when the mouse is near the lower-right corner of a page or frame: the tooltip is cut off at the page/frame edge. Native browser tooltips “float” above the page surface and can even extend beyond the edges of the browser window, but this is not possible with an HTML element. To work around this issue, I detect the “quadrant” of the page that the mouse cursor occupies, and position the tooltip away from the page corner. For example, if the mouse cursor is nearest the lower-right corner, I position the tooltip above and to the left of the cursor.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

$tooltipDiv = $('#tooltip');
$map
  .on('mouseenter', 'area', function(e) {
      var $this = $(this);
      
      // set the tooltip text from our custom attribute
      var customTitle = $this.attr('data-customtooltip');
      $tooltipDiv.html(customTitle);

      // determine if the mouse is in the left / top "halves" of the document
      var mouseLeft = e.pageX < (document.body.clientWidth / 2);
      var mouseTop = e.pageY < (document.body.clientHeight / 2);

      // position the tooltip away from the mouse quadrant
      var css = {};
      if (mouseLeft)
          css.left = e.pageX + 10 + 'px';
      else
          css.left = e.pageX - (7 + $tooltipDiv.width()) + 'px';
      if (mouseTop)
          css.top = e.pageY + 10 + 'px';
      else
          css.top = e.pageY - (7 + $tooltipDiv.height()) + 'px';

      $tooltipDiv.css(css);
      $tooltipDiv.show();
  })
  .mouseleave(
      function() { $tooltipDiv.hide(); }
  );

Note that I am always using the left and top CSS attributes to position the div. I ran into strange issues when I attempted to set the left/top to auto and position using right/bottom. I don’t think Internet Explorer supports positioning in this manner.

Also note that I don’t attach the mouseenter handler to each area directly. There can be dozens of areas on the page that require a tooltip - hooking up that many event handlers would not perform as well. It’s better to attach a single handler for when the event bubbles to the map, then let jQuery filter for the child elements that we want to deal with.

WinHaste supports piped or interactive entry - if you enter WinHaste.exe with no arguments, it will read user input from the console until an end-of-file ^Z character is entered. In this mode, Windows already writes user input to the console, so echoing within WinHaste would result in doubling every character typed. I ran across a nice technique in this StackOverflow answer for checking whether the current input stream is piped or interactive:

1
2
3
4
5
6
7
8
9
10
11
12

private static bool IsInputPiped()
{
    try
    {
        var tmp = Console.KeyAvailable;
        return false;
    }
    catch (InvalidOperationException)
    {
        return true;
    }
}

I navigated into the disassembly of the Console.KeyAvailable (thanks, ReSharper!) found found the following:

1
2
3
4
5
6
7

bool r = Win32Native.PeekConsoleInput(ConsoleInputHandle, out ir, 1, out numEventsRead);
if (!r) {
    int errorCode = Marshal.GetLastWin32Error();
    if (errorCode == Win32Native.ERROR_INVALID_HANDLE)
        throw new InvalidOperationException(Environment.GetResourceString("InvalidOperation_ConsoleKeyAvailableOnFile"));
    __Error.WinIOError(errorCode, "stdin");
}

So, I could P/Invoke PeekConsoleInput myself, but this works fine for me!

The Plan

The app will be a simple work item browser. After entering your TFS server connection information, you’ll be presented with a list of Team Projects. Select a Team Project and browse through Work Items. This will allow me to explore navigation, paging, presentation, and other new idioms in the WinRT platform.

There is an interesting wrinkle here: the TFS API client assemblies are not usable from WinRT. A brief attempt at hitting the TFS ASMX services directly proved too frustrating to waste time on - after all, the goal is to push my Windows Store app skills. This led me to the decision to host a TFS proxy on AppHarbor that would provide a simple ASP.NET Web API endpoint for retrieving Work Items, which should be simple to access from WinRT. Another option for proxying to TFS could have been the OData Service for Team Foundation Server, except that it is configured to connect only to a single server. I want my app’s users to be able to connect an arbitrary TFS server, which would require them to set up the OData service themselves. I opted instead to stand up a small service that allows connection to any TFS server and provides just enough functions for my app.

You can find the source for the TfsWorkItems work item browser and TfsProxy API proxy at my Github profile.

The app itself is available for testing in this ZIP archive. Extract, and then run the Add-AppDevPackage.ps1 PowerShell script to install the app.

Web API Proxy

As described above, in order to get to the TFS data from WinRT, I will stand up a simple Web API service with methods for retrieving Team Projects and Work Items. I created a Web API project and added controllers named ProjectsController and WorkItemsController. Along the way, I am using the handy Postman REST Client extension for Chrome to hit my service methods as I build them out. Fiddler or curl would be just as effective.

TFS Connection

The first thing I need is a connection to TFS - this requires a TFS URI, username, and password. Both of my controllers will require a connection, so I will compose this dependency to avoid cluttering all of the API calls with the TFS connection information. This will be implemented via an action filter that provides a TFS Connection in the current HttpContext.

My TfsBasicAuthenticationAttribute action filter passes the request headers to a UserDataPrincipal (IPrincipal) that provides a factory method named InitFromHeaders. This method handles the parsing of the connection information from the request headers. If no principal is returned, or if connecting to TFS with the given connection information fails, an HTTP 401 Unauthorized response is returned. When a connection issue occurs, the specific reason for failure is provided in the response content.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

public class TfsBasicAuthenticationAttribute : ActionFilterAttribute
{
    public override void OnActionExecuting(HttpActionContext actionContext)
    {
        var userDataPrincipal = HttpContext.Current.User as UserDataPrincipal;
        if (userDataPrincipal == null)
        {
            userDataPrincipal = UserDataPrincipal.InitFromHeaders(actionContext.Request.Headers);
        }

        if (userDataPrincipal == null)
        {
            SetUnauthorizedResponse(actionContext);
            return;
        }

        try
        {
            var configUri = new Uri(userDataPrincipal.TfsUrl);

            var provider = userDataPrincipal.GetCredentialsProvider();
            var tfsConfigServer = new TfsConfigurationServer(configUri, provider.GetCredentials(null, null), provider);

            tfsConfigServer.EnsureAuthenticated();

            HttpContext.Current.Items["TFS_CONFIG_SERVER"] = tfsConfigServer;
        }
        catch (TeamFoundationServerUnauthorizedException ex)
        {
            SetUnauthorizedResponse(actionContext, ex.Message);
            return;
        }

        HttpContext.Current.User = userDataPrincipal;

        base.OnActionExecuting(actionContext);
    }

    private void SetUnauthorizedResponse(HttpActionContext actionContext, string message = null)
    {
        string messageValue = message ?? "Authorization (Basic) and TfsUrl headers are required.";
        actionContext.Response = actionContext.Request.CreateResponse(HttpStatusCode.Unauthorized, new { Message = messageValue });

        string tfsUrl = actionContext.Request.Headers.GetTfsUrl();
        if (!String.IsNullOrWhiteSpace(tfsUrl))
        {
            actionContext.Response.Headers.Add(
                "WWW-Authenticate",
                String.Format("Basic realm=\"{0}\"", tfsUrl));
        }
    }
}

Note that in the SetUnauthorizedResponse method, I am adding the WWW-Authenticate header with the realm set to the TFS URL. Responding with a combination of HTTP 401 and this header is the standard for negotiating Basic Authentication. The WinJS.xhr wrapper for XMLHttpRequest handles this negotiation by automatically prompting for username and password in a modal popup, and then re-issuing the request with the Authorization header correctly encoded for Basic Authentication.

The UserDataPrincipal class used here implements IPrincipal and in its InitFromHeaders method, extracts the username, password, and TFS URL from the HTTP headers. The username and password are retrieved from the HTTP Authorization header using the Basic Authentication standard, and the TFS URL is expected in a separate HTTP header named TfsUrl. Upon authenticating with the TFS Configuration Server, its instance is stored in the current HTTP context. The UserDataPrincipal class also supplies an ICredentialsProvider to the TfsConfigurationServer constructor, which is the interface for providing the domain credentials.

Retrieving the Team Projects list

After applying the TfsBasicAuthorization attribute to the ProjectsController, I have access to the TfsConfigurationServer for retrieving information about Team Projects on the server. The highest level of organization within Team Foundation Server is a “Project Collection” that contains one or more Team Projects. Project Collections are accessed by by querying the configuration server’s CatalogNode for children with resource type ProjectCollection. For each Team Project Collection node, I get its WorkItemStore service and iterate its Projects collection looking for Team Projects where the authorized user has Work Item read rights. This method returns a list of TeamProjectInfo data transfer objects. Note that for each Team Project, I am including a list of the available Work Item Types. This will be leveraged for filtering in the app.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

[TfsBasicAuthentication]
public class ProjectsController : ApiController
{
    // GET api/projects
    public IEnumerable<TeamProjectInfo> Get()
    {
        var configServer = (TfsConfigurationServer) HttpContext.Current.Items["TFS_CONFIG_SERVER"];
        var collections = configServer.CatalogNode.QueryChildren(
            new Guid[] { CatalogResourceTypes.ProjectCollection }, false, CatalogQueryOptions.None);

        var projects = new List<TeamProjectInfo>();
        foreach (var collectionNode in collections)
        {
            var collectionId = new Guid(collectionNode.Resource.Properties["InstanceId"]);
            var collection = configServer.GetTeamProjectCollection(collectionId);
            var workItemStore = collection.GetService<WorkItemStore>();
            foreach (Project project in workItemStore.Projects)
            {
                if (project.HasWorkItemReadRights)
                {
                    var projectInfo = new TeamProjectInfo
                    {
                        CollectionName = collectionName,
                        CollectionId = collectionId.ToString(),
                        ProjectName = project.Name,
                        ProjectUri = project.Uri.ToString(),
                        WorkItemTypes = project.WorkItemTypes
                            .Cast<WorkItemType>()
                            .Select(wit => wit.Name)
                            .OrderBy(name => name)
                            .ToList()
                    };
                    projects.Add(projectInfo);
                }
            }
        }

        return projects;
    }
}

Retrieving a Work Items list

When the app user selects a Team Project, we want to display a list of Work Items in the project. This is implemented in the WorkItemsController on the Web API proxy service. The Get method requires the collectionId and projectName parameters, and returns a page of 10 work items, in the form of a WorkItemInfo data transfer object. The optional page parameter allows retrieving a particular page of work items, and the optional workItemType parameter allows filtering by work item type (e.g. Bug, Requirement, Task, etc).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

[TfsBasicAuthentication]
public class WorkItemsController : ApiController
{
    // GET api/workitems
    public IEnumerable<WorkItemInfo> Get(string collectionId, string projectName, int page = 0, string workItemType = "All")
    {
        if (String.IsNullOrWhiteSpace(collectionId) || String.IsNullOrWhiteSpace(projectName))
        {
            throw new HttpResponseException(
                new HttpResponseMessage(HttpStatusCode.NotFound) { Content = new StringContent("collectionUri and projectName are required") });
        }

        var configServer = (TfsConfigurationServer)HttpContext.Current.Items["TFS_CONFIG_SERVER"];
        var collection = configServer.GetTeamProjectCollection(new Guid(collectionId));

        var workItemStore = collection.GetService<WorkItemStore>();
        var wiql = String.Format("Select * From WorkItems Where [System.TeamProject] = '{0}'", projectName);
        if (!String.IsNullOrWhiteSpace(workItemType) &&
            !workItemType.Equals("All", StringComparison.OrdinalIgnoreCase))
        {
            wiql += String.Format(" AND [System.WorkItemType] = '{0}'", workItemType);
        }
        var query = workItemStore.Query(wiql);

        return query
            .Cast<WorkItem>()
            .Skip(10 * page)
            .Take(10)
            .Select(WorkItemInfoBuilder.Build)
            .ToArray();
    }
}

The WorkItemStore.Query method returns a late-bound IEnumerable that allows the use of Skip and Take for efficient paging. The WorkItemInfoBuilder helper class takes care of mapping the TFS WorkItem class to the WorkItemInfo data transfer object.

The Windows Store App

Now that we have a proxy that makes the TFS API accessible from WinRT, it’s time to get started on the Windows Store app. I began with the JavaScript Split App project template. This template provides a basic app frame and bootstrapper (default.html / default.js), navigation handler (navigator.js), data provider (data.js), and provides two screens for interaction: an “items” screen and a “split” screen. The data provider is set up to return static, hard-coded sample data.

The home screen of the app is the “items” screen, which would be more appropriately named “groups.” The items screen presents a list of top-level item groups as horizontally-scrolling tiles. Selecting an item group tile navigates to the “split” screen that presents a list-detail view of the individual items within the selected group. The overall shape of this data and navigation scheme (groups containing items) meshes well with Team Projects containing lists of Work Items. I plan to break one more level out of the hierarchy: Team Projects are found within Team Project Collections (as seen above), so rather than the simple grid view on the main screen, I will use a grouped grid view with the team projects grouped by collection.

Connection Preferences

Before I can replace the sample data with live TFS data, I need to be able to provide the proxy with the URL of the TFS server. This is going to be a per-user setting, so I will add a settings command for displaying a flyout where the user can set the TFS URL. The user will invoke the Charms sidebar, and then click Settings to see my app’s settings, which will include this custom command. Adding a settings command is accomplished by handling the WinJS.Application.onsettings event as seen here:

1
2
3
4

WinJS.Application.onsettings = function (e) {
    e.detail.applicationcommands = { "connection": { title: "Connection", href: "/pages/preferences/preferences.html" } };
    WinJS.UI.SettingsFlyout.populateSettings(e);
};

This adds a command to the settings flyout labeled “Connection” which will navigate to a flyout with the provided href. The markup for a flyout is simple - a top-level div inside the body for the flyout itself, with a back button and a label/input for the TFS URL.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<div data-win-control="WinJS.UI.SettingsFlyout"
     id="programmaticInvocationSettingsFlyout"
     aria-label="App Settings Flyout"
     data-win-options="{settingsCommandId:'connection',width:'narrow'}">

    <div class="win-ui-dark win-header">
        <button type="button" onclick="WinJS.UI.SettingsFlyout.show()" class="win-backbutton"></button>
        <div class="win-label">Preferences</div>
    </div>
    <div class="win-content">
        <div class="win-settings-section">
            <h3>TFS Connection</h3>
            <p>Enter the address of your TFS Server. It must be publicly accessible on the internet for the TFS Work Items proxy service to access it. Usually this URL will end in /tfs.</p>
            <label>TFS URL</label>
            <input type="url" id="tfsUrl" aria-label="Enter TFS URL" placeholder="https://account.visualstudio.com/tfs" />
        </div>
    </div>
</div>

In the JavaScript code-behind for the flyout, I added event listeners for blur and keyup on the tfsUrl input. The standard for Windows Store apps is for settings to take effect immediately, so when the user focuses away from the input or presses the Enter key, I will immediately store and react to the change.

Getting the Team Projects list

Now that the user has a way to specify the TFS URL, I can finally go fetch some live data. Windows Store apps are expected to launch as instantly as possible, so blocking while loading data at startup is not an option — control needs to be returned to the UI thread right away. In the data.js data provider, I will set up the Data namespace with an empty Team Projects list, then make an asynchronous call to fetch the Team Projects list from the proxy. The UI will bind to the team projects list so that once the asynchronous call returns and the list is filled, the UI binding will trigger it to be updated with the populated list.

Here you can see the definition of the Data namespace. Note that the Windows.ApplicationModel.DesignMode.designModeEnabled property is checked to determine if the code is being invoked in design mode. This is to allow the use of sample data when editing the views in Blend, but to fetch real data from the network when the app is actually running. When in design mode, Data.dataService is set to the static SampleDataService class; when not in design mode, Data.dataService is set to an instance of the WebDataService class. The call to Data.loadProjects() will return immediately to avoid blocking app startup, as you will see in the next code sample.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

var
        projectList = new WinJS.Binding.List(),
        designMode = Windows.ApplicationModel.DesignMode.designModeEnabled,
        webDataService = new WebDataService("https://tfsproxy.apphb.com");

    WinJS.Namespace.define("Data", {
        projects: projectList,
        groupedProjects: projectList.createGrouped(WebDataService.getProjectGroupKey, WebDataService.getProjectGroupData, WebDataService.compareProjectGroups),
        dataService: designMode? SampleDataService : webDataService,
        processingEvent: "processingEvent",
        processingStatus: false,
        processingMessage: "",
        loadProjects: function () {
            this.dataService.getTeamProjects(this.projects);
        },
        raiseProcessing: function (value, message) {
            this.processingStatus = value;
            this.processingMessage = message || "";
            WinJS.Application.queueEvent({ type: Data.processingEvent, processing: value });
        }
    });

    Data.loadProjects();

The WebDataService class provides access to the proxy for retrieving Team Projects and Work Items. It leverages the WinJS.xhr method to make asynchronous HTTP requests to the proxy. Note that if the Settings.tfsUrl property is not set, no call to the service is made and the list remains empty.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

getTeamProjects: function (list) {
    list.dataSource.beginEdits();
    while (list.length > 0) list.pop();

    if (!Settings.tfsUrl) {
        Data.processingMessage = "Please open the Settings charm, select Connection, and enter your TFS server URL.";
        return;
    }

    Data.raiseProcessing(true, "Retrieving Team Projects list...");

    WinJS.xhr({
        type: "GET",
        url: this.apiBaseUrl + "/api/projects",
        headers: { TfsUrl: Settings.tfsUrl }
    })
    .done(
        function (result) {
            Data.raiseProcessing(false);
                var responseJson = JSON.parse(result.responseText);
                responseJson.forEach(function (project) {
                    list.push(project);
                });
                list.dataSource.endEdits();
        }
    );
}

The following sequence occurs when making the request to the proxy:

• WinJS.xhr makes the initial GET request to /api/projects with no authentication information
• The custom Web API ActionFilter responds with HTTP 401 and the WWW-Authenticate header
• WinRT recognizes the Basic auth negotiation, prompts for credentials, and retries the request
• For the remainder of the app session, WinRT remembers the entered credentials and includes them in future requests to the same domain

Once the request is successfully completed, the JSON response is parsed and the TeamProjectInfo records are pushed into the list, triggering a data-binding refresh.

Displaying the Team Projects list

Note in the Data namespace above, the groupedProjects property is provided. This is a grouped view of the Team Projects, with the Team Project Collection name used as the group key. In the items page, I made some modifications so that Team Projects would be displayed in groups by their collection. I also simplified the item template markup to simply display the Team Project name.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

<div class="itemtemplate" data-win-control="WinJS.Binding.Template">
    <div class="item">
        <h4 class="workitem-title" data-win-bind="textContent: ProjectName"></h4>
    </div>
</div>

<div class="itemspage fragment">
    <header aria-label="Header content" role="banner">
        <button class="win-backbutton" aria-label="Back" disabled type="button"></button>
        <h1 class="titlearea win-type-ellipsis">
            <span class="pagetitle">TFS Work Items</span>
        </h1>
    </header>
    <section aria-label="Main content" role="main">
        <div
            class="itemslist win-selectionstylefilled"
            aria-label="List of groups"
            data-win-control="WinJS.UI.ListView"
            data-win-options="{ selectionMode: 'none', layout: {type: WinJS.UI.GridLayout} }">
        </div>
    </section>
</div>

There is not much code at all in the codebehind for this page, simply setting up the data binding and hooking the oniteminvoked event to trigger navigation to the Work Item list for the selected item. Because the ListView layout type has been set to WinJS.UI.GridLayout in the markup, the items in the list are automatically displayed in groups when the groupDataSource of the ListView is set.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

ui.Pages.define("/pages/items/items.html", {

    ready: function (element, options) {

        var listView = element.querySelector(".itemslist").winControl;
        listView.itemDataSource = Data.groupedProjects.dataSource;
        listView.groupDataSource = Data.groupedProjects.groups.dataSource;
        listView.itemTemplate = element.querySelector(".itemtemplate");
        listView.oniteminvoked = function (args) {
            var project = Data.projects.getAt(args.detail.itemIndex);
            WinJS.Navigation.navigate("/pages/split/split.html", { project: project });
        };

        this._initializeLayout(listView, Windows.UI.ViewManagement.ApplicationView.value);
        listView.element.focus();
    },
    // ...

So, putting it all together, here’s what the app’s home screen looks like:

Getting and Displaying Work Items

Selecting a Team Project on the items screen navigates to the split screen, with the project property of the options parameter set to the selected project. This is transformed by the framework into the arguments to the ready function of the split page. The split page has a lot more functionality than the items page – it needs to support:

• Selection of a work item to display its details
• Browsing to the next page of work items (a page of 10 at a time is returned by the proxy)
• Browsing to the preview page of work items
• Filtering the list of work items by type (e.g. Bug, Requirement, Task, etc.)

The ready function takes care of binding the App Bar commands, filling the filtering select control with work item types, and initiating the fetch of Work Items from the proxy.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

ready: function (element, options) {
    var self = this;

    self._project = options ? options.project;
    self._itemSelectionIndex = (options && "selectedIndex" in options) ? options.selectedIndex : -1;

    element.querySelector("header[role=banner] .pagetitle").textContent = self._project.ProjectName;

    document.getElementById("cmdPrev").addEventListener("click", self._prevWorkItemPage.bind(this), false);
    document.getElementById("cmdNext").addEventListener("click", self._nextWorkItemPage.bind(this), false);
    document.getElementById("cmdFilter").addEventListener("click", function() {
        var flyOut = document.getElementById("filterFlyout").winControl;
        flyOut.show(this, "top");
    });

    // fill the work item type select with the available types and listen for selection
    var workItemTypeSelect = document.getElementById("workItemTypeSelect");
    self._project.WorkItemTypes.forEach(function (workItemType) {
        var option = document.createElement("option");
        option.textContent = workItemType;
        option.value = workItemType;
        workItemTypeSelect.add(option);
    });
    workItemTypeSelect.onchange = function (event) {
        var currentValue = this.value;
        self._pageNumber = 0;
        this._itemSelectionIndex = -1;
        self._workItemTypeFilter = currentValue;
        document.getElementById("appbar").winControl.hide();
        self._getWorkItems();
    };

    self._getWorkItems();
}

The _getWorkItems function is triggered when the view is first loaded, as well as when a different page or filter is requested. It passes the parameters for page number and work item type to the proxy, and then fills the data-bound work item list with the response. The work item list and detail sections are faded out while processing. Code in the default.js bootstrapper hooks to the Data namespace’s processing event and shows an indeterminate progress bar and status message when the event is raised. By fading out the primary sections, we allow the progress bar to be easily seen.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

_getWorkItems: function() {
    var self = this;

    // fade list and workitem while loading
    WinJS.UI.Animation.fadeOut([[document.querySelector(".workitem-detail-section")], [document.querySelector(".workitem-list-section")]]);

    var listView = document.querySelector(".workitem-list").winControl;

    Data.dataService.getWorkItems(self._project, self._pageNumber, self._workItemTypeFilter).then(function (workItems) {
        self._workItems = workItems;

        // Set up the work item ListView.
        listView.itemDataSource = self._workItems.dataSource;
        listView.itemTemplate = document.querySelector(".workitem-template");
        listView.onselectionchanged = self._selectionChanged.bind(self);
        listView.layout = new ui.ListLayout();

        self._updateVisibility();

        if (self._isSingleColumn()) {
            if (self._itemSelectionIndex >= 0) {
                // for single-column detail view, load the article and change page title to Work Item title
                self._loadArticleDetails();
                WinJS.UI.Animation.fadeIn([[document.querySelector(".workitem-detail-section")], [document.querySelector(".workitem-list-section")]]);
            }
        } else {
            listView.selection.set(Math.max(self._itemSelectionIndex, 0));
            WinJS.UI.Animation.fadeIn(document.querySelector(".workitem-list-section"));
        }
    });

}

Note the use of the _isSingleColumn utility function - depending on the orientation or snapped state of the app, the view may be filled with the article details - in that case, we immediately load the current article details after the work items are retrieved; when in full landscape view, we set the selection in the list view knowing that our _selectionChanged handler will be triggered for loading the article.

The markup for the split page provides formatting for the work item list and detail view. It is not heavily modified from the Split App template, although the item images have been removed and additional binding fields have been added for the most important Work Item properties. At the bottom of the display area, a ListView is used to display a generic list of field name-value pairs - this is because work item templates can be heavily customized, and it is not possible to anticipate the names of the fields a user could define.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

<!-- Template for Work Item nav list -->
<div class="workitem-template" data-win-control="WinJS.Binding.Template">
    <div class="workitem">
        <div class="workitem-id"><h2 data-win-bind="textContent: Id"></h2></div>
        <div class="workitem-info">
            <h3 class="workitem-title win-type-ellipsis"><span data-win-bind="textContent: WorkItemType"></span>: <span data-win-bind="textContent: Title"></span></h3>
            <h4 class="workitem-state win-type-ellipsis" data-win-bind="textContent: State"></h4>
            <h6 class="workitem-assignedto win-type-ellipsis" data-win-bind="textContent: AssignedTo"></h6>
        </div>
    </div>
</div>

<!-- Template for individual work item fields list -->
<div class="field-template" data-win-control="WinJS.Binding.Template">
    <div class="field-pair">
        <div class="field-name win-type-ellipsis" data-win-bind="textContent: Name"></div>
        <div class="field-value win-type-ellipsis" data-win-bind="textContent: Value"></div>
    </div>
</div>

<!-- The content that will be loaded and displayed. -->
<div class="splitpage fragment">
    <header aria-label="Header content" role="banner">
        <button class="win-backbutton" aria-label="Back" disabled type="button"></button>
        <h1 class="titlearea win-type-ellipsis">
            <span class="pagetitle">Temp title</span>
        </h1>
    </header>
    <div class="workitem-list-section" aria-label="List column">
        <div class="workitem-list win-selectionstylefilled"
             aria-label="List of this Team Project's Work Items"
             data-win-control="WinJS.UI.ListView"
             data-win-options="{itemTemplate:select('.workitem-template'), selectionMode:'single', swipeBehavior:'none', tapBehavior:'toggleSelect'}">
        </div>
    </div>
    <article class="workitem-detail-section" aria-atomic="true" aria-label="Work Item detail column" aria-live="assertive">
        <header>
            <div class="workitem-id"><h2 data-win-bind="textContent: Id"></h2></div>
            <div class="workitem-title"><h2 class="win-type-ellipsis"><span data-win-bind="textContent: WorkItemType"></span>: <span data-win-bind="textContent: Title"></span></h2></div>
            <div class="header-left">
                <h4 class="workitem-subtitle"><span data-win-bind="textContent: State"></span> (<span data-win-bind="textContent: Reason"></span>)</h4>
                <h6 class="workitem-subtitle" data-win-bind="textContent: AssignedTo"></h6>
            </div>
            <div class="header-right">
                <h4 class="workitem-subtitle" data-win-bind="textContent: Area"></h4>
                <h6 class="workitem-subtitle" data-win-bind="textContent: Iteration"></h6>
            </div>
        </header>
        <div class="workitem-description"></div> <!-- content is set in code due to need to convert to static HTML -->
        <div class="workitem-history"></div>
        <div class="workitem-otherfields">
            <div class="workitem-field-list" data-win-control="WinJS.UI.ListView" data-win-options="{selectionMode:'none', swipeBehavior:'none', tapBehavior:'none'}"></div>
        </div>
    </article>
</div>
<div id="appbar" data-win-control="WinJS.UI.AppBar">
    <button data-win-control="WinJS.UI.AppBarCommand" data-win-options="{id:'cmdPrev', label:'Previous Page', icon:'previous', section:'selection'}" type="button"></button>
    <button data-win-control="WinJS.UI.AppBarCommand" data-win-options="{id:'cmdNext', label:'Next Page', icon:'next', section:'selection'}" type="button"></button>
    <button data-win-control="WinJS.UI.AppBarCommand" data-win-options="{id:'cmdFilter', label:'Filter', icon:'filter', section:'selection'}" type="button"></button>
</div>
<div id="filterFlyout" data-win-control="WinJS.UI.Flyout" data-win-options="{anchor:'cmdFilterButton'}">
    <label for="workItemTypeSelect">Work Item Type</label>
    <select id="workItemTypeSelect">
        <option value="All">All</option>
    </select>
</div>

The split.html markup also provides the App Bar for the page (defining the page and filter commands) as well as the flyout that is displayed when the filter command is invoked. The flyout simply contains a label and select list that is populated (as seen above) with the work item types available in the current project.

Wrapping Up

So, there you have it - a (very simple) TFS Work Item browser. This was a great learning exercise: it pushed my JavaScript skills and was a nice tour of some of the common features of the platform. While I’m happy with the insights I’ve gained into WinRT and with this app as a sample, I think it could take a more dynamic approach to browsing and viewing work items. The work item detail display does not seem to me to conform to the Windows Store design guidelines. I would like to consult with some of my UX colleagues for ideas about how to present the work item details in a way that is natural to the platform.

Future Plans

Here are some other potential ways to extend the app in the future

• Work Item Queries: returning a list of work items sorted ascending by ID is not very useful - most TFS users access work items using pre-defined work item queries.
• Content URIs: handle the vsts content URI for loading an individual work item.
• Leverage the Work Item Type definition to determine (and possibly reflect the layout definition of) the important custom work item fields.
• Display the Work Item details in a format more appropriate to a Windows Store app.
• Search, Sharing, and Print contracts.
• Allow simple modification actions, like assignment and state change; or, allow full editing.

Miscellaneous Tips

I ran into some issues along the way that don’t fit right in with the narrative above, but are worth sharing.

Tip 1: Secure XHR against IIS

Windows Store apps require all HTTPS server certificates to be trusted. I hit this message when attempting to use WinJS.xhr against my local IIS Express-hosted service:

SCRIPT7002: XMLHttpRequest: Network Error 0x800c0019, Security certificate required to access this resource is invalid.

I found a helpful blog post (see Step 7) that described how to install the IIS Express certificate in the local store so that it is trusted by the Windows Store app. In the deployed environment, this won’t be an issue, since AppHarbor supplies an HTTPS certificate from an already-trusted authority.

Tip 2: Fiddler with WinRT apps

By default, WinRT security prevents Fiddler from intercepting network traffic from Windows Store apps. This post explained how to work around the issue.

Tip 3: Dynamic content in InnerHTML

The Description and History work item fields will often contain HTML content. WinRT will throw a security error if you attempt to set the innerHTML property of an element to a string with certain attributes set. This article explains techniques for dealing with potentially dangerous content. The particular technique that I used was the window.toStaticHTML method for cleaning text before assigning it to an innerHTML property.

Tip 4: Deploying to and Debugging on Surface

To auto-deploy and test the app on my Microsoft Surface, directly from Visual Studio 2012, I followed the steps provided in this article. My colleague Rocky Lhotka also has a good article about packaging an app with a PowerShell script to allow distributing an app package for short-term side-loaded testing.

Implement program flow

Iterate across collections and array items; manage program decisions by using switch statements, if/then, and operators; evaluate expressions.

• Iterating a collection or array:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

for (item in collection) {
  console.log(item);
}

for (var i = 0; i < collection.length; i++) {
  var item = collection[i];
  console.log(item);
}

// NOT SUPPOTED IN IE
collection.forEach(item, index) {
  console.log(item + " at " + index);
}

$.each(collection, function(index, item) {
  console.log(item + " at " + index);
});

• Switch statement

1
2
3
4
5
6
7
8
9
10
11
12

function(stringVar) {
  switch (stringVar) {
      case "one":
          console.log(1);
          break;
      case "two":
          console.log(2);
          break;
      default:
          console.log(999);
  }
}

• If/then/else

1
2
3
4
5
6
7
8
9

if (condition) {
  // do a thing
}
else if (differentCondition) {
  // do another thing
}
else {
  // nothing at all
}

• JavaScript supports a similar set of comparison and assignment operators as other modern languages. Some special ones to watch for:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

var x = condition? "yes" : no;

function returnsUndefined {
  return void(5+5);
}

var y = (5, 6); // y = 6;

delete collection[4]; // collection[4] returns undefined

var x = new Date();
x instanceof Date; // true

typeof variable; // returns function, string, number, boolean, object, or undefined

• Evaluate expressions

1

eval("console.log('evaluated');");

Raise and handle an event

Handle common events exposed by DOM (OnBlur, OnFocus, OnClick); declare and handle bubbled events; handle an event by using an anonymous function

• Handling events

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

window.onload = (function(){
  alert('window load');
});

window.addEventListener('load', function(event) {
  alert('window load');
}, false);

var myButton = document.getElementById('button1');
myButton.addEventListener('click', function (event) {
  alert('clicked');
}, false);

$(window).on('click', 'div', function(event) {
  $(this).text = "changed text at " + new Date();
})

The third argument to addEventListener indicates whether you want to get the event in the capture stage. The capture stage begins at the HTML element and progresses through to the target, then the bubble stage flows from the target back to the HTML element. Using a combination of capture and Event.stopPropagation will allow you to grab an event before it reaches its actual target.

Event.preventDefault can be used to stop the default action from being invoked.

Implement exception handling

Set and respond to error codes; throw an exception; request for null checks; implement try-catch-finally blocks

To set an error:

throw new Error(100, "Yes sir");

Internet Explorer will treat the first argument as error number and second as description. Other browsers may support only a message.

You can get global errors

1
2
3

window.addEventListener('error', function(e) {
  console.log(e);
}, false);

Try/catch:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

try {
  // do stuff
}
catch (e) {
  console.log(e.name);
  console.log(e.number);
  console.log(e.message);
  console.log(e.description);

  // can check (e instanceof TypeError) etc
}
finally {
  // all done
}

Implement a callback

Receive messages from the HTML5 WebSocket API; use jQuery to make an AJAX call; wire up an event; implement a callback by using anonymous functions; handle the “this” pointer

To receive messages from the WebSocket API, first create a new WebSocket object using the ws protocol. Attach event handlers

1
2
3
4
5
6
7
8
9
10
11
12
13
14

var socket = new WebSocket("ws://my-host.com"); // optional protocols param 2
socket.onopen = function (openEvent) {
  console.log('opened');
};
socket.onmessage = function (messageEvent) {
  console.log(messageEvent.data); // this can be Blob, String (included serialized JSON), or ArrayBuffer
};
// similar callbacks for onerror and onclose

// events will fire after something is sent
socket.send("let's get started");

// in some event handler:
socket.close();

Making an AJAX call with jQuery is done as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

$.ajax(
  'http://my-host.com/rest-endpoint',
  {
      type: 'POST',
      data: {
          val1: 2,    // this will become a query string
          val2: 3     // for POST, should probably JSON.stringify
      },
      success: function (data) {
          // do something with it
      },
      error: function (e) { 
          // error
      }
  });

The ajax method returns a Promise interface (jqXhr in this case), so the event handlers can also be hooked up as:

1
2
3

$.ajax(...)
  .done(function(data){})
  .fail(function(error){});

The this pointer was addressed in other study guide posts.

Create a web worker process

Start and stop a web worker; pass data to a web worker; configure timeouts and intervals on the web worker; register an event listener for the web worker; limitations of a web worker

Here is a web worker sample:

1
2
3
4
5
6
7
8
9
10
11
12
13

// in the page HTML

var worker = new Worker('worker.js');
worker.onmessage = function(event) {
  console.log(event.data);
}
worker.postMessage('Hello.');

// and in the worker.js file

self.addEventListener('message', function(event) {
  self.postMessage('post back to the window's listener);
}, false);

Other web worker notes:

• Event data can be an object and is sent a serialized copy - modifying the object in one context will not change it in the other
• The self keyword is the global context in the worker js file
• There is no DOM, window, or document in the worker script
• The nav, location, XMLHttpRequest, and cache APIs can be accessed

Implement and Manipulate Document Structures and Objects (24%)

Apply styling to HTML elements programmatically

Much of this material was covered in my earlier study guide post.

More specifically, after getting a node, you can setAttribute('style', 'value') or access the .style property directly and set specific CSS attributes on it. For example, document.getElementById("container").style.color = "red". When applying hyphenated properties, drop hyphens as use lowerCamelCase (e.g. backgroundColor). Vendor-prefixed styles are accessed via ms, Moz, O, and webkit OR Webkit followed by the UpperCamelCase property.

With jQuery, it’s a matter of using the css method to set a CSS property.

Change the location of an element

The same prior post gives information about moving an element within the DOM (insertBefore and *Child methods) or with jQuery (after/before/append/prepend).

Position can also be changed by modifying the CSS position and top/right/bottom/left properties (node.style.*).

Apply a transform

CSS3 transformations allow translation (lateral movement), rotation, scaling, and skew, in both 2D (broad support) and 3D (much less support). Due to the immaturity of browser support, vendor-specific CSS attributes are required. The relevant 2D transform function values are:

matrix, translate[|X|Y], scale[|X|Y], rotate, skew[|X|Y]

Transforms are defined in CSS with the transform, transform-origin',transform-style,perspective,perspective-origin, andbackface-visibility` attributes.

Internet Explorer 10 supports 3D transforms:

matrix3d, translate3d, translateZ, scale3d, scaleZ, rotate[3d|X|Y

Other important considerations:

• Betas of IE10 required the -ms- prefix, but the current release does not.

• Multiple functions can be chained together in a single transform attribute and are cumulative.

• The box model and flow of a transformed element are calculated and applied before the transformation is applied - the element occupies its original position in the flow.

• Transforms can be combined with transitions for interesting animations. The transition attribute should be applied to the element’s original style. When a new style is applied, either programmatically or via JavaScript, the transition occurs. You can specify all or a particular CSS property to transition. The syntax is transition: property duration timing-function delay, .... Browser prefixes should be used.

• Remember this overall objective is about applying styling programmatically: in this case, the vendor-specific properties must be accessed, e.g. div.style.WebkitTransformOrigin = "2px 5px".

Show and hide elements

Elements can be shown and hidden via the display: none and visibility: hidden CSS properties. The primary difference is that display removes the element from the document flow while visibility makes the element invisible but keeps its space in the flow.

Via native API, use .style.display or .style.visibility. Via jQuery, the .hide() API can be used, which allows the setting of a duration and/or a more complex easing function. Under the covers, jQuery affects the display CSS attribute. When animating, the size of the object is gradually reduced to zero before display is set to none.

Implement HTML5 APIs.

Storage APIs

Cookies are traditionally used to associate values with a user and retrieve them at a later time, potentially across sessions. When the limitations of cookies are encountered, the storage API is useful.

• Cookies are limited by most browsers to 4KB and 300 max count within a domain.
• They must be included in all HTTP requests and responses to the domain; they are stored locally in plain text
• They are domain-wide and do not support multiple application sessions within a browser session.

HTML5 Web Storage offers many improvements over cookies:

• Purely client side - the data does not need to round-trip, so there is no download time or bandwidth usage.
• No 4KB limitation - IE provides around 10 MB of local and 10 MB of session storage.
• Multi-session - if you use session storage, you can have two separate state storage areas within a single browser session.

Working with the Storage API:

• Check for browser support by checking 'localStorage' in window && window['localStorage'] !=== null (similar for sessionStorage). In the following samples, sessionStorage can be substituted for localStorage.

• The lifetime of localStorage is persistent across browser sessions; sessionStorage persists only as long as a page/tab is open.

• The scope of localStorage is within the same linear domain hierarchy (e.g. domain.com, bob.domain.com, and alice.bob.domain.com can access one-another’s localStorage, but john.domain.com cannot access bob.domain.com localStorage). The scope of sessionStorage is within the current page/tab.

• There are three ways to store a key/value pair:

1
2
3

localStorage.myKey = 'myValue';
localStorage.setItem('myKey', 'myValue');
localStorage['myKey'] = 'myValue';

• To get the value of a key:

1
2
3

var value = localStorage.myKey;
value = localStorage['myKey'];
value = localStorage.getItem('myKey');

• To remove an item from storage:

1

localStorage.removeItem('myKey');

• To clear all items from storage:

1

localStorage.clear();

• Note that only string data may be stored as a value. Any non-string will be stored as a string using standard JavaScript conversion. If you want to preserve an object, JSON.stringify should be used to store and JSON.parse should be used to retrieve.

• Supported in IE 8, Firefox 3.5, Chrome 4, Safari 4, Opera 10.5, iOS Safari 3.2, Android 2.1.

AppCache API

The AppCache API allows the creation of offline web applications. Its primary functions are:

• Client-side cache of pages, images, scripts, style sheets, etc.
• Accessing cached content via standard URIs

In order to cache something you need to create a manifest. Following is a sample manifest:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

CACHE MANIFEST
# 2013-24-01:v3

CACHE:
# Defines resources to be cached after they are downloaded for the first time
script/app.js
css/styles.css
images/pic1.png

FALLBACK:
# Resources to use when online resources not available, in the form onlineURL cacheURL
# File-for-file
images/big_pic2.png images/pic2.png
# File-for-path
images/ images/offline.png
# File-for-wildcard
*.jpg offline.jpg

NETWORK:
# resources that will never be cached - user must be online
images/pic3.png

Manifest files must be served with the MIME type text/cache-manifest, have CACHE MANIFEST as the very first line, and be UTF-8 encoded.

The manifest is referenced in the html tag.

1
2
3

<html manifest="appcache.manifest">
...
</html>

Other AppCache notes:

• Any page that references a manifest is implicitly cached and does not need to be included in the manifest file itself.

• There are three ways to trigger a client-side cache update:

  • The cache automatically updated when the manifest file changes, so a version comment can be used to trigger an update.

  • The cache is updated programmatically with applicationCache.update() - this still requires that the manifest have changed from the last-downloaded version.

  • The user can manually clear the browser’s cache of your site.

• Pages served over HTTPS can work offline.

• The window.applicationCache object provides access to the cache. It has the following useful properties and events:

  • status field: Indicates the current cache status, returned as one of the following appCache members: UNCACHED, IDLE, CHECKING, DOWNLOADING, UPDATEREADY, OBSOLETE\
  • update function: Trigger an async check of the manifest. Will throw an exception of the page is not cached.
  • swapCache function: Swap currently ready cache update into the current storage. After swapping in the cache, the page must be reloaded to reflect the changes.
  • updateReady event: fires when a cache update has been downloaded. In the handler, you can swap the cache and prompt the user to reload if they choose.
  • error event: fires when the manifest cannot download, changes during its download, returns 404, manifest is OK but page itself fails to download.
  • progress event: fires as each resource listed in the manifest is fetched
  • Several other events: cached (first cache of manifest), checking (manifest update check began), downloading (update was found and resources are being downloaded), noupdate (first manifest download done or checking done and manifest not changed), obsolete (manifest response is 404 or 410)

• Supported in IE 10, Firefox 16, Chrome 23, Safari 5.1, Opera 12.1, iOS Safari 3.2, Android 2.1.

Geolocation API

The Geolocation API allows you to access geographical location information via JavaScript. It is exposed via the window.navigator.geolocation object.

The following geolocation members are useful:

• getCurrentPosition(successCallback, errorCallback, options): Async call to get the current position. The successCallback is called with a Geoposition object, or the errorCallback is called with an error object providing a code like error.PERMISSION_DENIED, error.POSITION_UNAVAILABLE, or error.TIMEOUT. The position object’s coords member gives latitude, longitude, altitude, heading, speed, and accuracy (in meters) information. Options can be provided for maximumAge (milliseconds) and enableHighAccuracy (can be affected by permissions).
• watchPosition(...): has the same signature as getCurrentPosition but returns an integer of the watchId which can be used to cancel the watch activity. The successCallback will be called whenever the position changes.
• clearWatch(watchId): stops watching position and will no longer call the callback for the watch set up with the watchPosition that returned watchId.

Establish the scope of objects and variables.

Define the lifetime of variables

All JavaScript objects and variables have scope and lifetime. Some that are provided by the browser have global scope and infinite lifetime, like document and window; other variables have local scope and limited lifetimes.

More lifetime notes:

• Locally-scoped objects are created and destroyed each time their functions execute.

• Globally-scoped objects live forever.

• A function executed in an asynchronous context still has access to the variables from its scope, even if the function that defines its scope has finished executing. This is called a closure.

Keep objects out of the global namespace

Techniques are available to keep variables and functions out of the global namespace:

• Always declare variables and functions (hereafter “objects”) with the var keyword.
• Always declare objects within the context of a function.
• The above principal is expanded in what is generally referred to as the “module pattern”. This refers to the use of an anonymous (key to avoid adding an identifier to the global namespace) Immediately-Invoked Function Expression (IIFE) to define a closure for the scope of the module. All of the following structures work to accomplish this goal.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

var x = 5;

(function(){
  var x = 10;
}());

(function(){
  var x = 20;
})();

(function($){
  $('#container').text('hi');
  var x = 30;
}(jQuery));   // assumes jQuery script already included.

console.log(x); // "5"

Use the “this” keyword to reference an object that fired an event

The this keyword has some wrinkles in JavaScript. In the classic Object-Oriented model, this always refers to the current object instance. This is not so simple in JavaScript:

• In the global scope (outside any function) or when invoked within a globally-scoped function, this refers to the “global object”, usually the same as window.
• In the context of a method (function member of an object), this refers to the object.
• In the context of a constructor, this refers to the function object being created.
• In the context of an event handler attached via jQuery’s on, this refers to the DOM object that triggered the event.
• Key for this objective: In the context of an event handler attached via addEventListener, attachEvent (IE) - this refers to the object that fired the event.

Scope variables locally and globally

More scope notes:

• There are two scopes, global and local. Variables and functions with local scope are declared within a function and are accessible only within the body of that function (this includes nested functions); globally-scoped objects are declared outside a function and are accessible everywhere. There is no such thing as block scope.

• JavaScript performs variable hoisting - this means that variables are treated as having been declared at the top of the function, regardless of the line where they are actually declared.

• Special case: a variable named inside a function without the var keyword has global scope, but does not exist until that function is invoked.

Create and implement objects and methods

Implement native objects

A native JavaScript object is created as follows:

1
2
3
4
5
6
7

var myObject = {
  stringMember: "xyz",
  intMember: 1,
  functionMember: function(thing) {
      console.log(thing);
  }
};

You can also create a new Object instance and then add members to it:

1
2

var myObject = new Object();
myObject.stringMember = "xyz";

More complex objects can be implemented using function constructors. This allows more control over the accessibility of the members of the object.

1
2
3
4
5
6
7
8
9
10

var Person = function(firstName, lastName) {
  var _privateInt = 5;
  var exports = {
      firstName: firstName,
      lastName: lastName
  }
  return exports;
};

var alice = new Person("alice", "jones");

Members of the object can then be accessed, e.g. myObject.intMember = 2.

Create custom objects and custom properties for native objects using prototypes and functions

There are several native objects, including:

Number, Boolean, String, Array, Date, Math, RegExp

A function can be added to an individual instance variable:

1
2

var d = new Date();
d.logIt = function() { console.log(this); };

A function can be added to the prototype of all objects created from the base function. These functions will be accessible on all objects created from that function, even those created before the function was added to the prototype.

1
2
3
4

var d = new Date();
if (!Date.prototype.logId) {
  Date.prototype.logIt = function() { console.log(this); };
}

Inherit from an object

Traditionally, inheritance has been accomplished as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

var Building = function(stories) {
  this.stories = stories;
  return this;
};
Building.prototype.writeStories = function() {console.log(this.stories); };

var House = function(stories, squareFeet) {
  Building.call(this, stories);
  this.squareFeet = squareFeet;
  return this;
}
House.prototype = new Building();
House.prototype.constructor = House;
House.prototype.dump = function() { console.log(this.stories + " " + this.squareFeet);};

var h = new House(2, 2500);
h.dump();

Inheriting from an object can be accomplished in modern browsers via Object.create(proto).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

var Building = function(stories) {
  this.stories = stories;
  return this;
};
Building.prototype.writeStories = function() {console.log(this.stories); };

var House = function(stories, squareFeet) {
  Building.call(this, stories);
  this.squareFeet = squareFeet;
  return this;
}
House.prototype = Object.create(Building.prototype);
House.prototype.dump = function() { console.log(this.stories + " " + this.squareFeet);};

var h = new House(3, 3300);
h.dump();

Fin.

This concludes the first of the four objectives - “Implement and Manipulate Document Structures and Objects”

Implement and Manipulate Document Structures and Objects (24%)

Write code that interacts with UI controls

Implement media controls

HTML5 has two new tags, video and audio, which allow direct embedding of these sources. Prior to HTML5, this was accomplished via the embed and object tags, and relied on plugins for playing the source. Modern browsers provide native implementations for playing audio and video, in support of the new tags.

Tag attributes

The audio and video tags supports the following custom attributes:

• src: URL for the source file
• autoplay: boolean - should the file play immediately?
• loop: boolean - should the file loop upon completion?
• controls: boolean - should the browser show its own controls?
• preload: value can be none, metadata, or auto. Indicates whether none of the file, only its metadata, or a browser-determined amount of the file should be pre-loaded before beginning playback.

The video tag supports the additional attribute:

• poster: URL for an image to display while the video is loading

Note that in HTML5 boolean attributes can be included without a value (<audio src='file.mp3' controls />), or self-value (, as )<audio src='file.mp3' controls="controls"/>).

Earlier HTML5 drafts had an autobuffer atrribute that is superseded by preload. Both attribute can be used while browsers transition.

These are block content tags, and so they support all of the attributes common to block content.

Source formats

Different browsers support different file formats, and there is no single format supported by all major browsers.

• For audio, WAV garners the most support, with only Chrome excluded. Firefox, Chrome, and Opera support Ogg; Safari, Chrome, and IE support MP3; Firefox, Safari, Opera, and IE support WAV.

• For video, webm has been agreed upon as the standard format for video, with some caveats. Safari does not currently support webm, and Internet Explorer will play webm video if the codec is installed separately. Within the type attribute, the codecs can be specified, video and then audio, e.g. <source src="movie.webm" type='video/webm; codecs="vp8, vorbis"'/>. Note the double quotes embedded within single quotes. The other major video types are mp4 and ogv . Because there is not a single source format supported by all major browsers, source elements can be nested inside the audio and video elements to provide multiple sources. The order of the sources is important: certain versions of Firefox had issues if the MP3 source was included first, so it’s recommended to provide an OGG source followed by an MP3 source to cover all browsers. For video, mp4 should be included first to avoid an iOS Safari issue.

MIME type should be specified on the source tags - this allows the browser to pre-determine which file to download.

Examples

Given the above information, here is an HTML5 audio control with all possible attributes set:

1
2
3
4
5

<audio controls autoplay loop preload="auto" autobuffer>
  <source src="file.ogg" type="audio/ogg">
  <source src="file.mp3" type="audio/mp3">
  <p>We could supply a Flash fallback or <a href="">link to the file for download</a> here.</p>
</audio>

And video:

1
2
3
4
5

<video controls autoplay loop preload="auto" autobuffer>
  <source src="movie.webm" type='video/webm; codecs="vp8, vorbis"' />
  <source src="movie.ogv" type='video/ogg; codecs="theora, vorbis"' />
  <p>We could supply a Flash fallback or <a href="">link to the file for download</a> here.</p>
</audio>

Browser compatibility

Create an audio or video element and check for the existence of the canPlayType function on it to determine if the HTML5 audio tag is implemented in the current browser. The canPlayType function can then be used to check what file types are supported: empty string, “maybe”, or “probably” will be returned. When the tag is not supported, or the browser does not support your available sources, you can fall back to Flash.

Currently only IE10 and Chrome support the <track> element within a media control. The purpose of tracks is to add parallel timed features such as navigation points, subtitles, or alternate audio streams.

Methods and Properties

If the controls attribute is not set, custom controls can be implemented by accessing the following methods and properties. You may wish to implement your own controls to achieve a more consistent appearance across browsers.

Important properties:

error, src, readyState, seeking, currentTime, duration, paused, playbackRate, played, seekable, ended, autoplay, loop, volume, muted

Important methods:

canPlayType, load, play, pause

Events

The media controls provide the following commonly-used events:

• canplay: Fires when the control determines whether it can play the video source.
• playing: Fires when playback is ready to start after having been paused or media not yet downloaded.
• ended: Fires when playback stops at the end of the file.
• timeupdate: Fires when the playback position changes during playback. Firefox fires once per frame, Webkit fires every 250ms.
• play: Fires when no longer paused, either after the play function is called or autoplay causes playback to begin.
• pause: Fires when paused after the pause function is called.
• volumechange: Fires after the volume or muted attribute value changes.

Note that the playing and play events seem very similar: play will fire as soon as the play command is issued, and then the playing event will fire once playback actually begins.

Implement HTML5 canvas and SVG graphics

Both the Canvas and SVG APIs are available to developers for creating graphics. Both are vector graphics technologies but are better suited for different tasks. The primary difference is that SVG can be expressed in markup and styled with CSS, while Canvas drawing is performed through scripting. Another difference is that SVG is a “retained mode” model in which the graphic definition remains in memory and can be modified and re-rendered, while Canvas is an “immediate” or “fire and forget” model that renders directly to the screen when its API is called.

The choice of which technology to use comes down to several factors:

• Developer familiarity: graphics APIs - Canvas versus markup - SVG
• Performance: size of screen has a large effect on Canvas, number of objects has a large effect on SVG
• Fidelity: SVG is scalable and stays crisp at any magnification
• High performance filtering: Canvas is better suited to pixel-based render, e.g. filters, ray tracers, pixel replacement/green screen
• Real-time data: Canvas is much better suited for images that require rendering real-time changes in many small objects, e.g. weather animations

Canvas

The canvas element enables rendering of resolution-independent graphics. A context is used for drawing, the most commonly implemented being Canvas 2D. Most browsers have implemented hardware-accelerated canvas rendering.

Canvas allows you to draw rectangles, lines, fills, arcs, shadows, Bezier curves, quadratic curves, images, and video.

Check for canvas support by creating a canvas element, verifying that it possesses the get getContext function, and that getContext('2d') is truthy. Canvas is supported on IE 7 / Firefox 3 / Safari 3 / Chrome 3 / Opera 10 / Android 1; basically, wide support on current browsers. Warning: IE 8 and below do not support the full API - the Explorercanvas library an be used in this case.

With a canvas element on the page, you can call its getContext('2d') method to get a Canvas 2D context and begin drawing.

The following are some interesting canvas APIs, assuming ctx is a Canvas 2D context:

• ctx.fillStyle = "style": sets the current fill style, may be a color, pattern, or gradient
• ctx.strokeStyle = "style": similar to fillStyle, but for outlines.
• ctx.drawImage(img, x, y): draw an HTML Image element into the context. Using an img on the page, it can be drawn during window.onLoad. For an Image created in JavaScript, the image.onLoad event should be used.
• ctx.fillRect(x, y, width, height): draw the fill of a rectangle in the current fillStyle
• ctx.strokeRect(x, y, width, height): draw the stroke of a rectangle in the current strokeStyle
• ctx.clearRect(x, y, width, height): clears the target rectangle
• ctx.beginPath(): begins a new path for the next stroke
• ctx.moveTo(x,y): moves the pen position without drawing
• ctx.lineTo(x,y): defines a path with the pen from the current position
• ctx.strokeStyle = "style": sets the stroke style
• ctx.stroke(): draws the current path with the current stroke style
• ctx.font, ctx.textAlign, and ctx.textBaseline: set the current text drawing properties
• ctx.fillText("text", x, y): write text at the given position (x at left edge, y relative to textBasline).
• var grad = ctx.createLinearGradient(x0, y0, x1, y1): create a linear gradient with the given angle
• grad.addColorStop(position, "color"): add a color stop to the gradient, at a position between 0.0 and 1.0.

Canvas coordinates originate in the upper left, with the X axis horizontal.

You can listen to the click event, which provides cursor position, to interact with the canvas.

SVG

SVG graphics can be displayed by including an <svg> tag with SVG markup inside. SVG graphic elements can be styled with their own attributes, or with CSS. SVG elements can be modified via the DOM API, but CSS styling takes precedence for rendering. CSS pseudo-classes (like :hover) can be used to trigger style changes. SVG has its own CSS namespace with attributes like fill, stroke, stroke-width, stop-color, etc.

The defs tag within the SVG tag allows the definition of gradients and filters, which can be combined for interesting fill effects, blurs, and shadows.

Example

The following example illustrates the primary primitives and styles possible

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

<style type="text/css">
  svg.draw {
      width: 300px;
      height: 300px;
      border: #666 1px solid;
  }
  .black-stroke {
      stroke: black;
      stroke-width: 2;
  }
  .red-fill {
      fill: red;
  }
  .blue-fill {
      fill: blue;
  }
</style>

<svg class="draw" xmlns="http://www.w3.org/2000/svg">
  <defs>
      <radialGradient id="gradient" cx="50%" cy="50%" r="50%" fx="50%" fy="50%">
          <stop offset="0%" style="stop-color:rgb(200,200,200); stop-opacity:0"/>
          <stop offset="100%" style="stop-color:rgb(0,0,255); stop-opacity:1"/>
      </radialGradient>
  </defs>
  <circle class="red-fill black-stroke" cx="50" cy="50" r="25" />
  <rect class="blue-fill black-stroke" x="5" y="5" width="30" height="40"/>
  <line class="black-stroke" x1="0" y1="0" x2="200" y2="200" />
  <ellipse cx="150" cy="150" rx="30" ry="50" fill="url(#gradient)" />
  <polygon  points="20,10 300,20, 170,50" fill="green" />
  <polyline points="0,0 0,20 20,20 20,40 40,40 40,60" fill="yellow" />
</svg>

Implement and Manipulate Document Structures and Objects (24%)

Write code that interacts with UI controls

Programmatically add and modify HTML elements

In general, the HTML DOM API or jQuery will be used to manipulate the page structure. It is important to understand the underlying native APIs - jQuery makes our code concise and cross-browser compatible, but a knowledge of what is happening under the covers will help you write more efficient jQuery. Moreover, there are times when you can accomplish something simple with the native API without the need to pull down jQuery.

In the following samples, I will give the native implementation, followed by its jQuery equivalent.

• The document object is a node that represents the entire HTML document (including the head). Everything in the DOM is a node. It’s important to differentiate between nodes and elements: all elements are nodes, but not all nodes are elements. For example, a div element may have an id attribute - the attribute is a node, but not an element.

• To get a single element by its ID:

1
2

document.getElementById('elementId') ==> HTMLElement
$('#elementId') ==> object ==> jQuery object

• To get an array of elements by tag name:

1
2

document.getElementsByTagName('div') ==> HTMLCollection / NodeList
$('div') ==> jQuery[]

• To get an array of elements by name (most useful for inputs):

1
2

document.getElementsByName('myInput') ==> HTMLCollection / NodeList
$('[name="myInput"]') ==> jQuery[]

• To get an array of elements by CSS class:

1
2

document.getElementsByClassName('cool-class') ==> HTMLCollection / NodeList
$('.cool-class') ==> jQuery[]

• To traverse between nodes, once you have a node reference:

1
2
3
4
5
6
7
8
9
10

var domNode = document.getElementById('elementId');
// note parentElement can be used but not *all* nodes are elements
var domParent = domNode.parentNode;
// note that childNodes may include inter-tag text, children returns only elements
var domFirstChild = domNode.childNodes[0];
var domFirstElement = domNode.children[0];

var jqNode = $('#elementId');
var jqParent = jqNode.parent();
var jqFirstChild = jqNode.children()[0];

• Important properties of a DOM node:

  • nodeType: Integer (enum) representing the type of node. 1 = Element, 2 = Attribute, 3 = Text, 8 = Comment, 9 = Document
  • nodeName: Name of the node. For tag elements, the tag name. For text content, #text.
  • nodeValue: Value of the node. For elements, null. For text, the text itself, and for attributes, the attribute value.
  • childNodes: Collection of children
  • parentNode: Parent
  • firstChild, lastChild, nextSibling, previousSibling: self-explanatory
  • jQuery equivalents:

1
2
3
4
5

var element = $('#container');
var firstChild = element.children(':first');
var lastChild = element.children(':last');
var nextSibling = element.next();
var previousSibling = element.prev();

• Element nodes may have one or more attributes. To access them, the attributes member is used. Attributes are not considered children of a node.

• Access all attributes of an element:

1
2
3
4

var div = document.getElementById('container');
var attribs = div.attributes;

// no jQuery equivalent

• Get and set the value of a particular attribute:

1
2
3
4
5
6
7
8
9
10

var div = document.getElementById('container');
var val = div.attributes['id'].value;
val = div.getAttribute('id');
var valNode = div.getAttributeNode('id');
div.attributes['id'].value = 'newValue';
div.setAttribute('id', 'newValue');

var jqDiv = $('#container');
var jqVal = jqDiv.attr('id');
jqdiv.attr('id', 'newValue');

• Check if an attribute exists:

1
2

var hasId = element.hasAttribute('id');
var jqHasId = (element.attr('id') !== undefined);

• Remove attribute:

1
2
3
4

element.removeAttribute('id');
element.removeAttributeNode(element.getAttributeNode('id'));

jqElement.removeAttr('id');

Now we have covered accessing and inspecting page elements via the DOM API and jQuery - it’s time to delve into modifying the structure of the page: adding, removing, and changing the contents of elements.

• Once you have a node reference, you can change its value. Tag nodes do not usually have values, but their first child will usually be a text node with value equal to the text content.

• To change a tag’s inner text:

1
2
3
4
5

var par = document.getElementById('paragraph1');
par.firstChild.nodeValue = 'Changed text';

var jqPar = $('#paragraph1');
jqPar.text('Changed text');

• To add an element to the DOM tree, you need to create an element, set any required attributes, and then append it to as the last child of an existing node:

1
2
3
4
5
6

var newNode = document.createElement('img');
newNode.setAttribute('src', 'https://www.google.com/images/srpr/logo3w.png');
var body = document.getElementsByTagName('body')[0];
body.appendChild(newNode);

$('body').append('<img src="https://www.google.com/images/srpr/logo3w.png"/>');

• Adding additional inner text to a span, div, or p tag is accomplished as follows. Note that jQuery append is equally effective for HTML or text:

1
2
3
4

var par = document.getElementById('paragraph1');
par.appendChild(document.createTextNode('Additional paragraph text here'));

$('#paragraph1').append('Additional paragraph text here')

• You can also insert an element as a sibling before an existing node:

1
2
3
4
5
6
7

var newNode = document.createElement('img');
newNode.setAttribute('src', 'https://www.google.com/images/srpr/logo3w.png');
var body = document.getElementsByTagName('body')[0];
body.insertBefore(newNode, document.getElementById('container'));

$('container').before('<img src="https://www.google.com/images/srpr/logo3w.png"/>');
$('body').prepend('img src="https://www.google.com/images/srpr/logo3w.png"/');

• Take care to note the differences between appendChild and insertBefore. A node added with appendChild will be the last node contained by the target. Calling insertBefore has the signature container.insertBefore(nodeToInsert, nodeThatWillBeAfter) - in this case as well, nodeToInsert will be a child of the target, but it will be the prior sibling to nodeThatWillBeAfter.

• To remove an element from the DOM:

1
2
3
4

var body = document.getElementsByTagName('body')[0];
var removedElement = body.removeChild(document.getElementById('container'));

$('#container').remove();

• To replace an existing element:

1
2
3
4
5
6
7

var body = document.getElementsByTagName('body')[0];
var newNode = document.createElement('img');
newNode.setAttribute('src', 'https://www.google.com/images/srpr/logo3w.png');
var oldNode = document.getElementById('container');
body.replaceChild(oldNode, newNode);

$('#container').replaceWith('<img src="https://www.google.com/images/srpr/logo3w.png"/>');

• In both the DOM and jQuery, you can move an element by getting a reference to it and then calling one of the above insertion/replacement methods. A node cannot exist at two places in the DOM, so it will automatically be removed from its previous location.

• jQuery in total provides after, before, append, prepend, replaceWith, wrap, wrapInner, and wrapAll for DOM manipulation - these methods are called on the selector for the existing element(s) with the new content as an argument. Companion methods insertAfter, insertBefore, appendTo, prependTo, and replaceAll are targeted to the new content with the target selector as an argument. The odd man out is remove, which is targeted to a selector for content to be removed.

‘Til Next Time

That will conclude DOM manipulation. We’ll pick up next time with media, canvas, and SVG.

Implement and Manipulate Document Structures and Objects (24%)

Create the document structure

Structure the UI using semantic markup, including for search engines and screen readers

• HTML5 introduces several new tags, and does not support some others that were deprecated in HTML 4.0.1.

• The new tags are:

article, aside, audio, bdi, canvas, command, datalist, details, embed, figure, figcaption, footer, header, hgroup, keygen, mark, meter, nav, output, progress, rp, rt, ruby, section, source, summary, time, track, video, wbr

• In total there are 30 new tags.

• The following 12 tags are no longer supported in HTML5. Most of these were deprecated in HTML 4.0.1, with the exception of acronym, big, frame, frameset, noframes, and tt.

acroynm, applet, basefont, big, center, dir, font, frame, frameset, noframes, strike, tt

• The objectives make special mention of the new semantic tags for structure.

  • section (block): Grouping of content. Typically will include a heading. W3C: “A generic section of a document. A thematic grouping of content, typically with a heading.” Sections usually will appear inside articles, but can be used independently.

  • article (block): Individual/independent block of content, such as a blog post or news article. Articles should be able to stand alone, whereas sections may be part of a larger whole. Usually contain sections. May be sub-articles (e.g. comments on blog entry). Should be independently re-distributable, e.g. in syndication.

  • nav (block): Navigational feature, usually site-level. Section of a page that links to other pages or parts within the page - a section with navigation links. W3C: “Not all groups of links need to be in a nav - intended for sections that consist of major navigation blocks. Common for footers to have list of links to policies etc, nav is not appropriate here.”

  • header: Will contain heading content, often will contain nav. Usually site/page-level header. Will include introductory and/or navigational aids. Usually will contain sections H? / HGROUP. Can wrap TOC, search form, logos, etc.

  • footer (block): Will contain foot-note content, like attributions, copyright, etc. Typically site/page-level footer.

  • aside (block): Content tangentially related to primary content.

• Some of the new semantic structuring tags have the property of being “sectioning content,”” or being a “sectioning root.” This means that the HTML outlining engine will give these nodes special treatment. Sectioning content defines the scope of headings and footers - within an article, aside, nav, section tag, headers are nested within the outline of their parents, regardless of header level. So, <body><h2>Top</h2><section><h1>Inner</h1></section></body> results in the H1 being outlined within the H2.

• Other new semantic tags not directly related to structure:

  • figure (block) / figcaption (text): The figure tag provides stand-alone, illustrative content, like a plot, image, or video; its first child figcaption tag provides a related caption.

  • hgroup (block): A group of headings. Should contain <h[1-6]> tags only. Provides a hint to the HTML outlining engine that only the first header in the group should be included in the outline, and that the following headings within the group are not additional outline-able sections but are instead subheadings of the first.

  • mark (text): Highlighted text, or text referred to elsewhere.

  • time (text): A date and/or time representation.

• The key to remember about the new “semantic” tags is that they allow one to express the meaning of a block in the tag itself, rather than via a CSS class or ID. This brings some standardization to naming (should I call it my class “article” or “feature”?), and promotes block roles to more prominence than other CSS attributes. They also aid in accessibility; for example, users of screen readers can indicate the order in which NAV sections should be read.

• It is important to frame the overall context for structuring a document as well. HTML documents always begin with a DOCTYPE declaration, and should include a HEAD and BODY, as well as charset declaration within the head.

  • The HTML5 doctype is simply <!doctype html>, without a URL or version number.
  • Inside the HEAD (and within the first 512 bytes of the document), a META tag indicating the charset should be included, e.g. <meta charset=utf-8>. Note META tags are not required to be closed, and the charset value does not need to be quoted. Specifying the charset is essential for avoiding potential security issues in which a URL could be crafted to inject arbitrary script into the page body.

• The new HTML5 tags are supported in IE 9, Firefox 16, Chrome 23, Safari 5.1, iOS Safari 4.0, Android Browser 2.2, and Blackberry 7.0. To ensure support in older browsers, an HTML5 shim can be employed, or the JavaScript document.createElement API can be used to create elements that do not exist.

Create a layout container in HTML

• Creating a layout container involves defining the elements that provide the overall structure to a page - positioning of the header/nav, footer, potential sidebar, and primary content.

• The primary CSS attribute that affects the layout of block display elements is position. It can have the following values:

  • absolute: An element positioned absolutely is offset (trbl) from its first parent with non-static position. Absolutely-positioned elements do not participate in normal layout flow.
  • relative: An element with relative position can be offset from its original/inherited position (trbl). Content moves, but originally reserved space is still preserved in flow.
  • static: Static position is the default, items are flowed normally and (trbl) has no effect.
  • fixed: Fixed position is (trbl) relative to the browser window and will not move when scrolled.

• When elements overlap, z-index must be considered. Higher z-index results in an element being positioned on top. Equal z-index results in the last item in the document being positioned on top.

• Modern layouts are most commonly achieved by floating various elements around each other. Floating allows sibling content to flow around an element, if there is room next to it. If not, the floated element will wrap to the next line. Floated elements should be inserted before float:none elements.

To Be Continued…

I think that’s a good introductory post and plenty of basic material to chew on. In my next post we’ll pick up with the next objective: “Write code that interacts with UI controls.”

It’s much easier to turn a critical eye on someone else’s work. Looking at your own stuff, you’ll always have the reasoning that led you to the current state in the back of your mind. You’re seeing what you have imagined and envisioned, not only what actually exists. Web design is about communication - with your own stuff, you already know the information that the site attempts to communicate. Reviewing someone else’s work is a great way to exercise critical muscles that you can then use on your own material.

So check out Criticue – it’s win-win: get timely, unbiased feedback on your stuff and practice your own critical eye.

Overview

The service is hosted in an ASP.NET MVC 4 application. It has a single ErrorReportingController with a a single POST endpoint Report that accepts only a string for the error report body. When the API is called, the error report is stored in RavenDB via the RavenHQ cloud service and emailed to me via SendGrid. The great thing is that the only thing deployed with my app is logic - storage and email are all handled by services.

The following sections provide a rough outline of the steps required to get it all working. I consider this spike a “proof of concept,” as it has plenty of hard-coded constants and no unit tests (which I would accomplish via injection of the SendGrid dependency and use of the in-memory RavenDB server).

Set up the required services

1. Sign up for an AppHarbor account and create an application.
2. Set up AppHarbor to build and deploy the solution when it is pushed to GitHub. Note that AppHarbor will automatically detect which project should be deployed, as long as the solution contains only a single Web Application.
3. Add the RavenHQ (for storing error reports) and SendGrid (for emailing error reports) add-ons. Note that this adds entries in the Configuration variables section for the RavenDB connection string and SendGrid username and password.

API Logic

The ErrorReportingController.Report method looks like this:

1
2
3
4
5
6
7
8

[HttpPost]
public ActionResult Report(string errorReport)
{
    SendEmail(errorReport);
    StoreInRaven(errorReport);

    return Json("Successful email.");
}

The code for sending an email creates a SendGrid email message and delivers it using the SendGridMail.Transport.REST API. The API requires a username and password, which I load from Web.config. AppHarbor automatically pushes these values into Web.config when you deploy, so these values are only stored securely with your AppHarbor account and live as dummy values in source control:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

private static void SendEmail(string errorReport)
{
    var message = SendGrid.GenerateInstance();
    message.From = new MailAddress("my@email.com");
    message.AddTo("my@email.com");
    message.Subject = "TFS Test Steps Editor Error";
    message.Text = errorReport;

    var username = ConfigurationManager.AppSettings["SENDGRID_USERNAME"];
    var password = ConfigurationManager.AppSettings["SENDGRID_PASSWORD"];
    var restTransport = REST.GetInstance(new NetworkCredential(username, password));

    restTransport.Deliver(message);
}

The code for persisting the error report creates an ErrorReport instance, opens a RavenDB session, and stores the error report:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

private static void StoreInRaven(string errorReportText)
{
    var errorReport = new ErrorReport
    {
        ReportedDateTime = DateTime.UtcNow,
        Source = "HTTP Post",
        Text = errorReportText
    };

    using (var session = MvcApplication.Store.OpenSession())
    {
        session.Store(errorReport);
        session.SaveChanges();
    }
}

Note the use of MvcApplication.Store. This is simply a static property defined on the MvcApplication class in Global.asax.cs and initialized in Application_Startusing the Web.config appSettings value automatically set by AppHarbor.

Hooking unhandled exceptions and sending error reports

The final piece is the actual sending of error reports. TFS Test Steps Editor is a Windows Forms application, so I use the following code in the Program.Main method to get access to unhandled exceptions:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

Application.SetUnhandledExceptionMode(UnhandledExceptionMode.ThrowException);
AppDomain.CurrentDomain.UnhandledException += (sender, unhandledExceptionEventArgs) =>
{
    if (_HandlingThreadEx) return;

    lock (_ExLock)
    {
        if (_HandlingThreadEx) return;
        _HandlingThreadEx = true;

        var reporter = new ExceptionReporter(unhandledExceptionEventArgs.ExceptionObject);
        reporter.ReportException();
    }
};

The lock and guard ensures that we don’t enter an infinite loop if an exception occurs while sending the error report.

The ExceptionReporter class logs the exception and presents a dialog asking whether the user wants to email an exception report. If the user confirms, my Error Reporting service is called. Here is the relevant snippet. The logBody variable is a string set by flushing the current NLog file and then reading its text:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

var wrapper = (AsyncTargetWrapper) LogManager.Configuration.FindTargetByName("logFile");
wrapper.Flush(x => { });

var fileTarget = (FileTarget) wrapper.WrappedTarget;
fileTarget.Flush(x => { });
var fileNameLayout = (SimpleLayout) fileTarget.FileName;
var fileName = fileNameLayout.Render(new LogEventInfo()).Replace(@"/", @"\");
string logBody = File.ReadAllText(fileName);

string body = String.Format(
    "Message: {0}\r\n\r\nDump: {1}\r\n\r\nLog Body:\r\n{2}",
    _messageTextBox.Text,
    _detailTextBox.Text,
    logBody);

string bodyEncoded = "errorReport=" + HttpUtility.UrlEncode(body);
var bodyBytes = Encoding.UTF8.GetBytes(bodyEncoded);

var request = WebRequest.Create("http://myservice.apphb.com/ErrorReporting/Report");
request.Method = "POST";
request.ContentType = "application/x-www-form-urlencoded";
request.ContentLength = bodyBytes.Length;

var requestStream = request.GetRequestStream();
requestStream.Write(bodyBytes, 0, bodyBytes.Length);
requestStream.Close();

string responseBody = "";
var response = (HttpWebResponse) request.GetResponse();
using (var responseStream = response.GetResponseStream())
{

    using (var reader = new StreamReader(responseStream, Encoding.UTF8))
    {
        string line;
        while ((line = reader.ReadLine()) != null)
            responseBody += line;
    }
}

if (String.IsNullOrWhiteSpace(responseBody))
    responseBody = "<no response from server>";

MessageBox.Show("Send error report: " + responseBody.Replace("\"", String.Empty));

Conclusion

This was a fun exercise that let me explore the integration of several cloud services while providing some value to my end users. I’ve already received several error reports that I can turn into tangible improvements in the TFS Test Steps Editor. Making it easy for your users to report errors lets them help each other. There is a class of “annoying but I can get around it” error that often goes unreported, but in aggregate causes a lot of pain.

AppHarbor makes things really easy. While its UI is not as slick or modern as Azure’s, I find it more intuitive to use than the Azure Web Sites featured, mostly because there are fewer knobs to twiddle. Obviously Azure provides a lot more out of the box, but for these simple purposes, AppHarbor is a perfect fit. And if you need some of the features that Azure has out-of-box, the AppHarbor add-on ecosystem is quite rich, not to mention the bevy of other cloud services that are easily integrated even without a native add-on.

After implementing this minimal, non-configurable service, I have been inspired to develop a generic, open service that could be used by other developers. Development of that service has begun in my GitHub repo and is being tested at http://errorgun.apphb.com.

• Choose a monospace font.
• In the style editor Format dropdown, choose Language, and then check the box labeled “Do not check spelling or grammar.”
• Ensure no specific color is selected so that colors pasted from your code editor appear correctly (if they look good on a white background).

If you use a Character style (as opposed to a Paragraph style), you can even apply the style to text inline within a paragraph. This can be a good way to set apart “input” text from explanatory text.

Keynote

John Theron (Red-Gate’s chief marketing officer) set the stage for the day with some audience participation. We were asked to pass untied balloons back through the audience, with our eyes closed, without losing any air. It was an analogy to the difficulty of pushing database and application changes from dev into production, without losing any important changes. The keynote transitioned into highlighting all of the ways Red-Gate has been helping users manage and deploy database (and now application) changes for the past several years. One of the primary themes of the day was employing automation for more reliable and controlled releases, including the use of continuous integration, automated testing, and automated deployments.

One point that hit home for me was about the value of frequent releases: the sooner your new stuff gets in front of actual customers, the more quickly you get their feedback; and customer feedback is the most valuable of all. There is also less time for a mess to accumulate: the larger the delta of a release, the longer it will take to deploy, and the greater the chance of an issue.

Monitoring

Robin Anderson delivered a session demoing the SQL Monitor tool. The tool provides the ability to remotely gain insight into the state of your SQL server. Many of us employ a bag of monitor queries to check on the health of our SQL servers. The Red-Gate tool bundles up many best-practice health checks (not only DMV queries, but PerfMon, WMI, and file watching) into a convenient and attractive package, and adds alerting on top of it.

A very nice feature is the ability to create custom metrics driven by an arbitrary SQL query. The demo showed monitoring of a particular DMV query. I can imagine this being very useful for creating application behavior-specific metrics. For example, we have a consolidated logging system that pushes all of our server text logs to a central database. One could create a custom metric that triggers an alert when the rate of exceptions per hour exceeds a threshold.

Red-Gate is planning a cloud-hosted monitoring service that is fed by a relay service installed inside the customer’s firewall. This is a nice compromise that should make it easier for DBAs to convince their IT departments to deploy the tool.

Source Control for SQL Databases

I attended two sessions that covered similar ground: source-controlling your database (schema and reference data). Ernest Hwang and Grant Fritchey presented about the use of SQL Source Control to automatically push changes made to the database in SSMS into corresponding source-controlled SQL files.

In “Case Study: Why You Should Source Control Your Database,” Ernest focused more on the deployment side, demoing the use of Jenkins to automatically build and deploy database changes when they are checked in. I was surprised that the build configuration required a good bit of hand-crafted MSBuild XML that used the Exec task to shell out to SQL Compare to deploy the database and run tests. I have found Exec to be pretty brittle for this kind of thing, because it introduces install and path dependencies on the build server. I found some MSBuild Tasks, posted by Phil Winstanley, that use the SQL Compare API - this could be a more reliable solution.

Grant Frichey’s talk was titled “A Sandbox Development Process.” He focused on the change-management side of database source control, presenting the use of SQL Virtual Restore to start from a (possibly scrubbed) production database, mapping it to a source-controlled schema, and then making “sandboxed” changes in a local development environment. SQL Virtual Restore looks like an awesome solution for working with real data while avoiding copying massive data files. A single full backup can exist in a shared location and be restored into a local database backed by small “virtual” vmdf and vldf files. Grant was my favorite speaker of the day - his style is humorous and engaging, and he’s obviously got a ton of experience to back up his advice.

Business Intelligence

The duo of Noemi Moreno and Tom Austin presented “Social Media, Business Intelligence, and Bridging the SSMS-VS Divide.” The talk used an interesting BI example to demonstrate the use of SQL Source Control (in Management Studio) and SQL Connect (in Visual Studio) by different developers to both evolve the same database schema. The integration looked pretty smooth, although the Visual Studio scenario seemed to involve a fair bit of magic behind the scenes that could be difficult to troubleshoot if things go south.

The application itself was cool, it involved an SSIS package that integrated data from an OLTP database and the Twitter API into a single SSAS cube which was then exported to Google Fusion Tables for a map visualization. I really like composing together several small implementations into a single solution, using the right tool for each part of the job. SSIS makes me queasy though.

T-SQL Unit Testing

The final session that I attended was “Thwarting Database Defects” (notice the play on “TDD?”). Sebastian Meine and Dennis Lloyd Jr presented about tSQLt, a T-SQL unit testing framework. Unit testing of the database is not something that I have ever done directly - usually the closest we get is testing against our repositories.

The capabilities of the framework are very impressive. Every unit test runs in a transaction that is rolled back after the test executes, forcing you to completely isolate your tests (no “this one has to run before that one”), and guaranteeing a consistent state before each test run. It’s driven by a set of stored procedures in a “tSQLt” schema that you create in your database itself, and provides the ability to mock out stored procs and even tables, and to assert about the expected results. Your tests themselves are a set of stored procedures under test-unit-specific schemas. The only drawback, in my opinion, is that the framework and unit tests must be created in the database that is being tested. Given the day’s theme of source-controlling your database, this creates the need to ensure the unit tests don’t make their way into production.

Conclusion

This was a worthwhile event, the pacing and organization were perfectly executed, the food was good, and plenty of Red-Gaters were available to talk between the sessions. I’ve got lots of inspiration to take back to work and turn into better-quality databases!

Sublime TFS will auto-check-out modified files (a must since files in TFS are readonly until checked out), and provides commands for Add, Delete, History, Check in, Check out, Undo, Get latest, and Compare with latest, available when the current file is under version control (except Add, obviously).

I made a small contribution to the project, adding support for the TFS Power Tools “Annotate” feature (commonly known as “blame”). I have one major complaint about the Annotate output from TFPT, though: you can’t open a changeset view by clicking a changeset number. I’m considering using the /noprompt option and dumping the Annotate output into a Sublime Text buffer, then providing the ability to open a changeset view from the buffer. Sounds like fun!