![36 chapter three
JavaScript
// Contained in jquery.qs.tagger.js
(function($, undefined) {
$.widget('qs.tagger', {
// definition of the widget goes here
});
}(jQuery));
The call to $.widget invokes the widget factory, which makes the widget available for
use. The first argument, qs.tagger, is the widget’s namespace and name separated by a
period (namespace.name). The name is used as the name of the widget method placed on
the jQuery prototype. The second argument, called the widget prototype, is an object lit-
eral that defines the specifics of the widget. The widget prototype is the definition of the
widget, and is used when the widget is applied to elements. The prototype is stored di-
rectly on the jQuery object under the namespace provided: $.qs.tagger.
Using a Widget
Once a widget has been defined, it’s ready to be applied to DOM elements. To apply the
widget to the matched elements, invoke the widget method just like you would other
jQuery methods. The following code shows how to apply the tagger widget to all span
elements with a data-tag attribute.
JavaScript
// Contained in startup.widget.js
$(‘span[data-tag]’).tagger();
Because the widget method is used as the primary interface to the widget, it’s not
only called when initially applying the widget to the element, it’s also used for calling
methods and reading and writing options and properties on the widget. When widgets
are applied to elements, an instance of the widget is created and stored inside each ele-
ment. This is how the widget factory knows if a widget has already been attached to an
element.
Managing Lifetime
There are three phases of a widget’s lifetime that you can control: creation, initialization,
and destruction.
Creation
The first time the widget is applied to an element, the widget’s _create function is in-
voked. Method names preceded with an underscore have private scope by convention,
which means they only expect to be invoked from inside the widget. The following code
shows the _create method in the infobox widget.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-69-320.jpg)
![41jquery ui widgets
Just like normal options, these can either define defaults or omit them. The use of
$.noop as a default value saves you the effort of having to ensure that the value isn’t null
before calling the option. Calling $.noop has no effect and won’t throw any exceptions.
The startup script will provide these options when it applies the tagger widget to the
span elements, as shown here.
JavaScript
// Contained in jquery.qs.tagger.js
$('span[data-tag]').tagger({
activate: function (event, data) {
// call displayTagLinks() on infobox here
},
deactivate: function () {
// call hideTagLinks() on infobox here
}
});
In the code examples above, the options are defined inside the widget’s implementa-
tion and passed in during creation. Later in this chapter you’ll see how function-based
options are used as callbacks for events.
The Widget Method
Well-designed objects have public interfaces that are intentional, intuitive, and focused.
Widgets go one step further and provide a single method, referred to as the widget
method, which is the entire public interface of the widget. The action the widget performs
when you call this method depends on the number and type of arguments provided in the
call. In addition to creating and initializing the widget, as shown earlier, the widget
method is also used to do the following:
• Invoke public methods
• Read and write public properties
• Read and write options
Public Methods
Public methods are defined on the widget prototype, as you can see here in the infobox
widget. The public methods are hideTagLinks and displayTagLinks.
JavaScript
// Contained in jquery.qs.infobox.js
$.widget('qs.infobox', {
hideTagLinks: function() {
...
},
displayTagLinks: function(event, tagName) {
...
}](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-74-320.jpg)
![46 chapter three
Events
Events are an effective way to communicate between widgets without forcing them to
be tightly coupled. jQuery supports and extends the DOM event model and provides the
ability to raise and handle custom events that are not defined in the DOM.
Raising the Event
A widget raises events by using the _trigger method. The first argument to _trigger is the
name of the event you are raising. If the event you are raising originates from a DOM
event, the DOM event can optionally be passed as the second argument. The third argu-
ment is any data to be passed to the event handler and is also optional. The following code
sample shows one way the tagger widget might raise the activated event when the mouse
enters the element.
JavaScript
// Code illustration: not in QuickStart
_create: function () {
var that = this,
tag = that.infoboxElement.text();
that.infoboxElement
.bind('mouseenter', function (event) {
that._trigger('activated', event, {name: tag});
});
},
In this fictitious code example, infobox is raising an activated event by binding to the
mouseenter event of an element. You can also use bind, as well as the live and delegate
methods, to handle events triggered from widgets.
Binding Handlers
Event handlers bind to widget events the same way as they bind to other events, although
the name of the event is influenced by the widget’s name.
JavaScript
// Code illustration: not in QuickStart
$('span[data-tag]').bind('taggeractivated', function(event, data) {
// handle the event
});
Notice how the name of the event being bound to has the name of the widget pre-
pended. This is the default behavior for event names. If you prefer a different name so
that your code is more readable, this behavior can be changed, as shown in the following
section.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-79-320.jpg)
![48 chapter three
JavaScript
$('span[data-tag]').tagger({
activated: function (event, data) {
infobox.infobox('displayTagLinks', event, data.name);
},
deactivated: function () {
infobox.infobox('hideTagLinks');
}
});
This allows the two widgets to interact without explicitly knowing about each other.
Using this approach causes the script that invokes the widgets to act as connective tissue
that describes a lot about the solution in a succinct, readable format.
Inheritance
Sometimes, when building a widget, another widget already has many properties and
much of the functionality the new widget requires. The widget factory’s inheritance sup-
port is designed for this case. For illustration purposes, consider the following widget.
JavaScript
// Code illustration: not in QuickStart
(function ($) {
$.widget('a.container', {
...
resize: function() {
// resize width and height
},
...
});
}(jQuery));
If this widget was built elsewhere and you wanted to change its resizing behavior to
an animation, a reasonable approach would be to inherit from a.container and override
its resize method. Inheritance is accomplished by passing three arguments into the widget
factory. The first argument is the namespace and name of the widget, the second is the
prototype of the widget you want to extend from, and the third argument is the object
you want to extend it with.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-81-320.jpg)
![95modularity
JavaScript
// Contained in mstats.header.tests.js
test('when title option is changed, then it displays new title', function() {
expect(1);
var header = $('#header').header();
header.header('option', 'title', 'test title');
equal($('[data-title]').text(), 'test title', 'header text set properly');
});
When this test runs, it ensures that the _setOption method on the header widget,
the code under test, updates the text for the header.
JavaScript
// Contained in mstats.header.js
_setOption: function (key, value) {
switch (key) {
case 'title':
this.element.find('[data-title]').text(value);
break;
...
}
$.Widget.prototype._setOption.apply(this, arguments);
}
In order for the tests to run in isolation, each test file must contain a copy of the
HTML markup that mirrors the markup to which the code under test will be applied. You
can find this markup at the top of the test files.
JavaScript
// Contained in mstats.header.tests.js
module('Header Widget Tests', {
setup: function () {
$('#qunit-fixture').append('<div class="header" id="header">' +
'<div><div><h1 data-title>Dashboard</h1>' +
...
'</div>'
);
}
});
For more information about unit testing, see Chapter 13, “Unit Testing Web Applica-
tions.”](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-128-320.jpg)
![104 chapter six
Data Cache
The Mileage Stats data manager uses an internal data cache for storing request results;
the data cache is only accessed by the data manager. Making the data caching internal to
the data manager allows the caching strategy to evolve independently without affecting
other JavaScript objects that call the data manager.
The data cache is implemented using a JavaScript object named dataStore that is
contained in the mstats-data.js file. Other data cache storage locations could include the
DOM, a browser data storage API or a third-party library. The dataStore JavaScript object
was implemented because Mileage Stats supports Internet Explorer 7, which does not
support the HTML5 web storage specification.
Adding and Retrieving Cached Data
Note: The Mileage Stats dataStore object is scoped to the page, not the browser
window. Consequently, when the page is fully reloaded from the server, the cached data
will no longer be cached since the data cache object will be recreated when the page
loads.
Mileage Stats integrates client-side data caching into the data manager’s sendRequest
method implementation that was described in the previous section.
Internally, the dataStore is implemented using name/value pairs. It exposes three
methods: get, to retrieve data by a name; set, to cache data by a name; and clear, to re-
move data corresponding to a name.
JavaScript
// Contained in mstats.data.js
mstats.dataStore = {
_data: {},
get: function (token) {
return this._data[token];
},
set: function (token, payload) {
this._data[token] = payload;
},
clear: function (token) {
this._data[token] = undefined;
},
};](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-137-320.jpg)
![113manipulating client-side html
To select all of the elements that carry the data-list-url attribute shown in the previ-
ous HTML listing, you could use the following JavaScript code.
JavaScript
// Example: select the element(s) with a data-list-url attribute
var myVehicleElement = myVehicleList.find(‘[data-list-url]’);
The jQuery library also supports data- attributes directly through the data method,
which can get and set multiple values on the attribute. The following example shows how
you can get the value of the metadata (the value of the name/value pair) from a refer-
enced element using the data method. Note that when using jQuery’s data method, the
“data-” part is omitted and just the remainder of the attribute name is used.
JavaScript
// Example: get the value of a data-list-url attribute
var myUrl = myVehicleElement.data(‘list-url’);
Because data- attributes are ideal for selecting elements, and for getting or setting
data associated with those elements in the DOM, you should use them wherever possible.
If your designer changes the layout and style information in the HTML, your JavaScript
won’t break. In addition, data- attributes allow the server to easily provide the client with
useful data without the client having to parse UI-specific HTML. Use data- attributes
wherever it is appropriate to specify metadata in the server-generated HTML or with
JavaScript on the client.
Keep in mind that the HTML represents the logical structure of the UI, not the visible
layout and style. The use of data- attributes provides you with a mechanism for annotat-
ing the structure and adding metadata without using style class names or element identi-
fiers.
Modifying Existing Elements
After you select your target element or set of elements, you can modify them as required.
The following sections provide some examples of scenarios and solutions for modifying
existing elements within the HTML structure of the page.
Showing and Hiding Content
When the user first navigates to your application, the server will return the HTML for the
page. This HTML includes the locations (URLs) for the resources such as images, scripts,
and HTML fragments that the browser will download as secondary requests in order to
create the complete page. However, there will be a noticeable delay as the content and
scripts are downloaded, the HTML and CSS is parsed, and any startup scripts run. While
usually short, this delay can affect the user experience, especially if there are a large
number of secondary requests for scripts, images, or other assets, or if the user is on a
slow Internet connection.
One solution is to include in the HTML sent from the server a progress indicator that
shows that the application is loading. Then, once the rest of the content is available,
the application can use JavaScript to change the UI by hiding the progress indicator and](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-146-320.jpg)
![115manipulating client-side html
newUrlBase = mstats.getRelativeEndpointUrl(url);
state.layout = 'dashboard';
this.element.find('#dashboard-link')
.attr('href', $.param.fragment(newUrlBase, state));
state.layout = 'charts';
this.element.find('#charts-link')
.attr('href', $.param.fragment(newUrlBase, state));
},
The first part of this code uses the jQuery Back Button and Query (BBQ) plug-in to
create a state object and get the actual base URL of the page. This value is discovered on
the server and can be obtained from the getRelativeEndpointUrl method of the global
mstats object defined in the JavaScript of the page. Chapter 9, “Navigation,” discusses in
more detail the BBQ plug-in, the use of a state object, and how this section of code
works.
After the base URL has been established, the code changes the name/value pair
named layout within the state object instance so that it specifies the correct layout style
(dashboard or charts) for each hyperlink. It then uses the find method to select the ap-
propriate hyperlink element based on the value of its id attribute, and sets the value of
the href parameter to the correct URL. This URL is a combination of the base URL of the
application and the relevant layout property held in the state object instance.
Mileage Stats uses data- attributes both to locate elements and to store data values
in the DOM. As another example, the _bindNavigation method of the fill ups widget
(part of which is shown below) relies on the presence of a data-action attribute to locate
navigation buttons. The method also uses the data-action and data-fillup-id attributes
to determine which action to take and which fill up to target.
JavaScript
// Contained in mstats.fillups.js
_bindNavigation: function () {
var that = this;
this.element.delegate('[data-action]', 'click.' + this.name, function (event) {
if ($(this).data('action') === 'select-fillup') {
that._setOption('selectedFillupId', $(this).data('fillup-id'));
event.preventDefault();
}
});
},
The above sample uses a specific type of jQuery selector, named the “Has Attribute”
selector, which simplifies the selection of elements having a specific attribute. For more
information on this type of selector, see “jQuery Selectors” in the “Further Reading”
section of this chapter.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-148-320.jpg)
![126 chapter eight
JavaScript
// Contained in mstats.utils.js
function buildFunction(widget, options) {
var context = options[widget],
fn;
if(!context) {
mstats.log('Attempted to create a helper for ' +
widget + ' but the widget was not found in the options.');
return;
}
fn = context[widget];
return function() {
var result = fn.apply(context, arguments);
return result;
};
}
mstats.setupWidgetInvocationMethods = function(host, options, widgetNames) {
var i,
widgetName;
for (i = widgetNames.length - 1; i >= 0; i -= 1) {
widgetName = widgetNames[i];
host["_" + widgetName] = buildFunction(widgetName, options);
}
};
The setupWidgetInvocationMethods function is called when the layout manager is
first created. This function call dynamically creates new methods called _charts, _header,
_infoPane, _summaryPane, and _vehicleList that will make invoking methods on those
widgets much easier, as you can see in the _goToChartsLayout method above.
JavaScript
// Contained in mstats.layout-manager.js
_create: function() {
...
// add on helper methods for invoking public methods on widgets
mstats.setupWidgetInvocationMethods(this, this.options,
['charts', 'header', 'infoPane', 'summaryPane', 'vehicleList']);
...
},
In addition to the layout manager, the above helper method is also used in the _create
method of the info pane, summary, and vehicle details widgets.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-159-320.jpg)
![130 chapter eight
The pubsub Object
The Mileage Stats’ pubsub interface provides publish, subscribe, and unsubscribe meth-
ods. Each method requires an event name. These events are defined in mstats.events.js as
objects that behave like string constants. The following code shows the interface of the
pubsub object.
JavaScript
// Contained in mstats.pubsub.js
mstats.pubsub = (function () {
var queue = [],
that = {};
that.publish = function (eventName, data) { ... };
that.subscribe = function (eventName, callback, context) { ... };
that.unsubscribe = function (eventName, callback, context) { ... };
return that;
}();
The mechanism for creating the pubsub object uses an immediate function which
executes as soon as its definition is parsed. As a result, the pubsub object is available
simply by adding the mstats.pubsub.js file to the page.
The subscribe method stores event subscriptions, which are comprised of a callback
in the form of a function and a context in the form of an object. More than one subscrip-
tion is possible for a single event name. Here is the code.
JavaScript
// Contained in mstats.pubsub.js
/**
* @param {string} eventName The name of the event to publish
* Uses a slash notation for consistency
* @param {function} callback The function to be called when the
* event is published.
* @param {object} context The context to execute the callback
*/
that.subscribe = function (eventName, callback, context) {
if (!queue[eventName]) {
queue[eventName] = [];
}
queue[eventName].push({
callback: callback,
context: context
});
};
The subscribe method modifies the queue variable. It adds a new array element for
the name that is passed as the eventName argument if that element does not already
exist. Then, it adds a new object to that array with the callback and context fields. These
fields store the function to be invoked when the event is published, and the context that
function should execute within.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-163-320.jpg)
![131communication
JavaScript allows you to use the context of one object to call an instance method of
a different object. This is what happens with the context value that is provided to the
subscribe method. The callback method will be invoked with the given context.
The publish method invokes the registered callback for a given eventName. The
publish method executes all callbacks that are associated with eventName by using the
context that was provided in the subscription.
JavaScript
// Contained in mstats.pubsub.js
/**
* @param {string} eventName The name of the event to publish
* Uses a slash notation for consistency
* @param {object} data Any data to be passed to the event
* handler. Custom to the event.
*/
that.publish = function (eventName, data) {
var context, intervalId, idx = 0;
if (queue[eventName]) {
intervalId = setInterval(function () {
if (queue[eventName][idx]) {
context = queue[eventName][idx].context || this;
queue[eventName][idx].callback.call(context, data);
idx += 1;
} else {
clearInterval(intervalId);
}
}, 0);
}
};
The code successively invokes each function that is stored in the queue array. It uses
the setInterval function with a timeout of 0 milliseconds to execute the callbacks
asynchronously. This allows each subscriber callback to be invoked before the previous
callback finishes. This also means callbacks can be invoked before other callbacks have
finished. A consequence of asynchronicity is that you cannot predict the order in which
callbacks are invoked or finish.
In Mileage Stats, only the unit tests take advantage of the unsubscribe method.
However, other applications may need to allow the dynamic subscription and unsubscrip-
tion of events.
An Example of Subscribing and Publishing
When a user fulfills a reminder, several areas of the UI need to refresh their own lists of
reminders. The application uses the mstats.events.vehicle.reminders.fulfilled event
name (this is the topic) to communicate the fact that a reminder was fulfilled. This variable
is initialized with the value “reminders/fulfilled” in the mstats.events.js file.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-164-320.jpg)
![140 chapter nine
CSHTML
<!-- Contained in _TemplateVehicleList.cshtml -->
<a href="@Url.Action("List", "Reminder")/${VehicleId}"
data-action="vehicle-reminders-selected"
alt="Reminders" title="Reminders">
<div class="hover"></div>
<div class="active"></div>
<img alt="Reminders"
src="@Url.Content("~/Content/command-reminders.png")" />
<div class="glass"></div>
</a>
This creates a URL for the hyperlink in the format http://mileagestats.com/
reminder/list/4. Notice that the hyperlink contains a data-action attribute, in this case
with the “vehicle-reminders-selected” value.
Note: Attributes that begin with the prefix data- are treated as metadata. The part
of the name after the hyphen can be used for querying the value of the attribute using
jQuery’s data method.
The client-side code in Mileage Stats includes the _adjustNavigation function, part
of which is listed below, to modify the URLs in hyperlinks. The code takes advantage of
jQuery’s support for HTML5 data- attributes to retrieve the value of the data-action
attribute and store it in a variable named action. Next, it obtains the identifier of the
vehicle from the widget’s options collection, then uses the BBQ getState method to read
the fragment identifier (if one exists) and store it in an object variable named state. If
there is no fragment identifier (which will be the case when the application starts) it
stores an empty object literal instead.
JavaScript
// Contained in mstats.vehicle.js
_adjustNavigation: function () {
var that = this;
this.element.find('[data-action]').each(function () {
var $this = $(this),
action = $this.data('action'),
vehicleId = that.options.id,
state = $.bbq.getState() || {},
newUrlBase = mstats.getBaseUrl();
state.vid = vehicleId;
switch (action) {
case 'vehicle-details-selected':
state.layout = 'details';
break;
case 'vehicle-fillups-selected':](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-173-320.jpg)
![142 chapter nine
identifier of the selected vehicle. The following listing shows a section of the server-side
code that creates the HTML for the hyperlink in the Fill ups view tab.
CSHTML
<!-- Contained in _TemplateFillups.cshtml -->
<a class="trigger"
href="@Url.Action("List", "Fillup")/${VehicleId}"
data-info-nav="fillups"></a>
This creates a URL for the hyperlink in the format http://mileagestats.com/fillup/
list/1. Notice that the hyperlink contains a data-info-nav attribute, in this case with the
“fillups” value.
The info pane widget that implements this section of the UI is responsible for han-
dling the click event of these accordion links and initiating the required transition. The
code in the _bindNavigation method (shown below) creates a delegate on the click
event, which uses the widget’s name as the namespace, for all elements that include a
data-info-nav attribute.
Note: Using the widget’s name as the namespace and appending it to the event allows
the delegation to automatically be cleaned up when the widget is destroyed.
Inside the delegate, the code uses the jQuery data method to read the value of the
data-info-nav attribute into a variable named action, and then passes this value to
another method named _setHashLayout. It also prevents the default behavior of the
hyperlink from initiating navigation.
JavaScript
// Contained in mstats.info-pane.js
_bindNavigation: function () {
var that = this; // closure for the event handler below
this.element.delegate('[data-info-nav]', 'click.infoPane', function (event) {
var action = $(this).data('info-nav');
that._setHashLayout(action);
event.preventDefault();
});
},
The _setHashLayout method, also defined within the info pane widget, is responsible
for setting the layout according to the user’s selection. It uses the BBQ getState method
to retrieve the existing navigation details, which are stored as name/value pairs in the
fragment identifier of the current URL, as an object named state. After setting the layout
property for the new layout, it uses the pushState method to modify the fragment and
update the browser’s address bar. The value 2, passed as the second argument, tells the
pushState method to completely replace any existing fragment identifier values with the
contents of the first argument.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-175-320.jpg)
![150 chapter nine
this.element.find(':mstats-tile').each(function () {
var $this = $(this);
vid = $this.find('.vehicle').vehicle('option', 'id');
animationInfoArray = [{
position: { top: runningTop },
duration: animationLength
}, {
position: { left: 0 },
duration: animationLength
}];
$this.tile('moveTo', animationInfoArray, function () {
that.element.find(':mstats-tile').tile('endAnimation');
});
// calculate the runningTop for next time around
if (vid === selectedVehicle) {
runningTop += 321;
} else {
runningTop += 206;
}
});
this._narrowToSingleColumn();
}
this._scrollToSelectedVehicle();
if (state && state.layout) {
this.options.layout = state.layout;
}
this.options.isCollapsed = true;
},
Not to be confused with the vehicle widget, the vehicle list widget also has an is
Collapsed option that indicates if it is currently displayed as a single column (collapsed)
or as two columns. If it is not collapsed, it immediately calls the beginAnimation method
on all tile widgets, as you can see in the sequence diagram above.
Note: The tile widget was created to reduce the complexity of the tile animations.
Initially, the vehicle list and vehicle widgets contained all of the animation logic.
Creating the tile widget freed up the vehicle widget to focus only on vehicle concepts.
In contrast, the vehicle list widget still contains a significant amount of logic specific
to the animations. A future refactoring might employ an additional widget that
specializes in animating generic tiles between a one-column and two-column layout
(or N-columns to N-columns).](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-183-320.jpg)
![160 chapter ten
that.currentStatus = null;
}, status.duration || this.options.duration);
},
_getPriority: function (status) {
return priorities[status.type];
},
User Session Timeout Notification
Mileage Stats uses forms authentication, with a session time-out threshold of 20 minutes.
If the session has timed out, the request (Ajax or non-Ajax) is redirected to the page
specified by the forms authentication loginUrl in the web.config file.
In traditional websites that perform page reloads between pages, it’s common to re-
direct the user to a sign-in page when their session times out. Applications like Mileage
Stats that make heavy use of Ajax calls to retrieve data perform few full-page reloads.
Consequently, if a session timeout occurs, it’s usually during an Ajax request. Let’s exam-
ine what happens when an Ajax request is redirected because of an authentication session
timeout:
1. Ajax JavaScript Object Notation (JSON) data request initiated.
2. Forms authentication runtime detects an expired session and redirects the
request to the sign-in page.
3. A parsing error occurs because the Ajax handler is expecting JSON data and not
HTML. The HTML is the content of the sign-in page to which the request was
redirected.
4. An Ajax error callback is invoked.
5. A global Ajax error callback is invoked.
Errors that can occur anywhere in the application can often be handled in a central-
ized location so that individual objects don’t need to repeat the same error handling code.
Mileage Stats implements the global ajaxError method handler shown below to catch
errors occurring during an Ajax request. In Mileage Stats, the primary purpose of this
method is to identify whether the initiating Ajax request caused a session time-out error
and, if so, to redirect the user to the sign-in page.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-193-320.jpg)
![169application notifications
The requeryJumpList function, shown below, is called when the pinnedSite object
is initialized, and also by the layout manager widget when a reminder is fulfilled. It’s the
layout manager’s call that initializes the dynamic updating of the jump list and notification
icon.
Note: Only the essential lines of code that demonstrate the loading of the jump list
and updating of the notification icon are listed below.
All of the following msSite functions are provided by Internet Explorer 9. After using
feature detection to determine if the site is pinned, the jump list and overlay icon are
cleared, and a new jump list is created.
If the Ajax request is successful and the data.Reminders array has data, a URL will be
constructed for each data item and added to the jump list. Next, the appropriate overlay
icon is set. Finally, msSiteModeShowJumpList is called to update the jump list.
JavaScript
// Contained in mstats.pinnedsite.js
requeryJumpList: function () {
var getRelativeUrl = mstats.getRelativeEndpointUrl;
try {
if (this.isPinned()) {
sendRequest({
url: '/reminder/overduelist/',
contentType: 'application/json',
cache: false,
success: function (data) {
try {
var g_ext = window.external,
...
g_ext.msSiteModeClearJumpList();
g_ext.msSiteModeCreateJumpList("Reminders");
g_ext.msSiteModeClearIconOverlay();
if (data.Reminders) {
for (i = 0; i < numReminders; i += 1) {
reminder = data.Reminders[i];
reminderUrl = getRelativeUrl('/reminder/details/' +
reminder.Reminder.ReminderId.toString());
g_ext.msSiteModeAddJumpListItem(reminder.FullTitle, reminderUrl,
faviconUrl, "self");
}](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-202-320.jpg)
![184 chapter eleven
should not contain much conditional logic; methods that handle POST should validate the
incoming data, perform the update when the data is valid, and conditionally return a view
depending on the success of the update. The following examples from Mileage Stats show
two versions of the FillupController’s Add method (first the GET version, and then the
POST version). In these examples, the generic method Using<T> is a helper method used
to delegate logic to the classes in the services layer.
C#
// Contained in FillupController.cs
public ActionResult Add(int vehicleId)
{
var vehicles = Using<GetVehicleListForUser>()
.Execute(CurrentUserId);
var vehicle = vehicles.First(v => v.VehicleId == vehicleId);
var newFillupEntry = new FillupEntryFormModel
{
Odometer = (vehicle.Odometer.HasValue)
? vehicle.Odometer.Value : 0
};
var fillups = Using<GetFillupsForVehicle>()
.Execute(vehicleId)
.OrderByDescending(f => f.Date);
var viewModel = new FillupAddViewModel
{
VehicleList = new VehicleListViewModel(vehicles, vehicleId)
{IsCollapsed = true},
FillupEntry = newFillupEntry,
Fillups = new SelectedItemList<Model.FillupEntry>(fillups),
};
ViewBag.IsFirstFillup = (!fillups.Any());
return View(viewModel);
}
C#
// Contained in FillupController.cs
[HttpPost]
[ValidateInput(false)]](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-217-320.jpg)
![185server-side implementation
[ValidateAntiForgeryToken]
public ActionResult Add(int vehicleId, FillupEntryFormModel model)
{
var vehicles = Using<GetVehicleListForUser>()
.Execute(CurrentUserId );
if (ModelState.IsValid)
{
var errors = Using<CanAddFillup>()
.Execute(CurrentUserId, vehicleId, model);
ModelState.AddModelErrors(errors, "AddFillup");
if (ModelState.IsValid)
{
Using<AddFillupToVehicle>()
.Execute(CurrentUserId, vehicleId, model);
TempData["LastActionMessage"] = Resources
.VehicleController_AddFillupSuccessMessage;
return RedirectToAction("List", "Fillup",
new { vehicleId = vehicleId });
}
}
var fillups = Using<GetFillupsForVehicle>()
.Execute(vehicleId)
.OrderByDescending(f => f.Date);
var viewModel = new FillupAddViewModel
{
VehicleList = new VehicleListViewModel(vehicles, vehicleId)
{ IsCollapsed = true },
FillupEntry = model,
Fillups = new SelectedItemList<Model.FillupEntry>(fillups),
};
ViewBag.IsFirstFillup = (!fillups.Any());
return View(viewModel);
}](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-218-320.jpg)
![193server-side implementation
The XML format is useful when the client receives data based on a pre-defined
schema. XML is also used when working in open-standards formats such as RSS, Atom,
and oData. Web clients can use the known schema structure to process the XML into
HTML.
Binary formats are generally employed for media. Images are the most common ex-
ample; the server returns an img element with a src attribute, the browser makes a sec-
ondary request to the server and then renders the binary result as an image.
Note: Not all browsers send the same data to the server when requesting images and
other resources. Some browsers will send authentication headers and cookies while
others will not. If you have secondary requests that must be authenticated, you need to
verify that those requests work on the browsers you intend to support. In addition, you
should perform testing in both the ASP.NET development server and in a Microsoft
Internet Information Services (IIS)-deployed web application.
To support a particular format in ASP.NET MVC, return a JsonResult, ContentResult,
or FileResult instead of a ViewResult from your action methods.
The following example from Mileage Stats returns a JsonResult. The view model is
created and then the Controller.Json method is called to convert the object into JSON
for the response.
C#
// Contained in VehicleController.cs
[Authorize]
[HttpPost]
public JsonResult JsonDetails(int id)
{
VehicleModel vehicle = Using<GetVehicleById>()
.Execute(CurrentUserId, vehicleId: id);
// we are limiting this to 3 reminders
// after we retrieve the full set from the server
var overdue = Using<GetOverdueRemindersForVehicle>()
.Execute(id, DateTime.UtcNow, vehicle.Odometer ?? 0)
.Take(3);
var vm = ToJsonVehicleViewModel(vehicle, overdue);
return Json(vm);
}
Note: Controller actions that return a JsonResult are easy to unit test because you
can inspect the JsonResult.Data property directly. However, debugging a serialization
issue with a JsonResult is harder because it requires you to inspect the returned data
from the web service in the web client.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-226-320.jpg)
![195server-side implementation
Data Validation
Interactive web applications need to let users know when they have provided data that
is invalid. Data validation checks need to happen in three places: on the client in the
context of what the user is trying to accomplish, on the server to protect from untrust-
worthy callers, and in the database to ensure data integrity. Having data validation occur
at multiple levels in the stack makes creating common and consistent validation logic
important to the user experience. This section covers data validation techniques you can
use to validate your data on both the server and the client.
Data Annotation Attributes
Applying data annotation attributes to your model allows ASP.NET MVC and the ADO.
NET Entity Framework to provide data validation at the server level. As mentioned in the
“Creating a Data Model” section, the ADO.NET Entity Framework also inspects the data
annotation attributes on your entity classes in order to create the database schema. You
can find the standard data annotation attributes in the System.ComponentModel.Data
Annotations namespace. In this section, data annotation attributes that provide valida-
tion are referred to as validation attributes.
The following example shows the validation attributes applied to the VehicleForm
Model class in the MileageStats.Domain project. The attributes applied to the Vehicle
FormModel.Name property validate that the name is not null, is not an empty string, is
no more than 20 characters, and does not contain script injection characters.
C#
// Contained in VehicleModel.cs
[StringLength(20,
ErrorMessageResourceName = "VehicleNameStringLengthValidationError",
ErrorMessageResourceType = typeof(Resources))]
[TextLineInputValidator]
[Required(AllowEmptyStrings = false,
ErrorMessageResourceName = "VehicleNameRequired",
ErrorMessageResourceType = typeof(Resources))]
public string Name
{
get { return this.Vehicle.Name; }
}
Validation attributes also support localization. By using the resource names, the error
messages are loaded from a RESX file.
Validating Data in MVC
The ASP.NET MVC default model binder uses the Validator and ValidationContext
classes when parsing incoming data into an instance of your model class. These two
classes work together to validate the data based on the validation attributes you have
applied.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-228-320.jpg)
![196 chapter eleven
If any of the validation fails, AddModelError is called on the ModelState class.
ModelState.IsValid returns false when ModelState has one or more errors. Because all
of this happens before your action is called, validating data in your controller actions is
easy. The following example shows the FillupController using ModelState.IsValid
before making the update.
C#
// Contained in FillupController.cs
[HttpPost]
[ValidateInput(false)]
[ValidateAntiForgeryToken]
public ActionResult Add(int vehicleId, FillupEntryFormModel model)
{
var vehicles = Using<GetVehicleListForUser>()
.Execute(CurrentUserId );
if (ModelState.IsValid)
{
var errors = Using<CanAddFillup>()
.Execute(CurrentUserId, vehicleId, model);
ModelState.AddModelErrors(errors, "AddFillup");
if (ModelState.IsValid)
{
Using<AddFillupToVehicle>()
.Execute(CurrentUserId, vehicleId, model);
TempData["LastActionMessage"] = Resources
.VehicleController_AddFillupSuccessMessage;
return RedirectToAction("List", "Fillup",
new { vehicleId = vehicleId });
}
}
...
var viewModel = new FillupAddViewModel
{
...
};
return View(viewModel);
}
In the previous example, invoking the handler CanAddFillup returns a Validation
Result collection. These validation results are returned from the business services layer.
The AddModelErrors extension method iterates over the ValidationResult collection
and calls ModelState.AddModelError for each. This level of indirection keeps the
business services layer from depending on ASP.NET MVC.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-229-320.jpg)
![197server-side implementation
Note: The previous example turns off the ASP.NET-provided input validation of
cookies, form data, and querystring properties by using the [ValidateInput(false)]
attribute. This was done to allow certain characters that the default input validation
does not allow. However, to prevent the user from using these characters to introduce
malicious data into the system, the TextLineInputValidator data validation attribute
is applied to the text properties of the FillupEntryFormModel class.
It is recommended that you be very careful when disabling the default input
validation and ensure that there are mitigations in place to stop malicious input.
Creating Custom Validation Attributes
When the standard validation attributes don’t provide what you need, you can write your
own. All the standard validation attributes derive from the ValidationAttribute class that
contains the abstract IsValid method.
The following example validates a postal code. The implementation is much simpler
than would be used in many applications, but it shows how a model object can validate
one field based on the value of a different field.
C#
// Contained in PostalCodeValidatorAttribute.cs
protected override ValidationResult IsValid(object value, ValidationContext context)
{
var userToValidate = context.ObjectInstance as User;
var memberNames = new List<string>() { context.MemberName };
if (userToValidate != null)
{
if (string.IsNullOrEmpty(userToValidate.Country) &&
string.IsNullOrEmpty(userToValidate.PostalCode))
{
return ValidationResult.Success;
}
if (string.IsNullOrEmpty(userToValidate.PostalCode))
{
return ValidationResult.Success;
}
if (userToValidate.Country == Resources.UnitedStatesDisplayString)
{
if (USPostalCodeRegex.IsMatch(userToValidate.PostalCode))
{
return ValidationResult.Success;
}
return new ValidationResult(Resources.USPostalCodeValidationErrorMessage,
memberNames);
}
else](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-230-320.jpg)
![200 chapter eleven
Note: In the previous example, you can see that the validation type and the names
of the validation parameters are lowercase. These values are converted into HTML
attributes and used by the client-side JavaScript code. Due to the limitations of this
transformation, these values must contain only numbers, lowercase letters, and dashes.
When MVC HTML helper extension methods such as TextBoxFor and EditorFor are
called, MVC inspects the property definition for validation attributes. When a validation
attribute implements IClientValidatable, MVC uses the client validation rules to include
data-val attributes. The following HTML fragment shows the data-val attributes present
on the postal code field in the registration form.
HTML
<!-- sent from server using Views/Shared/_ProfileForm.cshtml -->
<div class="editor-field">
<input data-val="true"
data-val-length="Postal code must be less than 10 characters."
data-val-length-max="10"
data-val-postalcode="Only alpha-numeric characters and [.,_-&#39;]
are allowed."
data-val-postalcode-internationalerrormessage=
"Postal codes must be alphanumeric and ten characters or less."
data-val-postalcode-internationalpattern="^[dw]{0,10}$"
data-val-postalcode-unitedstateserrormessage=
"United States postal codes must be five digit numbers."
data-val-postalcode-unitedstatespattern="^[d]{5}$"
data-val-textlineinput=
"Only alpha-numeric characters and [.,_-&#39;] are allowed."
data-val-textlineinput-pattern="^(?!.*--)[A-Za-z0-9.,'_ -]*$"
id="PostalCode" maxlength="10" name="PostalCode" size="10" type="text" value=""
/>
<span class="field-validation-valid" data-valmsg-for="PostalCode"
data-valmsg-replace="true">
</span>
</div>
The JavaScript that participates in MVC validation on the client side can be found in
jquery.validate.js and jquery.validate.unobtrusive.js. These files include standard validation
attributes, methods to register validation routines, and unobtrusive validation adapters.
The following example shows the registration of the postalcode validation routine.
Notice how it uses the params object to access the data-val attributes.
JavaScript
// Contained in mstats.validation.js
$.validator.addMethod('postalcode', function (value, element, params) {
if (!value) {
return true; // not testing 'is required' here!](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-233-320.jpg)
![201server-side implementation
}
try {
var country = $('#Country').val(),
postalCode = $('#PostalCode').val(),
usMatch = postalCode.match(params.unitedStatesPattern),
internationalMatch = postalCode.match(params.internationalPattern),
message = '',
match;
if (country.toLowerCase() === 'united states') {
message = params.unitedStatesErrorMessage;
match = usMatch;
} else {
message = params.internationalErrorMessage;
match = internationalMatch;
}
$.extend($.validator.messages, {
postalcode: message
});
return (match && (match.index === 0) &&
(match[0].length === postalCode.length));
} catch (e) {
return false;
}
});
IClientValidatable helps you to share validation information, but you still have two
copies of your validation logic to maintain. You may choose remote validators (that is, by
implementing validation actions in your controller) and call them using Ajax from the
client. However, the round trip to the server will not be as responsive as validating di-
rectly on the client.
Note: It is important to remember that client-side validation only helps improve the
user experience and is not a substitute for proper validation and security on the server.
Hackers won’t use your web client JavaScript or even the browser when maliciously
posting data to the web application on the server, so you must ensure that any client-
side validation is repeated on the server before any data changes occur.
Unit Testing Validation Logic
Because validation occurs at multiple levels of the stack, you may end up with duplicate
validation attributes and validation logic to keep in sync. While proper factoring of your
application logic, your models, and data validation information can help, you should
always unit test each layer in isolation to make sure the validation works as expected.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-234-320.jpg)
![202 chapter eleven
While you don’t need to unit test the standard validation attributes, you should test
that the validation attributes are properly applied to your model and validate as expected
(just as if you had written code inside the setter of your model property). The following
example shows a unit test verifying that the Title of the Reminder is required.
C#
// Contained in ReminderFixture.cs
[Fact]
public void WhenTitleSetToNull_ThenValidationFails()
{
Reminder target = new Reminder();
target.Title = null;
var validationContext = new ValidationContext(target, null, null);
var validationResults = new List<ValidationResult>();
bool actual = Validator.TryValidateObject(target, validationContext,
validationResults, true);
Assert.False(actual);
Assert.Equal(1, validationResults.Count);
Assert.Equal(1, validationResults[0].MemberNames.Count());
Assert.Equal("Title", validationResults[0].MemberNames.First());
}
Note: The true parameter at the end of the TryValidateObject call is important
because it causes the validation of all properties on the target. This means your unit
test must ensure all other properties are set to valid values when you verify that one
invalid property fails validation.
Other Considerations
This section describes some other areas of server architecture you may want to consider.
Dependency Injection
Mileage Stats uses Unity for dependency injection. The unity.config file in the web ap-
plication maps interfaces to concrete classes. It also determines the lifetime for each
mapping. For example, Unity ensures that the VehicleController constructor receives
implementations of the IUserServices, ICountryServices, IServiceLocator, and IChart
DataService interfaces.
In an effort to manage dependencies and improve testability in the MVC pattern, ASP.
NET MVC also provides a dependency resolver. This gives ASP.NET MVC applications a
designated place to resolve dependencies for framework-created objects such as control-
lers and action filters. In the following example, Mileage Stats registers Unity as the MVC
dependency resolver as part of initializing the dependency injection container for the
application.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-235-320.jpg)
![204 chapter eleven
should return the same view as the GET action populated with the incoming data. When
a POST action succeeds, it can redirect.
In the following example, if a ReminderFormModel doesn’t pass data validation, the
Add view result is returned populated with the reminder data that was passed into the
action method.
C#
//Contained in ReminderController.cs
[HttpPost]
public ActionResult Add(int vehicleId, ReminderFormModel reminder)
{
if ((reminder != null) && ModelState.IsValid)
{
var errors = Using<CanAddReminder>()
.Execute(CurrentUserId, reminder);
ModelState.AddModelErrors(errors, "Add");
if (ModelState.IsValid)
{
Using<AddReminderToVehicle>()
.Execute(CurrentUserId, vehicleId, reminder);
return RedirectToAction("Details", "Reminder",
new { id = reminder.ReminderId });
}
}
var vehicles = Using<GetVehicleListForUser>()
.Execute(CurrentUserId);
var vehicle = vehicles.First(v => v.VehicleId == vehicleId);
var reminders = Using<GetUnfulfilledRemindersForVehicle>()
.Execute(CurrentUserId, vehicleId, vehicle.Odometer ?? 0)
.Select(r => new ReminderSummaryModel(r, r.IsOverdue ?? false));
var viewModel = new ReminderAddViewModel
{
VehicleList = new VehicleListViewModel(vehicles, vehicleId)
{ IsCollapsed = true },
Reminder = reminder,
Reminders = new SelectedItemList<ReminderSummaryModel>(reminders),
};
return View(viewModel);
}](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-237-320.jpg)
![213security
Both the mock authenticator and the OpenID relying party class implement the
IOpenIdRelyingParty interface, which acts as a wrapper around the DotNetOpenAuth
interfaces to expose only what is required to interact with the authentication provider
and to process the results. Implementing IOpenIdRelyingParty enables you to configure
a different relying party implementation if your application requirements change.
AuthController
AuthController is an MVC controller in Mileage Stats that is responsible for handling the
user redirect for authentication and converting the response from a successful authenti-
cation attempt into an ASP.NET forms authentication ticket. The AuthController uses
the relying party implementation specified in the unity.config file. AuthController’s Sign
InWithProvider method is invoked to redirect the user to the authentication provider’s
sign-in page. The following code snippet shows the SignInWithProvider method.
C#
// Contained in AuthController.cs
public ActionResult SignInWithProvider(string providerUrl)
{
if (string.IsNullOrEmpty(providerUrl))
{
return this.RedirectToAction("SignIn");
}
var fetch = new FetchRequest();
var returnUrl = this.Url.Action("SignInResponse", "Auth", null,
this.Request.Url.Scheme);
try
{
return this.relyingParty.RedirectToProvider(providerUrl, returnUrl, fetch);
}
catch (Exception)
{
this.TempData["Message"] =
Resources.AuthController_SignIn_UnableToAuthenticateWithProvider;
return this.RedirectToAction("SignIn");
}
}
The AuthController’s SignInResponse method is invoked to process the response
from the user’s authentication attempt with the authentication provider. SignInResponse
calls the GetResponse method on the relying party class and processes the result. If the
result is a successful authentication, AuthController creates an ASP.NET forms authen-
tication ticket and attaches it to the response. If anything other than a successful authen-
tication result is returned from the authentication provider, the user is redirected back to
the authentication provider’s sign-in page.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-246-320.jpg)
![214 chapter twelve
C#
// Contained in AuthController.cs
public ActionResult SignInResponse(string returnUrl)
{
var response = this.relyingParty.GetResponse();
switch (response.Status)
{
case AuthenticationStatus.Authenticated:
var user = this.userServices.GetOrCreateUser(response.ClaimedIdentifier);
this.formsAuthentication.SetAuthCookie(this.HttpContext,
UserAuthenticationTicketBuilder.CreateAuthenticationTicket(user));
return this.RedirectToRoute("Dashboard");
case AuthenticationStatus.Canceled:
this.TempData["Message"] = "Cancelled Authentication";
return this.RedirectToAction("SignIn");
case AuthenticationStatus.Failed:
this.TempData["Message"] = response.Exception.Message;
return this.RedirectToAction("SignIn");
default:
this.TempData["Message"] =
Resources.AuthController_SignInResponse_Unable_to_authenticate;
return this.RedirectToAction("SignIn");
}
}
The following sequence diagram shows the calls made in AuthController.SignIn
Response to authenticate the user with the relying party and to attach the encrypted
forms ticket as a cookie if the authentication attempt was successful.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-247-320.jpg)
![216 chapter twelve
new Uri(returnUrl));
authenticationRequest.AddExtension(fetch);
return
new OutgoingRequestActionResult(authenticationRequest.RedirectingResponse);
}
Forms Authentication Sliding Expiration
Sliding expiration of the forms authentication ticket in Mileage Stats is accomplished by
resetting the expiration time of the ticket whenever the user makes a new request to the
server. Normally, the reset is enabled by setting the slidingExpiration attribute to true
on the forms security configuration in the web.config file; however, because the ticket
is being manually created and attached to the response in the AuthController, the
ticket needs to be refreshed manually. A custom handler for the HttpApplication.Post
AuthenticateRequest event implements the sliding expiration for the forms ticket.
C#
// Contained in Global.asax.cs
private void PostAuthenticateRequestHandler(object sender, EventArgs e)
{
HttpCookie authCookie =
this.Context.Request.Cookies[FormsAuthentication.FormsCookieName];
if (IsValidAuthCookie(authCookie))
{
var formsAuthentication =
ServiceLocator.Current.GetInstance<IFormsAuthentication>();
var ticket = formsAuthentication.Decrypt(authCookie.Value);
var mileageStatsIdentity = new MileageStatsIdentity(ticket);
this.Context.User = new GenericPrincipal(mileageStatsIdentity, null);
// Reset cookie for a sliding expiration.
formsAuthentication.SetAuthCookie(this.Context, ticket);
}
}
The advantage of using a forms ticket with a sliding expiration is that it does not force
the user to authenticate again if he or she maintains a reasonable level of activity in the
application. Otherwise, the user would be redirected to the authentication page after a
fixed amount of time had elapsed after the original authentication. While sliding expira-
tion greatly enhances the usability of the application, it is also a potential security risk
because the user’s authenticated session can be kept alive indefinitely by submitting re-
quests to the server before the sliding expiration time on the forms ticket has passed. This
risk can be mitigated by introducing an additional timeout value that does not slide, after
which the ticket will expire regardless of user activity. While this approach is effective, it](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-249-320.jpg)
![217security
was not implemented in Mileage Stats because it would add complexity to the forms
ticket handling that is beyond the scope of the application.
Input Validation
One of the primary ways of preventing an application from accepting malicious content
is validating any input before it is accepted by the application. While out-of-the-box ASP.
NET input validation does a good job of preventing script or HTML injection, it is not
always practical to use this mechanism in an ASP.NET MVC application. In Mileage Stats,
this mechanism is disabled to handle input validation directly within the MVC model
classes. If you don’t implement your own input validation and rely on the built-in ASP.NET
input validation instead, two things will happen. First, the input will not be validated until
after the controller has processed it and before the view has rendered. Next, you will get
the default “yellow screen of death” input validation page, which is not a pleasant user
experience. When the out-of-the box ASP.NET input validation is disabled, you also lose
HTML encoding on your input. To account for this, the @ operator in Razor syntax auto-
matically HTML-encodes output that is rendered in an MVC view.
Although input validation can be done on the client side to reduce round trips to the
server, it must also be performed on the server because client-side validation can be by-
passed by an attacker. One of the advantages of ASP.NET MVC is that it can be configured
to render client-side validation based on server-side validation attributes defined on MVC
model properties. This provides a single point in the application to define and maintain
data validation rules. For example, in Mileage Stats, the _ProfileForm view is configured
to use the MileageStats.ServicesModel.User class as its MVC model via the @model
directive. If you look at the DisplayName property on the class, you will see attributes
that limit the length of the value, that require a value for the property, and that use a
custom text input validator that filters input using a regular expression.
C#
// Contained in User.cs
[StringLength(15,
ErrorMessageResourceName = "UserDisplayNameStringLengthValidationError",
ErrorMessageResourceType = typeof(Resources))]
[TextLineInputValidator]
[Required(AllowEmptyStrings = false,
ErrorMessageResourceName = "UserDisplayNameRequired",
ErrorMessageResourceType = typeof(Resources))]
[Display(Name = "UserDisplayNameLabelText", ResourceType = typeof(Resources))]
public string DisplayName { get; set; }
Here is the custom input validator class that is behind the TextLineInputValidator
attribute.
C#
//Contained in TextLineValidatorAttribute.cs
public class TextLineInputValidatorAttribute : RegularExpressionAttribute,
IClientValidatable](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-250-320.jpg)
![218 chapter twelve
{
public TextLineInputValidatorAttribute()
: base(Resources.TextLineInputValidatorRegEx)
{
this.ErrorMessage = Resources.InvalidInputCharacter;
}
public IEnumerable<ModelClientValidationRule>
GetClientValidationRules(ModelMetadata metadata, ControllerContext context)
{
var rule = new ModelClientValidationRule()
{
ErrorMessage = Resources.InvalidInputCharacter,
ValidationType = "textlineinput"
};
rule.ValidationParameters.Add("pattern", Resources.TextLineInputValidatorRegEx);
return new List<ModelClientValidationRule>() { rule };
}
}
The TextLineInputValidatorAttribute class uses a set of regular expressions it loads
from the resources file. If any of the regular expression patterns are matched in the input,
it fails validation. The regular expression pattern used to validate text input is ^(?!.*--)
[A-Za-z0-9.,’_ -]*$. This limits the text assigned to the property to alphanumeric char-
acters and allows only a limited range of punctuation characters. Notice that the regular
expression pattern is used to validate legitimate characters rather than to exclude invalid
characters. By default, anything not explicitly defined in the regular expression is ex-
cluded from the application data. The list that limits input by only allowing what is known
to be valid is commonly referred to as a safe list. The advantage of safe lists is that anything
that falls outside of the valid set of characters is not allowed; you don’t have to worry
about accidentally omitting a character from the regular expression that shouldn’t be
allowed in the application input.
What’s nice about this validation mechanism is that the client-side validation for
these properties is generated for you based on the server-side validation defined in the
MVC model when the HTML for the MVC view is rendered. The following code shows
you what the rendered client-side validation looks like for the user display name form
field when you view the HTML source for the page.
HTML
<!-- Rendered HTML in the client browser -->
<input data-val="true"
data-val-length="Display name must be less than 15 characters."
data-val-length-max="15" data-val-required="Display name is required."
data-val-textlineinput="Only alpha-numeric characters and [.,_-&#39;]
are allowed."](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-251-320.jpg)
![219security
data-val-textlineinput-pattern="^(?!.*--)[A-Za-z0-9.,'_ -]*$"
id="DisplayName"
maxlength="15"
name="DisplayName"
type="text"
value="Sample User" />
Note: If you want to accept HTML tags or other types of input that would normally be
rejected by simple input validation, you can leverage the regular expression/input
validation mechanism to do it. However, you will need to create more sophisticated
patterns to allow the input you want to be accepted while still excluding the input that
you don’t want submitted to your application.
Anti-Forgery
As previously explained in the “Security Threats” section, CSRF has a high damage poten-
tial and should be prevented. ASP.NET MVC has a simple yet effective mechanism for
mitigating CSRF attacks. In your MVC view content, add an @Html.AntiForgeryToken
directive to the view, as shown here.
CSHTML
<!-- Contained in _ProfileForm.cshtml -->
@model MileageStats.ServicesModel.User
@Html.AntiForgeryToken()
When the view HTML is rendered to the client, MVC places a unique value for the
user in a hidden form field and in a session cookie. The form field in the rendered HTML
might look like this.
HTML
<!-- Rendered HTML in the client browser -->
<input name="__RequestVerificationToken"
type="hidden"
value="H4zpQFvPdmEdGCLsFgeByj0xg+BODBjIMvtSl5anoNaOfX4V69Pt1OvnjIbZuYrpgzWxWHIjbn
zFOLxP5SzVR4cM9XZeV78IPi8K4ewkM3k2oFkplrXL4uoAqy+aoSOg8s1m1qxrE7oeBBtvezEHCAs6nKE
h2jAwn3w0MwmhkcDQiJfJK7hGvN0jXA4d7S8x7rbLxp4Y8IJZS9wka2eOLg==" />
There’s another piece to implementing the anti-forgery tokens in ASP.NET MVC. You
must also put a ValidateAntiForgeryToken attribute on corresponding MVC controller
actions that you want to protect. The following code is an example of the attribute
decorating the edit action on the ProfileController class.
C#
// Contained in ProfileController.cs
[HttpPost]
[ValidateInput(false)]
[ValidateAntiForgeryToken]
public ActionResult Edit(User updatedUser)](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-252-320.jpg)
![220 chapter twelve
When ASP.NET MVC checks for a request forgery, it verifies that the request verifica-
tion token form field and cookies are present and that the values match each other. If
either the cookie or the form field values are missing, or the values don’t match, ASP.NET
MVC does not process the action and returns an authorization failure instead.
Note: MVC anti-forgery tokens do not work using HTTP GET requests because the
_RequestVerificationToken value from the client needs to be sent as a posted value.
Therefore, it is important to make sure that you only accept client requests that use
HTTP POST when you want to implement anti-forgery tokens. This shouldn’t be an
issue because you should already be using HTTP POST only for data updates, and using
HTTP GET exclusively for read-only operations.
If you want to implement more tightly controlled anti-forgery measures so that
the tokens will only validate to a particular set of MVC views and actions, you can pass
a salt as a parameter to the @Html.AntiForgeryToken directive in the MVC model.
A salt is a value combined with a cryptographic key to make the output of an encryp-
tion algorithm more random and less susceptible to attack.
Make sure that you are using the same salt values in the @Html.AntiForgeryToken
directive in the MVC model and in the parameter for the ValidateAntiForgeryToken
attribute on the MVC controller action; otherwise, the anti-forgery token will not validate
properly when the MVC action is called. For more information about using a salt with an
MVC anti-forgery token, see the reference to “Prevent Cross-Site Request Forgery
(CSRF) using ASP.NET MVC’s AntiForgeryToken() helper” at the end of the chapter.
JSON Hijacking Prevention
In some situations, it may be possible for an attacker to access data via a JSON request by
using an attack that closely resembles a CSRF attack. If an attacker can get a user to click
on a malicious link that makes a JSON request via HTTP GET and returns a JSON array, it
may dump the contents of the array in the response, making it accessible to the attacker.
The mitigation for JSON hijacking is fairly straightforward: either you can make sure to
never return JSON arrays in a response, or you can restrict JSON requests to respond only
to requests that use the HTTP POST action. To configure a JSON action on an MVC
controller to respond to requests only via HTTP POST, add the HttpPost attribute to it.
The following code shows the HttpPost attribute on the ProfileController’s JsonEdit
action.
C#
// Contained in ProfileController.cs
[HttpPost]
[ValidateInput(false)]
public ActionResult JsonEdit(User updatedUser)
This may not be an issue if you don’t care whether or not someone can gain unauthor-
ized access to data that is not sensitive; however, as a general practice you should protect
your JSON calls against hijacking. For more information, see the reference to JSON
Hijacking in the “Further Reading” section at the end of the chapter.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-253-320.jpg)
![232 chapter thirteen
'[ <a id="dashboard-link" href="/Dashboard">Dashboard</a>' +
'| <a id="charts-link" href="/Chart/List">Charts</a>' +
'| <a id="profile-link" href="/Profile/Edit">Profile</a>' +
'| <a id="login-link" href="/Auth/SignOut">Sign Out</a> ]' +
'</div>' +
'</div></div>' +
'</div>'
);
}
});
In QUnit, any DOM elements added for your test should be added to the element
with the id attribute containing qunit-fixture, as shown above. You should only add the
minimal amount of structure needed to appropriately simulate your test needs as this will
make the structural dependencies of the test clearer.
When testing jQuery UI widgets you will also often need to supply an alternate im-
plementation of dependent functions or objects. Because you don’t control the creation
of the jQuery UI widgets directly, you will typically do this as part of the options object
passed into the widget (See Chapter 3, “jQuery UI Widgets” for more details about the
use of an options object). For example, when testing the Mileage Stats vehicle details
widget, an alternative implementation for the event publisher is supplied as part of the
options.
JavaScript
// Contained in mstats.vehicle-details.tests.js
test('when loading data errors out, then triggers error status', function () {
expect(2);
var eventType = 'loadError',
details = $('#details-pane').vehicleDetails({
templateId: '#testTemplate',
sendRequest: function (options) { options.error({}); },
publish: function (event, status) {
if (status.type === eventType) {
ok(status, 'status object passed to publisher');
equal(status.type, eventType, 'status is of type : ' +
eventType);
}
}
});
// force a data refresh
details.vehicleDetails('option', 'selectedVehicleId', 1);
});](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-265-320.jpg)
![234 chapter thirteen
There is a unit test project for the Services, ServicesModel, SqlCe, and Web projects.
Some projects don’t have a corresponding unit tests project primarily because these proj-
ects contain only shared interfaces and data transfer classes that do not have significant
logic to test.
The team chose xUnit.net as the unit testing framework for the Mileage Stats project.
While you can accomplish unit testing with either Microsoft Test or xUnit.net, the team
chose xUnit.net because it was built specifically for developer unit testing. The remainder
of this section discusses unit testing using examples in xUnit.net, but you can readily im-
plement the same approaches with Microsoft Test or another unit testing framework,
although some of the exact mechanics may be different.
To create a new unit test project, add a C# or Microsoft Visual Basic® Class Library
project, and reference the xUnit.net assemblies. In the test project, there will be a class
to contain all the related tests for a particular component. For example, the MileageStats.
Web.Tests project contains a test class for each controller in the Web project. They
generally have the same name as the controller name with the term “Fixture” appended.
To write a test, create a method with the Fact attribute specified. The xUnit.net
framework searches for these attributes and executes these methods. Each test should
follow the arrange-act-assert pattern. In this pattern all the setup for the test is done first
(arrangement), then the action to be tested is executed (act), and then the validation is
done (assert).
C#
//Contained in ReminderFixture.cs
[Fact]
public void WhenReminderIsNotOverdue_ThenIsOverdueReturnsFalse()
{
// Arrange
var reminder = new ReminderFormModel()
{
Title = "future reminder",
DueDate = DateTime.UtcNow.AddDays(2),
DueDistance = 10000
};
reminder.UpdateLastVehicleOdometer(10);
// Act
bool isOverdue = reminder.IsOverdue;
// Assert
Assert.False(isOverdue);
}](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-267-320.jpg)
![238 chapter thirteen
{
...
store.Persist(value);
...
}
}
When you write a test for this class that depends on IStore, you can then provide an
alternative implementation.
C#
[Fact]
public void WhenSaving_ThenSendsValueToStore()
{
var mockStore = new StoreMock();
var classToTest = new ClassToTest(mockStore);
classToTest.Save("Test");
Assert.Equal(mockStore.ValueSaved, "Test");
}
private class StoreMock : IStore
{
public string ValueSaved { get; set; }
public void Persist(string item)
{
ValueSaved = item;
}
}
The StoreMock object captures the saved item to verify that ClassToTest sends the
correct value to the store. Instead of making these mocks by hand, as shown above, the
team relied on Moq—a mocking framework—when writing Mileage Stats tests. The test
shown above would look like this using Moq.
C#
[Fact]
public void WhenSaving_ThenSendsValueToStore()
{
var mockStore = new Mock<IStore>();
var classToTest = new ClassToTest(mockStore.Object);
classToTest.Save("Test");
mockStore.Verify(s => s.Persist("Test"));
}](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-271-320.jpg)
![240 chapter thirteen
In a unit test, it is very simple to provide these parameter values during testing of the
Add method. The example below demonstrates how you would supply the reminder and
vehicle ID directly in the test.
C#
// Contained in ReminderControllerFixture.cs
[Fact]
public void WhenAddReminderWithValidReminder_ThenReturnsToReminderDetailsView()
{
...
var result = (RedirectToRouteResult)controller.Add(vehicle.VehicleId, formModel)
;
Assert.NotNull(result);
Assert.Equal("Details", result.RouteValues["action"]);
Assert.Equal("Reminder", result.RouteValues["controller"]);
}
While many unit tests for controllers can use this approach, there are still cases in
which the controllers require access to the HttpContext. Providing alternate implementa-
tions of HttpContext is usually very difficult, making certain scenarios very hard to test.
But because the MVC base controller class, Controller, relies on the abstract Http
ContextBase class instead of HttpContext itself, it can be substituted much more easily.
Mileage Stats uses a mock HttpContextBase in many of its controller tests to ensure that
the HttpContextBase.User property is set appropriately.
To do this, Mileage Stats uses an MvcMockHelpers class that wraps the building
of a Moq object that substitutes HttpContext information. This controller context is
then set on the controller under test by calling the static SetFakeControllerContext
extension method in the MvcMockHelpers class. The RemindersControllerFixture sets
this when it builds a testable controller.
C#
// Contained in ReminderControllerFixture.cs
private ReminderController GetTestableReminderController()
{
var controller = new ReminderController(_mockUserServices.Object,
_serviceLocator.Object);
controller.SetFakeControllerContext();
controller.SetUserIdentity(new MileageStatsIdentity(_defaultUser.AuthorizationId,
_defaultUser.DisplayName,
_defaultUser.UserId));
return controller;
}](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-273-320.jpg)
![248 chapter fourteen
<div id="container">
<img src="projectsilk.png" />
<h1>Project Silk Overview</h1>
<p>
Project Silk provides guidance and example implementations
that describe and illustrate recommended practices for
building next generation web applications using web
technologies like <span data-tag>HTML5</span>,
<span data-tag>jQuery</span>, <span data-tag>CSS3</span>
and Internet Explorer 9. The guidance will be taught in
the context of real-world development scenarios rather
than focusing on <span data-tag>technology</span>
features.</p>
Attaching Widgets
Once created, the widget is attached to an HTML element and its options can be set.
JavaScript
// Contained in startup.js
(function ($) {
var infobox = $('body').infobox({
dataUrl: 'http://feeds.delicious.com/v2/json/popular/'
});
$('span[data-tag]').tagger({
activated: function (event, data) {
infobox.infobox('displayTagLinks', event, data.name);
},
deactivated: function () {
infobox.infobox('hideTagLinks');
}
});
} (jQuery));
The code above demonstrates how the infobox widget is attached to the body ele-
ment. The dataUrl option value will be used when performing popular keyword link
lookups.
The jQuery selector span[data-tag] returns a jQuery wrapped set that contains all
span tags with a data-tag attribute. A tagger widget will be attached to each of the span
tags in the returned collection. The tagger widget has activated and deactivated options
that are used as callbacks. These callbacks are used to handle events raised when the
mouse hovers over the tag.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-281-320.jpg)
![251widget quickstart
The jQuery UI widget factory will automatically call any option with the same name
as the event being raised. This feature allows the event handlers to be associated with the
event by setting the value of the option. The QuickStart does this in the startup file.
JavaScript
// Contained in startup.js
$('span[data-tag]').tagger({
activated: function (event, data) {
infobox.infobox('displayTagLinks', event, data.name);
},
deactivated: function () {
infobox.infobox('hideTagLinks');
}
});
This approach is also a nice way to avoid having to know if the event is called tag
activated or taggeractivated or something else. The displayTagLinks method accepts a
browser event and the name to look up. The first part of the method sets up enclosed
variables to be used in the second part of the method.
JavaScript
// Contained in jquery.qs.infobox.js
displayTagLinks: function (event, tagName) {
var i,
html,
that = this,
options = that.options,
elem = that.infoboxElement,
top = event.pageY + offsetY,
left = event.pageX + offsetX,
url = options.dataUrl + tagName + '?count=' + options.maxItems,
displayResult = function () {
elem.html(html);
elem.css({top: top, left: left});
elem.show();
};
if (event.pageX > window.screenWidth / 2) {
left = event.pageX + leftSideAdjustment;
}
After the closure is prepared, left is adjusted in case the tag is on the right-hand side
of the page. The second part of the displayTagLinks method is an Ajax call to the url,
constructed above, for the Delicious bookmarking service.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-284-320.jpg)
![252 chapter fourteen
JavaScript
// Contained in jquery.qs.infobox.js
$.ajax({
url: url,
dataType: 'jsonp',
success: function (data) {
if (data != null) {
html = '<h1>Popular Links for ' + tagName + '</h1><ul>';
for (i = 0; i < data.length - 1; i += 1) {
html += '<li><a href="' +
data[i].u +
'" target="_blank">' +
data[i].d + '</a></li>';
}
html += '</ul>';
} else {
html = '<h1>Data Error</h1><p>[snipped]</p>';
}
displayResult();
},
error: function (jqXHR, textStatus, errorThrown) {
html = '<h1>Ajax Error</h1>' +
'<p>The Ajax call returned the following error: ' +
jqXHR.statusText + '.</p>';
displayResult();
}
});
The local displayResult function is scoped only to the displayTagLinks method since
it was needed for both success and error conditions and nowhere else. This is the meth-
od that applies the result to the element for the user to see.
Mouse Leaving a Keyword Span
When the mouse leaves the tag’s span, a similar coordination occurs. The tagger widget
has a namespaced event bound to the span’s mouseleave event.
JavaScript
// Contained in jquery.qs.tagger.js
.bind('mouseleave.' + name, function () {
timer = setTimeout(function () {
that._trigger('deactivated');
}, hideAfter);
});
The timer is set to raise the tagdeactivated event after 1000 milliseconds, which is
the value of hideAfter.](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-285-320.jpg)
![253widget quickstart
When the tagger widget was applied to the span elements, a function was supplied
to the deactivated callback, as you also saw earlier in the QuickStart.
JavaScript
// Contained in startup.js
$('span[data-tag]').tagger({
activated: function (event, data) {
infobox.infobox('displayTagLinks', event, data.name);
},
deactivated: function () {
infobox.infobox('hideTagLinks');
}
});
The function invokes the hideTagLinks method on the infobox widget.
JavaScript
// Contained in jquery.qs.infobox.js
hideTagLinks: function () {
!mouseOverBox && this.infoboxElement.hide();
},
The infobox is only hidden if the mouse is not over it. Effectively, the 1000 ms delay
provides the user time to move the mouse from the keywords to the links.
Mouse Entering the Pop-up List
Internally, the infobox widget uses the mouseOverBox variable to maintain state indicat-
ing whether or not the mouse is over the pop-up list. This variable is defined in the closure
created by the self-executing anonymous function wrapping the file.
JavaScript
// Contained in jquery.qs.infobox.js
(function ($) {
var offsetX = 20,
offsetY = 20,
mouseOverBox = false,
leftSideAdjustment = -270;
$.widget(‘qs.infobox’, {
When the mouse enters the infobox, mouseOverBox is set to true.
JavaScript
// Contained in jquery.qs.infobox.js: _create
.bind('mouseenter.' + name, function () {
mouseOverBox = true;
})](https://image.slidesharecdn.com/microsoftprojectsilk-130620152726-phpapp02/85/Microsoft-project-silk-286-320.jpg)
Microsoft project silk
- 1. PR O J E C T SI L K Bob Brumfield Geoff Cox Nelly Delgado Michael Puleio Karl Shifflett Don Smith Dwayne Taylor Client-Side Web Development for Modern Browsers • • • • • • • • • • • • • • • • • • • • • • • • • •
- 2. project silk
- 4. Project Silk Client-side Web Development for Modern Browsers Bob Brumfield Geoff Cox Nelly Delgado Michael Puleio Karl Shifflett Don Smith Dwayne Taylor
- 5. ISBN: 978-1-62114-011-5 This document is provided “as-is.” Information and views expressed in this document, including URL and other Internet website references, may change without notice. You bear the risk of using it. Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred. © 2011 Microsoft. All rights reserved. Microsoft, Windows, Windows Server, Windows Vista, Windows Azure, Silverlight, Expression, Expression Blend, MSDN, IntelliSense, Internet Explorer, SQL Azure, SQL Server, Visual C#, Visual C++, Visual Basic, and Visual Studio are trademarks of the Microsoft group of companies. All other trademarks are the property of their respective owners.
- 6. Contents foreword xv foreword xvii the team who brought you this guide xix ReadMe xxi installation overview xxi Step 1: Install System Requirements xxii Step 2: Download and Install Project Silk xxii Step 3: Run Script to Install NuGet Packages xxiii Step 4: Download External JavaScript Libraries xxiii jqPlot xxiii Step 5: Install Test Libraries (Optional) xxiv jquery.simulate.js (Optional) xxiv QUnit (Optional) xxiv Step 6: Run Mileage Stats xxiv Running in Release Mode xxvi About Mileage Stats xxvi About the Book xxix Requirement for Jump List Items to Appear xxix Known Issues xxx Community xxxi Resources and Further Reading xxxi 1 introduction 1 Prerequisties 2 Spectrum of Web Applications 2 Characteristics of Modern Web Applications 3
- 7. Considerations for Building Modern Web Applications 3 Team Skills 4 Technologies 4 Ajax 5 JavaScript 5 jQuery 6 Modernizr 6 ASP.NET MVC Razor 7 Dependency Injection 7 Exploring This Guidance 8 Exploring the Mileage Stats Reference Implementation 8 Using Mileage Stats 9 Exploring the QuickStart 16 Exploring the Documentation 16 Community 18 Further Reading 18 2 architecture 21 Introduction 21 Structure 23 jQuery Templates 23 Modularity 24 Communication 26 Direct Communication 27 Loose Communication 27 Navigation 27 Data 28 Architectural Alternatives 29 Summary 30 Further Reading 31 3 jquery ui widgets 33 Introduction 33 Widget Fundamentals 34 Defining a Widget 35 Using a Widget 36 Managing Lifetime 36 Creation 36 Initialization 38 Destruction 38 Defining Options 38 When Options Change 39 Functions as Options 40
- 8. The Widget Method 41 Public Methods 41 Reusing an Instance 42 Using the Pseudo Selector 43 Private Members 43 Methods 43 Properties 44 Static Members 44 Events 46 Raising the Event 46 Binding Handlers 46 Event Naming 47 Options as Callbacks 47 Inheritance 48 Summary 49 Further Reading 50 Resources 50 4 design and layout 51 Introduction 51 Design is a Worthwhile Investment 51 Web Project Designer Roles 52 Focus on the User 53 Design Prototyping 53 User Experience Design Considerations 54 Consistency 54 Responsiveness 55 Familiar Metaphors 55 Streamlining the Experience 55 Anticipate Usability Issues 57 Limit the Choices 57 User Interface Design Considerations 57 Color 58 Typography 58 Balance and Symmetry 59 Consistency 60 Simplicity 60 Other Design Considerations 60 Designing the Mileage Stats Reference Implementation 60 Identifying User Stories 60 Mileage Stats User Story 60 Using Flow Diagrams to Prototype the UX 61 Using Wireframes to Prototype the UI 63 Creating Site Mockups 64
- 9. Implementing the Design 67 Converting a Mockup to HTML 67 CSS Organization 70 Vendor-Prefixed Attributes 71 Debugging 72 Summary 73 Useful Design Tools 73 Further Reading 74 5 modularity 77 Introduction 77 Benefits of Modularity for Hybrid-Design Web Applications 78 Leveraging Frameworks 78 Support for an Immersive UI 79 Support for Team-Oriented Development 79 Explicit Control over Application Initialization 79 Ability to Externally Configure Modules 79 Decoupled Module Interactions 79 Troubleshooting and Debugging 80 Code Base Maintenance 80 Testing 80 Factors That Influence a Modular Design 80 Page Layout 81 The Dashboard Layout 83 The Details Layout 84 Animations 85 Refreshing Data 87 Functional Roles and Categories for Modules 88 UI Modules 88 Behavioral Modules 88 Infrastructure Modules 89 JavaScript Module Implementations 89 Using JavaScript Objects as Modules 90 Using jQuery Plug-ins as Modules 90 Using Widgets as Modules 91 Externally Configuring Modules 93 Initializing Modules 93 Communicating Between Modules 94 Testing Modules 94 Summary 96 Further Reading 96
- 10. 6 client data management and caching 97 Introduction 97 Client-Side Data Design 98 Data Manager 99 Benefits of the Data Manager Abstraction 99 Data Request 99 Data Request Options 100 Performing a Data Request 101 Performing Ajax Requests 101 Data Cache 104 Adding and Retrieving Cached Data 104 Removing a Data Cache Item 105 Summary 105 Further Reading 106 7 manipulating client-side html 107 Introduction 107 The Roles and Responsibilities of Client-Side Languages 107 Structure, Appearance, and Behavior 108 Adding Interactive Behavior to an Application 108 Using a JavaScript Library to Manipulate the DOM 109 Selecting and Manipulating Existing HTML Elements 110 Selecting Elements 110 Using Context 111 Using Data- Attributes 112 Modifying Existing Elements 113 Showing and Hiding Content 113 Updating Element Attributes 114 Generating and Loading New HTML in a Page 116 Generating HTML Dynamically with JavaScript and jQuery 116 Retrieving HTML Fragments from the Server 117 Content Retrieval Decisions in Mileage Stats 117 Using Templates to Retrieve and Generate HTML 118 Anatomy of a jQuery Template 118 Server-Side Rendering and jQuery Templates 120 Summary 121 Further Reading 122
- 11. 8 communication 123 Introduction 123 Direct Method Invocation 124 Getting a Widget Reference 124 Method Invocation in Mileage Stats 124 A Helper for Method Invocation 125 Raising and Handling Events 127 Publishing and Subscribing 128 Pub/Sub in Mileage Stats 129 The pubsub Object 130 An Example of Subscribing and Publishing 131 Finding the Right Balance 133 Summary 133 Further Reading 134 9 navigation 135 Introduction 135 Supporting the Single-Page Interface Pattern 136 Browser History and the Back Button 137 The BBQ Plug-in 138 Modifying Hyperlinks 138 Modifying URLs When the Application Loads 139 Modifying URLs When the User Activates a Link 141 Responding to User Actions 143 Animating Screen Transitions 145 The Layout Manager 145 Coordinating Transitions 146 Animating Vehicle Tiles 147 Calculating Coordinates 151 Summary 152 Further Reading 153 10 application notifications 155 Introduction 155 Notifying the User 156 Where Notification Messages are Displayed 156 How Notification Messages are Initiated 157 How Individual or Multiple Notification Messages are Displayed 159 User Session Timeout Notification 160 Website Error Notification 161 Prompting Users 162
- 12. Desktop Notifications 163 Implementing Pinned Sites 165 Pinned Sites in Mileage Stats 165 Feature Detection 165 Enabling Website Pinning 165 Dynamic Jump List Updating and Notification Icons 168 Requirement for Jump List Items to Appear 170 Summary 171 Further Reading 172 11 server-side implementation 173 Introduction 173 Creating a Data Access Layer 174 Rapid Data Modeling Using the ADO.NET Entity Framework and SQL Server Compact 175 Using the DbModelBuilder to Create a Data Model 177 Creating the Database 178 Initializing the Database 179 Optimized Data Access 180 Implementing the Repository Pattern 180 Composing Application Logic 182 Factoring Application Code with ASP.NET MVC 182 Design Checklist for MVC Applications 186 Creating a Business Services Layer 187 Supporting Interactive Web Clients 189 Providing HTML Structure 189 Using View Model and View Bag 191 Providing Data Asynchronously 192 Choosing a Data Format 192 Factoring Controller Actions for Ajax 194 Data Validation 195 Data Annotation Attributes 195 Validating Data in MVC 195 Creating Custom Validation Attributes 197 Handling Complex Data Validation 198 Supporting Validation on the Client 199 Unit Testing Validation Logic 201 Other Considerations 202 Dependency Injection 202 Unit Testing 203 Error Management 203 Concurrency 205 Summary 205 Further Reading 205
- 13. 12 security 207 Introduction 207 Security Threats 207 Unauthorized Access 208 Malicious Input – Content Injection and Cross-Site Scripting 208 Eavesdropping, Message Tampering, and Message Replay 208 Cross-Site Request Forgery 208 Web Platform Security 209 MVC View Encoding 209 ASP.NET Input Filtering 209 Protecting Application-Specific Data 210 Mileage Stats Application Security 210 Authentication 210 Configuration 212 AuthController 213 DefaultOpenIdRelyingParty 215 Forms Authentication Sliding Expiration 216 Input Validation 217 Anti-Forgery 219 JSON Hijacking Prevention 220 Additional Security Considerations 221 Securing Communication between Client and Server 221 Protecting Connection Strings 222 Deploying to a Shared Environment 222 Summary 222 Further Reading 223 13 unit testing web applications 225 Introduction 225 JavaScript Unit Testing 226 Getting Started with Unit Testing 226 Creating Unit Tests 228 What to Test 229 Isolating Your Tests 230 jQuery UI Widget Testing 231 Server-Side Unit Testing 233 Getting Started with Unit Testing 233 What to Test 236 Isolating Your Components 237 Testing Your ASP.NET MVC Controllers 239 Summary 241 Further Reading 242
- 14. 14 widget quickstart 243 Business Scenario 243 Walkthrough 243 Conceptual View 247 Attaching Widgets 248 Widget Initialization 249 Widget Interactions 249 Mouse Entering a Keyword Span 250 Mouse Leaving a Keyword Span 252 Mouse Entering the Pop-up List 253 Mouse Leaving the Pop-up List 254 Further Reading 254 appendices a glossary 255 b project silk road map 263 About the Topic Areas 263 Immersive Web Applications 264 Technology Choices 264 Mileage Stats 264 Widgets 268 UI and UX Design 269 Modularity 270 Data 270 Client-Side HTML 271 Communication 272 Navigation 273 Application Notifications 274 Server-Side Implementation 275 Security 276 Unit Testing 277 Automated Acceptance Testing 278 index 279
- 16. xv Foreword I was in New York when I first got the call from Don Smith asking about Project Silk. The idea and vision that Don described to me over the phone that day were ambitious. At the time, very little had been published about large application architecture with jQuery. Don explained how he and the team planned to tackle the task, developing a working sample application alongside documentation that thoroughly described the approach and the architecture decisions. The result of that vision is the book that you hold in your hands today, and I can confidently say that the Project Silk team did an incredible job. The most impressive and meaningful aspect of this book is the care taken to integrate and work with the open source community to develop this material. Karl, Don, and their team went above and beyond to talk with members of the jQuery community. They spent time researching the latest approaches recommended by the open source community. They held team trainings and brought in industry experts to learn the latest techniques. After the initial project had been completed, they solicited a number of community re- views to get feedback from several developers. This feedback was integrated into the guidance, which then underwent additional community reviews and releases. The results of these efforts are clear. The approach and examples outlined in these pages are focused on helping you create an application in the best way possible. It is this intentional effort that makes the open source process sustainable. I couldn’t be more proud to have been a part of it all and I highly commend Karl and Don for their leadership. The method by which this guidance was produced will stand as an example of how to properly tackle a project like this one. The result of their work could not have been published at a better time. JavaScript, jQuery, HTML5, and CSS3 are gaining tremendous importance as unifying standards for producing cross-platform applications. This fact is only reinforced by the release of the Microsoft Windows 8 Developer Preview in September 2011. With many developers now choosing to use these technologies to produce software, high-quality guidance such as Project Silk is needed. With this renewed emphasis on the use of these technologies, comprehensive guid- ance is required to leverage their full potential. The methods described here for how to successfully integrate standard web technologies into the Microsoft ASP.NET stack will help ensure that developers who depend on the Microsoft technology stack will be using the latest techniques when developing applications. Not only will developers be using the
- 17. xvi latest techniques to build maintainable applications, they will be participating as good citizens of the web by practicing the standards-based development that is exemplified in this book. This makes the web a better place for everyone, and it is exciting to see the leadership role Microsoft is taking in this effort. From a technical perspective, the most exciting thing about the approach and guid- ance documented in Project Silk is the use of the jQuery UI Widget Pattern. In my per- sonal opinion, the Widget Pattern is incredibly underutilized when building web applica- tions. The Widget Pattern is a technique used to build user interface (UI) widgets in a maintainable and extensible way. Most jQuery UI Widgets in jQuery UI 1.8 are based upon this pattern, yet it is rarely seen outside of the jQuery UI project. With such an important project leveraging this pattern, I hope to see it used more and more. It is my hope that as a developer, you will benefit greatly from reading the Project Silk guidance. Having been a small part of the process, I can testify to the care and research that went into producing Project Silk for your benefit. The developers behind this book and the application that accompanies it truly care about the web and about making your job easier. It is now your turn to adopt these patterns and principles to make better software. The completion and release of Project Silk is not the end, but the beginning, as it is now in your hands. Please join the Silk team in spending the time to adopt and lever- age these patterns as we practice our craft together. In closing, Microsoft has proven to be an incredible resource to the jQuery Com- munity and it is exciting to see efforts like this. Project Silk represents that commitment in several ways. The way this guidance was produced is an example for similar projects that will follow it. The quality that it achieves sets a new standard in how to build and architect large, maintainable web applications with jQuery and ASP.NET. I hope that this book serves you well and teaches you new and exciting ways to work with these technologies. Mike Hostetler CEO, appendTo—The Company Dedicated to jQuery
- 18. xvii Foreword We’re in an incredibly exciting time where the Internet is dramatically changing the way we live our lives. From communication and shopping, to gaming and organizing groups, the Internet has become a vital part of our lives—as important as the basic utilities we take for granted daily. If we look at the evolution of the web, it’s evident that the effort of developers to continuously push the capabilities and boundaries of web technologies has uniformly transformed the way users experience the web. No longer are we bound to simplistic pages with generic text and hyperlink navigation. Technologies and frameworks like HTML5, CSS3, JavaScript, and jQuery have allowed us to dramatically alter the way information is presented to consumers by providing rich, immersive user interfaces that are engaging and, most importantly, responsive. They are impacting every aspect of development on every platform, from traditional browsers to the smallest mobile devices. If you consider, for example, that these technologies allow most anyone with a cell phone to shop online or map a route, you realize how important they are and the impact that the applications built with them have on our daily lives. The web is ubiquitous, and the developers who are leveraging these technologies are having a direct and positive impact on the lives of millions. The obvious question that any developer should be asking is, “How do I leverage these technologies today so I can build the next great web experience?” One of Microsoft’s greatest strengths is its commitment to ensuring that developers have the knowledge, tools, and infrastructure to be successful. This guide exemplifies that commitment by providing the information developers need to build and manage responsive websites using the latest web languages, tools, and best practices. Creating guidance is not at all trivial, and all the time, research, and coding that went into this effort are truly a testament to the Microsoft patterns & practices team and their genuine desire to provide the absolute best and most timely information to developers. Vetted by professional web developers, both internal and external to Microsoft, including jQuery team members, this guidance will help you understand the real-world implications of designing a dynamic and responsive website. It’s certainly possible to scour the Internet to compile a massive list of blog posts and articles that may (or may not) articulate how to approach web development, but the guidance offered in this book can realistically serve as a priority resource for developers wanting to acquire a firm understanding of how to use the best web development technologies and apply them professionally.
- 19. xviii I’m so proud to have been a part of this incredible project and appreciate the impact it will have on the way developers build great experiences. It takes more than just sprin- kling some JavaScript or HTML5 on a site to make it worthwhile. It takes thought, time, experience, and a firm understanding of how to use the technologies. This book will help you tackle these key points and make you a better developer. Rey Bango Senior Technical Evangelist Microsoft Corporation jQuery Team member
- 20. xix Authors Bob Brumfield, Geoff Cox, Nelly Delgado, Michael Puleio, Karl Shifflett, Don Smith, and Dwayne Taylor Reviewers Mark M. Baker, Christopher Bennage, Larry Brader, Bob Brumfield, Colin Campbell, Geoff Cox, Nelly Delgado, Julian Dominguez, Dan Dole, Barry Dorrans, Norman Headlam, Israel Hilerio, Alex Homer, Simon Ince, Poornimma Kaliappan, Stuart Leeks, Roberta Leibovitz, Katie Neimer, Michael Puleio, Steve Sanderson, Chris Sells, Karl Shifflett, Adam Sontag, Don Smith, Aaron Sun, Jonathan Wall, Dave Ward, Bill Wilder, Rob Zelt Editors Nancy Michell and Roberta Leibovitz Graphic Artist Katie Niemer Project Silk Development Team The Microsoft patterns & practices team involves both experts and the broader community in its projects. Thanks to the individuals who contributed to Project Silk. Project Silk Team Christopher Bennage, Larry Brader, Bob Brumfield, Nelly Delgado, Alex Homer, Michael Puleio, Karl Shifflett, and Don Smith (Microsoft Corporation); Geoff Cox (Southworks SRL); Ara Pehlivanian; Aaron Sun (Content Master Ltd); Poornimma Kaliappan, Hailin Wei, Hongran Zhou (VanceInfo); Dwayne Taylor (RDA Corporation); Roberta Leibovitz and Colin Campbell (Modeled Computation LLC) Editing / Production Nancy Michell (Content Master Ltd); Roberta Leibovitz and Katie Niemer (Modeled Computation LLC); John Hubbard (Eson); Ted Neveln (Ballard Indexing Services); Tom Draper and Patrick Lanfear (Twist Creative LLC); Richard Burte (ChannelCatalyst.com, Inc.) External Advisors Scott González, Mike Hostetler, Jonathan Sharp, and Andrew Wirick of appendTo, LLC; Adam Sontag of the jQuery UI Project; Mark M. Baker of BNA Software; Norman Headlam; Michael Kenyon of IHS, Inc.; Chris Love of Tellago; Dave Ward of Encosia; Bill Wilder; Rob Zelt of Digital Commute LLC The Team Who Brought You This Guide
- 21. xx Microsoft Corporation Rachel Appel, Rey Bango, John Bristowe, Doris Chen, Dan Dole, Barry Dorrans, Advisors Damian Edwards, Phil Haack, Simon Ince, Tim Laverty, Stuart Leeks, Steve Sanderson, Giorgio Sardo, Justin Saint Clair, Brandon Satrom, Chris Sells, Amanda Silver, and Brad Wilson
- 22. xxi Project Silk provides guidance for building cross-browser web applications with a focus on client-side interactivity. These applications take advantage of the latest web standards, including HTML5, CSS3 and ECMAScript 5, along with modern web technologies such as jQuery, Windows® Internet Explorer® 9, and ASP.NET MVC 3. To illustrate this guidance, the project includes the Mileage Stats Reference Imple- mentation (Mileage Stats) that enables its users to track various metrics about their ve- hicles and fill ups. Much of the effort in building Mileage Stats was applied to the us- ability and interactivity of the experience. Animations were included to enhance the enjoyment of the site and Ajax is used to keep the interface responsive and immersive. A great deal of care was also taken to ensure that the client-side JavaScript facilitates modularity and maintainability. To accomplish these design goals, the JavaScript code was structured into widgets that benefit from the jQuery UI Widget Factory. This guidance is intended for existing web developers who are interested in taking advantage of the latest web standards and technologies. Installation Overview To install and run the reference implementation, you must perform the following steps: 1. Install system requirements. 2. Download and install Project Silk. 3. Run script to install NuGet packages. 4. Download external JavaScript libraries. 5. Install test libraries (optional). 6. Run Mileage Stats. Readme
- 23. xxii Step 1: Install System Requirements Mileage Stats was designed to run on the Microsoft Windows 7 or Windows Server 2008 operating system. It has been smoke tested on Windows Vista and Windows XP. Before you can use Mileage Stats, the following must be installed: • Microsoft® Visual Studio® 2010 Professional, Premium, or Ultimate edition • Microsoft Visual Studio 2010 SP1 • ASP.NET MVC 3 • Microsoft SQL Server Compact 4.0 • ADO.NET Entity Framework 4.1 - Update 1 • To install the Entity Framework, download it from the Microsoft Download Center rather than using NuGet. • For information about the Entity Framework 4.1 release, see EF 4.1 Released. • For information about the Entity Framework 4.1 - Update 1 release, see EF 4.1 Update 1 Released. • NuGet version 1.4 or later • Internet Explorer 9 or another modern web browser. Firefox 3.x is not supported. Use Firefox 4.0.1 or higher. • Optional: • Web Standards Update for Microsoft Visual Studio 2010 SP1 Mileage Stats requires several external libraries that cannot be included in the down- load. These fall into two categories: NuGet packages and JavaScript libraries, which are explained below. Step 2: Download and Install Project Silk Project Silk includes written guidance and the source code for both Mileage Stats and the Widget QuickStart. To download and install, follow these steps: 1. Download Project Silk from the Microsoft Download Center. 2. To extract the download, run the .exe file. This will extract the source code and documentation into the folder of your choice. 3. Install external dependencies from NuGet and download the required external JavaScript libraries, as explained in the steps below.
- 24. xxiii Step 3: Run Script to Install NuGet Packages Before building Mileage Stats, you will need to install the required NuGet packages. There are two scripts in the Solution Items folder, which are used to install and remove the NuGet packages. To install the NuGet packages: 1. Open MileageStats.sln located in {silk}MileageStats. 2. In Visual Studio, from the Tools menu, point to Library Package Manager, and select Package Manager Console. 3. Run the install script with the following command: .InstallRequiredNuGetPackages.ps1 You can remove the packages with the RemoveRequiredNuGetPackages.ps1 packages. Step 4: Download External JavaScript Libraries Mileage Stats requires several external JavaScript libraries. These libraries were chosen because they fit the needs of the project, not as a general recommendation or implied endorsement of these libraries. Every project is different and may have different needs. jqPlot jqPlot is a jQuery plugin to easily create charts with JavaScript. To learn more about jq- Plot, see http://www.jqplot.com/. To obtain the files needed to run Mileage Stats: 1. Go to https://bitbucket.org/cleonello/jqplot/downloads/ and download the file jquery.jqplot.1.0.0a_r701.zip. 2. Unzip the downloaded file to a folder of your choice, for example c:temp. 3. Copy the following .js files from the dist folder in the above folder into the {silk}MileageStatsMileageStats.WebScripts folder: • excanvas.min.js • jquery.jqplot.min.js 4. Copy jquery.jqplot.min.css from the dist folder in the above folder into the {silk}MileageStatsMileageStats.WebContent folder. 5. Copy the following .js files from the distplugins folder in the above folder into the {silk}MileageStatsMileageStats.WebScripts folder: • jqplot.cursor.min.js • jqplot.dateAxisRenderer.min.js • jqplot.canvasAxisTickRenderer.min.js • jqplot.canvasTextRenderer.min.js readme
- 25. xxiv Step 5: Install Test Libraries (Optional) The test libraries are only required when you deploy the web site to a server running Microsoft Internet Information Services (IIS). Otherwise, if you are running Mileage Stats from Visual Studio, these files are optional. jquery.simulate.js (Optional) jquery.simulate is a JavaScript API that allows you to simulate user interaction to help with QUnit tests. To obtain the files needed to run Mileage Stats: 1. Go to http://code.google.com/p/jqueryjs/source/browse/trunk/plugins/ simulate?r=6063&spec=svn6063 and download the files jquery.simulate.js. 2. Copy the saved file into the {silk}MileageStatsMileageStats.WebScriptstests folder. Note: You can also download the file from the jQuery UI tests folder at: https:// github.com/jquery/jquery-ui/tree/008def00bd565d0984c47cdd97d65e1c7bd7 3e04/tests. QUnit (Optional) QUnit is a JavaScript unit testing framework. To learn more about QUnit, see http://docs. jquery.com/Qunit. To obtain the files needed to run the unit tests in Mileage Stats: 1. Go to https://github.com/jquery/qunit and download the files qunit.js and qunit.css from the QUnit folder. 2. Copy the saved file into the {silk}MileageStatsMileageStats.WebScriptstests folder. 3. Build and run Mileage Stats, and navigate to http://localhost:23495/scripts/ tests/tests.htm. 4. Wait while the QUnit tests execute. Step 6: Run Mileage Stats Mileage Stats is an application that provides you with information about your cars’ fuel consumption, operational efficiency, and service records, allowing you to track and visual- ize data about your cars.
- 26. xxv To run Mileage Stats 1. Open MileageStats.sln located in {silk}MileageStats. 2. Press F6 to build the solution. 3. Select the MileageStats.Web project as the startup project. To do this, right- click the project, and then click Set as StartUp project. 4. Press Ctrl+F5 to run the application. 5. (optional) In Internet Explorer 9, you can pin the Mileage Stats icon to the Windows Taskbar. 6. Click the Sign in or Register button. 7. On the Mock Authentication page, use the default name provided and click Sign In. 8. On the Dashboard page, click the Add Vehicle button. 9. Enter the name of your car in the Name textbox. 10. (optional) Select the year. You have 1997, 2003, 2010, 2011 as options. 11. (optional) Select one of the car manufacturers from the drop-down box. 12. (optional) Select one of the models from the drop-down box. 13. (optional) Browse to a photo. 14. Click Save. 15. You should then see your car added to the Dashboard. You can add a fill up, add a reminder, view/edit details, add a new vehicle, or visually view your data by clicking Charts. 16. You can update your profile on the Profile page. 17. You can look at the other default car’s information. You can learn more about the design and implementation of Mileage Stats in the documentation included with Project Silk. readme
- 27. xxvi Running in Release Mode By default, Mileage Stats will run in Debug mode with non-minified JavaScript files. To run in Release mode with minified JavaScript files 1. Set Visual Studio to Release mode. 2. Update the web.config file: • Change <compilation debug=”true” targetFramework=”4.0”> to <compilation debug=”false” targetFramework=”4.0”> • Comment out the unity configSource section and replace it with the commented out version. 3. Build the solution. At the end of the build, the minified file ScriptsMileage Stats.min.js will be available. 4. Press Ctrl+F5. When you run the app, the new minified file will be used. To verify this, sign into the RI, press F12 (Internet Explorer developer tools), go to the Scripts tab, and look at the much shorter list of scripts that are now available. About Mileage Stats Mileage Stats is a multi-page interactive web application whose pages are rendered with- out requiring full-page reloads. This creates the illusion of a desktop application. By not requiring the browser to reload the full page, the user sees rich UI transitions between states (pages). In addition, the browser application runs very fast because of client-side data caching. The Mileage Stats JavaScript is modularized using jQuery UI Widgets. The widgets allow the UI to be broken down into small, discrete, stateful objects; this provides a clean separation of responsibilities and concerns. See the Widget QuickStart for an example application that uses the jQuery UI widget factory. Mileage Stats uses OpenID for authentication.
- 28. xxvii Mileage Stats home page Mileage Stats uses Internet Explorer 9 Pinned Sites features. Below you can see the notification icon that indicates there are more than three outstanding maintenance tasks for the owner’s three vehicles. Mileage Stats also displays dynamic jump lists for mainte- nance tasks. readme
- 29. xxviii Notification icon in Internet Explorer 9 Mileage Stats contains a rich chart page that allows you to select three charts, vehi- cles, begin and end date, and data.
- 30. xxix Charts in Mileage Stats View a two minute video on Mileage Stats on Channel 9. About the Book The chapters in this book cover a wide range of topics, including: planning and designing your web application, understanding and writing jQuery UI Widgets, writing server-side code that supports the client-side application, patterns and concepts used in JavaScript code, data and caching, and securing and testing your application. It also provides more information about Mileage Stats and the design decisions and challenges addressed by the team. Requirement for Jump List Items to Appear In Internet Explorer, the Windows 7 taskbar jump list items can be disabled. If disabled, you will not see the jump list items display even though the website has been pinned to the taskbar. The Store and display recently opened items in the Start menu and the taskbar property setting needs to be checked for the jump list items to appear. readme
- 31. xxx Taskbar and Start menu properties Known Issues • After you upgrade to Visual Studio 2010 SP1, you may encounter an issue when deploying the web site to your Localhost on IIS. The SP1 update resets the IIS Application pool configuration so it is no longer the latest version. You will need to navigate to C:WindowsMicrosoft.NETFramework64v4.0.30319 on 64-bit computers and C:WindowsMicrosoft.NETFrameworkv4.0.30319 on 32-bit computers and run aspnet_regiis -i. • In Internet Explorer 7, you will only see static charts in all scenarios (whether JavaScript is enabled or disabled). This is by design. • When deploying a release-compiled version to IIS, there may be an extra Uri section definition in the web.config file added by installing one of the NuGet packages. Remove the following extra section definition from the web.config file: <section name="uri" type="System.Configuration.UriSection, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" /> The NuGet package that adds this extra Uri section is: Install-Package DotNetOpen- Auth -Project MileageStats.Web • When upgrading from a community version of the Mileage Stats, you may encoun- ter problems where a cached version of JavaScript is used. If so, clear the browser’s cache. In some browsers this can be accomplished with Crtl+F5.
- 32. xxxi Community Project Silk’s community site is http://silk.codeplex.com. There, you can post questions, provide feedback, or connect with other users for sharing ideas. Community members can also help Microsoft plan and test future offerings. In addition, the community site has links to tutorial videos and MSDN content. Resources and Further Reading Download Project Silk from the Microsoft Download Center: http://www.microsoft.com/download/en/details.aspx?id=27290 The online version of this document is on MSDN: http://msdn.microsoft.com/en-us/library/hh404100.aspx For information about the Entity Framework 4.1 release, see “EF 4.1 Released”: http://blogs.msdn.com/b/adonet/archive/2011/04/11/ef-4-1-released.aspx For information about the Entity Framework 4.1 - Update 1 release, see “EF 4.1 Update 1 Released”: http://blogs.msdn.com/b/adonet/archive/2011/07/25/ef-4-1-update-1-released.aspx Internet Explorer 9: http://windows.microsoft.com/en-US/windows/downloads/internet-explorer jqPlot: http://www.jqplot.com/ ASP.NET MVC 3: http://www.asp.net/mvc/mvc3 jQuery UI widget factory: http://docs.jquery.com/UI/Developer_Guide View a two minute video on Mileage Stats on Channel 9: http://channel9.msdn.com/posts/Project-Silk-Mileage-Stats-Application readme
- 34. 1 Introduction1 Project Silk provides guidance for building maintainable cross-browser web applications that are characterized by an intentional design, rich interactivity, and a responsive user interface (UI), resulting in an immersive and engaging user experience (UX). Such applica- tions take advantage of the latest web standards, including HTML5, CSS3, and ECMAS- cript version 5, and modern web technologies such as jQuery and ASP.NET MVC3. An intentional design indicates that deliberate attention was paid to the modularity of the JavaScript code, and the usability of the application was an explicit focus. Under the direction of the team’s web designer, UI and UX concerns received special attention, and this guidance aims to help you be successful addressing these concerns in your own applications. Modularity is important when building highly interactive web applications because they often require a significant amount of JavaScript code. This guidance aims to help you understand how to write maintainable JavaScript code that reaps the many benefits of a modular design. Project Silk also illustrates how you can take advantage of the fast JavaScript engines of the modern, standards-based web browsers to achieve a user experience and execution speeds that rival desktop applications. Windows® Internet Explorer® 9 further enriches the user experience by taking advantage of integration with the operating system and hardware-accelerated graphics processing. The concepts explained in the Project Silk written guidance are demonstrated via a real-world customer-facing web application called the Mileage Stats Reference Implementation (Mileage Stats). Mileage Stats allows users to track and compare their vehicles’ fuel efficiency, usage, and operating costs, and to schedule vehicle maintenance reminders.
- 35. 2 chapter one Prerequisites This guidance is intended for web developers and assumes you have some hands-on ex- perience with ASP.NET MVC, CSS, HTML, JavaScript, and jQuery. Mileage Stats relies heavily on a few important JavaScript and jQuery concepts that you need to understand. They include: • JavaScript: Object literals, immediate functions, closures, object prototypes, scoping rules, use of the this keyword • jQuery: Selectors, wrapped sets, chaining If you are not familiar with these concepts or have not used them in your own proj- ects, see the “Further Reading” section at the end of this chapter for more information on these topics. Spectrum of Web Applications There is a spectrum of web applications being built today that can be grouped into four application types. These types of web applications are categorized by their full-page re- load behavior and the amount of client-side interactivity they provide. Each application type provides a richer experience than the one listed before it. • Static sites. These consist of static HTML pages, CSS, and images. They are static in that as each page is navigated to, the browser performs a full-page reload and there is no interaction with portions of the page. In addition, the page does not change no matter who requests it or when. • Server rendered. In this model, the server dynamically assembles the pages from one or more source files and can incorporate data from another source during the rendering. The client-side script in these applications might perform some data validation, simple hover effects, or Ajax calls. As each page is navigated to, the browser performs a full-page reload. ASP.NET applications that don’t make heavy use of client-side JavaScript are examples of server-rendered web applications. • Hybrid design. This model is similar to the server-rendered web application, except that it relies heavily on client-side JavaScript to deliver an engaging experience. This type of application has islands of interactivity within the site that do not require full-page reloads to change the UI as well as some pages that do require a full-page reload. Mileage Stats is an example of a hybrid design. • Single-page interface. In this model, a full-page load happens only once. From that point on, all page changes and data loading is performed without a full-page reload. Hotmail, Office Live, and Twitter are examples of single-page-interface web applications.
- 36. 3introduction Characteristics of Modern Web Applications While there are many types of modern web applications, addressing many different needs, they all have some characteristics in common. • They are standards-focused. To have the broadest reach across multiple platforms and devices, applications attempt to implement the current and evolving standards and adopt future standards once ratified. • They are interactive. Modern web applications keep the user engaged by providing constant feedback on their actions. This feedback can come in the form of mes- sages, animations to hide or show elements, mouse-over effects, drag and drop feedback, the automatic refreshing of screen data, animation of various elements, or the implementation of fade-in or fade-out effects. Interactive applications leverage the fast JavaScript engines in modern browsers to perform their client-side tasks. • They limit full-page reloads. Modern web applications seek to limit the number of full-page reloads. Reloads are much slower than a localized Ajax call to update a portion of the UI. Full-page reloads also limit the ability to animate state or page changes. By not performing a full-page reload, users can be kept in context, provid- ing a fluid experience as they navigate from one task to another. • They are asynchronous. Modern web applications use Ajax to dynamically load data, page fragments, or other assets instead of performing a full-page reload to acquire data or HTML content. Because the loading of data is asynchronous, the UI is able to stay responsive and keep the user informed while the data request is being fulfilled. This asynchronous on-demand loading also reduces application response time because requests can be tuned to return only the data and other content that needs to change. • They manage data. When applicable, modern web applications provide client-side data caching and prefetching to boost client-side performance. This enables the UI to immediately respond to user input gestures because it does not have to make a call to the server for data. Data caching also serves to minimize the impact on server resources, increasing application scalability because fewer calls to the server are required. Considerations for Building Modern Web Applications Building a rich modern web application can be rewarding and fun. For developers or web software firms that have typically delivered server-centric applications, possibly with small amounts of JavaScript, embarking on a modern web application project will involve a paradigm change that should not be minimized or overlooked. In the next two sections we will examine the skill sets a project team will need and the technologies used when building a modern web application.
- 37. 4 chapter one Team Skills Developing modern web applications requires a broad range of skills. Depending on your application requirements, your team will need expertise provided by people in the follow- ing roles: • Designer roles. These will be responsible for user experience, user interface, and graphics. • Client-side developer roles. These will bring programming expertise in the areas of user interface, user interaction, and test. • Server-side developer roles. These will have programming expertise in the areas of web pages, business objects and logic, databases, and test. The composition of the web project team will vary from project to project based on the application’s requirements and the team’s resources. For example, on a large project, each of the roles above would probably be filled by a different person or possibly a team. On a small project, team members will likely fill multiple roles with augmentation from consultants as required to fill in the gaps. On Project Silk, all of the above roles were filled by a lead developer, web designer, server-side developer, and two client-side developers. Project Silk also had a test team that consisted of a test manager, test program manager, and two software test engineers. The test team was responsible for testing browser compatibility, deployment testing, performance testing, stress testing, and security testing. To accomplish this, the test team set up a lab with servers running Windows Server® 2008, each with different configura- tions, and client computers configured with different operating systems and browsers. These systems were then used to perform daily automated and manual tests. Technologies This section will familiarize you with technologies and patterns used in building Mileage Stats. If any of these are new to you, please review the resources in the “Further Reading” section so you will get the most from the guidance and will be able to understand the Mileage Stats JavaScript, HTML5, CSS3, and C# code. This section does not intend to convey all of the important concepts you must know. Rather, you should consider it a list of indicators you may need to research further before building an application such as Mileage Stats.
- 38. 5introduction Ajax For over 10 years, the web has benefited from the ability to replace full-page reloads with Ajax calls. But given the advances in standards such as CSS3 and HTML5, browsers adher- ence to those standards, and the arrival of powerful, cross-browser JavaScript frameworks, we have all the tools necessary to build highly engaging client-side experiences. Ajax facilitates a paradigm change in web development from the traditional full-page reload model of server-centric applications to rich, responsive client-centric applications. The client receives data and updates the UI using JavaScript. Bandwidth requirements are minimized because the server responds to requests by returning just the requested data instead of HTML pages (and all their elements) along with the data. The application runs faster because the data requests take less time to complete, and the UI is quickly updated without a full-page reload. Asynchronous calls are essential to keeping interactive and immersive applications responsive from the user’s perspective. JavaScript JavaScript is a dynamic, functional, prototypal language that has a very close relationship with the document object model (DOM). For both JavaScript and the DOM, there are features you can use with confidence and others you should avoid. Over the past ten years, the web development community has learned a great deal about how to use these together to maximize success. See the “Further Reading” section for resources that ex- plain the recommended ways of using JavaScript. Project Silk adheres to these practices, but we do not present a primer here. As is true with all environments, you will be most successful using it as intended. If you aren’t presently writing JavaScript code according to the patterns currently accepted in the JavaScript community, be sure your team has time to become familiar with them, because you may be surprised. For example, the Project Silk team members who had re- cently worked in the Microsoft .NET environment needed to ramp up on the following aspects of JavaScript: • JavaScript uses object-oriented concepts, but classes and inheritance hierarchies are not the same as in other .NET languages such as Visual C# and Visual Basic.NET. • Understanding closures and variable scoping is important. They are used intention- ally and often by allowing variables defined within one scope to be used in another function. • The object that the this keyword refers to changes based on where it is used. For example in a single method, this may refer to the object the method is defined on, and in a loop within that same method this may refer to the current item of the collection being iterated over. You should understand its rules. • Objects without type definitions are very common and use an object literal syntax. The commas between properties and functions used in these object literals may cause syntax errors until you are familiar with them.
- 39. 6 chapter one jQuery jQuery is an open-source JavaScript library that addresses the challenges of working with the DOM across browsers. It has a straightforward API that can be divided into two calling conventions: • Functions are called on the jQuery object itself. For example, the extend function merges the properties and methods of two different objects together. It looks like this: $.extend(targetObject, objectToMerge). • Methods are called on the wrapped set. A wrapped set is the result of a query that uses a selector to find elements in the DOM. To call a method on a wrapped set of elements, a selector is used to select elements in the DOM. For example, to add the listing CSS class to all ul elements directly inside a div element, $(‘div ul’). addClass(‘listing’) can be used. jQuery also provides features to raise and handle events, make Ajax requests, and process the data returned from Ajax requests. To be successful developing with jQuery, you should: • Know that the selector syntax uses and extends the CSS selector syntax. The better you’re able to leverage this syntax, the cleaner your HTML can be. • Understand what the wrapped set is, how it’s different from an array of DOM elements, and which you’re working with at any given time. For example, when using $.each, inside the callback, this is not wrapped. • Understand that animations are asynchronous and are queued. Use a named queue or the stop method to gain more control over how the animations behave. Modernizr In the past, the client-side application would use navigator.userAgent to determine which browser was in use and choose its code paths accordingly. Today, the accepted practice is to explicitly detect each feature the application intends to use. Modernizr is an open-source JavaScript library that detects the support for browser features (geolocation, canvas, SVG, border-radius, etc.) and exposes its findings in CSS and JavaScript. Once a script reference to Modernizr is included, Modernizr will add a CSS class to the html element for each feature it can detect. If the feature isn’t supported, the CSS class will start with no-. For example, if a browser supports canvas and not webgl, its html element will look like this: <html class=”canvas no-webgl ...”>. Modernizr also ex- poses a Modernizr JavaScript object that has Boolean properties for each feature it can detect.
- 40. 7introduction ASP.NET MVC Razor Razor is the name of one of the view engines in ASP.NET MVC 3 (WebForms is the other). The razor view engine is used to render MVC views, which are comprised of HTML and server-side code. The Razor syntax is clean and concise, and easy to learn, and Visual Studio includes IntelliSense® and syntax highlighting for Razor syntax. For a more detailed overview of Razor, see “ASP.NET MVC 3 Overview, The Razor View Engine” in the “Further Reading” section. Dependency Injection Dependency injection is a variant of the Inversion of Control design pattern. Dependency injection containers reduce the dependency coupling between objects by providing a facility to instantiate instances of classes and manage their lifetimes based on the con- figuration of the container. During the creation of objects, the container injects into the object any dependencies the object requires. If those dependencies have not yet been created, the container creates and resolves their dependencies first. Dependency injection provides several benefits: • Reduced coupling; classes and components don’t have to locate dependencies or manage their lifetimes. • Improved testability; dependencies can be easily substituted with mocked imple- mentations. • Improved flexibility and maintainability; dependencies can be replaced easily. ASP.NET MVC 3 provides better support for applying dependency injection and for integrating with dependency injection or inversion of control containers. For more infor- mation about dependency injection in ASP.NET MVC 3, see “ASP.NET MVC 3 Overview, Dependency Injection Improvements” in the “Further Reading” section. For an introduc- tion to dependency injection and inversion of control, see “Loosen Up: Tame Your Soft- ware Dependencies for More Flexible Apps” in MSDN Magazine.
- 41. 8 chapter one Exploring This Guidance The purpose of this guidance is to show you how to plan, design, and build a rich, interac- tive web application your users will enjoy using. This guidance includes the following re- sources: • Mileage Stats Reference Implementation. Comprehensive sample application demonstrating a real-world, interactive, cross-browser, consumer-facing, rich web application. The reference implementation is intentionally incomplete, but does illustrate the core concepts, design patterns, coding patterns, security requirements, web technologies, and unit testing necessary to be successful. • Widget QuickStart. Small sample application that demonstrates how to use and develop jQuery UI Widgets. • Documentation. This guidance provides an architectural overview of rich web applications and chapters that cover the design, concepts, patterns, security, testing, and implementation of Mileage Stats. This guidance also includes documen- tation that covers the Widget QuickStart and How-to topics on automated testing. Exploring the Mileage Stats Reference Implementation Mileage Stats is an ASP.NET MVC application that enables users to track and compare various metrics about their vehicles including fuel consumption, fuel costs, miles driven, and maintenance reminders. The application is a multi-page interactive web application where the pages are rendered without requiring a full-page reload. The lack of full-page reloads enables rich UI transitions between states (pages) and the application runs fast because of the client-side data caching and some data prefetching. Much of the effort in building Mileage Stats was applied to the usability and rich interactivity of the experience. Animations were included to enhance the enjoyment of the site and Ajax is used to keep the interface responsive and immersive. A great deal of care was also taken to ensure that the client-side JavaScript was modularized for maintain- ability. To accomplish these design goals, the JavaScript code was structured using jQuery UI Widgets and JavaScript objects. Widgets allow you to break the UI into discrete state- ful objects that provide a clean separation of responsibilities and concerns. The Mileage Stats solution is partitioned into three layers: data, business, and web, spread across five Visual Studio projects pictured on the left side of the image below. Mileage Stats also includes four unit test projects for testing the C# projects, and a suite of JavaScript unit tests, pictured on the right side of the image below.
- 42. 9introduction Mileage Stats project and unit tests The design and implementation of the Mileage Stats solution is used for illustration throughout the guidance and will be covered in the remaining chapters. Now let’s walk through Mileage Stats from a user’s perspective. Using Mileage Stats Unauthenticated users accessing Mileage Stats will be redirected to the landing page to sign in. Mileage Stats uses third-party OpenID providers for user authentication. Mileage Stats supports deep linking, so that previously authenticated users returning to the web- site can go directly to any page. For Internet Explorer 9 users, Mileage Stats provides a customized pinned sites expe- rience that is accessed from the landing page. The image below shows the pinned site running in the pinned sites customized chrome of Internet Explorer 9. The menu, favorites bar, command bar, and status bar have been removed from view. The back and forward buttons are rendered with a custom color, and the site’s favicon is displayed to the left of the back button, which navigates to the landing page.
- 43. 10 chapter one Landing page The first time a new user logs into Mileage Stats, the summary pane will display the “Complete your Registration” form pictured below. This form will continue to be dis- played in the Summary pane until the user clicks the Save button. Further edits to the user’s profile can be made by clicking the Profile link at the top right of the browser window.
- 44. 11introduction Third-party authentication providers do not uniformly expose their user data to ap- plications requesting authentication services. For example, a user may have an OpenID account, but Mileage Stats may not be able to request information such as the user’s first and last name from the provider to populate the Display Name field. The UX designer did not want to force a new user to complete a form in order to use Mileage Stats. Instead, we implemented a non-intrusive form for collecting the new user’s name, country, and postal code. New users can immediately use Mileage Stats and can complete the registra- tion information at their leisure. First time logging in
- 45. 12 chapter one The dashboard provides a summary view of the user’s vehicles. From here the user can add a new vehicle, drill down to more detail for a vehicle, and see maintenance reminders that are overdue or due soon. There is a navigation bar at the top of the browser window that provides top-level navigation to the Dashboard, Charts, or Profile pages and a link to sign out of the application. Dashboard A high-value scenario for this guidance was to demonstrate fluid and rich UI transi- tions and animations. The image below shows the application transitioning from the Dashboard (two column vehicle listing) to the Details view (single column vehicle listing) in response to the user clicking the Details button in Hot Rod’s vehicle tile. The image demonstrates the synchronization of opacity and position animations as the summary pane, vehicle tiles, and info pane animate into their respective positions.
- 46. 13introduction Transitioning from the Dashboard to Details The Details view displays aggregated monthly trends for fuel efficiency, distance trav- eled, and fuel cost. Users are able to quickly see trends in their vehicle usage as well as overdue maintenance reminders. In addition to displaying maintenance reminders, the Details view allows users to edit or delete the vehicle, as well as navigate to the Fill ups and Reminders views.
- 47. 14 chapter one Details The Charts page provides three charts, which allow users to easily compare their ve- hicles’ fuel efficiency, distance travelled, and cost. The displayed data can be filtered by vehicle and date range. The data displayed in these charts is prefetched and cached, pro- viding a fast user experience.
- 49. 16 chapter one Exploring the QuickStart The Widget QuickStart is a small, focused application that illustrates the way Mileage Stats uses the jQuery UI Widget Factory to create maintainable widgets that implement client-side behavior. Exploring the Documentation This guidance covers a wide range of topics, including: planning and designing your ap- plication, understanding and writing jQuery UI Widgets, writing server-side code that supports the client-side application, patterns and concepts used in JavaScript code, data and caching, and securing and testing your application. The documentation includes the following: • Chapter 2, “Architecture.” This chapter explains the Mileage Stats client-side architecture by studying how its structure, modularity, communication, navigation, and data relate to one another. • Chapter 3, “jQuery UI Widgets.” An understanding of jQuery UI Widgets is important to comprehending this guidance and Mileage Stats because the applica- tion makes heavy use of widgets to modularize its JavaScript. This chapter provides instruction on widget fundamentals, lifetime, creation, events, properties and methods, and inheritance. It largely uses code examples from the Widget Quick- Start. • Chapter 4, “Design and Layout.” This chapter explains the importance of an itera- tive design process and the roles different team members fulfill. After a survey of user experience and UI design considerations, we will walk through the design and building of Mileage Stats and see how these considerations influenced the applica- tion. • Chapter 5, “Modularity.” Rich and interactive web applications can require a fair amount of JavaScript coding. Modularizing your JavaScript makes your code easier to maintain and evolve. In this chapter we will explain how the Mileage Stats JavaScript was modularized using jQuery UI Widgets and JavaScript objects. • Chapter 6, “Client Data Management and Caching.” This chapter covers how JavaScript objects in Mileage Stats request and send data. It also covers how the data manager façade performs the Ajax calls to the server and provides transparent data caching. • Chapter 7, “Manipulating Client-Side HTML.” This chapter discusses how an interactive application like Mileage Stats can manage client-side HTML changes without having to fully reload the page each time the user navigates or completes a task. • Chapter 8, “Communication.” This chapter explains how communication between widgets and JavaScript objects was implemented in Mileage Stats. Some topics include loosely coupled communication that uses the “publish and subscribe” metaphor, events, and inter-widget communication.
- 50. 17introduction • Chapter 9, “Navigation.” Rich web applications support client-side transitions, animations, and deep linking. Even when the site avoids the use of full-page re- freshes, users expect their browser back button to function as expected. This chapter explains the challenges client-side web developers face maintaining the browser history when using Ajax calls instead of full-page reloads. In addition, the Mileage Stats state-change management is fully explained. • Chapter 10, “Application Notifications.” Web applications that users consider responsive have one thing in common: they provide appropriate and timely feed- back to the user. In this chapter we show how to provide unobtrusive feedback to the user and how to implement notifications on the desktop with the Internet Explorer 9 Pinned Sites API. • Chapter 11, “Server-Side Implementation.” This chapter covers the Mileage Stats ASP.NET MVC application, the components it’s dependent upon, and the services they provide to support the client-side JavaScript objects. The chapter takes you from the database, through the repositories, to the business objects that provide data validation and data shaping services to the controllers that consume their data and render it to the client. • Chapter 12, “Security.” Web security is critical to consumer confidence. Poor security can cause your customer’s data, your own data, or your intellectual prop- erty to be compromised. This chapter covers some of the security features of the ASP.NET MVC platform and security features in Mileage Stats that provide coun- termeasures against the relevant threats for authentication, input validation, anti-forgery, and JavaScript Object Notation (JSON) hijacking. • Chapter 13, “Unit Testing Web Applications.” Unit tests are long-term investments that give the development team confidence when refactoring or evolving the application, and when updating external dependencies, such as when versions of external libraries are updated. This chapter is meant to help you get started unit testing JavaScript and ASP.NET MVC code. • Chapter 14, “Widget QuickStart.” This topic describes the Widget QuickStart and includes information on attaching widgets, widget initialization, and widget interac- tions. • “Project Silk Road Map.” This list helps you locate sections of the guidance by topic. • “Glossary.” This topic provides a summary of the terms, concepts, and technologies used in this guidance. The following topics are included with the Project Silk download and on MSDN: • “Readme.” This file contains instructions on installing external dependencies from NuGet and downloading the required external JavaScript libraries to build and run Mileage Stats. • “How to: Check UIElement Properties Using Coded UI Test.” This How-to topic walks you through the creation of an automated test that checks that UIElement properties in Mileage Stats are displayed with the correct values. It uses Coded UI Test that is available in Visual Studio 2010 Premium or Ultimate Edition.
- 51. 18 chapter one • “How to: Create an Automated Negative Test Case Using Coded UI Test.” This How-to topic walks you through the creation of an automated negative test case that checks the error handling capability of Mileage Stats. It uses Coded UI Test that is available in Visual Studio 2010 Premium or Ultimate Edition. • “How to: Create a Web Client UI Test Using Coded UI Test.” This How-to topic walks you through the creation of an automated test that verifies that the correct controls are displayed with the correct values. It uses Coded UI Test that is available in Visual Studio 2010 Premium or Ultimate Edition. • “Bibliography.” This is a summary of the resources referred to in the guidance. Community Project Silk’s community site is http://silk.codeplex.com. There, you can post questions, provide feedback, or connect with other users to share ideas. Community members can also help Microsoft plan and test future offerings. In addition, the community site has links to tutorial videos and MSDN content. Further Reading To download Project Silk source code and documentation, see “Project Silk: Client-Side Web Development for Modern Browsers” on MSDN at http://msdn.microsoft.com/ en-us/library/hh396380.aspx. If you have comments on this guide, visit the Project Silk community site at http://silk.codeplex.com. View a two minute video on Mileage Stats on Channel 9: http://channel9.msdn.com/posts/Project-Silk-Mileage-Stats-Application. Additional content is provided on MSDN: “Readme” file online at http://msdn.microsoft.com/en-us/library/hh404100.aspx. “How to: Check UIElement Properties Using Coded UI Test” online at http://msdn.microsoft.com/en-us/library/hh404081.aspx. “How to: Create an Automated Negative Test Case Using Coded UI Test” online at http://msdn.microsoft.com/en-us/library/hh404089.aspx. “How to: Create a Web Client UI Test Using Coded UI Test” online at http://msdn.microsoft.com/en-us/library/hh404082.aspx. For information on the designer role, see Chapter 4, “Design and Layout.” For information on unit testing, see Chapter 13, “Unit Testing Web Applications.” Crockford, Douglas. JavaScript: The Good Parts. O’Reilly Media, 2008. Stefanov, Stoyan. JavaScript Patterns. O’Reilly Media, 2010. “ASP.NET MVC 3 Overview, The Razor View Engine” on ASP.NET:
- 52. 19introduction http://www.asp.net/mvc/mvc3#BM_The_Razor_View_Engine “ASP.NET MVC 3 Overview, Dependency Injection Improvements” on ASP.NET: http://www.asp.net/mvc/mvc3#BM_Dependency_Injection_Improvements “Loosen Up: Tame Your Software Dependencies for More Flexible Apps” in MSDN Magazine: http://msdn.microsoft.com/en-us/magazine/cc337885.aspx “Entity Framework 4.1 Released” on the ADO.NET team blog: http://blogs.msdn.com/b/adonet/archive/2011/04/11/ef-4-1-released.aspx “Entity Framework 4.1 Update 1 Released” on the ADO.NET team blog: http://blogs.msdn.com/b/adonet/archive/2011/07/25/ef-4-1-update-1-released. aspx jQuery Documentation Main Page: http://docs.jquery.com/Main_Page ASP.NET MVC 3: http://www.asp.net/mvc/mvc3 NuGet version 1.4 or later: http://nuget.org/ Internet Explorer 9: http://windows.microsoft.com/en-US/windows/downloads/internet-explorer Modernizr: http://www.modernizr.com/ To access web resources more easily, see the online version of the bibliography on MSDN: http://msdn.microsoft.com/en-us/library/hh404094.aspx.
- 54. 21 Introduction The Mileage Stats Reference Implementation (Mileage Stats) is a cross-browser, ASP.NET Model-View-Controller (MVC) application that takes advantage of the features of mod- ern browsers. The application offers two types of user experiences: 1. A traditional website experience. In this approach, a form post and page reload are executed each time a button or hyperlink is clicked. 2. A rich website experience. In this approach, the initial page is loaded once, and server requests are only made when new data is required or updated. In addition to other user-friendly features, the lack of a full-page reload enables the animation of client-side state changes. The rich website approach provides a superior experience for the user, as the applica- tion feels more responsive and more like a desktop application. However, because some users do not have scripting enabled or available on their user agent (web browser or ac- cessibility tool, such as a screen reader), which is necessary for the partial-page reloads, we must also support the traditional website experience. In the traditional approach, the ASP.NET MVC controllers are responsible for acquir- ing data and for returning a built-up view that consists of HTML structure and data. In the case of the rich website experience, we perform asynchronous data requests and the controller returns only data. The client then renders the data in the user interface (UI) without reloading the whole page. Supporting both these experiences introduces complexity that requires careful plan- ning on both the client and server sides to ensure that the application is responsive, maintainable, has a clean separation of concerns, and is testable. You should determine early in the design phase which experience the user should expect in each browser and browser version the application will support. If you choose to support older browsers, you may limit your technology choices and affect the run-time experience of the application. Shims and polyfills, such as those that provide HTML5 support, are available for adding support for some technologies in older browsers, but these come at the cost of additional dependencies (see “Further Reading” at the end of the chapter to learn more about shims and polyfill solutions). Making decisions early on Architecture2
- 55. 22 chapter two about which technologies you will need to support allows you to establish realistic ex- pectations for users and project stakeholders. This chapter provides a high-level map of the Mileage Stats client-side architecture, and is divided into five areas of discussion: structure, modularity, communication, naviga- tion, and data. • Structure refers to client-side HTML structure and manipulation. It is represented below as the Template. • Modularity refers to how a clean separation of JavaScript objects helps create a more maintainable application. It is represented below as the Widget. • Communication defines how JavaScript objects communicate. It is represented below as Pub/Sub. • Navigation explains how to manage user gestures and coordinate animations. It is represented below as Navigation and the Layout Manager. • Data provides guidance for client-side data requests and data caching. It is repre- sented below as the Data Manager. Mileage Stats client architecture In this chapter you will learn: • Options and strategies for getting the right HTML to the client. • The advantages of modular code, and techniques for using jQuery UI widgets. • How the Publish/Subscribe (pub/sub) pattern can be used for loosely coupled communication.
- 56. 23architecture • How to solve browser history and back-button problems when the site doesn’t perform full-page reloads. • How a loosely coupled data layer can simplify caching for client-side data requests. • How the Mileage Stats team solved a number of challenges related to structure, modularity, communication, navigation, and data. The technologies and libraries discussed in this chapter are JavaScript, jQuery, jQuery UI Widgets, and jQuery Back Button & Query Library (jQuery BBQ). Structure Websites like Mileage Stats provide an engaging user experience when viewed using modern browsers with JavaScript enabled. The site can also be viewed without JavaScript enabled and will function when viewed in an older browser. To provide an engaging, responsive, and interactive experience, the application needs to manage client-side structure changes without performing full-page reloads. This re- quires client-side loading, creation, and replacement of HTML fragments or pages. To support both rich and traditional user experiences, the Project Silk team chose to have the web server generate the initial HTML; then, after using JavaScript to detect the browser capabilities, we enhanced the user experience in capable browsers by replacing the server-generated HTML structure with a client-side version. Elements replaced include portions of HTML, button actions, and CSS classes. Enhancement can mean add- ing animation, page transitions, or Ajax functionality to client-side elements. Client-side enhancement of server-generated HTML is called progressive enhancement. Progressive enhancement adds features to the client-side experience based on browser capabilities. After the initial enhancement of the server-generated HTML, the client-side Java Script responds to user gestures, requests data, and initiates UI changes without posting back to the server. Client-side UI structure can be generated with JavaScript, loaded on demand from the server, or rendered by a plug-in or a library. Initially, the team tried on-demand loading of granular HTML fragments from the server. This approach was motivated by the team’s desire to limit the creation of HTML to a single location. However, this approach failed to provide the desired result, so the team changed tactics and used jQuery templates instead. See Chapter 7, “Manipulating Client-Side HTML” for a full explanation of this choice. jQuery Templates jQuery templates are HTML markup with inline JavaScript expressions that are used to populate values in the markup. The jQuery Template plug-in applies data to the template and renders the output into the document object model (DOM). Mileage Stats uses jQuery UI widgets to coordinate the data retrieval, applying of the data to the template using the plug-in, and overwriting the DOM element.
- 57. 24 chapter two jQuery template rendering in Mileage Stats The data can be a single object or an array of objects. jQuery templates separate structure and data, making the application easier to code, test, and maintain. If you use ASP.NET MVC or ASP.NET Web Forms, you can use the rendering engine to dynamically create or modify the jQuery template while it’s being rendered. Mileage Stats uses this capability to inject URLs and data- (pronounced “data dash”) attributes into the templates at render time. Mileage Stats loads all jQuery templates as part of the initial page load. Preloading templates simplifies the client-side application and provides much faster client-side ren- dering than on-demand loading of templates. For more information on the jQuery Template plug-in and authoring templates, see “jQuery Templates” in the “Further Reading” section. For more information on jQuery templates in Mileage Stats, see Chapter 7, “Manipulating Client-Side HTML.” Modularity Modularized code simplifies the overall application, establishes clear boundaries of re- sponsibility, provides separation of concerns, increases testability, eases maintenance, and enables reuse. The modularization of code in Mileage Stats is achieved by composing client-side JavaScript into jQuery UI widgets and JavaScript objects. jQuery widgets are objects attached to page elements that supply services for managing lifetime, state, inheritance, theming, and communication with other widgets or JavaScript objects. Objects in Mileage Stats belong to one of the following functional categories:
- 58. 25architecture • UI. Includes these jQuery UI widgets: vehicle, vehicle list, information pane, vehicle details, vehicle fill ups, vehicle reminders, registration, statistics, summary, status, header, and charts. • Behavior. Includes the tile and layout manager widgets, and JavaScript objects for pinned sites and validation. • Infrastructure. Includes JavaScript objects for data access, caching, and pub/sub messaging. The jQuery widgets that compose the Mileage Stats Dashboard are pictured in the image below. The complexity of the application demonstrates the need for modulariza- tion. By breaking the implementation into discrete, loosely coupled objects, the client- side code is much easier to understand, author, maintain, test, and debug. 1. Pinned sites. JavaScript object that provides the pinned sites implementation for Windows® Internet Explorer® 9. 2. Status widget. Provides management and display of user notification messages. 3. Summary widget. Acts as a container, managing its child registration, statistics, and reminders widgets. 4. Statistics widget. Displays summary statistics for all vehicles. 5. Reminders widget. Lists overdue and upcoming maintenance reminders. Manages the action of clicking on a reminder. 6. Layout manager widget. Services navigation requests and coordinates UI layout changes. 7. Vehicle list widget. Displays the vehicle tiles in a one-column or two-column listing. Invokes the child widget animation when required and controls when child widgets are displayed in expanded or contracted view. 8. Tile widget. Provides drag-and-drop capability for the child vehicle widget. 9. Vehicle widget. Displays vehicle information in expanded or contracted view. Manages the actions of each button. 10. Header widget. Provides top-level navigation and user name display. Manages actions when a hyperlink in the header is clicked.
- 59. 26 chapter two Modularization in Mileage Stats For more information on modularity in Mileage Stats, see Chapter 5, “Modularity.” For more information on jQuery UI widgets see Chapter 3, “jQuery UI Widgets” and Chapter 5, “Modularity.” For more information on pinned sites, see Chapter 10, “Applica- tion Notifications.” Communication jQuery widgets and JavaScript objects help you modularize your code, but these objects are not isolated islands; rather they are small objects that work together to form the complete application. Well-defined communication between objects is critical not only from a functional view, but from an architectural view as well. If not carefully planned, communication between objects can lead to tight coupling and undesirable dependencies. Mileage Stats objects either communicate directly with one another, or loosely by using a publish and subscribe pattern (pub/sub).
- 60. 27architecture Direct Communication Direct widget communication is typically reserved for high-level widgets controlling lower-level widgets, such as when the layout manager tells a widget to hide or show itself. Layout manager and pub/sub Loose Communication Pub/sub is a messaging pattern that enables loose communication between publishers and subscribers. When a message is published, zero or more subscribers will be notified. A pub/sub object manages communication, relieving the publishers and subscribers of need- ing direct knowledge of one another. Pub/sub messages are individually defined and can optionally contain a payload. The pub/sub pattern provides clean separation between the object invoking the ac- tion and the object that handles the action. This separation allows the publisher and subscriber’s internal implementations to evolve without affecting each other. Mileage Stats has its own pub/sub implementation that provides for loose communi- cation. For example, the Status widget subscribes to the status message. The status message has a payload that contains message, type, duration, and priority values. Publish- ers of the status message provide these values when publishing this message. Mileage Stats widgets have publish and subscribe functions passed into their options object during construction to decouple them from the pub/sub implementation. For more information about the pub/sub implementation in Mileage Stats, see Chapter 8, “Communication.” Navigation Rich client-side web applications like Mileage Stats do not perform full-page reloads each time a button or hyperlink is clicked. Instead, client-side application code handles these events. The jQuery BBQ plug-in is responsible for providing address bar URL changes. Chang- ing the address bar URL performs two functions. First, it allows users to bookmark ad- dresses so that they can return directly to a particular application state. This is known as deep linking. Second, it enables the browser history and back button to perform as the user expects. The Mileage Stats layout manager is a widget that works in conjunction with the BBQ plug-in to service navigation requests. It subscribes to the BBQ plug-in hashchange event, and initiates layout changes based on address bar URL changes.
- 61. 28 chapter two Navigation and layout manager Along with hiding and showing UI elements, the layout manager is also responsible for initiating UI animations during navigation. The layout manager does not perform the animation, but sequentially calls methods on one or more lower-level widgets, resulting in an engaging UI transition. As part of the layout manager’s top-level widget responsibilities, it subscribes to several pub/sub messages and invokes lower-level widget data refresh methods when those messages are published. For more information about navigation and the layout manager, see Chapter 9, “Navigation.” Data When designing your client-side data architecture, several key decisions will impact ap- plication performance, maintainability, and browser support. Will data requests flow through a central object or will objects make direct calls to the server? Will data be cached, and if so, how much? Will data be prefetched, and if so, how much? Answers to these questions will vary based on your application’s specific requirements. In Mileage Stats, all data requests are made via Ajax and are routed through the data manager. Having a single object handle data requests simplifies the client-side calling code, improves application testability, and facilitates cleaner application evolution when client- side libraries advance or change. The single data manager object also affords you the op- portunity to implement client-side data caching in a central location. Data is cached in a JavaScript object, rather than using HTML5 local storage or similar APIs, in order to meet the cross-browser requirements of the application. Mileage Stats prefetches chart data during the initial page load, enabling instant ap- plication response when the user navigates to the Charts page. Whenever data is returned from the server, it’s cached. This can make the application more scalable because re- peated requests to the server for the same data are no longer necessary, requiring less server processing per user. Widgets and JavaScript objects request their data from the data manager. The data manager services the request, first checking if the request should be cached, and if so, checks the cache before making a call to the server. Upon successful completion of the request, the returned data will be added to the cache, and then passed to the calling widget. If an error occurs, the error will be returned to the calling widget.
- 62. 29architecture Data request For in-depth coverage of data management and caching, see Chapter 6, “Client Data Management and Caching.” Architectural Alternatives The Project Silk team built Mileage Stats using jQuery UI Widgets as a way to provide modularity in JavaScript while keeping external dependencies on other libraries to a minimum. This is an effective way to separate different client-side concerns and facilitates testability and readability of the code base. This approach worked well for Mileage Stats, but it isn’t the only option. A common UI design pattern separates the application’s user content (the model) from the details that dictate how that information is displayed (the view). This separation necessitates logic that connects these two concepts (the controller). The MVC pattern has been implemented as described here and has also been adapted to specialized uses such as data binding that have resulted in similar patterns such as the Model View View- Model (MVVM) pattern. There are popular JavaScript libraries such as Backbone.js and Knockout.js that, for all intents and purposes, implement the MVC and MVVM patterns, respectively. There are also more comprehensive JavaScript frameworks such as Sprout- Core, YUI, and the Dojo Toolkit that aim to address more aspects of the client-side application in a single framework rather than using various libraries, each with a specific purpose.
- 63. 30 chapter two The use of these libraries does create more dependencies, but this usually has a posi- tive impact on the overall design of the application by making it easier to control the separation of concerns that is so important to complex user interfaces. If your UI has a number of screens made up of multiple regions and includes complex interaction patterns, and having additional dependencies is acceptable to you, you should consider applying these patterns and using these libraries. A design the Project Silk team is interested in investigating in the future involves the use of jQuery UI Widgets that can be data bound within an MVVM implementation such as Knockout.js. Summary Building a rich web application that reduces the number of full-page loads, includes anima- tions, and is responsible for updating the UI dynamically requires a thoughtful approach to managing structure, modularity, communication, navigation, and data. This chapter provided a high-level view of the Mileage Stats client-side application architecture. The following image shows the client-side objects and their implementation mapped to librar- ies or frameworks. Mileage Stats client architecture technology map
- 64. 31architecture Further Reading For more information on jQuery UI widgets see Chapter 3, “jQuery UI Widgets,” and Chapter 5, “Modularity.” For more information on jQuery templates in Mileage Stats, see Chapter 7, “Manipulating Client-Side HTML.” For more information on pinned sites, see Chapter 10, “Application Notifications.” For more information on modularity in Mileage Stats, see Chapter 5, “Modularity.” For more information about the pub/sub implementation in Mileage Stats, see Chapter 8, “Communication.” For more information about navigation and the layout manager, see Chapter 9, “Navigation.” For more information about data management and caching, see Chapter 6, “Client Data Management and Caching.” For more information about the libraries and guidelines discussed in this chapter, see the following: jQuery: http://jquery.org jQuery Templates: http://api.jquery.com/category/plugins/templates/ Backbone.js: http://documentcloud.github.com/backbone/ Knockout.js: http://knockoutjs.com/ SproutCore: http://www.sproutcore.com YUI: http://developer.yahoo.com/yui Dojo Toolkit: http://dojotoolkit.org “jQuery BBQ: Back Button & Query Library” on Ben Alman’s blog: http://benalman.com/projects/jquery-bbq-plugin/ “Filling the HTML5 Gaps with Polyfills and Shims” from Rey Bango’s MIX11 session: http://channel9.msdn.com/Events/MIX/MIX11/HTM04 “Making HTML5 and CSS3 work with polyfills and shims” by Rey Bango on .net magazine: http://www.netmagazine.com/features/making-html5-and-css3-work-polyfills-and-shims To access web resources more easily, see the online version of the bibliography on MSDN: http://msdn.microsoft.com/en-us/library/hh404094.aspx
- 66. 33 jQuery UI Widgets3 Introduction When building rich, client-side web applications, some of the visual elements on the page will naturally take on roles, responsibilities, and state. As more of these elements are added to the page, complexity will increase, so it’s important for the design to support a maintainable code base. Maintainable solutions have at least three important characteris- tics: they have an intentional design, are modular, and they have unit tests. All of these characteristics should play to the strengths of the platform, language, and key parts of the environment. The web browser is the platform, JavaScript is the language, and various JavaScript libraries represent key parts of the environment. Among other benefits, libraries such as jQuery and jQuery UI can simplify the code you write by: • Decreasing the amount of code you need to write and maintain. • Addressing typical challenges, such as browser compatibility issues. • Providing consistency for Ajax interactions, animations, and events. • Assisting in creating a maintainable code base through modularity. A concept that is central to the visual parts of jQuery UI is the widget. According to the official jQuery UI project, jQuery UI “provides abstractions for low-level interaction and animation, advanced effects and high-level, themeable widgets, built on top of the jQuery JavaScript Library, that you can use to build highly interactive web applications.” Widgets are objects attached to page elements that supply services for managing lifetime, state, inheritance, theming, and communication with other widgets or JavaScript objects. One of the most valuable aspects of jQuery is that extensibility is built in and well defined. This extensibility is accomplished through the construction of jQuery plug-ins. Even though they have a number of extra features in addition to those in a typical jQuery plug-in, it’s important to know that a widget is a jQuery plug-in. This may not be obvious because a widget is defined differently, but they are used the same way you use official jQuery methods and most custom plug-ins. Sometimes a plug-in is sufficient and other times a widget is more appropriate. When you need to apply behavior or state to indi- vidual elements and need to communicate between elements, widgets provide a number of capabilities you would otherwise have to write yourself. This chapter illustrates these
- 67. 34 chapter three capabilities. See the “Further Reading” section at the end of the chapter for more informa- tion about jQuery plug-ins and how to author them. In this chapter you will learn: • How to define and apply widgets. • How to manage the lifetime of widgets. • How to define default options that permit overrides and change notifications. • How to use options for decoupling behavior and facilitating event subscriptions. • How to use private methods to improve the readability of the code. • How to define and use public methods, properties, and events. • How to inherit from a base widget. The technologies discussed in this chapter are jQuery Plug-ins and the jQuery UI Widget Factory. The code examples used here largely come from the Widget QuickStart included with Project Silk. Widget Fundamentals If you know how to use jQuery, you know how to use a widget. In practical terms, a jQuery UI widget is a specialized jQuery plug-in. Using plug-ins makes it easy to apply behavior to the elements they are attached to. However, plug-ins lack some built-in capa- bilities, such as a way to associate data with its elements, expose methods, merge options with defaults, and control the plug-in’s lifetime. Widgets have these capabilities built in. A plug-in can be made to have the same features as a widget, but you must add these capabilities yourself. However, before you can use a widget, it must be defined. Once it has been defined, it can be applied to elements. Widgets are defined using the widget factory. When the widget factory is invoked, it creates a widget method on the jQuery prototype, $.fn, the same place that plug-ins and other jQuery functions are located. The widget method represents the primary interface for applying the widget to elements and using the widget after it’s applied. This important concept is covered in more depth in “The Widget Method” later in the chapter. Unlike other chapters, this chapter uses the Widget QuickStart for the code examples rather than the Mileage Stats Reference Implementation (Mileage Stats). The focus of the Widget QuickStart is to enable the client-side behavior for tagged keywords. When a user hovers over a keyword, the browser will display a pop-up list of popular links for that keyword from the Delicious.com bookmarking service. The following figure illustrates the QuickStart and the corresponding widgets.
- 68. 35jquery ui widgets The tagger and infobox widgets displayed The page accomplishes this through the use of two widgets: • tagger adds the hover behavior to the tagged keywords. • infoBox retrieves the links and controls the box that displays them. For more information about the QuickStart or to walk through the process of build- ing it, see Chapter 14, “Widget QuickStart.” Defining a Widget The dependencies for a widget can be fulfilled with script references to the content delivery network (CDN) locations for jQuery and jQuery UI. Widgets often reside in their own .js file and are wrapped in an immediate function, as you can see in the follow- ing code example. This wrapper creates a JavaScript closure, which prevents new variables from being globally scoped. A single solution should allow no more than one global object to be created, as per well-accepted JavaScript practices. The jQuery argument at the end of the following code example becomes the $ argu- ment passed in, which allows you to use the common $ symbol to represent the jQuery function. Because there is no second argument, the undefined argument becomes truly undefined. Therefore the $ and undefined arguments reestablish their expected behavior inside the closure in case another script previously defined these variables as something else.
- 69. 36 chapter three JavaScript // Contained in jquery.qs.tagger.js (function($, undefined) { $.widget('qs.tagger', { // definition of the widget goes here }); }(jQuery)); The call to $.widget invokes the widget factory, which makes the widget available for use. The first argument, qs.tagger, is the widget’s namespace and name separated by a period (namespace.name). The name is used as the name of the widget method placed on the jQuery prototype. The second argument, called the widget prototype, is an object lit- eral that defines the specifics of the widget. The widget prototype is the definition of the widget, and is used when the widget is applied to elements. The prototype is stored di- rectly on the jQuery object under the namespace provided: $.qs.tagger. Using a Widget Once a widget has been defined, it’s ready to be applied to DOM elements. To apply the widget to the matched elements, invoke the widget method just like you would other jQuery methods. The following code shows how to apply the tagger widget to all span elements with a data-tag attribute. JavaScript // Contained in startup.widget.js $(‘span[data-tag]’).tagger(); Because the widget method is used as the primary interface to the widget, it’s not only called when initially applying the widget to the element, it’s also used for calling methods and reading and writing options and properties on the widget. When widgets are applied to elements, an instance of the widget is created and stored inside each ele- ment. This is how the widget factory knows if a widget has already been attached to an element. Managing Lifetime There are three phases of a widget’s lifetime that you can control: creation, initialization, and destruction. Creation The first time the widget is applied to an element, the widget’s _create function is in- voked. Method names preceded with an underscore have private scope by convention, which means they only expect to be invoked from inside the widget. The following code shows the _create method in the infobox widget.
- 70. 37jquery ui widgets JavaScript // Contained in jquery.qs.infobox.js _create: function () { var that = this, name = this.name; that.infoboxElement = $('<div class="qs-infobox" />'); that.infoboxElement.appendTo('body') .bind('mouseenter.' + name, function () { mouseOverBox = true; }) .bind('mouseleave.' + name, function () { mouseOverBox = false; that.hideTagLinks(); }); }, Note: The that variable is defined to capture a reference to the widget so it can be accessed within the mouseleave event handler. Inside the event handler this refers to the element that raised the event, not the widget. An alternative to using that is to use the jQuery.proxy function. This function, according to the jQuery API documentation at http://api.jquery.com/jQuery.proxy/, “takes a function and returns a new one that will always have a particular context.” When used with event handlers, the widget can be used as the context, and event. target, which is normally this inside the event handler, can be used to reference the object that raised the event. The _create method is the most appropriate place to perform a number of common tasks: • Adding classes to various elements the widget is attached to is the recommended way to apply styling, layout theming, and more to the widget. • Storing references to commonly accessed elements can increase performance when a particular set of elements is used from a number of methods. Simply create object-level variables for them once, and all other methods can use them. This is an accepted jQuery performance best practice. • Creating elements in the DOM is common for widgets that have requirements such as animations, effects, styling, accessibility, and cross-browser compatibility. As an example, consider the div.qs-infobox element created by the infobox widget. • Applying other widgets is recommended during creation when your widget relies on other widgets. Even if your widgets don’t require each other, consider using the standard jQuery UI widgets from inside yours to add useful behaviors and interac- tions.
- 71. 38 chapter three Initialization The _init method is called after _create when the widget is first applied to its elements. The _init method is also called every time thereafter when the widget is invoked with no arguments or with options. This method is the recommended place for setting up more complex initialization and is a good way to support reset functionality for the widget if this is required. It’s common for widgets to not implement an _init method. Destruction The widget’s destroy method is used to detach a widget from an element. The goal of the destroy method is to leave the element exactly like it was before the widget was at- tached. Therefore, it’s not surprising that common tasks are to remove any CSS classes your widget added to the element, detach any elements your widget added to the DOM, and destroy any widgets your widget applied to other elements. Here is the destroy method for the tagger widget. JavaScript // Contained in jquery.qs.tagger.js destroy: function () { this.element.removeClass('qs-tagged'); // if using jQuery UI 1.8.x $.Widget.prototype.destroy.call(this); // if using jQuery UI 1.9.x //this._destroy(); } The last part calls the widget’s base implementation of destroy and is a recom- mended practice when you provide your widget with a destroy method. The base destroy method will be called if you don’t define one for your widget or if you explicitly call it, as in the code example above. The base implementation will remove the instance of the widget from the element and unbind all namespaced event bindings (this topic is discussed in more detail later in this chapter). Defining Options Options give widgets the ability to be extended with values and functions from the JavaScript code that creates and uses the widget. Options are automatically merged with the widget’s default options during creation, and the widget factory supports change notifications when option values change. Options and their default values are defined in the options property of the widget prototype, as shown below in the infobox widget. JavaScript // Contained in jquery.qs.infobox.js $.widget('qs.infobox', { options: {
- 72. 39jquery ui widgets dataUrl: '' maxItems: 10, }, ... To override default options during the creation of the widget, pass them in as an object literal to the widget method, as shown in this startup code of the widget. JavaScript // Contained in startup.widget.js var infobox = $('body').infobox({ dataUrl: 'http://feeds.delicious.com/v2/json/popular/' }); To read the options from inside the widget, use the options property directly, as shown in the last line of this code. JavaScript // Contained in jquery.qs.infobox.js displayTagLinks: function (event, tagName) { var i, that = this, options = that.options, url = options.dataUrl + tagName + '?count=' + options.maxItems, ... Reading the values directly from options is acceptable when reading values from in- side the widget, but you should not use this approach when changing the value of options. Instead, use the option method (without an ‘s’). JavaScript // Code illustration: not in QuickStart var max = this.option('maxItems'); this.option(‘maxItems’, max + 4); The option method is called with one argument when reading an option’s value, two arguments when setting a value, and a single object hash when setting more than one option. The option method should always be used to change the value of options so that change notifications will work as expected. Changing the option directly on the options property bypasses the notification mechanism. When Options Change The options on your widgets should be aware that their values can change and should be prepared when they do. To respond to changes, widgets use the _setOption method. This method is called by the widget factory just after the value has been set on the options property. The Widget QuickStart doesn’t have a need for _setOption; but, as an example, if the number of links in the infobox widget were configurable by the user, the widget might need to adjust the size of the box when maxItems changes.
- 73. 40 chapter three JavaScript // Code illustration: not in QuickStart _setOption: function (name, value) { if(name === 'maxItems') { this._resizeBoxForMaxItemsOf(value); } $.Widget.prototype._setOption.apply(this, arguments); }, In the code above, if maxItems is the name of the option being set, the _resizeBox ForMaxItemsOf method will be called. Rather than placing a lot of code in the _set Option method, you should place the logic in private methods. This allows you to call the logic from other places that might need it, such as _create. The last line calls the base widget’s _setOption method. This will set the value of the option and will be useful for supporting a disabled state. Note: All widgets support the notion of being disabled, whether they choose to implement it or not. The Boolean value is stored at this.options.disabled or $(selec- tor).widget(‘option’, ‘disabled’) if you’re asking from the outside. In return for honoring this option (whatever that would mean for the user interface (UI) and behavior of your widget) the widget factory will default it to false and manage some CSS classes related to theming and accessibility. The _setOption method is not called for the options passed in during the creation of the widget. Functions as Options Defining functions as options is a powerful way to decouple the widget from functional- ity better located elsewhere. Note: The widgets in Mileage Stats use this approach for publishing and subscribing to global events by using their publish and subscribe options and getting data from the dataManager using their sendRequest option. To learn more about the pub/sub engine, see Chapter 8, “Communication.” For more details on the dataManager, see Chapter 6, “Client Data Management and Caching.” For example, rather than forcing the tagger widget to know how to get a reference to the infobox widget and invoke the public methods on the infobox widget, the widgets can be kept free of any knowledge of each other by passing in the functions from the startup script, since the startup script already knows about both widgets. To set this up, the tagger widget defines activated and deactivated options. JavaScript // Contained in jquery.qs.tagger.js $.widget('qs.tagger', { options: { activated: $.noop, deactivated: $.noop },
- 74. 41jquery ui widgets Just like normal options, these can either define defaults or omit them. The use of $.noop as a default value saves you the effort of having to ensure that the value isn’t null before calling the option. Calling $.noop has no effect and won’t throw any exceptions. The startup script will provide these options when it applies the tagger widget to the span elements, as shown here. JavaScript // Contained in jquery.qs.tagger.js $('span[data-tag]').tagger({ activate: function (event, data) { // call displayTagLinks() on infobox here }, deactivate: function () { // call hideTagLinks() on infobox here } }); In the code examples above, the options are defined inside the widget’s implementa- tion and passed in during creation. Later in this chapter you’ll see how function-based options are used as callbacks for events. The Widget Method Well-designed objects have public interfaces that are intentional, intuitive, and focused. Widgets go one step further and provide a single method, referred to as the widget method, which is the entire public interface of the widget. The action the widget performs when you call this method depends on the number and type of arguments provided in the call. In addition to creating and initializing the widget, as shown earlier, the widget method is also used to do the following: • Invoke public methods • Read and write public properties • Read and write options Public Methods Public methods are defined on the widget prototype, as you can see here in the infobox widget. The public methods are hideTagLinks and displayTagLinks. JavaScript // Contained in jquery.qs.infobox.js $.widget('qs.infobox', { hideTagLinks: function() { ... }, displayTagLinks: function(event, tagName) { ... }
- 75. 42 chapter three Widgets must be created before their methods can be called. The following calls to the infobox widget assume the widget method has already been called once to apply the widget to the body element. To call hideTagLinks from outside the widget, use a jQuery selector to match the element and pass the name of the method to the widget method as its only argument. JavaScript // Code illustration: not in QuickStart $(‘body’).infobox(‘hideTagLinks’); When you need to pass any arguments into the call, such as displayTagLinks, simply add the arguments after the method name. JavaScript // Code illustration: not in QuickStart $(‘body’).infobox(‘displayTagLinks’, event, tag.name); The option method covered earlier (in the section “Defining Options”) is an example of a public method. When one argument is passed to it, the method will return the value of that option. When two arguments are passed, it will set the option specified in the first argument to the value of the second argument. When calling the option method from outside the widget, pass the method name as the first argument, the name of the option as the second, and the value as the third argument, as shown here. JavaScript // Code illustration: not in QuickStart $(‘body’).infobox(‘option’, ‘maxItems’, 10); Public methods can also return values by placing the expression on the right-hand side of the assignment operator (=). Returning a value from methods on infobox is reasonable because infobox is only attached to a single element. But be aware that if you call a method on a wrapped set that contains more than one element, the method will only be called on and returned from the first element. In the examples so far, each time the widget method is invoked it is being called on the instance returned by the jQuery function, $(selector), which requires accessing the DOM. The next section recommends a couple of alternatives. Reusing an Instance Each time the jQuery function uses a selector to invoke the widget method, it must search the DOM. This has a negative impact on performance and is unnecessary because widget methods return a jQuery object, which includes the wrapped set of matched elements. JavaScript // Code illustration: not in QuickStart var ib = $('body').infobox(); // queries the DOM ib.infobox(‘displayTagLinks’); // does not query the DOM
- 76. 43jquery ui widgets Rather than use a selector with the jQuery method each time you need to call a method on a widget, create a variable when the widget is initially attached to the ele- ments. The DOM will be accessed during this initialization, but it should be the only time you need to access it. In subsequent calls, such as the second line in the snippet above, you can call the widget method on the variable you created and it won’t access the DOM. Using the Pseudo Selector In a situation where neither the selector nor the instance is available, there is still a way to obtain all instances of a particular widget. As long as you know the name of the widget, you can use a pseudo selector to get all instances that have been applied to elements. JavaScript // Contained in an older, more tightly coupled version of startup.js $('body').infobox(); // Contained in an older, more tightly coupled version of jquery.qs.tagger.js var ibInstance = $(':qs-infobox'); ibInstance.infobox('displayTagLinks', // method name $(this).text(), // tag event.pageY + offsetY, // top event.pageX + offsetX); // left A pseudo selector begins with a colon, followed by the widget’s namespace and name separated by a hyphen. The pseudo selector in the example above is :qs-infobox. Pseudo selectors have the potential to increase coupling between widgets, so be aware of this if you intend to use them. Private Members Private methods and properties have private scope, which means you can only invoke these members from inside the widget. Using private members is a good idea because they improve the readability of the code. Methods Private methods are methods that start with an underscore. They are expected to be ac- cessed directly using the this keyword. Private methods are common and recommended. Private methods are only private by convention and cannot be enforced. This means that if a widget isn’t called according to the convention for calling public methods (de- scribed later), its private methods can still be accessed. The convention is easy and con- sistent, and the underscore makes it easy to distinguish between the public and private interface.
- 77. 44 chapter three Properties Methods are designated as private by using underscores. Unlike methods, properties on the widget prototype are private by default; they are not designated private by prepend- ing an underscore. The reason properties don’t need underscores is that they cannot be accessed through the widget method. JavaScript // Code illustration: not in QuickStart $.widget('qs.infobox', { dataUrl: '', // should only be accessed using this.dataUrl _maxItems: 10 // unnecessary; properties are already private }); Because each element contains its own instance of the widget, the dataUrl property can be different for each element. Clearly dataUrl is best exposed as an option, but if this was not a configurable option you would probably want to define it so that only one copy of the value is available to all instances of the widget. Let’s call these static members. Static Members To define a variable that’s available to all instances of the widget, but nowhere else, place them inside the self-executing function wrapper and above the call to the widget factory, as shown in the tagger widget. JavaScript // Contained in jquery.qs.tagger.js (function ($) { var timer, hideAfter = 1000; // ms $.widget('qs.tagger', { ... Because the timer variable is defined outside the widget prototype, only a single timer will be created and shared across all instances of the tagger widget. Functions that don’t rely on the instance of the widget can also be defined here. If you need access to static members from outside the widget, they can be added to the widget after the widget’s definition. They are defined afterwards because they extend the widget, as you will see in a moment. Let’s make a fictitious change to the infobox widget to illustrate this by moving an isolated function to a more accessible location. Inside the displayTagLinks method in the infobox widget, a function variable called displayResult is defined.
- 78. 45jquery ui widgets JavaScript // Contained in jquery.qs.infobox.js var displayResult = function () { elem .html(html); .css({top: top, left: left}); .show(); }; The variable, displayResult, is defined in displayTagLinks because this is the only method that uses it. In our fictitious change, let’s say the infobox widget needs to make Ajax calls from other methods. That means the displayResult function will need to be moved so that it is available to all methods that need it. Defining it as a static member outside the scope of the widget is a way to make this happen. JavaScript // Code illustration: not in QuickStart $.widget('qs.infobox', { ... }); $.extend($.qs.infobox, { displayResult: function(elem, html, top, left) { elem .html(html); .css({top: top, left: left}) .show(); } }); The $.extend method is used to merge the object passed as the second argument into the object passed as the first argument. Therefore, the displayResult method is merged into the prototype of the widget, $.qs.infobox. With displayResult defined here, the infobox widget can use it from anywhere, as shown in this code. JavaScript // Code illustration: not in QuickStart // assume elem, html, top, and left variables were already defined $.qs.infobox.displayResult(elem, html, top, left);
- 79. 46 chapter three Events Events are an effective way to communicate between widgets without forcing them to be tightly coupled. jQuery supports and extends the DOM event model and provides the ability to raise and handle custom events that are not defined in the DOM. Raising the Event A widget raises events by using the _trigger method. The first argument to _trigger is the name of the event you are raising. If the event you are raising originates from a DOM event, the DOM event can optionally be passed as the second argument. The third argu- ment is any data to be passed to the event handler and is also optional. The following code sample shows one way the tagger widget might raise the activated event when the mouse enters the element. JavaScript // Code illustration: not in QuickStart _create: function () { var that = this, tag = that.infoboxElement.text(); that.infoboxElement .bind('mouseenter', function (event) { that._trigger('activated', event, {name: tag}); }); }, In this fictitious code example, infobox is raising an activated event by binding to the mouseenter event of an element. You can also use bind, as well as the live and delegate methods, to handle events triggered from widgets. Binding Handlers Event handlers bind to widget events the same way as they bind to other events, although the name of the event is influenced by the widget’s name. JavaScript // Code illustration: not in QuickStart $('span[data-tag]').bind('taggeractivated', function(event, data) { // handle the event }); Notice how the name of the event being bound to has the name of the widget pre- pended. This is the default behavior for event names. If you prefer a different name so that your code is more readable, this behavior can be changed, as shown in the following section.
- 80. 47jquery ui widgets Event Naming The widgetEventPrefix property defines what will be prepended to the names of the events the widget raises. By default, the value is the name of the widget and is set by the widget factory. If you want to use something other than the widget name, simply define this property and provide an alternative value. JavaScript // Contained in jquery.qs.tagger.js $.widget('qs.tagger', { widgetEventPrefix: 'tag', ... When widgetEventPrefix has a value, it will be used instead of the widget name. The code that uses this widget and binds to its activated event will use the event name tagactivated. Options as Callbacks When options are defined as functions and the option name corresponds to an event name (without the prefix), they are referred to as callbacks. The _trigger method on the base widget will automatically invoke the callback whose name matches the event being raised. JavaScript // Contained in jquery.qs.tagger.js widgetEventPrefix: 'tag', options: { activated: $.noop, deactivated: $.noop }, _create: function () { var that = this, name = this.name(), tag = this.element.text(); this.element .bind('mouseenter.' + name, function (event) { that._trigger('activated', event, {name: tag}); }); }, The JavaScript that creates the tagger widget can now define the handler for the activated and deactivated events when it creates the widgets.
- 81. 48 chapter three JavaScript $('span[data-tag]').tagger({ activated: function (event, data) { infobox.infobox('displayTagLinks', event, data.name); }, deactivated: function () { infobox.infobox('hideTagLinks'); } }); This allows the two widgets to interact without explicitly knowing about each other. Using this approach causes the script that invokes the widgets to act as connective tissue that describes a lot about the solution in a succinct, readable format. Inheritance Sometimes, when building a widget, another widget already has many properties and much of the functionality the new widget requires. The widget factory’s inheritance sup- port is designed for this case. For illustration purposes, consider the following widget. JavaScript // Code illustration: not in QuickStart (function ($) { $.widget('a.container', { ... resize: function() { // resize width and height }, ... }); }(jQuery)); If this widget was built elsewhere and you wanted to change its resizing behavior to an animation, a reasonable approach would be to inherit from a.container and override its resize method. Inheritance is accomplished by passing three arguments into the widget factory. The first argument is the namespace and name of the widget, the second is the prototype of the widget you want to extend from, and the third argument is the object you want to extend it with.
- 82. 49jquery ui widgets JavaScript // Code illustration: not in QuickStart (function ($) { $.widget('an.animatedContainer', $.a.container, { ... resize: function() { // override with animations } }); }(jQuery)); The only difference between the signature above and the signature usually used for defining widgets is the addition of the second parameter. Inheritance is a useful tool when you are using a widget that almost does what you want it to do. In version 1.9 of jQuery UI, widgets can inherit from themselves. This makes it easy to add functionality to a widget for your application without the need of changing the original implementation. The jQuery UI bridge method allows you to retain the name of the original widget to be used with your specialized widget. Summary Using jQuery UI widgets is a great way to add modularity to client-side web applications. Widgets are objects that attach to page elements and supply services for managing life- time, state, inheritance, theming, and communication with other widgets or JavaScript objects. Options give widgets the ability to have state that is public, readable, writable, and callable. Options are automatically merged with the widget’s default options during cre- ation, and the widget factory supports change notifications when option values change. In addition, defining functions as options is a powerful way to decouple the widget from functionality better located elsewhere. Widgets provide just a single method that represents the entire public interface of the widget. Widgets also allow for private methods that can only be invoked from within the widget. jQuery supports and extends the DOM event model and provides the ability to raise and handle custom events that are not defined in the DOM. Widgets can trigger and handle these events and options can be used as callbacks. Finally, widgets can inherit from other widgets, and in jQuery UI version 1.9, a widget can inherit from itself.
- 83. 50 chapter three Further Reading For more information about the QuickStart or to walk through the process of building it, see Chapter 14, “Widget QuickStart.” For more information about the pub/sub engine, see Chapter 8, “Communication.” For more information on the dataManager, see Chapter 6, “Client Data Management and Caching.” Widget Factory documentation on the jQuery UI wiki: http://wiki.jqueryui.com/w/page/12138135/Widget-factory jQuery Documentation for Plugins/Authoring: http://docs.jquery.com/Plugins/Authoring jQuery UI Developer Guidelines: http://jqueryui.com/docs/Developer_Guide jQuery UI source code: https://github.com/jquery/jquery-ui To access web resources more easily, see the online version of the bibliography on MSDN: http://msdn.microsoft.com/en-us/library/hh404094.aspx. Resources Microsoft Ajax Content Delivery Network (CDN) addresses: http://www.asp.net/ajaxlibrary/cdn.ashx
- 84. 51 Introduction The development of rich, responsive web applications requires an iterative design process to create applications that result in a user interface (UI) design that harmonizes beauty, simplicity, symmetry, and consistency. The combination of new web technologies and innovations in web browsers makes it possible for designers and developers to comple- ment their UI with an engaging and intuitive user experience (UX). The design process includes the collaboration of stakeholders and team members with different skills and perspectives. If your team invests in a design process, you are more likely to create an application that users enjoy, find useful, and continue to use. A goal of this chapter is to illustrate the importance of the design process, and UI and UX designer roles. If you are not able to have dedicated designers on your team, then think about the concepts discussed here as you plan and build your own site. Many books have been written on UI and UX design. This chapter does not attempt to provide comprehensive UI and UX guidance, nor is it a primer on web technologies such as HTML5 or CSS3. Instead, this chapter explains the design process and consider- ations the team applied when building the Mileage Stats application. In this chapter you will learn: • The importance of the designer roles and the design process. • UX and UI design artifacts and considerations. • How the design of Mileage Stats evolved. Technologies discussed in this chapter are HTML and CSS. Design is a Worthwhile Investment We cannot overstate the value of a high-quality design. Design may easily be the deter- mining factor between a successful website and a website that does not get the expected traffic, repeat visitors, or recognition from its users. Design is beauty and function. Design invokes the correct emotion. A successful design helps users feel confident that they are visiting a credible site. A high-quality design makes users feel valued and encourages them to explore the site. Design and Layout4
- 85. 52 chapter four Design communicates ideas that resonate with users and enriches the user experi- ence. Design brings clarity to the presented information. But a successful design does more than that. It provides the user with an experience that naturally flows and is enjoy- able. Effective design results in websites that are easier and faster to use. It helps users achieve a result and save time by making fewer mistakes and knowing what to do in case of an error. Design improves the process and ensures the right result. Design is hard work. It takes time and effort, and there is a cost to working with one or more designers. How- ever, investing in design early in the project will likely reduce the overall development costs and provide many other benefits as well. The design process helps to focus the project and set its priorities. It determines what the site will accomplish. The design arti- facts facilitate communication with stakeholders. The iterative prototyping process al- lows the design to quickly and easily change and gives team members the freedom to be creative because they are not constrained by working code. Defining the user experience and user interface early clarifies scope. This facilitates the identification and prioritization of features and the technical requirements to deliver these features. Web Project Designer Roles Developing modern web applications requires a broad range of skills. Depending on your application requirements, your team will need expertise to fill the following roles: user experience designer, information architect, user interface designer, graphic designer, user interface and user interaction developer, production designer, integrator, producer, and server-side developers and testers. The UI designer and information architect are more focused on the audience and the consumption of the website than they are concerned about how the website is implemented. On the other hand, integrators are more con- cerned with how the design is implemented. Designers don’t necessarily care about how it gets done; they just assume that devel- opers can do it. Developers may be frustrated at how difficult the design can be to imple- ment. Designers may get frustrated that developers don’t understand the importance of the design. The composition of the web project team will vary from project to project based on the application’s requirements and the team’s resources. Depending on the size of the team, you may have a number of specialized people or one person filling multiple roles. A large project will typically include two or three designers, an information architect, a producer, and two integrators. A medium-sized project will probably have one designer and one integrator. A small team typically has a single integrator/designer who can do CSS, JavaScript, and visual design. The tradeoff is that this individual is probably not as strong in all areas because his or her skills are spread across many areas rather than having exper- tise in only one of these roles. Teams that value the UX and UI roles receive a significant return on investment. This is illustrated by looking at websites that invested in UX; these sites exhibit a polished UI that is intuitive, responsive, and facilitates the easy completion of tasks. UX and UI designers positively impact the team by being the customer advocate, providing a user- centric perspective on what the site offers and how the site is used.
- 86. 53design and layout In this chapter, designer is an umbrella term that covers the above designer roles. Focus on the User When you are starting a project, the first thing you should focus on is the user. You should start by defining who the user is, what their characteristics are, and identify scenarios for each persona, which is a user in a particular context. A persona embodies work style, role, motivation, skills, and goals. If you have a complicated or large application, some features might target different personas. The process of identifying users and scenarios helps drive the design of both the experience and the branding of the application. As your design evolves, continue to think about the user’s characteristics and inten- tions. Think about creating the flow through the application that provides a path that is natural and makes sense to the user. Don’t be afraid to reduce features or start over again. Companies that research user behavior are able to evolve their applications to reduce failure rates and increase adoption. Many companies have dedicated user research teams for this purpose. They instrument their websites to track, for example, how long people take to navigate from page to page. This helps identify areas of confusion and difficulty. This is important because in a large company, even a very small percentage of people abandoning the order pipeline could cost millions of dollars. Design Prototyping Design prototyping begins after the application requirements, user scenarios, and user stories have been identified. Design prototyping provides structured time for stakehold- ers and team members to iterate on the application design. It is much cheaper to add and remove pages to the site earlier in the design, and it is cheaper to change paper diagrams than code. The iterative process of creating the following artifacts allows design decisions to be made at the right time with the right level of effort. • Mood board. A mood board is a visual collage that can include words representing the concepts you want the application to convey, along with colors and images that would appeal to your users from a variety of sources. A mood board is created early in the project because you want everyone on the team to be on the same page about what you are building and to be inspired. The mood board allows you to set direction about the feel of the application and about your design principles, and allows you to eliminate unnecessary elements and ideas. It doesn’t represent the end product, but helps you establish the personality of the product. If you are following a style guide or have an established experience, skip this step. If you are creating a new experience, this is a common first step. This is a low-cost, fast exercise that provides high value in establishing your brand. • Flow diagram. Based on application requirements, the UX designer defines the pages in the site, actions available on those pages, and navigation between pages. These decisions need to consider the user stories identified in the requirements. The result of this work is a flow diagram, typically drawn on paper.
- 87. 54 chapter four • Wireframe. The UX and UI designers collaborate to create wireframe models that depict rough placement of the text, data, and basic controls. These models are used to help organize the page’s information. The wireframes can be hand drawn or created using an application such as SketchFlow or Balsamiq. Wireframes inten- tionally lack detail such as color, images, drop shadows, and finished controls. • Image-based Mockups. UI and graphic designers work together to create images that show what the application will eventually look like. These mockups contain details such as typography, color, gradients, images, and transparency. Mockups should communicate all necessary details of the UI. Multiple mockups for a single page may be required to effectively convey details of the different states. Mockups can be created using a tool like Adobe PhotoShop or Illustrator. • Functional mockups. The designers and UI developer build functioning HTML pages that include CSS and possibly JavaScript. These pages are autonomous and don’t yet interact with the server, and use fake data when needed. It’s during this phase that the team makes decisions about implementation details and balances browser capabilities with HTML, CSS, images, and JavaScript. Note: Depending on the project scope and the team’s resources or preferences, image-based mockups may be skipped. Note that it’s cheaper to modify and iterate the design using a graphical image than HTML and CSS. User Experience Design Considerations A UX design specifies the site’s structure, the web pages it uses, what actions users can perform on each page, and the transitions that can occur once a user performs an action. A well-designed site has a short learning curve, makes the user feel successful, saves them time, is intuitive, and presents clear, useful information. The following sections discuss UX design considerations. Consistency User success is the primary motivation for consistency. User gestures, colors, metaphors, navigation, and similar concepts should be consistent across your application. Keep your navigation model consistent across your site and be sure that you don’t change the way users do things on different pages. Make sure the user always knows the context they are in so they don’t have to think about it. The degree of consistency in your application is directly related to user success. When your users encounter inconsistency, it causes them to question their understanding. They are forced to determine whether this was an oversight in the application or whether they misunderstood how the application works. Regardless of the degree of the inconsistency or how much additional time it takes, the user has been taken out of the flow of what they were trying to accomplish. An example of consistency in Mileage Stats is the use of vehicle tiles in both the dashboard and details layouts. Because the vehicle list animates the transitions between these layouts, the user sees the relationship, understands why some are collapsed, and
- 88. 55design and layout never loses sight of the vehicle they selected. Animations should provide feedback or direct the user’s attention but not be a distraction or be irritating to your users. Responsiveness Users appreciate a site that is responsive. The goal of a responsive website is to never leave the user wondering what is going on. Responsiveness means the site provides feedback when the user takes an action, and the site loads content quickly. Feedback can be a visual cue such as a confirmation graphic that appears when the user clicks a Submit button or a progress bar displayed during a long-running task. An- other example of immediate feedback is an error message that appears as soon as the user makes a mistake in a form rather than after the form has been submitted. When loading content, you can improve a user’s perception of responsiveness even if the actual load time is slow. Text, images, data, and scripts can be downloaded in the background. Mileage Stats demonstrates a responsive UI by prefetching chart data when the Dashboard loads, so that when the Charts page is accessed, the chart displays imme- diately. Data is also loaded asynchronously during UI transitions. You can optimize page rendering times by putting script tags for JavaScript files at the bottom of the HTML page or by using a JavaScript loader so the JavaScript files are loaded in parallel to rendering the HTML page. Doing this allows the majority of the page content to be loaded and rendered first. When a script tag is found by the browser, all rendering stops until the script is downloaded and evaluated, so if the scripts are on the top, the user may see a white screen for a few moments. Familiar Metaphors People naturally associate new concepts with what they already know, so familiarity shortens the user’s learning curve. The canonical metaphor is the shopping cart. People know what a shopping cart is, so you don’t need to explain the virtual equivalent. Streamlining the Experience Streamlining is about optimizing the navigational flow through the site. Users should not have to spend time searching for information they care about most or reading about how to navigate the site. One of the most important things in site design is global navigation. This is the top- level channel for how users get into your site and accomplish the tasks that are most important to them. Navigation should feel natural and familiar to users. If you want to innovate, innovate by building upon the familiar. Designers and developers should work together to create a prioritized list of the top-level actions based on your user scenarios. Consider ways to improve the use of the site. Evaluate how easy it is for users to lo- cate information or complete a task. Logically place features where users need them. An example of this is placing a reset password button next to the password field on a sign-in page. Additional examples of streamlining the experience are setting focus to the first field in an input form, and designing the UX so that the user does not have to use a mouse. Think about how to get people to willingly do what you want them to do without feeling like they are being forced. For example, think about form registration. Don’t ask the user for any more information than you will actually use. You can help the user pro-
- 89. 56 chapter four gressively fill out the form by breaking the input process into multiple steps that build on each other based on the user’s input. This will require less of the user’s time, but you need to be clear about the number of steps it will take to complete the process. You can use a progress bar to communicate to the user where they are in the process. Save users as much time as you can by automatically filling in form fields whenever possible. For ex- ample, when given a zip code, fill in the city and state. Use a country field to control the display of address input fields, or a credit card type to change the security code prompt. Sites that take shipping and billing information should provide the option to use the same address for both. Mileage Stats demonstrates a streamlined experience in a number of ways. It provides a simple site navigation experience, as shown below. Navigation in Mileage Stats It also has a Complete Registration form that is optional, asks for the minimum amount of information, and can easily be dismissed. The Mileage Stats vehicle tiles on the Dashboard prominently display commonly used vehicle performance metrics. The vehicle tiles are easy to read and provide the user with the ability to drill down for more detail. Example Mileage Stats vehicle tile
- 90. 57 Design for desirability and usability. Think about how you progressively disclose in- formation and options. You don’t necessarily want everything to be at the same level of discoverability. You should think about what items you are putting above the fold, which means that they are immediately visible on the web page without scrolling. Anticipate Usability Issues When possible, account for user actions that that can lead to frustration. For example, saving form data as the user completes a form prevents them from having to reenter data if they accidently press the backspace key and navigate to the previous page. Prompting the user to save unsaved form data when they close the browser is another technique for preventing unintended data loss. Another feature to help users be successful is to prevent data loss through the use of a trash can or by providing an undo action that is available after the user completes a destructive action. You can evaluate the impact of your design and reduce risk by gathering data through user research. Limit the Choices UX designers encourage focused applications. These applications perform a limited num- ber of tasks very well, rather than overwhelming the user with choices. Iterate on your design, reducing it down to its essence. Focus fiercely on the core scenarios and spend less effort on the edge cases that won’t affect the majority of users. Elegance, usability, and desirability are easier to achieve with fewer concepts and less complexity. It is easier to limit the choices if you have a very clear understanding of who the user is. User Interface Design Considerations Users visiting your site get their first impressions from the visual elements and layout. You need to think about the visual aspects that will resonate with your users. Look at web- sites, applications, books, magazines, and anything that might help you gain inspiration for creating something new. Of course, you don’t want to copy someone else’s ideas. At the same time, however, you don’t necessarily want to be different just for the sake of being different. Designing for the web is no different than designing clothing or anything else; you need to understand what the current trends are and what appeals to your user base. One tool that you can use to convey ideas, personality, and emotion is a mood board, mentioned earlier. For more information about mood boards and to see an example, see the following resources: • “Website Mood Boards: A Successful Precursor to Visual Prototyping” by Kevin Flahaut http://weblog.404creative.com/2007/02/14/website-mood-boards-a-successful- precursor-to-visual-prototyping/ • “Why Mood Boards Matter” by Mindy Wagner http://www.webdesignerdepot.com/2008/12/why-mood-boards-matter/ As we mentioned, a mood board should be created early in the design process. It helps get the whole team on the same page, facilitates important conversations between team members, and helps establish principles and direction for the project. design and layout
- 91. 58 chapter four Focusing on the user can drive everything in the UI from the color palette to the design elements and typography. When you feel like your visual design is jelling, bounce your ideas off other designers, potential users, and customers to validate your ideas and help you focus. Your UI design should be unified and provide a visual signal to your audience that all your elements belong together. The following sections provide some thoughts about the website’s UI in terms of color, typography, symmetry, consistency, and simplicity. Color Color can be used effectively to communicate an idea or to focus a user’s attention. Color discloses a mood, creates images, and highlights items. For example, the various shades of gray can create the illusion of depth or add drama. Be aware that many indi- viduals perceive colors differently and so you should not rely solely on color to commu- nicate information. People tend to have a strong reaction to color. Color also has specific connotations in different cultures. Blue is one of the colors most commonly seen as neutral. When working on the branding and personality of the product, you should focus on your color palette early. There are many tools, such as Kuler, to help you select your color palette. The key to color is that it needs to evoke the correct emotion for your targeted users and/ or your brand. Color contrast is also important. Make sure that there is enough contrast between your foreground and background colors. For example, Mileage Stats uses red to indicate that a maintenance reminder is over- due. Example overdue vehicle maintenance reminder Typography The font you choose greatly influences the emotion your website conveys. In general, you don’t want to use more than three typefaces across your application. However, certain typefaces, especially similar typefaces, don’t work well together. Certain fonts are de- signed specifically for headlines and some fonts can be used anywhere in your application. There are tools such as Typekit that you can use to choose a web font and font stack. Font size, font weight, and the spacing between letters, words, and paragraphs are also important. You should avoid sizes that are too large or too small. It is often helpful to make the font size of a text field slightly larger than the surrounding text, but you need to take into consideration the size of the page and avoid forcing the user to scroll down if possible. Designers often set the font smaller than the 16 pixels that the browser uses as its default. You may want to adjust the line height as well.
- 92. 59design and layout Use a CSS reset file so that you can set the base font sizes explicitly and not depend on the default browser settings. A CSS reset file is also helpful in establishing default values for padding, margins, and borders to ensure consistency across browsers. These defaults are typically set to zero so other CSS rules can provide values on top of a known baseline. For an example of a CSS reset, see the reset.css file in Mileage Stat’s Web Content folder. Balance and Symmetry Balance refers to the distribution of visual weight and whether it is symmetrical or asym- metrical. Symmetry can communicate stability and strength, which may be appropriate for a traditional audience. Asymmetry is a more informal balance that may be more ap- propriate for a modern audience or an entertaining website. Studies have shown that there are certain proportions of a physical page layout that intrinsically feel better to users. You can use a grid system to help you set the width of the site navigation and the content of the page with the proper proportions. One example is the 960 Grid System. You should also think about using the rule of thirds in your layout. This is a rule of thumb for visual composition that states that an image should be imagined as divided into nine equal parts by two equally-spaced horizontal lines and two equally-spaced vertical lines. Important compositional elements should be placed along these lines or their inter- sections. The Mileage Stats landing page illustrates this idea by placing the title, descrip- tion and login form on these intersections. Mileage Stats landing page
- 93. 60 chapter four Consistency Page layout, branding, color, and typography should be consistent across the site. You can use master pages and CSS to help drive consistency. You should follow established con- ventions for UI elements so that users can quickly understand and use your site. You should think about your UI control choices and keep them consistent across your applica- tion. Don’t confuse the use of radio buttons and check boxes. Don’t interchangeably use links and buttons to do the same thing on different pages. Be aware that because of touch interfaces, people assume that everything is clickable. Simplicity Lay out the page logically to help users accomplish the most important features or tasks. Don’t put crucial elements in areas that usually contain ancillary information. Avoid tech- nical jargon that users won’t understand. Limit the number of animations, special effects, colors, gradients, fonts, and other design options. Other Design Considerations In addition to the considerations mentioned above, you should think about designing for accessibility, globalization, and localization. An accessible design is one that can be used by as many people as possible, with varying abilities. Globalization ensures that your ap- plication can be translated to another language and culture. Localization is the act of translating your application into another language. Designing the Mileage Stats Reference Implementation This section walks through the design process and decision points that influenced the design of the Mileage Stats application. Coverage includes UX and UI design prototyping, creating mockups, and integrating design assets with the application code. Identifying User Stories The team created a prioritized list of user stories identified from the application require- ments and user scenarios. The user stories are a tool used by the designer to drive the creation of the flow diagrams and prototypes. Developers use the user stories to drive their weekly backlog task items and to validate the completed work. The user story below was used to describe the requirements for displaying the dashboard. Mileage Stats User Story The team wrote their acceptance criteria using the given-when-then template. This pro- vides for clear and concise documentation that can be understood by all team members and can be used to generate both manual and automated test scripts. For more informa- tion, see the “Introducing Behavior Driven Design” in the “Further Reading” section below.
- 94. 61design and layout User Story: As an authenticated user, I want to see my dashboard so I can use the site. Acceptance Criteria: Given an authenticated user when they navigate to the dashboard page then the user name and the word “Dashboard” are displayed. Given an authenticated user when they are redirected to the dashboard page then the user name and the word “Dashboard” are displayed. Using Flow Diagrams to Prototype the UX Based on the user stories, the UX design came to life on paper in the form of flow dia- grams. The early diagrams were rough and only pictured main features of the application. These flow diagrams outlined the primary pages and how the pages would link to each other. The following figure illustrates an early application flow diagram. Early UX flow diagram The flow diagram was then expanded to show data placement and the available ac- tions for users, as pictured below. The flow diagram evolved through an iterative process with the team and stakeholders. As features were added or removed, the flow diagram was updated to reflect the current user stories, ensuring that no important functionality was left out.
- 95. 62 chapter four Additional details for the flow diagram
- 96. 63design and layout Using Wireframes to Prototype the UI Based on the flow diagrams, each section of the UI had multiple wireframes created for it. The wireframe was drawn on paper, with some pieces on sticky notes. The team tested each variation against user stories, moving the pieces around to decide what worked best. The following figure illustrates one of the wireframes. Early wireframe Wireframes can also be used to illustrate animations and interesting transition ef- fects. In Mileage Stats the vehicle tiles animate into position when transitioning between the Dashboard and Details layouts. The vehicle tiles also expand and collapse based on the selected vehicle, and allow you to change the ordering of your vehicles. Using the wireframes allowed the team to easily iterate on the details of these animations. The following figure is a hand-drawn wireframe of a vehicle tile and its associated animations.
- 97. 64 chapter four Early animation wireframe Creating Site Mockups Once everyone agreed on the wireframes, the designer began to create site mockups of the actual pages. As you would expect, there were several iterations before the final version. This section highlights a few things that we learned that led to changes in the design. Note: You can conduct usability testing during the process of refining your design. During usability testing, users walk through the scenarios, using the interface, while you watch them. Let them do what they would normally do. Ask them to think out loud about what they are looking for, and what they expect to be available on any page. Be sure not to give them any clues or ask them leading questions. It’s best if you can remain silent and just observe. After every walkthrough, refine the site based on the feedback.
- 98. 65design and layout You can see how the Mileage Stats UI and UX evolved in the following images. The first image illustrates an early version of the Fill Up page. It gave the developers a good sense of what the end product would look like. The next image shows the final screenshot of the same page. Early mockup of Fill Up page
- 99. 66 chapter four Final screenshot of Fill Up page We wanted consistency in navigating between the pages. We also wanted users to realize that on some pages they are viewing information specific to a particular vehicle and on other pages they are viewing aggregate information about all vehicles. The links in the top, right corner in the final version of Mileage Stats provide a unified, consistent, and understandable way to navigate between the Dashboard, Profile, Sign In/Out, and Charts pages. The Dashboard and Chart pages show information pertaining to multiple vehicles, so it made sense to include those links with the more general Sign In/Out and Profile links. Adding the Details, Fill ups, and Reminders buttons on the vehicle tiles made it clear that those pages were only relevant to the individual vehicle. User registration brought up several interesting questions: Should a user have to register in order to use the site? Will users be discouraged from using the site if they have
- 100. 67design and layout to register? We decided that anyone should be able to use the site but it would be best if users signed in so that they could track their metrics, and this would allow us to build up an interesting database over time. We wanted to strike the right balance between encour- aging the user to complete their registration and not annoying the user. The screenshot below shows user registration in Mileage Stats. User registration in Mileage Stats Once the team was satisfied with the Mileage Stats mockups, the developers began to code the site’s infrastructure. They created static pages and basic forms that imple- mented the user actions. In the meantime, the designer started work on the final UI and graphics. Implementing the Design A functional mockup can consist of a single HTML and CSS file, while the run-time ren- dering of the page is composed from multiple code fragments, files, and data sources that come from the client and/or server. This section explains some of the considerations for converting a mockup to HTML, organizing CSS styles, adopting new standards, and de- bugging. Converting a Mockup to HTML You can convert mockups to HTML by breaking down areas into component div block elements. Usually, the div blocks group together related elements, or they represent single text blocks, or single interactive elements. Once you decide how to lay out the divs, you can use different CSS styles to position and size them correctly. The following figure shows the boundaries of some of the elements that make up the vehicle tile and the classes applied to those elements. Not all elements are shown because it would have made the image too complicated, but this gives you the idea of how the tile is constructed.
- 101. 68 chapter four Vehicle tile construction These tiles are meant to look exactly like the mockup, to the pixel, so absolute posi- tioning is used. There are div groups for the header, navigation, and statistics in order to facilitate the animation that collapses the tiles. Depending on what vehicle a user selects, a tile can collapse into a more condensed version of itself, omitting some divs that repre- sent information that is not relevant. For example, the currently selected vehicle is “Hot Rod” so the “Soccer Mom’s Ride” vehicle tile is collapsed as shown below: Collapsed and expanded vehicle tiles
- 102. 69design and layout For aesthetic reasons, there are extra layers of divs on the vehicle tile. For example, the semi-transparent outer border of the tile was created with CSS, so it required an- other nested div to hold the contents of the tile. In situations like this, it can be easier to use parent > child selectors and other relational selectors to style them rather than to create CSS classes for all the divs. The following example shows portions of the template used when rendering the vehicle list. CSHTML <!-- Contained in _TemplateVehicleList.cshtml --> <script id="mstats-vehicle-list-template" type="text/x-jquery-tmpl"> ... <div class="wrapper"> <div class="vehicle" data-vehicle-id="${VehicleId}"> <div class="content"> <div class="header">...</div> <div class="actions">...</div> <div class="statistics footer">...</div> </div> </div> </div> </script> The following CSS shows the rules applied to the vehicle and content classes. The CSS3 Color Module defines a color value that includes a parameter for the alpha channel. The form of this value is rgba(red, green, blue, alpha) where the red, green, and blue values are integers or percentages and the alpha value is between 0.0 (completely trans- parent) and 1.0 (completely opaque). CSS3 /* Contained in stylesheet.css */ .vehicle { position: relative; width: 220px; overflow: hidden; padding: 9px; background-color: #bbb; background: rgba( 233, 233, 233, 0.6 ); border: 1px solid #bababa; border: 1px solid rgba( 233, 233, 233, 0.8 ); -webkit-border-radius: 5px; -moz-border-radius: 5px;
- 103. 70 chapter four -o-border-radius: 5px; border-radius: 5px; -webkit-box-shadow: 0px 0px 12px rgba( 0, 0, 0, 0.4 ), inset 0px 0px 10px rgba( 233, 233, 233, 0.4 ); -moz-box-shadow: 0px 0px 12px rgba( 0, 0, 0, 0.4 ), inset 0px 0px 10px rgba( 233, 233, 233, 0.4 ); -o-box-shadow: 0px 0px 12px rgba( 0, 0, 0, 0.4 ), inset 0px 0px 10px rgba( 233, 233, 233, 0.4 ); box-shadow: 0px 0px 12px rgba( 0, 0, 0, 0.4 ), inset 0px 0px 10px rgba( 233, 233, 233, 0.4 ); z-index: 0; } .vehicle .content { width: 220px; -webkit-border-radius: 4px; -moz-border-radius: 4px; -o-border-radius: 4px; border-radius: 4px; -webkit-box-shadow: 0px 0px 10px rgba( 0, 0, 0, 0.5 ); -moz-box-shadow: 0px 0px 10px rgba( 0, 0, 0, 0.5 ); -o-box-shadow: 0px 0px 10px rgba( 0, 0, 0, 0.5 ) box-shadow: 0px 0px 10px rgba( 0, 0, 0, 0.5 ); } The above CSS code also illustrates other new CSS3 features such as box-shadow and border-radius. Given some practice, the process of converting a mockup to HTML will become easier and more straightforward. It’s a good idea to look at various websites and see how they construct their HTML and CSS structures. You can use the techniques in the “Debugging” section below to inspect other websites. CSS Organization You need to structure your CSS so that you know where things are and what you are changing. At the beginning, it is easiest to create a style for every element. When you start consolidating styles, it’s a cost/benefit tradeoff. On the one hand, there is more to figure out. For example, you need to keep track of styles that you can override and styles that should cascade down. In the long run, if you group common styles together, it will be easier to maintain these centralized styles. It can be hard to know what common styles
- 104. 71design and layout you need at the beginning of a project but easier to understand at the end. This is an exercise similar to refactoring code. Good naming helps organization, and there aren’t many restrictions to naming. In general, you should think about whether you know what CSS style is being applied to each element on the page and whether you can identify each element by looking at the HTML. Here are some guidelines for assigning IDs to elements and naming CSS classes: • Apply IDs only to elements unique to the page. Classes should be used for repeating elements. • Use IDs and classes to apply style to elements using CSS. Do not use data- attributes to apply style to elements; data- attributes should only be used by developers. • Use logical names in the domain. For example, Mileage Stats uses vehicle and chart. This is in contrast to naming the CSS rule based on its location on the page, for example, column2. • Group logical elements together in the CSS file. For example, all navigation buttons should be together, and all elements in the header should be together. In Mileage Stats, there is only one place where there are tiles. • Elements should be styled consistently across pages. Forms should all be styled the same. In the Mileage Stats stylesheet.css file there are common elements for lists and forms and page-specific styles for elements such as vehicle tiles and panels. Vendor-Prefixed Attributes The standards that govern web technologies are always evolving, and CSS is not immune to this evolution. In order to maintain progress, new proposals should be implemented and tested soon and often by browser makers and the web-building community. Tradi- tionally, the use of cutting-edge standards means more work in the future when the standard is approved. Vendor-prefixed attributes provide a way for the browser makers to implement early specifications so designers can use them right away. Browsers use the last attribute they understand. By placing the final attribute after the vendor-prefixed attributes, browsers will use the most appropriate one given their level of standards sup- port. The following example shows this technique being applied to the box-shadow attribute. CSS3 /* contained in stylesheet.css */ -webkit-box-shadow: 0px 0px 10px rgba( 0, 0, 0, 0.50 ); -moz-box-shadow: 0px 0px 10px rgba( 0, 0, 0, 0.50 ); -o-box-shadow: 0px 0px 10px rgba( 0, 0, 0, 0.50 ); box-shadow: 0px 0px 10px rgba( 0, 0, 0, 0.80 );
- 105. 72 chapter four Debugging You should understand how to debug styles using the browser tools for each of the common browsers. The Internet Explorer 9 F12 developer tools allow you to view the style stack of any DOM (document object model) element. It is very convenient to test style changes in the browser because you get instant feedback. Using the F12 tools you can also disable or enable specific styles for a selector, or add a style to an individual DOM element. This allows you to determine if the properties of one style override the proper- ties of another. You can click on any of the styles and edit them in place. You can also check or uncheck the check box and it will enable or disable the value. HTML styles shown in Internet Explorer 9 F12 developer tools
- 106. 73design and layout Summary A UX design that empowers users to quickly accomplish tasks via a UI that resonates with them does not happen without a great deal of effort. Rely on a web designer to help you create a beautiful, useful website. Consider the designer to be the voice of the customer. Together with the designer, establish a design process for iteratively creating your UX and UI artifacts before you begin implementing any features of the application. As you create your design, remember the design considerations outlined in this chapter. Your customers will appreciate your responsive and easily understood site. Useful Design Tools Microsoft Expression® Web http://www.microsoft.com/expression/ Balsamiq: http://balsamiq.com/ SketchFlow: http://www.microsoft.com/expression/products/Sketchflow_Overview.aspx PhotoShop: http://www.photoshop.com/ Typekit: http://typekit.com/ Kuler: http://www.adobe.com/products/kuler/ Image compression tools: • OptiPNG: http://optipng.sourceforge.net/ • Pngcrush: http://pmt.sourceforge.net/pngcrush/ • jpegtran: http://sylvana.net/jpegcrop/jpegtran/ • CSS Compressor on CSSDrive.com: http://www.cssdrive.com/index.php/main/csscompressor/ • CSS Optimizer: http://www.cssoptimiser.com/ • Code Beautifer: http://www.codebeautifier.com/ • CSS Tidy: http://csstidy.sourceforge.net/
- 107. 74 chapter four Further Reading Krause, Jim. Design Basics Index. How, 2004. Lidwell, William, Kritina Holden, Jill Butler. Universal Principles of Design: 100 Ways to Enhance Usability, Influence Perception, Increase Appeal, Make Better Design Decisions, and Teach through Design. Rockport Publishers, 2003. Norman, Donald. The Design of Everyday Things. Doubleday Business, 1990. Samara, Timothy. Design Elements – A Graphic Style Manual. Understanding the rules and knowing when to break them. Rockport Publishers, 2007. Snyder, Carolyn. Paper Prototyping: The Fast and Easy Way to Design and Refine User Interfaces. Morgan Kaufmann, 2003. Tidwell, Jenifer. Designing Interfaces – Patterns for Effective Interaction Design. Second edition. O’Reilly Media, 2011. Weinman, Lynda and William Weinman. <creative html design.2>: a hands-on web design tutorial. Waite Group Press, 2001. White, Alexander. The Elements of Graphic Design: Space, Unity, Page Architecture, and Type. Allworth Press, 2002. Web Form Design: Filling in the Blanks: http://www.lukew.com/resources/web_form_design.asp A Book Apart: Brief books for people who make websites: http://www.abookapart.com/ A List apart: For People Who Make Websites: http://www.alistapart.com/ Smashing Magazine: http://www.smashingmagazine.com/ Six Revisions: Useful Information for Web Developers & Designers: http://sixrevisions.com/ “10 Usability Tips Based on Research Studies” by Cameron Chapman on Six Revisions: http://sixrevisions.com/usabilityaccessibility/10-usability-tips-based-on-research-studies/ Tuts+: http://tutsplus.com/ 52 weeks of UX: A discourse on the process of designing for real people: http://52weeksofux.com/ UX Booth: User Experience & Usability Blog: http://www.uxbooth.com/ Web Content Accessibility Guidelines (WCAG) 2.0: http://www.w3.org/TR/2008/REC-WCAG20-20081211/ Marcotte, Ethan. Responsive Web Design. Available on A Book Apart: http://www.abookapart.com/products/responsive-web-design
- 108. 75design and layout User Stories: http://en.wikipedia.org/wiki/User_story Behavior Driven Development: http://en.wikipedia.org/wiki/Behavior_Driven_Development Introducing Behavior Driven Design: http://dannorth.net/introducing-bdd/ “Why Mood Boards Matter” by Mindy Wagner: http://www.webdesignerdepot.com/2008/12/why-mood-boards-matter/ “Website Mood Boards: A Successful Precursor to Visual Prototyping” by Kevin Flahaut: http://weblog.404creative.com/2007/02/14/website-mood-boards-a-successful- precursor-to-visual-prototyping/ “8 Definitive Web Font Stacks Article” by Aaron Boodman: http://www.sitepoint.com/eight-definitive-font-stacks/ Windows Internet Explorer Developer Tools: http://msdn.microsoft.com/en-us/ie/aa740478 Herding Code 108: Jin Yang and Nathan Bowers on Web Design: http://herdingcode.com/?p=309 “Design Fundamentals for Developers” by Robby Ingebretsen on Channel 9: http://channel9.msdn.com/Events/MIX/MIX09/02W To access web resources more easily, see the online version of the bibliography on MSDN: http://msdn.microsoft.com/en-us/library/hh404094.aspx.
- 110. 77 Introduction A modular application is divided into functional units named modules that can be inte- grated into a larger application. Each module provides a portion of the application’s overall functionality and represents a set of related concerns. Within a browser-based application, a module can add or remove user interface (UI) elements, add or enhance functionality (or behavior) already available in the UI, or enhance the user experience (UX). Modules can be built independently of one another but still communicate with each other in a loosely coupled fashion. Modular applications can make it easier for you to develop, test, deploy, and extend your application. Modular designs also have well-under- stood benefits that help you unit test your applications and make them easier to maintain over time. Achieving a modular design in a complex JavaScript application requires specific tech- niques that are not immediately obvious if your previous experience is with object-orient- ed languages such as C# or Microsoft® Visual Basic®. While environments such as the Microsoft .NET Framework allow you to use classes, interfaces, and assemblies to organize application functionality, there are fewer options for creating explicit boundaries in Java Script. Without a modular approach, JavaScript source files tend to be large and hard to maintain, and often the entire application is found in a single source file with numerous unstructured global variables. You can easily end up with an application that is prone to defects and difficult to troubleshoot and maintain. An application with the feature set of Mileage Stats is much more straightforward to develop and test when its design is modular. In this chapter you will learn: • The benefits of modularity for hybrid-designed web applications. • The factors that influence a modular design, such as the module’s boundaries. • Types of modules to consider for your application, along with their functional roles and categories. • When to use a JavaScript object, a jQuery plug-in, or a jQuery UI Widget. The technologies and libraries discussed in this chapter are JavaScript, jQuery, and jQuery UI. Modularity5
- 111. 78 chapter five Benefits of Modularity for Hybrid-Design Web Applications There are a number of benefits of modular application design that apply specifically to hybrid-design web applications. These benefits can be seen through the whole applica- tion lifecycle, which includes design, development, testing, troubleshooting, and maintenance. Modular design provides the following benefits: • The ability to leverage frameworks • Better support for an immersive UI • Support for team-oriented development • Explicit control over application initialization • The ability to externally configure modules • Decoupled module interactions • Easier troubleshooting and debugging • Easier code base maintenance • Easier testing Leveraging Frameworks There are a number of approaches to creating modular applications. When writing ap- plications with JavaScript, the simplest way to partition your code into modules is to use JavaScript objects. However, for a truly flexible system, using only JavaScript objects to create modules, as opposed to other options presented in this chapter, will result in a code base that is larger than needed. Another option is to use a framework that allows for modular designs. The Project Silk team chose the jQuery library because it supports modular designs through plug-ins and widgets and because it helps avoid cross-browser compatibility issues. • jQuery plug-ins allow developers to create libraries that extend the functionality of jQuery. There are jQuery plug-ins for everything from simplifying Ajax calls to implementing drag and drop. • jQuery UI Widgets are high-level building blocks that are provided by the jQuery UI library. Widgets are a way to create modules within an application that already takes advantage of the jQuery library, and to help impose modular design on client-side code. For more information on widgets, see Chapter 3, “jQuery UI Widgets.” Note: This chapter uses the term module to refer to a JavaScript object, a jQuery plug-in, or a jQuery UI Widget, which contain cohesive sets of functionalities. Of course, there are other high-quality libraries besides jQuery to choose from, such as Prototype and Script.aculo.us. Finding a framework to act as a starting point for a modular application is important. If the framework allows you to avoid having to imple- ment low-level DOM manipulation yourself and offers cross-browser support (as jQuery does), so much the better. For other examples of JavaScript libraries and frameworks, see “Architectural Alternatives” in Chapter 2, “Architecture.”
- 112. 79modularity Support for an Immersive UI Immersive experiences use modern UI design approaches to keep the user in context while inside the defined boundaries of the immersive experience. In context means that users are never confused about where they are in the application. Breadcrumbs are one way to help the user, but they do not match the intuitiveness of an immersive UI. The user expects either instant responsiveness or some indication of progress from an immersive web application. The experience must be fluid. This requirement places a number of non- trivial responsibilities on the client-side code. Some of these responsibilities have to do with Ajax data retrieval and caching, updating UI content, state management, and animat- ing layout transitions. It is difficult to implement the complex behavior required for an immersive UI with- out a design that is partitioned into modules with clear boundaries and responsibilities. Dividing functionality into widgets that are associated with specific HTML elements ensures that only a local region needs to be refreshed in the display. This can improve performance. Support for Team-Oriented Development Most complex web applications will be written by a team rather than by a single person. Dividing the application into modules allows pieces of the application to be developed in parallel by different teams or individuals. For example, after this approach was decided upon for Mileage Stats, the fill ups and reminders modules were simultaneously developed by separate members of the development team. Explicit Control over Application Initialization One of the challenging parts of a complex application is initializing and cleaning up vari- ous parts of the application at the appropriate times. A modular design can help to or- chestrate these tasks. Fortunately, widgets contain several hooks for controlling what happens during initialization and cleanup. See “Initializing Modules” later in this chapter for an example of how Mileage Stats uses these hooks. Ability to Externally Configure Modules Modern applications often defer the configuration of components until the application is deployed. If you design your application in a modular way, you can implement ways to externally configure your modules. Without external configuration you must use hard- coded component dependencies, which result in brittle code that is hard to test and maintain. Decoupled Module Interactions A modular design allows you to formalize the interactions between the components of your system. For example, in Mileage Stats the interface of each widget allows the widget to work with other parts of the UI without unnecessary coupling. The interface of a widget is made up of three things: the options it accepts, the public methods it exposes, and the events it raises. To see an example of how modules in Mileage Stats collectively respond to user actions in a loosely coupled way, see “Communicating Between Modules” later in this chapter.
- 113. 80 chapter five Troubleshooting and Debugging Modular applications are easier to troubleshoot and debug. When a problem occurs, it is usually easy to isolate the source of the issue to either a single module or to the com- munication between modules. Once a faulty module is located, troubleshooting should be straightforward. For communication issues between modules, unit tests should indi- cate which side of the communication is causing the problem, allowing for a quick resolu- tion. Code Base Maintenance A modular design allows your code base to be more maintainable by making it easier to understand. Adding new features and evolving the application over time is easier than it is in a monolithic application. Since each module has a well-defined set of responsibilities, decisions about where a new feature belongs should be straightforward. If the new fea- ture is an addition to the responsibilities that a module owns, then the feature should be added to the module. If the new feature is outside the areas of responsibility for existing modules, there may be a need for a new module. Changes to the code tend to be more localized in applications that were originally designed with a clear and well-motivated modular structure. This makes adding new features less costly. For example, in the future the Project Silk team may want to add an additional chart to the Mileage Stats application. This chart would show the user’s average fuel efficiency for each vehicle compared to the average fuel efficiency of other vehicles of the same make and model. This feature is a type of chart, so extending the charts module to show the new type of data is a good option. However, if the team decides that the responsi- bilities are too different from those of the existing chart module due to the types of data or how the data should be displayed and partitioned, they could create a new module to handle the retrieval and display of this information. Adding the new module to the ap- plication would simply require initializing it at the appropriate time in the mileagestats.js file, and modifying the layout manager to handle any new user interactions and navigation required for the new feature. Testing Modular applications can be tested module by module. In addition, it is possible to create test frameworks that isolate modules from their application context. This technique, which is sometimes called sandboxing, allows components of the application to be tested before the entire application is complete. It also makes testing more robust by preventing software defects in one module from blocking or affecting the testing of other modules. Factors That Influence a Modular Design Numerous factors come into play when defining the roles and responsibilities of modules within an application. For interactive modules, some questions to consider are: • What are the design goals and constraints for the application? • How is the module defined visually? • What will the module do?
- 114. 81modularity Using the UI elements to determine the responsibilities of a module requires answers to a few questions: • What UI element or elements define a visual boundary for the module? • Does the module need to create, insert, remove, or replace elements in the UI? • Will the module contain other modules? If so, will it be responsible for managing the lifecycle of the child modules? In addition to defining the visual boundaries of a module, it is important to define what the module does. Several questions to consider are: • What behaviors or interactions should the module add to the UI elements? • What animations or screen transitions is the module responsible for? • What data responsibilities does the module have? • How does the module interact with other modules and the rest of the application? To determine the boundaries of the modules in your application, a few techniques can be used. If you applied an approach for defining the UI and UX of your application, such as the one described in Chapter 4, “Design and Layout,” you should already have the as- sets you need to begin defining application modules. After applying UX considerations you should have flow diagrams that illustrate user navigation and transitions throughout the application. After applying UI considerations you should have wireframes and various mockups that show the dimensions and relationship between UI elements. These assets can be used to influence the boundaries of modules. You can identify the modules in your application by evaluating the following three aspects: • Layout. Wireframes and mockups are used to guide the design of UI modules that are made up of groups of related elements. • Animations. Flow diagrams and navigation transitions are used to identify anima- tions that are independent of the UI elements that the animation affects. Anima- tions can influence the need for behavioral modules. • Data Refreshes. UX considerations identify how user actions that update the data in portions of the UI will affect the design of modules. The boundaries of these updates can indicate the possible boundaries of additional UI modules as well as infrastructure modules to accommodate the refreshing of data. The Mileage Stats team used the assets from the design phase to initially define module boundaries. As a result, the team found that most of these modules remained unchanged throughout the building and refactoring of the application. The remainder of this section illustrates how applying these techniques influenced Mileage Stats. Page Layout The UI layout gave the developers a good indication of how to begin defining widgets, most of which would be associated with visual elements. In Mileage Stats, a user can view statistics for each vehicle at three levels of granularity. A top priority was that users never see any page refreshes while switching from the dashboard to the details and charts layouts. In other words, these levels define the boundaries of an immersive experience. The following figure illustrates the three main layouts.
- 115. 82 chapter five The three main screen layouts in Mileage Stats The dashboard contains a summaryPane region and the vehicleList region. The details layout contains vehicleList and infoPane regions, and the charts layout uses a single region.
- 116. 83modularity The Dashboard Layout The following figure shows the Mileage Stats dashboard. The Mileage Stats Dashboard The information presented to the user includes: • Site navigation links • A registration form • A list of vehicles that the user has entered in the system • Statistics aggregated across all the vehicles • A list of reminders that are overdue or nearly due • Status messages about actions the user has taken
- 117. 84 chapter five After partitioning the screen based on its layout, the team arrived at the following module boundaries. Dashboard regions As you can see, the main components of the dashboard are the summaryPane region and the vehicleList region. The summary pane, like the vehicle list, is a parent widget with three child widgets. After registration is completed, the registration widget is no longer shown. The status and header regions appear in all layouts. The Details Layout The details layout, shown in the following figure, is another main screen that provides one of the three levels of granularity. The details layout is divided into the vehicleList region (which is shared with the dashboard layout) and the infoPane region. As you can see, the tile widget is applied to each child in the vehicle list while the vehicle widget is applied only to vehicle tiles. Only the tile widget is applied to the Add Vehicle button at the bottom of the vehicle list. The responsibilities of these widgets are described in the “Animations” section that follows.
- 118. 85modularity Details regions Note: Because the vehicleList region is used in both the dashboard and details layouts, users never lose sight of the selected vehicle, which keeps them in context. There are no full-page refreshes when users navigate to the different layouts, so each region of the page must know how to respond to show, hide, and animate directives. These requirements are good indications that the regions should be widgets. Also, some module must be responsible for telling each of these widgets to show, hide, or animate. This is the role of the layoutManager. This module has no UI, but it controls the opera- tion of other widgets. For more information about the layoutManager, see Chapter 9, “Navigation.” Animations Animations are another factor that can influence the need for a module. Animation mod- ules can be implemented as widgets, which permit them to focus on the details of the animation. This separates the animation code from the code that manages the state of the UI elements, such as data refreshes. In Mileage Stats, the region that shows the list of vehicles appears in both the dash- board and details layouts. Transitions between the dashboard and details layouts are animated: the summary pane and the vehicle list regions enter and exit at the left side of
- 119. 86 chapter five the screen, and the info pane and chart regions enter and exit at the right. This animation influenced the decision to create the tile and vehicle widgets. The vehicle list widget contains two types of elements: vehicle tiles and a tile that holds the Add Vehicle button. When a user transitions to and from the dashboard and details layouts, the animation uses a two-step process to move the vehicle tiles so that they are displayed in either one or two columns. At the same time, the vehicle tiles that were not selected shrink to a smaller size. These are two distinct cases, which indicate that there should be a widget for each type of animation. Mileage Stats uses the tile widget to animate the position of all boxes horizontally and vertically, because both the vehicle boxes and the Add Vehicle box need that behav- ior. The vehicle widget expands and collapses the vehicle boxes, because only they need that behavior. The following figure illustrates the transition from the dashboard layout to the details layout. Transitioning from the dashboard to details Modularizing these animations into widgets results in pieces of code that have clear boundaries and responsibilities. Note: It would also be possible to separate the animation logic into its own widget that the vehicleList widget could then apply to itself. This would be particularly useful if you needed to apply the animation elsewhere or needed the ability to easily change the animation applied to the vehicleList widget.
- 120. 87modularity Refreshing Data When all data updates happen through Ajax calls, the various parts of the UI must know how and when to request updates from the server and how to apply any necessary changes to the UI. Depending on the user’s action, only parts of the UI, rather than all of the data on the page, may need to be updated. The boundaries that delineate the data to be refreshed and the data that remains the same can influence the boundaries of modules. The statistics and imminent reminders regions of the summary widget are themselves widgets. They both must be able to request updates from the server and apply them. The following figure illustrates the summary widget, with two of the widgets it is responsible for. The summary widget The statistics and imminent reminders regions each know how to request their own relevant data and update their content when changes in the vehicle, fill ups, or reminder data are detected. Many of the other widgets in Mileage Stats are also responsible for retrieving and applying updated content. However, the code that actually makes the re- quests and adds caching functionality is implemented in a separate module as a JavaScript object. To learn more about data abstraction in Mileage Stats, see Chapter 6, “Client Data Management and Caching.”
- 121. 88 chapter five Functional Roles and Categories for Modules The role of a given module generally falls into one of three categories, each with a spe- cific focus: • UI modules are responsible for adding, removing, and modifying UI elements within the boundaries of the module. • Behavioral modules are responsible for applying behavior to the elements within the module. Animation is an example of a behavior. • Infrastructure modules are responsible for application-wide requirements that are not specific to the UI, such as data access and communication. UI Modules UI modules, such as the statistics and imminentReminders widgets in Mileage Stats, are responsible for the visual representation of an element. UI modules can be commonly used controls such as date and time pickers, combo boxes, or tab controls. They can also be application specific, which is true of the Mileage Stats widgets. Some of the Mileage Stats widgets rely on HTML and CSS for their appearance, and may correspond to elements with child elements. Alternatively, a widget may be applied to an element that has no child elements. In this case, the widget is responsible for adding the elements that make up the UI. This situation commonly occurs when the initial re- sponse from the server doesn’t contain all of the necessary elements. When this happens, the widget may have to request the elements from the server or apply a data template. An example of this type of widget is the infoPane widget. A widget can also act as a container for other widgets. An example of a container in Mileage Stats is the summary widget, which contains the registration, statistics, and imminentReminders widgets. Containers can have knowledge of their children because they are often responsible for creating those children, attaching children to the correct elements, and responding to events from their children. Note: You should avoid creating children in container widgets that have knowledge of their parent because the resulting bidirectional dependencies make it more difficult to create a layered application. Bidirectional module dependencies also make the applica- tion harder to test. Behavioral Modules Behavior widgets and JavaScript objects add functionality to an existing element. The jQuery UI library calls these pieces of functionality interactions. Commonly used behavioral widgets include the draggable, droppable, resizable, selectable, and sortable widgets. In Mileage Stats, the behavior widgets include tile and layoutManager. There is also a JavaScript object for managing the process of pinning the site to the operating system’s taskbar.
- 122. 89modularity Infrastructure Modules Infrastructure modules provide commonly needed functionality that isn’t related to the visual aspects of the application. They don’t interact with the UI. Typically, their function- ality includes data access, communication, logging, or caching. The infrastructure modules in Mileage Stats are JavaScript objects. They include dataManager, dataStore, and pubsub. JavaScript Module Implementations Applications such as Mileage Stats that use JavaScript and jQuery can implement modules in any of the following ways: • JavaScript objects. JavaScript objects are a good choice for implementing modules that are not associated with visual elements on the page. JavaScript objects are the most lightweight type of module. • jQuery plug-ins. You should consider jQuery plug-ins when you need to extend the functionality of the jQuery framework. Plug-ins can encapsulate notions of UI and behavior. • jQuery UI Widgets. When modules are associated with specific HTML elements, consider using jQuery UI Widgets. The jQuery UI framework provides helpful, built-in, functionality that makes widgets behave like user controls. These capabili- ties include creation, initialization, a property notification system, an event model, and teardown. Associating widgets with UI elements is an easy way to organize the code that supports your UI. For example, you can use a widget to populate a visual element with a new form dynamically in response to a UI event. The following table shows the suitability of these three types of JavaScript modules for the functional roles or categories described in the previous section. These are not definitive rules, just suggestions on how to choose the appropriate module. The following sections describe the implementation of these JavaScript modules in more detail. JavaScript objects jQuery plug-ins jQuery UI widgets UI modules No OK Ideal Behavioral modules OK Ideal OK Infrastructure modules Ideal OK No Note: Behavioral modules span a wide array of scenarios, which may or may not need to operate directly on DOM elements. Any of the three implementations may be appropriate. Use the guidance throughout this section to help you decide which module to use. For consistency, Mileage Stats uses widgets for everything that is associated with an HTML element or adds behavior to HTML elements, and uses JavaScript objects for everything else.
- 123. 90 chapter five Using JavaScript Objects as Modules JavaScript objects are the most basic implementation of a module. They can be easy to write for simple modules, but they do not automatically provide the features available to plug-ins and widgets. Implementing a module as a JavaScript object is most appropriate when its functionality is not directly related to the HTML elements in the page. These modules only require logic that can be fulfilled by the language and don’t need to extend existing libraries, such as jQuery, that abstract DOM manipulation. When a module ex- tends the functionality of a library, for example to operate on DOM elements, it is more appropriate to use the library’s extensibility points. The following table lists the JavaScript objects that are used in Mileage Stats. File Purpose Functional Category mstats.pinnedsite.js Provides the pinned sites implementation for Windows® Internet Explorer® 9 Behavioral mstats.data.js Data manager that retrieves and stores data; lets callers know when data is available Infrastructure mstats.pubsub.js Manages subscriptions and publication of events Infrastructure mstats.events Sets the event, which can be any button a user clicks, such as Details, or Add Vehicle Infrastructure mstats.vehicle-drop-down- monitor Displays the Edit form Infrastructure Using jQuery Plug-ins as Modules One of the characteristics of a good framework, such as jQuery, is a robust extensibility mechanism. Creating a plug-in is the recommended way to extend jQuery. In fact, a plug- in that follows the recommendations included in the “jQuery Plug-in Authoring Guide- lines” is indistinguishable from the methods in the core library. Many features in jQuery began as external plug-ins that were later added to the library. Note: For more information on authoring plug-ins, see the “jQuery Plug-in Author- ing Guidelines” in the “Further Reading” section at the end of the chapter. Because plug-ins behave just as other jQuery functions do, they can be invoked on elements by using jQuery selectors. Inside the plug-in, the this keyword is a reference to the set of DOM elements selected when the plug-in is applied. As an added advantage, the each function on this reassigns the this keyword to each DOM element of the selected elements.
- 124. 91modularity The following code shows a plug-in named doubleSizeMe that doubles the size of an element. JavaScript // Code example not in Mileage Stats (function($){ $.fn.doubleSizeMe = function() { return this.each(function() { var $this = $(this), width = $this.width(), height = $this.height(); $this.width(width * 2); $this.height(height * 2); }); }; })(jQuery); This example code adds the doubleSizeMe method to the jQuery prototype so that it is available when you operate on a wrapped set. For example, to invoke the function on all elements with a class of icon, you would use the following call. JavaScript $(‘.icon’).doubleSizeMe(); Note: The example uses the jQuery functions for height and width, which provide cross-browser compatibility. There is much more functionality that you can add to your plug-ins. However, in some cases, plug-ins may not provide all the functionality you need. If you are writing a module that stores state internally, exposes methods you expect others to call, hides private methods, inherits from another object, or requires per-instance configuration, then a widget may be a better option. Using Widgets as Modules A jQuery UI Widget provides you with a number of capabilities that are useful when creating modules. These include features for object construction and destruction, storing state, merging options, and exposing public methods. To learn more about how to build widgets, see Chapter 3, “jQuery UI Widgets” and Chapter 14, “Widget QuickStart.” Mileage Stats uses UI widgets, which you can see on the web page, and behavioral widgets whose effects, such as animations, are visible. The UI widgets are responsible for visual elements and help to implement the application’s presentation layer. Behavior wid- gets add functionality and help to implement the behavior layer of the application. The following table lists the main widgets that are used in Mileage Stats.
- 125. 92 chapter five File Purpose Functional Category mstats.status.js Manages and displays user notification messages UI mstats.summary.js Container that manages registration, statistics, and reminders widgets UI mstats.registration.js Contained in summary widget; manages user registration UI mstats.statistics.js Contained in summary widget; displays summary of vehicle statistics UI mstats.reminders.js Contained in summary widget; lists overdue and upcoming maintenance reminders; manages click action when user selects a reminder UI mstats.layout-manager.js Manages navigation requests and coordinates UI layout changes Behavioral mstats.vehicle-list.js Displays vehicle tiles in one or two columns; invokes animation of child widgets; controls their contraction and expansion UI mstats.vehicle-list.js Manages vehicle tiles, which are children of vehicle list widget UI mstats.vehicle.js Displays vehicle information; manages actions of Details, Fill ups and Reminder buttons UI mstats.vehicle-details.js Gathers and displays vehicle details UI mstats.charts.js Creates charts displayed when user clicks Charts button UI mstats.info-pane.js Controls display of fill ups, reminders, and vehicle details widgets, which are created in the same file UI mstats.tile.js Moves vehicle tiles vertically and horizontally UI
- 126. 93modularity Externally Configuring Modules In Mileage Stats, some widgets are configured externally to reduce the coupling between them. For example, when the layoutManager widget is constructed in mileagestats.js, its subscribe option is populated with the mstats.pubsub.subscribe method. The rest of the options are references to the modules the layout manager is responsible for coordinating. JavaScript // Contained in mileagestats.js $('body').layoutManager({ subscribe: mstats.pubsub.subscribe, pinnedSite: mstats.pinnedSite, charts: charts, header: header, infoPane: infoPane, summaryPane: summaryPane, vehicleList: vehicleList }); Injecting dependencies through options allows the code that creates the widget to supply data, functions, and other modules during creation. This prevents the widget from needing to know how to resolve the dependencies itself, without sacrificing functionality. See “Defining Options” in Chapter 3, “jQuery UI Widgets” for more information about configuring modules. Initializing Modules The _create method of a widget contains initialization code, and the destroy method is used to clean up what the widget created. For example, in Mileage Stats, the vehicle list widget initializes the vehicle, tile, and sortable widgets when it is created. These widgets must be cleaned up in the destroy method. JavaScript // Contained in mstats.vehicle-list.js _create: function () { dataUrl = this.element.data('list-url'); this._widgetizeVehicleTiles(); this._bindEventHandlers(); this._makeSortable(); ... }, destroy: function () { this.element .sortable('destroy') .find(':mstats-tile').tile('destroy')
- 127. 94 chapter five .find(':mstats-vehicle').vehicle('destroy'); $.Widget.prototype.destroy.call(this); } The _create method uses private methods to initialize the other widgets. The _widgetizeVehicleTiles method initializes the vehicle and tile widgets and _make Sortable initializes the sortable widget. The destroy method cleans up these widgets by calling their destroy methods, and then calls the base widget’s destroy method on the last line. Communicating Between Modules In order to coordinate the responses to user actions, modules must be able to communi- cate with each other. Method calls and events are an effective way to accomplish this. As an example, the following sequence diagram shows some of the public methods that are called when a reminder is fulfilled in Mileage Stats. Sequence diagram for fulfilling a reminder When the Fulfill button on the reminders pane is selected, it publishes its status, makes the Ajax call to save the reminder, and publishes an mstats.events.vehicle.remind- ers.fulfilled event. At this point, the reminders widget has not yet updated its UI with an updated list of reminders. The layout manager then instructs the summary, info pane, and pinned site modules to retrieve updated reminder data, and they coordinate the interac- tions with their child widgets. As a result, the reminders widget that initiated the action doesn’t update its data until it is told to do so by the info pane. These interactions illustrate the flexibility of a modular design. For more information on enabling communication between widgets, see Chapter 8, “Communication.” Testing Modules Even without sandboxing, modular applications are easier to test using techniques such as unit testing. The modules can be tested by invoking each function of the interface that is exposed to other modules. For example, in Mileage Stats the header widget controls the header text it displays through its title option. The following test ensures that the header text changes each time the value of the option changes.
- 128. 95modularity JavaScript // Contained in mstats.header.tests.js test('when title option is changed, then it displays new title', function() { expect(1); var header = $('#header').header(); header.header('option', 'title', 'test title'); equal($('[data-title]').text(), 'test title', 'header text set properly'); }); When this test runs, it ensures that the _setOption method on the header widget, the code under test, updates the text for the header. JavaScript // Contained in mstats.header.js _setOption: function (key, value) { switch (key) { case 'title': this.element.find('[data-title]').text(value); break; ... } $.Widget.prototype._setOption.apply(this, arguments); } In order for the tests to run in isolation, each test file must contain a copy of the HTML markup that mirrors the markup to which the code under test will be applied. You can find this markup at the top of the test files. JavaScript // Contained in mstats.header.tests.js module('Header Widget Tests', { setup: function () { $('#qunit-fixture').append('<div class="header" id="header">' + '<div><div><h1 data-title>Dashboard</h1>' + ... '</div>' ); } }); For more information about unit testing, see Chapter 13, “Unit Testing Web Applica- tions.”
- 129. 96 chapter five Summary There are several possibilities for imposing a modular structure on complex JavaScript applications. JavaScript objects are a good choice for implementing modules that are not associated with elements on the page. When the boundaries of the module are defined by visual elements of the UI, consider using jQuery UI widgets. You can use jQuery plug- ins to extend the functionality of the jQuery library. Independent of the types of modules you use, you can expect the same sorts of benefits from modularity that you see in solutions created with object-oriented lan- guages. A modular design makes your code base more maintainable, easier to test, easier to troubleshoot, and suitable for team development. The boundaries of your modules can be influenced by considering page layouts, ani- mations used during transitions, and the need to selectively refresh parts of the UI based on user actions. When defining these boundaries, consider the various layouts in the ap- plication and the regions in those layouts. Also, take animations into account, as well as content that must be updated with Ajax. The modules should each be easily identifiable as belonging to the presentation (UI) layer, the behaviors layer, or the infrastructure layer. Further Reading jQuery Plug-in Authoring Guidelines: http://docs.jquery.com/Plugins/Authoring For more information about how to build widgets, see Chapter 3, “jQuery UI Widgets” and Chapter 14, “Widget QuickStart.” To learn more about data abstraction in Mileage Stats, see Chapter 6, “Client Data Management and Caching.” For more information on enabling communication between widgets, see Chapter 8, “Communication.” For more information about how the tile widget performs its animation, see Chapter 9, “Navigation.” For more information about unit testing, see Chapter 13, “Unit Testing Web Applications.” For other examples of JavaScript libraries and frameworks, see “Architectural Alternatives” in Chapter 2, “Architecture.” For examples of other libraries that support a modular design, see: • Prototype: http://prototypejs.org • Script.aculo.us: http://script.aculo.us To access web resources more easily, see the online version of the bibliography on MSDN: http://msdn.microsoft.com/en-us/library/hh404094.aspx.
- 130. 97 Introduction Web applications are intended to present data to the user. In rich, interactive, client- centric applications like Mileage Stats, users expect the application to respond quickly to mouse gestures, page transitions, and the saving of form data. Delays caused by data re- trieval or saving data can negatively impact the user’s experience and enjoyment of the site. Therefore, carefully managed data retrieval and caching is critical to today’s web applications. Note: The term data caching used in this documentation refers to the caching of client-side JavaScript objects within the DOM (document object model) rather than using the browser’s built-in page caching mechanism. A sound client-side data management strategy is critical to the success of a web application and will address fundamental concerns such as: • Maintainability. Writing clean maintainable JavaScript code requires skill, discipline, and planning. The Mileage Stats data implementation addresses maintainability by providing a simple object for centralized data access that other application objects use to execute data requests and to cache the results. • Performance. Client-side caching and prefetching of data plays a key role in achieving application responsiveness from the user’s perspective. Eliminating unnecessary data calls to the server enables the browser to process other tasks, such as animations or transitions, more quickly.. Mileage Stats addresses these performance concerns by caching data returned from the server, using prefetching to acquire data that a user is likely to view, and using Ajax to perform asynchronous data calls to the server. • Scalability. Client-side objects should avoid making repeated requests to the server for the same data. Unnecessary calls to the server require additional server-side resources, which can negatively impact the scalability of your application. Mileage Stats uses client-side data caching to increase scalability. • Browser support. Your choice of a data caching mechanism will influence which browsers your application can support. Rather than employing a browser-specific Client Data Management and Caching 6
- 131. 98 chapter six feature such as local storage, Mileage Stats caches data using a generic JavaScript object caching mechanism so that older browsers such as Windows® Internet Explorer® 7 are supported. In this chapter you will learn: • How Mileage Stats manages and centralizes application data requests. • The benefits of a client-side data manager and how data requests are abstracted. • How to improve application performance by caching and prefetching data. The technologies and libraries discussed in this chapter are Ajax, JavaScript, jQuery, and jQuery UI Widgets. Note: Data validation on the client and server is covered in Chapter 11, “Server-Side Implementation.” Client-Side Data Design The Mileage Stats data solution centers on the data manager, which handles client-side data requests and manages the data cache. The diagram below shows the relationship of the client-side JavaScript objects to one another and to the server JSON (JavaScript Object Notation) endpoints. Mileage Stats client-side data architecture Mileage Stats objects use URLs when requesting data from the server. URLs were chosen because their use simplifies the data manager’s design by providing a mechanism to decouple the server JSON endpoints from the data manager’s implementation. The URL contains the JSON endpoint and, optionally, a data record key value corre- sponding to the requested object. The URL typically aligns with the UI elements the object is responsible for. For example, the reminders widget uses “/Reminder/JsonList/1” to retrieve the reminders for the vehicle with the ID of 1. When data is requested from the data manager, it returns the data to the caller and optionally caches it. The caching of data improves the performance of the application because repeated requests to the server for the same data are no longer necessary. In addition to data caching, Mileage Stats also prefetches the chart data. The chart data is prefetched on the initial page load because there is a reasonable expectation that
- 132. 99client data management and caching users will use the Charts page to compare their vehicles. The prefetching of this data enables an instant response when the user navigates to the Charts page. In your applications, the amount of data you elect to prefetch should be based on the volatility of the data, the likelihood of the user accessing that data, and the relative cost to get that data when the user requests it. Of course, the number of concurrent users and the capabilities of your web and database servers also play a role in this decision. Data Manager All Ajax data requests are routed through the dataManager JavaScript object contained in the mstats-data.js file. The data manager is responsible for performing data requests and managing interactions with the data cache. The data manager has a simple public interface that exposes two methods: sendRequest, which processes Ajax calls to the server, and resetData, which removes a requested item from the data cache. The next three sections examine the benefits of the data manager abstraction, look at how data requests are initiated by jQuery UI widgets, and show how those requests are executed by the data manager. Benefits of the Data Manager Abstraction Abstracting the data request implementation as a data manager object provides an injec- tion point for data caching, which is a cross-cutting concern. Data requestors get the full benefit of data caching without taking on another dependency or implementing addi- tional code. Isolating the data cache also makes it much easier to change the data cache implementation because only the data manager has a direct dependency on it. The data manager improves application testability by allowing developers to unit test data requests and data caching in isolation. The data manager also facilitates changing the application over time. Evolution of an application is required not only after its release but during development as well. For example, the team added a feature to the data manager that would have required modifying all the Ajax request code. Had the data manager not been implemented, the change would have been riskier and potentially costlier. The team discovered that when the website was deployed to a virtual directory as opposed to the root directory of the web server, the URLs in the JavaScript code had not taken the virtual directory into account. The fix for this problem only had to be applied to the data manager, which saved development and testing resources. This feature is dis- cussed in the “Performing Ajax Requests” section below. Data Request Client-side data requests in Mileage Stats are initiated by jQuery UI widgets and Java Script objects, and performed by the data manger. The data manager sendRequest method has a signature similar to the signature of the jQuery ajax method. Widgets making requests set their calls up as if they are calling jQuery ajax, passing an options object that encapsulates the URL, a success callback, and optionally an error callback or other callbacks such as beforeSend or complete.
- 133. 100 chapter six Data Request Options When a widget is constructed, the options provided supply the methods needed to execute a data request or to remove an item from the data cache. Externally configuring widgets removes tight coupling and hard-coded values from the widget. Widgets can also pass their options, like sendRequest, to other widgets they create. This technique of external configuration enables Mileage Stats widgets to have a common data request method injected during widget construction. In addition to run- time configuration, this technique also enables the ability to use a mock implementation for the data request methods at test time. In the following code, the summaryPane widget is constructed, and its sendRequest and invalidateData options are set to corresponding data manager methods. The sum- mary widget does not make any data requests; instead, these two methods will be passed into child widgets created by the summary widget. JavaScript // Contained in mileagestats.js summaryPane = $('#summary').summaryPane({ sendRequest: mstats.dataManager.sendRequest, invalidateData: mstats.dataManager.resetData, publish: mstats.pubsub.publish, header: header }); In the code snippet below, the summary widget constructs the child widget, statistics Pane, and passes the above sendRequest and invalidateData data manager methods as options. Setting these options replaces the default implementation defined in the statis- tics widget for making data requests. Now, when the statistics widget performs a data request, the method defined in the data manager will be executed. JavaScript // Contained in mstats.summary.js _setupStatisticsWidget: function () { var elem = this.element.find('#statistics'); this.statisticsPane = elem.statisticsPane({ sendRequest: this.options.sendRequest, dataUrl: elem.data('url'), invalidateData: this.options.invalidateData, templateId: '#fleet-statistics-template' }); }, The dataUrl option is the URL or endpoint for the data request. The url value is stored below in the data- attribute in the HTML. The statisticsPane widget is attached to and is queried by the elem.data method call seen above. Externally configuring data endpoints prevents you from having to hard-code knowledge about the server URL structure within the widget.
- 134. 101client data management and caching CSHTML // Contained in ViewsVehicle List.cshtml <div id="statistics" class="statistics section" data-url="@URL.Action("JsonFleetStatistics","Vehicle")"> ... </div> Performing a Data Request The sendRequest method has the same method signature as the jQuery ajax method, which takes a settings object as the only argument. The _getStatisticsData method, below, passes the sendRequest method an object literal that encapsulates the url, success, and error callbacks. When the Ajax call completes, the appropriate callback will be invoked and its code will execute. JavaScript // Contained in mstats.statistics.js _getStatisticsData: function () { var that = this; that.options.sendRequest({ url: this.options.dataUrl, success: function (data) { that._applyTemplate(data); that._showStatistics(); }, error: function () { that._hideStatistics(); that._showErrorMessage(); } }); }, The above pattern simplified the Mileage Stats data request code because it does not need to know about the data caching implementation or any other functionality that the data manager handles. Now that you understand how widgets and JavaScript objects initiate a data request, let’s examine how the data manager makes the Ajax request to the server and see how data caching is implemented. Performing Ajax Requests The data manager sendRequest method is used to request data from the server and in some places it is used to execute a command on the server, such as fulfilling a reminder. Because the jQuery ajax method signature is the same for requesting as well as posting data, the team chose to implement a single method for Ajax calls to the server. In addition to success and error callbacks, the sendRequest method has an option to cache the re- quest or not. By default, requests are cached.
- 135. 102 chapter six Mileage Stats has two use cases where data is not cached: data requests that only post data to the server, and the Pinned Sites requests. Results of the Pinned Sites requests are not cached because these requests are only initiated by events after data has changed. Because Pinned Sites only refreshes its data after a change, the data request needs to get fresh data from the server. The diagram below illustrates the logical flow of a data request. The data manager services the request by first checking if the request should be cached and, if so, checks the cache before making a call to the server. Upon successful completion of the request, the resulting data will be returned to the user and added to the cache according to the option. Data request Now let’s look at the code that implements the functionality of the above diagram. The sendRequest method, shown below, first modifies the URL to account for the vir- tual directory the website is deployed to by calling the getRelativeEndpointUrl function. Using the modified URL, it attempts to retrieve the requested data from the data cache. The options are then merged with the data manager’s default options. If the caller wants the data cached, and data was found in the cache, it’s immediately returned to the caller. If the data is not found, the jQuery ajax call is made. If successful, and the caller re- quested the data to be cached, it is added to the cache and the caller’s success callback
- 136. 103client data management and caching is invoked. If an error occurs and the caller implemented an error callback, it will be in- voked. If a global Ajax error handler has been defined, it will be invoked after the error callback. Note: The jQuery ajax method can be configured at the global level to define default options as well as default event handlers. Mileage Stats defines the global Ajax error handler shown above. For more information about how Mileage Stats implements the global Ajax error handler, see the “User Session Timeout Notification” section in Chapter 10, “Application Notifications.” JavaScript // Contained in mstats.data.js sendRequest: function (options) { // getRelativeEndpointUrl ensures the URL is relative to the website root. var that = mstats.dataManager, normalizedUrl = mstats.getRelativeEndpointUrl(options.url), cachedData = mstats.dataStore.get(normalizedUrl), callerOptions = $.extend({ cache: true }, that.dataDefaults, options, { url: normalizedUrl }); if (callerOptions.cache && cachedData) { options.success(cachedData); return; } callerOptions.success = function (data) { if (callerOptions.cache) { mstats.dataStore.set(normalizedUrl, data); } options.success(data); }; $.ajax(callerOptions); }, Note: getRelativeEndpointUrl is a utility method in the mstats.utils.js file that is used to modify the URL passed in the argument, inserting the virtual directory the website is installed under. This is necessary because the virtual directory is not known until run time.
- 137. 104 chapter six Data Cache The Mileage Stats data manager uses an internal data cache for storing request results; the data cache is only accessed by the data manager. Making the data caching internal to the data manager allows the caching strategy to evolve independently without affecting other JavaScript objects that call the data manager. The data cache is implemented using a JavaScript object named dataStore that is contained in the mstats-data.js file. Other data cache storage locations could include the DOM, a browser data storage API or a third-party library. The dataStore JavaScript object was implemented because Mileage Stats supports Internet Explorer 7, which does not support the HTML5 web storage specification. Adding and Retrieving Cached Data Note: The Mileage Stats dataStore object is scoped to the page, not the browser window. Consequently, when the page is fully reloaded from the server, the cached data will no longer be cached since the data cache object will be recreated when the page loads. Mileage Stats integrates client-side data caching into the data manager’s sendRequest method implementation that was described in the previous section. Internally, the dataStore is implemented using name/value pairs. It exposes three methods: get, to retrieve data by a name; set, to cache data by a name; and clear, to re- move data corresponding to a name. JavaScript // Contained in mstats.data.js mstats.dataStore = { _data: {}, get: function (token) { return this._data[token]; }, set: function (token, payload) { this._data[token] = payload; }, clear: function (token) { this._data[token] = undefined; }, };
- 138. 105client data management and caching Removing a Data Cache Item In addition to the data manager retrieving and adding data to the cache, it also provides the resetData method for removing cached data by URL. JavaScript // Contained in mstats.data.js resetData: function (endpoint) { mstats.dataStore.clear(mstats.getRelativeEndpointUrl(endpoint)); } Mileage Stats objects call the resetData method when client-side user actions make the cached data invalid. For example, when a maintenance reminder is fulfilled, the requeryData method shown below will be called by the layout manager widget. When designing your data architecture, it is important to consider which client-side actions should invalidate the cache data. JavaScript // Contained in mstats.statistics.js refreshData: function () { this._getStatisticsData(); }, requeryData: function () { this.options.invalidateData(this.options.dataUrl); this.refreshData(); }, The requeryData method first invokes the invalidateData method, passing the URL of the cache item to remove. The invalidateData method is an option on the statistics widget, which was passed the data manager’s resetData method when the widget was created. Now that the data cache item has been removed, the next call to refreshData will result in the data manager not locating the cached data keyed by the URL, and then executing a request to the server for the data. Summary In this chapter, you have learned about the design, benefits, and implementation of a centralized client-side data manager that executes all Ajax requests and manages the cach- ing of data. This approach simplifies testing, facilitates application or external library changes over time, and provides a consistent pattern for objects to follow to execute data requests. You have also learned how Mileage Stats keeps its widgets free from external depen- dencies and the hard-coding of server URLs by constructing and configuring them exter- nally. This approach of injecting external dependencies increases the flexibility and maintainability of the JavaScript code, and the absence of hard-coded server URLs pre- vents the creation of brittle JavaScript code.
- 139. 106 chapter six Further Reading For more information on jQuery UI widgets, see Chapter 3, “jQuery UI Widgets.” For more information on the global Ajax error handler, see Chapter 10, “Application Notifications.” For more information on data validation, see Chapter 11, “Server-Side Implementation.” HTML 5 Web Storage: http://dev.w3.org/html5/webstorage/ jQuery: http://jquery.com/ jQuery ajax() method: http://api.jquery.com/jQuery.ajax/ jQuery data() method: http://api.jquery.com/data/ jQuery ajaxError() method: http://api.jquery.com/ajaxError/ Ajax Programming on Wikipedia: http://en.wikipedia.org/wiki/Ajax_(programming) To access web resources more easily, see the online version of the bibliography on MSDN: http://msdn.microsoft.com/en-us/library/hh404094.aspx.
- 140. 107 Introduction Both hybrid and single-page interface (SPI) web applications that do not perform full- page post backs in order to change the rendered user interface (UI) must use client-side techniques for manipulating the document object model (DOM). This DOM manipulation could include updating the content of the page, displaying new UI elements, or loading entire pages in response to user gestures and other events. The three client-side tech- nologies you can use when implementing these techniques are HTML, cascading style sheets (CSS) and JavaScript. This chapter discusses how you can clearly define the roles of HTML, CSS, and Java Script on the client to ensure that developers and designers can work together without affecting each other’s code. You will also see how to use JavaScript to manipulate HTML effectively in the browser. In this chapter you will learn: • The roles and responsibilities of HTML, CSS, and JavaScript within a client applica- tion. • How to use jQuery to select and manipulate HTML elements. • How to use jQuery to generate new HTML within the client. • How to use jQuery Templates to generate new HTML within the client. • How to choose the most appropriate option when manipulating HTML. Technologies discussed in this chapter are HTML, CSS, and JavaScript. The Roles and Responsibilities of Client-Side Languages When building the client-side portion of a web application, you generally use three tech- nologies that can be viewed as separate development languages: HTML, CSS, and Java Script. You may not be accustomed to thinking of these technologies as development languages. However, considering them in this way can help to clarify the role that each one plays in your application, and can help you keep their responsibilities separate. Manipulating Client-Side HTML 7
- 141. 108 chapter seven As with any development language, it is possible to use these languages in a way that makes the application harder to maintain and extend. This can be avoided by taking ad- vantage of the strengths of each language, and by keeping their responsibilities clear and distinct. Structure, Appearance, and Behavior There are three areas of responsibility within client applications, and each client-side language is associated with one of those areas. The three areas are: • The structure of the UI. HTML is used to define the logical structure of the UI. Structure refers to the hierarchy of objects that make up the UI, not the visual appearance or layout of the UI. Today, HTML is ideally used only for the logical, non-visual structure. • The appearance of the UI. This is the responsibility of CSS, which applies styling to elements and manages visual layout (positioning and flow) for the UI. CSS allows designers and developers to change the layout, styling, and appearance of the UI elements without requiring changes to the structure defined by the HTML. • The behavior of the UI. JavaScript is responsible for the behavior of the applica- tion. It is used to define or re-define how UI elements respond to user interactions and gestures, as well as other events not directly initiated by the user. HTML also has an additional responsibility that might not be immediately obvious. It is frequently used to transport the data that the client requires from the server. For ex- ample, when the Mileage Stats Reference Implementation (Mileage Stats) renders a page, the information about the vehicles is stored as metadata in attributes within the HTML markup. Using metadata in this way is discussed in “Using Data- Attributes” later in this chapter. It is surprisingly easy to blur the lines of responsibility among the client-side lan- guages. For example, you might be tempted to use a CSS class to associate semantic or structural meaning to an HTML element. In fact, this approach was commonly used in the past to identify elements in order to attach some behavior. An example of this approach would be to add an attribute such as class=”vehicleLink” to relevant hyperlinks so that you can select these elements in your JavaScript code. However, using a CSS class in this way is problematic because it muddles the responsi- bilities of CSS as a language. In particular, if you use a CSS class to specify the style and the behavior of elements, your designer might unintentionally break your application by changing a class name or relocating a CSS class to another element when updating the layout and style of the page. Adding Interactive Behavior to an Application When you have a simple web application, you can rely on the web server to handle changes to the HTML by posting back to the server so that it can update the page, or by loading a different page that contains the required HTML. However, this approach limits the level of interactivity in the application. There are several ways that JavaScript code can add interactivity to a page through manipulation of the HTML structure and content without requiring a full-page reload.
- 142. 109manipulating client-side html Some typical approaches are: • Using the existing page structure and simply hiding and showing elements as necessary. This is the simplest approach and is appropriate in some scenarios. For example, you might use JavaScript code to change the CSS properties that specify the visibility of elements within the page as it is loading, or in response to user actions. • Using JavaScript to modify, add, or remove elements within the browser’s DOM. The code can also add, remove, or update the attributes and style classes applied to elements. For small applications that do not require the appearance, structure, and behavior to change very much, this may be an acceptable solution. For example, you might want to add a new UI element to the page, enable or disable controls in the page, change the text displayed in elements, or show a different image. • Using JavaScript to retrieve HTML fragments from the server and add them to the DOM. This is an ideal approach when the server-generated HTML fragments can be reused directly within the client. The HTML fragments may be generated dynami- cally on the server to include data relevant to the current state of the application, or may be static content, perhaps read directly from disk files. • Using templates to generate HTML fragments dynamically on the client, and adding or replacing elements in the DOM with the generated HTML. This approach is ideal when there is a lot of content to be generated on the client. It can be used to combine HTML in the template with data provided by the server. This is the solution used in Mileage Stats. Using a JavaScript Library to Manipulate the DOM For a rich user experience, where your application can change the UI while avoiding full page reloads, it is obviously necessary to have a mechanism for manipulating the DOM. JavaScript is the primary way to do this. However, due to different DOM and JavaScript implementations within different browsers, using a JavaScript library to shield you from cross-browser compatibility issues is the only practical approach for anything more than very simple interactions. There are several libraries that do this very well, but this chapter discusses only the jQuery library. Mileage Stats uses the jQuery library because it provides many powerful methods for selecting and changing elements in the DOM, modifying element attributes, wrapping existing elements, and creating new elements while remaining compatible with almost all modern browsers. Note: For more information about jQuery, see “jQuery Home Page” in the “Further Reading” section of this chapter. For more information about browser support for jQuery, see “jQuery Browser Compatibility” in the “Further Reading” section of this chapter. jQuery uses an element selection syntax that is very similar to CSS, and extends it to provide additional ways to select elements within the HTML. This means that the same syntax you use in style sheets to select elements can be used to attach JavaScript
- 143. 110 chapter seven behaviors to elements. Once the elements have been selected, the code can modify them, remove them, or insert new elements within them. Modifying these elements could be as simple as adding or removing a CSS style, or changing the contents of the element. The remainder of this chapter focuses on how you can select elements and modify them, and how you can add new HTML elements to the page rather than changing the behavior of existing elements. Selecting and Manipulating Existing HTML Elements Many scenarios for interactive web applications only require client-side languages such as CSS and JavaScript to modify existing elements. Modification usually involves adding, removing, or updating the attributes and style classes applied to elements. In some cases, CSS alone may be capable of performing the required changes, such as changing the style of hyperlink elements as the mouse pointer passes over them. In other cases, JavaScript code is required to manipulate the elements directly. Before you can perform actions on elements, you must specify how the CSS or Java Script will select them. You can select one or more elements, as described in the following section, and then use a range of techniques to manipulate the elements. These techniques are described in “Modifying Existing Elements,” later in this chapter. Selecting Elements There are several ways you can use selectors within an application to select elements you want to modify. Each approach has its own benefits and drawbacks: • Using data- attributes. data- attributes (pronounced “data dash” attributes) provide a simple and efficient way to select elements based on the presence and value of attributes whose name starts with “data-”. jQuery provides the data method for working with data- attributes, as you will see in the next section of this chapter. This is the preferred approach for most element selection scenarios. • Using the id attribute. This works well when there is a single element in the DOM with the specified value for its id attribute. However, this approach often causes jQuery to search the entire DOM to find the element, which can have significant impact on the client-side performance of your application. In addition, using the id as a selector is not a valid approach when you must support multiple elements on the page that may have the same id attribute values. • Using element name selectors. This is a useful technique when you want to apply an action to all elements of a specific type (for example, all of the <tr> elements in a table). However, it can cause problems because it is easy to select more elements than intended if the element occurs elsewhere in the page. It also means that changing the type of elements in the HTML in the future will require changes to the JavaScript code. • Using class name selectors. This is a useful technique for selecting multiple elements across the element hierarchy, but (as described in the introduction to this chapter) it can cause confusion between class names used for applying CSS styles and class names used as selectors to apply JavaScript behavior. It can also lead to
- 144. 111manipulating client-side html subtle bugs when the JavaScript adds and removes classes on elements; suddenly the class name you use to find an element is no longer there. • Using relative location. You can select one or more elements by relative position within the DOM with respect to a known element. For example, you might select all of the elements that are the children of a target element. This can be an efficient way to locate elements because it is usually much faster than searching from the root element of the DOM. It can be combined with the previous selection meth- ods. However, selectors that rely on this approach are fragile because they depend on the specific hierarchy of the HTML structure. Note: All of these selection methods run the risk of impacting client-side performance. It is important to ensure that you provide additional context with the selectors to prevent searching the entire DOM. See “Using Context” below for more information. For more information on jQuery selectors, see “jQuery Selectors” in the “Further Reading” section of this chapter. It is important to note that your HTML structure becomes an unofficial contract between the server and the client. The JavaScript code will expect elements with specific ids to exist as well as expecting the presence of certain data- attributes. The more as- sumptions that the JavaScript makes about the HTML, the more fragile the application will become. Writing unit tests to verify that the HTML provides the expected metadata can save significant effort if changes to the HTML structure are required at a later time. For more information on how the server can provide the correct initial HTML to the client, see “Providing HTML Structure” in Chapter 11, “Server-Side Implementation.” Using Context One of the ways to achieve maximum performance when selecting elements is to specify a context to search within. This context allows searches based on a known and referenced element. There are two ways to provide this context. The jQuery method can take a second parameter, a known element, to scope the search through the DOM. Alterna- tively, the find method of an element can be used to obtain a collection of all or specific child elements. Both techniques are shown here. JavaScript // Example: select the child element(s) with id="dashboard-link" // Both of the following lines return the same elements. var myLinkElements =$('#dashboard-link', someKnownElement); var myLinkElementsByFind = someKnownElement.find(‘#dashboard-link’); Similar methods that you can use to select elements based on their relative position in- clude next, nextAll, prev, prevAll, siblings, closest, and parent. You can use this approach to find a collection of elements, and then apply other selection techniques on the collec- tion to maximize efficiency.
- 145. 112 chapter seven Using Data- Attributes HTML5 provides data- attributes as a mechanism for applying metadata to elements. It turns out that this metadata is also useful when selecting elements. The browser does not use data- attributes when rendering the page. This means that they can be used to select elements independently of the element hierarchy and styling. In addition, data- attributes can store other arbitrary metadata, such as the state of a UI element, because they are merely attributes on the element. For example, the attri- bute data-action=”reminders” can represent the action=”reminders” name/value pair. In Mileage Stats, data- attributes are used to provide the client with useful informa- tion. The client will make Ajax requests to the server to load and save data, so the client must know the URLs corresponding to the endpoints for those data requests. Rather than hard-coding the URLs within the client-side script, the server can provide the URLs in the HTML by using data- attributes, and the code can extract this value when it needs to make a request to the server. This means that the code will continue to work if the URLs change, such as when changing the routing in a Model-View-Controller (MVC) application or when moving the application to a different virtual directory on the server. The following code shows the CSHTML code that Mileage Stats uses to render the vehicle list on the dashboard. Both the id attribute and CSS class are set so that they can be used for styling the vehicle list with CSS. There are also two data- attributes that contain URL metadata for use within the JavaScript that controls the behavior of the vehicle list. CSHTML <!-- Contained in_VehicleList.cshtml --> <div id="vehicles" class="article @compactClass" data-list-url="@Url.Action("JsonList","Vehicle")" data-sort-url="@Url.Action("UpdateSortOrder", "Vehicle")"> ... </div> The server-side code shown above creates the following HTML in the page sent to the client. HTML <!-- result of _VehicleList.cshtml --> <div id="vehicles" class="article" data-list-url="/Vehicle/JsonList" data-sort-url="/Vehicle/UpdateSortOrder"> ... </div> Note: Only the first hyphen in the attribute name is significant. Everything in the attribute name after the first hyphen is treated as a simple string value. For example, data-list-url=”/Vehicle/JsonList” is a data- attribute containing the metadata list-url=”/Vehicle/JsonList”.
- 146. 113manipulating client-side html To select all of the elements that carry the data-list-url attribute shown in the previ- ous HTML listing, you could use the following JavaScript code. JavaScript // Example: select the element(s) with a data-list-url attribute var myVehicleElement = myVehicleList.find(‘[data-list-url]’); The jQuery library also supports data- attributes directly through the data method, which can get and set multiple values on the attribute. The following example shows how you can get the value of the metadata (the value of the name/value pair) from a refer- enced element using the data method. Note that when using jQuery’s data method, the “data-” part is omitted and just the remainder of the attribute name is used. JavaScript // Example: get the value of a data-list-url attribute var myUrl = myVehicleElement.data(‘list-url’); Because data- attributes are ideal for selecting elements, and for getting or setting data associated with those elements in the DOM, you should use them wherever possible. If your designer changes the layout and style information in the HTML, your JavaScript won’t break. In addition, data- attributes allow the server to easily provide the client with useful data without the client having to parse UI-specific HTML. Use data- attributes wherever it is appropriate to specify metadata in the server-generated HTML or with JavaScript on the client. Keep in mind that the HTML represents the logical structure of the UI, not the visible layout and style. The use of data- attributes provides you with a mechanism for annotat- ing the structure and adding metadata without using style class names or element identi- fiers. Modifying Existing Elements After you select your target element or set of elements, you can modify them as required. The following sections provide some examples of scenarios and solutions for modifying existing elements within the HTML structure of the page. Showing and Hiding Content When the user first navigates to your application, the server will return the HTML for the page. This HTML includes the locations (URLs) for the resources such as images, scripts, and HTML fragments that the browser will download as secondary requests in order to create the complete page. However, there will be a noticeable delay as the content and scripts are downloaded, the HTML and CSS is parsed, and any startup scripts run. While usually short, this delay can affect the user experience, especially if there are a large number of secondary requests for scripts, images, or other assets, or if the user is on a slow Internet connection. One solution is to include in the HTML sent from the server a progress indicator that shows that the application is loading. Then, once the rest of the content is available, the application can use JavaScript to change the UI by hiding the progress indicator and
- 147. 114 chapter seven replacing it with the desired HTML (which was also part of the server response, but hid- den using CSS styles). The code needs only to change the CSS styles applied to the relevant elements. This technique means that the user perceives a reduced waiting time and better responsiveness, even though there is no actual increase in performance. Note: Many applications require JavaScript. One approach to communicating this requirement to the user is to include a notice in the initial HTML that the site requires JavaScript. The first action the application script takes is to hide the notice, so that it remains visible only when the client does not support JavaScript. A more common approach is to require that the application run on a recent browser and check that features such as JavaScript are enabled. This is often easier for users, who are immedi- ately aware that the application requires JavaScript or other features, and it simplifies the work of technical support teams who do not encounter errors caused by the use of older browsers. Updating Element Attributes Interactivity in the page can be implemented using JavaScript code that runs in response to user actions, or when events such as completion of page load occur. Typically, the HTML sent from the server will contain all of the structure (the HTML element hierarchy) required to render the page. Unless you actually need to build all or part of the UI dy- namically on the client, having the initial structure in place is much faster than creating the same structure in the script each time. However, you may need to modify the HTML elements after the page has loaded in the browser. For example, the Mileage Stats main page contains a header with links to the dash- board and chart views (The HTML is shown here with some content removed for clarity). HTML <!-- Rendered from _Layout.cshtml --> <div class="nav"> <span id="welcome">Welcome <span data-display-name>Sample User</span></span> [ <a href="/Dashboard" id="dashboard-link">Dashboard</a> | <a href="/Chart/List" id="charts-link">Charts</a> ... </div> These hyperlinks must be updated when the page loads to include in the URL any subfolder name (if the application is installed on the server in a subfolder of the default website). If this is not done, the links will not work correctly. When the page load is complete, the following JavaScript runs in the browser to update the href attributes of these hyperlink elements to include the correct URL. JavaScript // Contained in mstats.header.js _adjustNavigation: function () { var state = $.bbq.getState() || { }, url = this.element.data('url'),
- 148. 115manipulating client-side html newUrlBase = mstats.getRelativeEndpointUrl(url); state.layout = 'dashboard'; this.element.find('#dashboard-link') .attr('href', $.param.fragment(newUrlBase, state)); state.layout = 'charts'; this.element.find('#charts-link') .attr('href', $.param.fragment(newUrlBase, state)); }, The first part of this code uses the jQuery Back Button and Query (BBQ) plug-in to create a state object and get the actual base URL of the page. This value is discovered on the server and can be obtained from the getRelativeEndpointUrl method of the global mstats object defined in the JavaScript of the page. Chapter 9, “Navigation,” discusses in more detail the BBQ plug-in, the use of a state object, and how this section of code works. After the base URL has been established, the code changes the name/value pair named layout within the state object instance so that it specifies the correct layout style (dashboard or charts) for each hyperlink. It then uses the find method to select the ap- propriate hyperlink element based on the value of its id attribute, and sets the value of the href parameter to the correct URL. This URL is a combination of the base URL of the application and the relevant layout property held in the state object instance. Mileage Stats uses data- attributes both to locate elements and to store data values in the DOM. As another example, the _bindNavigation method of the fill ups widget (part of which is shown below) relies on the presence of a data-action attribute to locate navigation buttons. The method also uses the data-action and data-fillup-id attributes to determine which action to take and which fill up to target. JavaScript // Contained in mstats.fillups.js _bindNavigation: function () { var that = this; this.element.delegate('[data-action]', 'click.' + this.name, function (event) { if ($(this).data('action') === 'select-fillup') { that._setOption('selectedFillupId', $(this).data('fillup-id')); event.preventDefault(); } }); }, The above sample uses a specific type of jQuery selector, named the “Has Attribute” selector, which simplifies the selection of elements having a specific attribute. For more information on this type of selector, see “jQuery Selectors” in the “Further Reading” section of this chapter.
- 149. 116 chapter seven Generating and Loading New HTML in a Page In the previous section, you saw how you can select HTML elements and manipulate them. This obviously requires existing elements to work with. However, you will often need to create new elements and content within the existing HTML structure. There are several ways to generate new HTML and modify the existing HTML structure on the client. Typical techniques, which are discussed in this chapter, are: • Generating the HTML structure dynamically using JavaScript and jQuery • Retrieving HTML fragments from the server and injecting them into the page • Using templates both to retrieve and to generate the HTML structure to insert into the page Generating HTML Dynamically with JavaScript and jQuery When developing a hybrid or SPI application, you often need to modify the existing page by inserting into it fragments of new HTML. You can, of course, remove elements from the page as well, but it is usually easier to change the CSS styles that control visibility. Mileage Stats generates and inserts fragments of HTML into its pages in several places. For example, it uses JavaScript to add new elements to the page structure as the user navigates through the application. The following code (it is part of the info pane widget) creates the HTML structure that displays a vehicle’s details. JavaScript // Contained in mstats.info-pane.js _setupDetailsPane: function () { var elem = this.element, options = this.options; if (!elem.find('#details-pane').length) { elem.find('div:first') .append('<div id="details-pane" class="tab opened section" />'); } this.vehicleDetails = elem.find('#details-pane').vehicleDetails({ // options for the widget }); }, This code uses the find method to check if the Details pane is already present in the structure. If it does not exist, the code locates the first div element within the current context and uses the append method to insert a new div element with id=”details-pane” into the page. Generally, the amount of HTML generated with script should be small. Script that creates large amounts of HTML is difficult to read and can easily create a structure that is invalid because of syntax errors in the code. If you need to generate a large amount of HTML, you should reevaluate the design or consider using one of the other methods described in this section to retrieve or generate the HTML you require.
- 150. 117manipulating client-side html Retrieving HTML Fragments from the Server In some situations, it may make sense to retrieve an HTML fragment from another source (for example, a URL on the web server) and inject it directly into the page, perhaps after manipulating it, rather than dynamically generating the content on the client. For example, it may make sense to reuse an HTML form generated on the server and dynamically em- bed it in a web page, rather than generating the entire form and its contents with Java Script. This approach can simplify the client-side code by moving some of the complexity to the server. Typically, you will use Ajax methods, including the load method of existing elements, to load the new content asynchronously, directly into the target element. An alternative is to retrieve the new content in the background, perhaps in a hidden element or as a string variable, and then insert it into the page at the appropriate location using JavaScript and jQuery. The final version of Mileage Stats does not retrieve HTML fragments from the server. However, this technique was investigated during development. Content Retrieval Decisions in Mileage Stats Now that we’ve arrived at the topic of using HTML fragments and templates, let’s take a moment to talk about the design process our team followed while looking for the optimal solution. Since we knew that we wanted to support both a full-page reload and a hybrid experience for most of the features in Mileage Stats, we realized that we needed to generate HTML on the server as well as manipulate the HTML on the client. Our goal was to reuse as much HTML as possible, following the Don’t Repeat Yourself (DRY) principle. Unfortunately, this was more difficult than expected. The markup necessary for the full- page reload scenarios was rendered as large chunks of HTML combined with data, while the markup needed for the SPI scenarios was focused and generally independent of the data. Our strategy was to break the server-side HTML views into small, granular, partial views (small fragments of the UI). The client-side code could request the partial views using an Ajax call, and use the result to replace a small portion of the rendered UI. When we needed to reload a full page, the server could assemble the requested page from the granular partial views and send the complete page to the client. In this way, none of the HTML would be duplicated. We envisioned the final result as a set of composable blocks that could be used to build the UI structure for both scenarios. Once we began implementing this strategy, we found that the code quickly became very complicated. Both the controller and the view code became intertwined and confus- ing. Many conditional blocks were required to share the numerous partial views between the server-side and client-side code. Back on the client side, widgets were given URLs to request the partial views they needed. This had a number of drawbacks. First, it increased the surface area of the server by exposing the additional endpoints the widgets needed to request the necessary HTML fragments. Second, the number of Ajax calls made by the client increased because each widget needed to retrieve both the required data and the partial views. The increase in calls also created additional failure points and made the error handling code for the widgets more complex.
- 151. 118 chapter seven As an alternative, we had considered using a client-side templating engine such as the jQuery Templates plug-in. That would have involved using the server-generated HTML for the full-page reload experience, and creating a second set of client HTML templates for use only on the client. We initially decided against this approach because we thought that we would be duplicating all of the HTML code that was generated on the server. However, after working through the difficulties of managing the small partial views, we decided that it would actually be easier to maintain the application if we used two methods to generate the HTML—one on the server side and one on the client side—so we chose to rewrite the application using the jQuery Template plug-in. Ensuring that the HTML that was duplicated in both the server and client code remained synchronized was a bit of a challenge. However, we were able to mitigate this issue through developer dili- gence when changing HTML or HTML templates, through test automation, and through either paired programming or code reviews (a practice we already followed to mitigate other risks). There were also several cases where we intentionally generated different HTML on the client than we generated on the server in order to accommodate the differ- ent UIs for the JavaScript-enabled experience and the non-JavaScript experience. These situations were handled on a case-by-case basis and communicated to the entire team. Using Templates to Retrieve and Generate HTML As mentioned in the previous section, another option for generating HTML is to use HTML templates. The idea behind templates is fairly simple: given a set of data and a template with placeholders for the data, you merge the HTML in the template with the data to generate an HTML fragment that can be inserted into the DOM. Templates pro- vide the opportunity for generating HTML dynamically without the need for a lot of Ja- vaScript code. This approach also allows you to generate the HTML using standard design tools, and to insert the placeholders for the data afterwards. There are a number of HTML templating engines that can be used. As you saw, Mile- age Stats uses the jQuery Templates plug-in because it was a natural fit after the team decided to use jQuery and jQuery UI. Anatomy of a jQuery Template jQuery templates consist of HTML and placeholders for data. By convention, jQuery templates usually reside in a script element that has a unique value for its id attribute, and a type attribute set to type=”text/x-jquery-tmpl”. The template script element can be located within any HTML element in the structure; it does not have to be located where the result will be displayed. The id attribute allows the jQuery template plug-in to locate the template. The type attribute is the Internet media type (also known as the MIME Type or Content Type), and the value shown above is unknown to browsers. When the browser parses the HTML, it will not parse the content of any section with the unknown type, which is the desired result. The following example shows part of the template used in Mileage Stats to generate the Statistics panel located on the Dashboard screen. The ${…} expression is a place- holder within the template that the jQuery Template plug-in uses to render a JavaScript value or expression when the data is applied to the template. The generated HTML frag-
- 152. 119manipulating client-side html ment will contain several values, including the value of the AverageFuelEfficiency prop- erty of the data applied to the template. Only the section containing the first of these placeholders is shown in this listing. JavaScript // Contained in _TemplateFleetStatistics.cshtml <script id="fleet-statistics-template" type="text/x-jquery-tmpl"> <h1>Summary Statistics</h1> <div class="statistic mile-per-gallon"> ${mstats.makeMPGDisplay(AverageFuelEfficiency)}<span class="units">mpg</span></div> ... </script> The template in this example runs other JavaScript code to create a string represent- ing the value that is inserted into the placeholder. It calls the mstats.makeMPGDisplay method, which formats the AverageFuelEfficiency value of the original data to ensure that it displays correctly. The example below shows the _applyTemplate method, which uses the previous template to generate an HTML fragment, and places this fragment in the element with the id of statistics-content. JavaScript // Contained in mstats.statistics.js _applyTemplate: function (data) { var options = this.options, $template = $(options.templateId); ... this.element.find('#statistics-content') .html($template.tmpl(data)); } When the user runs the application, the following HTML is generated: HTML // Run-time HTML <div id="statistics-content"> <h1>Summary Statistics</h1> <div class="statistic mile-per-gallon">24<span class="units">mpg</span></div> ... </div> For more information on the jQuery Template plug-in and authoring templates, see “jQuery Templates” in the “Further Reading” section.
- 153. 120 chapter seven Server-Side Rendering and jQuery Templates jQuery Templates are a powerful feature of the jQuery library. Developers can use their chosen server-side rendering engine to dynamically create or inject values into jQuery templates on the server instead of, or in addition to, having the templates combined with data on the client. This dynamic server-side rendering of the template provides many additional options when developing your application. In one respect, the approach of populating a template on the server instead of on the client resembles the approach described earlier of retrieving HTML fragments that con- tain the final HTML for display. There is no requirement to merge the data and template on the client. However, there is no reason why you cannot combine both approaches. Your server code could populate some of the dynamic content in the template, but leave other placeholders in the content that will be populated by merging the template with data on the client. Mileage Stats uses server-side code to generate jQuery templates in several places. For example, templates were used in cases where the URLs for buttons and links in the rendered page depended on where the application was deployed. For example, if the application is deployed in a subfolder instead of in the root of the website on the server, the URL must include the folder name. Mileage Stats jQuery templates are in the ViewsShared folder of the application and use the “_TemplateNAME.cshtml” naming convention so that they will be processed by the Razor rendering engine. This allows the server-side code to inject values into the template HTML before it is sent to the client. For example, the @Url.Action view helper method can render the correct URL of the add action of the vehicle controller, whether or not the application is deployed in a subfolder on the server, as shown here. CSHTML <-- Contained in _TemplateVehicleList.cshtml --> <script id="mstats-add-vehicle-button-template" type="text/x-jquery-tmpl"> <div class="framed command section"> <div> <a data-action="vehicle-add-selected" href="@Url.Action("add", "vehicle")">+ Add Vehicle</a> </div> </div> </script> The _TemplateVehicleList template shown above is processed by the Razor render- ing engine using the @Html.Partial view helper method in _Layout.cshtml, as shown below. CSHTML <!-- Contained in _Layout.cshtml --> @Html.Partial(“_TemplateVehicleList"); The HTML fragment shown below is the rendered _TemplateVehicleList template when the web application is deployed to the root web site on the server.
- 154. 121manipulating client-side html HTML <!-- Rendered to the browser at runtime --> <script id="mstats-add-vehicle-button-template" type="text/x-jquery-tmpl"> <div class="framed command section"> <div> <a data-action="vehicle-add-selected" href="/vehicle/add">+ Add Vehicle</a> </div> </div> </script> If, instead, the web application is deployed to the MileageStats folder in the root website, the rendered HTML will be the code shown below. You can see the folder name in the value of the href attribute. HTML <!-- Rendered to the browser at runtime --> <script id="mstats-add-vehicle-button-template" type="text/x-jquery-tmpl"> <div class="framed command section"> <div> <a data-action="vehicle-add-selected" href="/MileageStats/vehicle/add">+ Add Vehicle</a> </div> </div> </script> Now the template can be used within the client application, and will provide the correct URLs for the current deployment on the web server. Summary There are three key technologies that work together in the browser to enable interactive applications: HTML, CSS, and JavaScript. HTML specifies the structure of the elements available within the UI, CSS controls the styling and positioning of those elements, and JavaScript allows the elements to respond to user gestures and other events such as timers and animations. Within an application, there is often a requirement to manipulate the HTML that generates the page the user sees, and there are a number of options for selecting the HTML elements whose appearance or behavior you wish to change. Of these, the use of relative position provides the best performance, while using data- attributes can signifi- cantly help with both the selection of HTML elements and the transmission of metadata to the client code. Data- attributes also help to ensure separation between the HTML and the metadata the application requires. Finally, you saw how you can create new HTML structure within a page by using Ja- vaScript and jQuery, by retrieving fragments of HTML from the server, or by using jQuery Templates on the client to combine data retrieved from the server with HTML
- 155. 122 chapter seven included in the templates. Further Reading jQuery Home Page: http://jquery.com jQuery Browser Compatibility: http://docs.jquery.com/Browser_Compatibility jQuery Selectors: http://api.jquery.com/category/selectors jQuery Templates: http://api.jquery.com/category/plugins/templates For more information on how the server can provide the correct initial HTML to the client, see “Providing HTML Structure” in Chapter 11, “Server-Side Implementation.” For more detail on the BBQ plug-in and the use of a state object, see Chapter 9, “Navigation.” To access web resources more easily, see the online version of the bibliography on MSDN: http://msdn.microsoft.com/en-us/library/hh404094.aspx.
- 156. 123 Introduction In a client-side application composed of discrete objects, many of those objects need to communicate with one another. You have a few options when deciding how they do this. Generally, your options are direct method invocation, and an indirect communication mechanism such as events. These options give you the ability to control the amount of complexity applied to the object’s interface and implementation, and allow you to control the level of coupling the objects have with each other. For example, an object that invokes a method on another object must have a direct reference to that object. If you chose to implement a form of events, the objects may either have a direct dependency or use a broker object to enable them to communicate in a loosely coupled manner. This broker prevents the objects from needing to have direct knowledge of each other. Comparison between direct and loosely coupled communication Most applications will use more than one form of communication between their objects because there are advantages and disadvantages to each option. Your responsibil- ity is to apply an appropriate balance based on the application. Communication8
- 157. 124 chapter eight In this chapter you will learn: • How to implement direct method invocation between widgets. • The advantages and disadvantages of direct method invocation. • How to implement event triggering and handling between widgets. • How to control dependencies between the objects triggering events and those handling them. • When using the Publish/Subscribe (pub/sub) pattern is appropriate. • How to use pub/sub to manage multiple handlers and reduce coupling. • How the Mileage Stats Reference Implementation (Mileage Stats) implements these options and how the team chose various communication options. Direct Method Invocation When a widget needs to communicate with another widget and no other objects are in- terested in the communication, the calling widget can use direct method invocation. This option is the easiest to understand, the easiest to implement, and the easiest to follow when tracing code paths. You could use this option for all communication, but if your application has many objects and many calls between those objects, this approach will force the objects to have more methods on their interface than the loosely-coupled op- tions require and it can greatly increase the coupling between those objects. Getting a Widget Reference Many of the JavaScript objects in Mileage Stats are implemented as jQuery UI Widgets, which have a specific way to expose public methods. After a widget has exposed a method, the calling widget needs a reference to it before it can invoke the method. One option would be for the calling widget to know how to get a reference to the widget it needs to call. The widget pseudo selector is a good way to do this without having to know the exact elements the widget is attached to. This approach to getting a widget reference requires the calling widget to know that it is invoking the method on a specific widget by name. Another option is to have the references passed in as part of the options object. This allows the calling widget to invoke the method without having to know the name of the widget it is calling. For information on how to expose and invoke methods on widgets, see “Public Methods” in Chapter 3, “jQuery UI Widgets.” For more information on the widget pseudo selector see “Using the Pseudo Selector” in Chapter 3, “jQuery UI Widgets.” Method Invocation in Mileage Stats In the following example, an object reference called charts is captured when the charts widget is created. This reference is then passed as the value to the charts option when initializing the layoutManager widget.
- 158. 125communication JavaScript // Contained in mileagestats.js charts = $('#main-chart').charts({ sendRequest: mstats.dataManager.sendRequest, invalidateData: mstats.dataManager.resetData }); $('body').layoutManager({ subscribe: mstats.pubsub.subscribe, pinnedSite: mstats.pinnedSite, charts: charts, header: header, infoPane: infoPane, summaryPane: summaryPane, vehicleList: vehicleList }); The layout manager uses this reference to invoke methods on the charts widget. For example, when the layout manager is coordinating the transition to the charts layout, it calls the chart’s moveOnScreenFromRight method. JavaScript // Contained in mstats.layout-manager.js _goToChartsLayout: function() { this._summaryPane('moveOffScreen'); this._vehicleList('moveOffScreen'); this._infoPane('moveOffScreenToRight'); this._charts('moveOnScreenFromRight'); }, You probably noticed that the method calls in _goToChartsLayout are not using the calling convention described in the see “Public Methods” section in Chapter 3, “jQuery UI Widgets.” A Helper for Method Invocation Rather than using this.options.widgetName.widgetName(‘methodName’), many of the calls in Mileage Stats, and particularly in the previous code example, have been simplified to this._widgetName(‘methodName’). Mileage Stats uses a helper for method invoca- tion to improve readability. This isn’t necessary; the long form works fine, but the helper method does take advantage of the dynamic nature of JavaScript and can make the code more readable and less repetitive. The setupWidgetInvocationMethods function dy- namically creates an underscore-prefixed method on the host argument for each widget whose name is passed in the widgetNames argument. The options argument tells the helper function where to find the implementation of the widget functions.
- 159. 126 chapter eight JavaScript // Contained in mstats.utils.js function buildFunction(widget, options) { var context = options[widget], fn; if(!context) { mstats.log('Attempted to create a helper for ' + widget + ' but the widget was not found in the options.'); return; } fn = context[widget]; return function() { var result = fn.apply(context, arguments); return result; }; } mstats.setupWidgetInvocationMethods = function(host, options, widgetNames) { var i, widgetName; for (i = widgetNames.length - 1; i >= 0; i -= 1) { widgetName = widgetNames[i]; host["_" + widgetName] = buildFunction(widgetName, options); } }; The setupWidgetInvocationMethods function is called when the layout manager is first created. This function call dynamically creates new methods called _charts, _header, _infoPane, _summaryPane, and _vehicleList that will make invoking methods on those widgets much easier, as you can see in the _goToChartsLayout method above. JavaScript // Contained in mstats.layout-manager.js _create: function() { ... // add on helper methods for invoking public methods on widgets mstats.setupWidgetInvocationMethods(this, this.options, ['charts', 'header', 'infoPane', 'summaryPane', 'vehicleList']); ... }, In addition to the layout manager, the above helper method is also used in the _create method of the info pane, summary, and vehicle details widgets.
- 160. 127communication Direct method invocation is useful when an object must invoke a method on another object. However, depending on the direction of the method call, it may result in incorrect dependencies. For example, in the case of a widget that manages other widgets in a par- ent/child relationship, the child widgets should not have knowledge of their parent. This is where events can be helpful. Raising and Handling Events Events allow an object to communicate with other objects without a direct reference to them. Rather than having to know how to resolve the reference to the receiver or how to invoke a specific method, event handlers only need to know the name of the event and any data sent with it. Therefore, using an event is more appropriate than invoking a method when a child widget needs to communicate with its parent. It’s acceptable for a parent in a hierarchy to know about its children, but not the other way around. When a child widget knows too much about its parent, it makes it difficult or impossible to relo- cate the widget and use it from inside a different parent. In Mileage Stats, the registration widget is created by and contained within the summary widget, which means that there is a parent/child relationship. When a user registers with the Mileage Stats application, the registration widget raises an event through its displayNameChanged event callback. The summary widget handles this event by setting the displayNameChanged option on the registration widget to the handler, which sets an option on the header widget. JavaScript // Contained in mstats.summary.js _setupRegistrationWidget: function () { var that = this, elem = this.element.find('#registration'); this.registration = elem.registration({ dataUrl: elem.data('url'), publish: this.options.publish, sendRequest: this.options.sendRequest, displayNameChanged: function (event, args) { that._header('option', 'displayName', args.displayName); } }); }, When the user successfully registers, the registration widget raises the display NameChanged event using the _trigger method. The _trigger method is available on the base jQuery UI Widget and accepts three arguments: • The name of the event to trigger. • The original event if it originated from a DOM event such as click. • The data to be sent to the event handler.
- 161. 128 chapter eight JavaScript // Contained in mstats.registration.js (in the saveProfile method) this.options.sendRequest({ url: this.options.dataUrl, data: formData, cache: false, success: function () { that._startHidingWidget(); that._showSavedMessage(); // we update the username after successfully the updating the profile that._trigger('displayNameChanged', null, { displayName: formData.DisplayName } ); }, error: function () { that._showSavingErrorMessage(); } }); Using events is a powerful way to reduce coupling without sacrificing communication between widgets. For more details on raising and handling events, see “Events” in Chapter 3, “jQuery UI Widgets.” Using options to expose the callback and wire up the handler reduces the coupling between the sender and receiver, but this requires that some other code, usually the code that creates the widgets, to perform the connections, as you can see in the _setup RegistrationWidget method above. An alternative to wiring up event handlers is to use the Publish/Subscribe pattern, which employs a broker to manage these connections. Publishing and Subscribing A common strategy for reducing the coupling between objects is for those objects to use an intermediary object, referred to as a broker, rather than communicating directly with each of their dependencies. The Publish/Subscribe pattern (commonly referred to as pub/ sub) applies this strategy. The pattern provides a way for objects to communicate without needing a reference to the source or the destination of the messages. Rather, the objects have references to the pub/sub implementation and know how to use it based on their needs. In its most general form, the Publish/Subscribe pattern identifies publishers, topics, and subscribers. Publishers and subscribers are software components that need to com- municate with each other. Topics represent the contract between the sender and receiver and are made up of a name and an optional message. The following figure illustrates the Publish/Subscribe pattern.
- 162. 129communication The Publish/Subscribe pattern The pattern has two phases. The first phase is the subscription phase. Objects sign up to be notified when information about particular topics becomes available. For ex- ample, in the figure, Subscriber 2 is subscribed to messages about Topic A and Topic B, while Subscriber 1 is subscribed only to Topic A. The second phase is the publication phase, when publishers provide information about topics. For example, in the figure, the Publisher creates messages about Topic A and Topic B. Each implementation of the Publish/Subscribe pattern provides the communications infrastructure that receives and delivers messages. However, the details of how messages are routed between publishers and subscribers can differ between implementations. For example, it is possible that messages can be delivered synchronously or asynchronously, depending on the situation. Pub/Sub in Mileage Stats Mileage Stats uses a pub/sub JavaScript object to broker communication between the objects and widgets that make up the client-side application. Global events are events that are not constrained to an isolated part of the application. These events may cause multiple widgets to update their data and UI, such as when a vehicle is deleted or a re- minder is fulfilled. Publishers and subscribers do not communicate directly with each other. Instead, widgets subscribe using callback functions for relevant topics. The widgets managing UI elements publish topics in response to lower-level DOM events caused by user actions.
- 163. 130 chapter eight The pubsub Object The Mileage Stats’ pubsub interface provides publish, subscribe, and unsubscribe meth- ods. Each method requires an event name. These events are defined in mstats.events.js as objects that behave like string constants. The following code shows the interface of the pubsub object. JavaScript // Contained in mstats.pubsub.js mstats.pubsub = (function () { var queue = [], that = {}; that.publish = function (eventName, data) { ... }; that.subscribe = function (eventName, callback, context) { ... }; that.unsubscribe = function (eventName, callback, context) { ... }; return that; }(); The mechanism for creating the pubsub object uses an immediate function which executes as soon as its definition is parsed. As a result, the pubsub object is available simply by adding the mstats.pubsub.js file to the page. The subscribe method stores event subscriptions, which are comprised of a callback in the form of a function and a context in the form of an object. More than one subscrip- tion is possible for a single event name. Here is the code. JavaScript // Contained in mstats.pubsub.js /** * @param {string} eventName The name of the event to publish * Uses a slash notation for consistency * @param {function} callback The function to be called when the * event is published. * @param {object} context The context to execute the callback */ that.subscribe = function (eventName, callback, context) { if (!queue[eventName]) { queue[eventName] = []; } queue[eventName].push({ callback: callback, context: context }); }; The subscribe method modifies the queue variable. It adds a new array element for the name that is passed as the eventName argument if that element does not already exist. Then, it adds a new object to that array with the callback and context fields. These fields store the function to be invoked when the event is published, and the context that function should execute within.
- 164. 131communication JavaScript allows you to use the context of one object to call an instance method of a different object. This is what happens with the context value that is provided to the subscribe method. The callback method will be invoked with the given context. The publish method invokes the registered callback for a given eventName. The publish method executes all callbacks that are associated with eventName by using the context that was provided in the subscription. JavaScript // Contained in mstats.pubsub.js /** * @param {string} eventName The name of the event to publish * Uses a slash notation for consistency * @param {object} data Any data to be passed to the event * handler. Custom to the event. */ that.publish = function (eventName, data) { var context, intervalId, idx = 0; if (queue[eventName]) { intervalId = setInterval(function () { if (queue[eventName][idx]) { context = queue[eventName][idx].context || this; queue[eventName][idx].callback.call(context, data); idx += 1; } else { clearInterval(intervalId); } }, 0); } }; The code successively invokes each function that is stored in the queue array. It uses the setInterval function with a timeout of 0 milliseconds to execute the callbacks asynchronously. This allows each subscriber callback to be invoked before the previous callback finishes. This also means callbacks can be invoked before other callbacks have finished. A consequence of asynchronicity is that you cannot predict the order in which callbacks are invoked or finish. In Mileage Stats, only the unit tests take advantage of the unsubscribe method. However, other applications may need to allow the dynamic subscription and unsubscrip- tion of events. An Example of Subscribing and Publishing When a user fulfills a reminder, several areas of the UI need to refresh their own lists of reminders. The application uses the mstats.events.vehicle.reminders.fulfilled event name (this is the topic) to communicate the fact that a reminder was fulfilled. This variable is initialized with the value “reminders/fulfilled” in the mstats.events.js file.
- 165. 132 chapter eight The Mileage Stats layout manager widget is a coordinating widget. It subscribes to the mstats.events.vehicle.reminders.fulfilled event when it is created. Whenever this event is published, the registered callback refreshes each of the layout manager’s child widgets. The following code shows how the subscription is implemented, and what happens during the callback. JavaScript // Contained in mstats.layout-manager.js _subscribeToGlobalEvents: function () { var state = {}, that = this; ... this.options.subscribe(mstats.events.vehicle.reminders.fulfilled, function() { // we need to refresh the summary reminders, fleet statistics, // details pane, reminders pane, charts, and jump list that._summaryPane('requeryStatistics'); that._summaryPane('requeryReminders'); that._infoPane('requeryVehicleDetails'); that._infoPane('requeryReminders'); that._charts('requeryData'); that.options.pinnedSite.requeryJumpList(); }, this); }, When the user fulfills a reminder, the reminders widget uses the pubsub object to publish the event. By passing the subscribe method into the layout manager as an option, the layout manager is able to participate in pub/sub without having to know how to resolve the dependency to the pubsub object. JavaScript // Contained in mstats.reminders.js _fulfillReminder: function (fulfillmentUrl) { var that = this; this._showFulfillingMessage(); this.options.sendRequest({ url: fulfillmentUrl, dataType: 'json', cache: false, success: function () { that._showFulfilledMessage(); that.options.publish(mstats.events.vehicle.reminders.fulfilled, {}); }, error: function () {
- 166. 133communication that._showFulfillErrorMessage(); } }); }, The options.publish method is initialized to be the value of mstats.pubsub.publish when the reminders widget is created. Even though the reminders widget does not have a direct connection to the layout manager, the layout manager receives notification of the reminders/fulfilled event because it has subscribed to that event. The reminders/ fulfilled event does not require a data payload, so the second parameter to the publish call is an empty object. Finding the Right Balance While building Mileage Stats, the team initially wanted the widgets to be as loosely coupled as possible in hopes of gaining the most flexibility. To this end, pub/sub was used exclusively for communication between widgets. Because each widget had to manage all of its subscriptions and the topics it published, this approach reduced readability by mak- ing it difficult to follow code paths. It is reasonable to have some level of coupling be- tween widgets, especially if it improves the readability of the code base. Reducing the number of pub/sub topics also simplified the implementation of the widgets. After this experience, the team replaced some pub/sub messages with direct method calls and jQuery events. The following guidelines can be used to determine when you might choose one option over the other. • Use direct method invocation when only two objects are participating in the action, and when readability and simplicity are more important than coupling and flexibility. • Trigger an event when it is unacceptable for the sender and receiver to know more about each other than the message they are passing. • Use pub/sub when multiple subscribers are needed for a single message or the same message needs to be sent from multiple publishers to a single subscriber. Pub/sub is also a good choice when subscribers may be added and removed during the lifetime of the page. Summary When a client-side web application is composed of multiple, discrete objects, those ob- jects have a number of communication options to choose from. To keep the solution flexible, pub/sub can be used to keep the objects from having to take dependencies on all the other objects they communicate with. Pub/sub implementations, such as the one in Mileage Stats, typically have a way to publish, subscribe, and unsubscribe. If only pub/ sub is used, it can complicate the implementation of the objects that have to manage the many subscriptions and handlers. Alternatively, if only direct communication, such as method invocation, is used, it can complicate the interface of the object by requiring more members. Balancing these options allows the application to have flexibility while keeping
- 167. 134 chapter eight the interfaces and implementations as simple as possible. Mileage Stats accomplishes this by using pub/sub for global messages that multiple objects must react to and uses method calls and events for everything else. Independent of the approach you take, you should understand the implications and balance them to achieve the simplicity and flexibility appropriate for your application. Further Reading For more information about the Publish/Subscribe pattern, see http://msdn.microsoft. com/en-us/library/ms978603.aspx. For more information on how to use JavaScript to implement the Publish/Subscribe pattern, see “Understanding the Publish/Subscribe Pattern for Greater JavaScript Scalability” at http://msdn.microsoft.com/en-us/scriptjunkie/hh201955.aspx. For more information about closure, see the Wikipedia entry: http://en.wikipedia.org/ wiki/Closure_(computer_science). For more information on how to expose and invoke methods on widgets, see “Public Methods” in Chapter 3, “jQuery UI Widgets.” For more information on the widget pseudo selector see “Using the Pseudo Selector” in Chapter 3, “jQuery UI Widgets.” For more information on raising and handling events, see “Events” in Chapter 3, “jQuery UI Widgets.” To access web resources more easily, see the online version of the bibliography on MSDN: http://msdn.microsoft.com/en-us/library/hh404094.aspx.
- 168. 135 Introduction This chapter describes how the Mileage Stats Reference Implementation (Mileage Stats) manages navigation as users interact with the application, and how it uses animated tran- sitions from one state to another to provide an attractive and immersive user experience. Traditional web applications and websites implement navigation between pages and states by loading separate pages from the server. Hyperlinks and other controls such as buttons typically initiate a request to the server, which sends back the next page or an updated version of the same page. This is the static or server-rendered model. In some cases the pages may contain client-side code that adds interactivity to the page without initiating a request to the server, or by reloading only a part of the page. This is the hybrid model; it provides islands of interactivity within the site that do not require a full-page reload. Mileage Stats uses the hybrid model. However, the majority of user interactions occur within a single page, portions of which are updated with data retrieved from the server using background requests. This is the Single-Page Interface (SPI) pattern. When a user performs an action such as selecting a hyperlink or clicking a button, the application modifies the current web page without reloading the entire page, resulting in a more re- sponsive, less jarring experience. Adherence to the SPI pattern presents a number of navigation challenges. These chal- lenges include managing the browser’s history mechanism so that the back button works as expected, providing direct access to a specific layout or state of the page (deep linking), and implementing anchors that allow users to bookmark the application so that it displays in a specific state. Fortunately, these challenges can be addressed by using some of the features of mod- ern browsers, by using JavaScript, and by taking advantage of some useful libraries to progressively enhance the way that browsers manage navigation. The approach used in Mileage Stats, and described in this chapter, augments the way the browser handles his- tory and hyperlinking. In a few cases, navigation in Mileage Stats triggers an animation sequence that transi- tions between screen layouts. Performing these layout changes requires coordination of the necessary transitions, manipulation of the document object model (DOM) elements Navigation9
- 169. 136 chapter nine that make up portions of the screen, and appropriate modularity to manage the complex- ity of the animation code. In this chapter you will learn: • How to keep your users within a single-page interface • How to manage hyperlinks and respond to user actions • When to rewrite URLs and when to handle the click event • How to ensure that deep linking, bookmarking, and the back button work as expected • How to coordinate and animate screen transitions Supporting the Single-Page Interface Pattern To support the SPI pattern, an application must handle user interactions that would, in a traditional web application, cause a request to the server and a full reload of the page to occur. The way that the interaction is handled for both hyperlinks and buttons varies depending on the behavior and requirements of the link. This figure shows the types of links used in Mileage Stats. Comparison of different kinds of links used in Mileage Stats As you can see, there are three different types of links. Links in the vehicle tiles on the left must specify the identifier of the vehicle to which that tile applies, which doesn’t change throughout the user’s session. Links in the vehicle details panel on the right, which
- 170. 137navigation change based on the selected vehicle, must specify both the identifier of the currently selected vehicle and the currently selected view tab (Details, Fill ups, or Reminders) so that deep linking and bookmarks work correctly. You can also see that the page includes links that are not added to the browser’s history list. When links are added to history, users can return to the previous page or any page in the list using the back button or the browser’s history explorer. From a user expe- rience perspective, it is not likely users would want to use the back button to return to a previously viewed reminder or fill up on the same view tab. Applications that partially or fully apply the SPI pattern create page transitions by using JavaScript to override default user navigation actions and control the resulting ac- tion. Even though the application is taking over responsibility for the action, it must help the browser understand the important details of the action so the browser will continue to behave as expected. This partnership between your code and the browser isn’t difficult to implement if you have some understanding of how the browser works. Sometimes hyperlinks can be rewritten after the page loads, and other times the user action is better handled dynami- cally, when the user clicks the link. In either case, you have full control over the response to the user, and can include support for deep linking and bookmarking, as well as for the back button. Browser History and the Back Button On a traditional hyperlinked website, the browser can adequately manage the history list and behavior by itself. Each time the browser is instructed by the user or by code to navigate to a unique URL, it registers the URL as a new entry in the browser’s history. Clicking the browser’s back and forward buttons causes the browser to load the corre- sponding URL from the history list. These URLs can contain a fragment identifier (often known as a hash). This is the part after the # delimiter character in the URL. For example, in the URL /article.html#intro, the fragment identifier is intro. This may represent a named location on the page (the name of an anchor element in the page) to support deep linking and bookmarking, or a value that corresponds to the state of the page. A fragment identifier may also include a series of name/value pairs. For example, the following URL contains a fragment that includes two name/value pairs, where layout equals details and vid equals 4. HTTP URL http://mileagestats.com/Dashboard#layout=details&vid=4 Mileage Stats uses the name/value pairs in the fragment identifier to manage state related to the view tab and the vehicle being displayed. Note: Do not confuse the fragment identifier with the query segment of a URL. The query segment (or query string) is the part that follows the ? delimiter. It usually contains name/value pairs that the server uses to generate the appropriate output. For more information about the structure of URLs, see “RFC 3986, Uniform Resource Identifier (URI): Generic Syntax” at http://www.ietf.org/rfc/rfc3986.txt.
- 171. 138 chapter nine Most URLs cause the browser to perform a full-page refresh, which conflicts with the requirements of the SPI pattern. However, if the URL added to the history is identical to the previous URL except for the fragment identifier, the browser will not perform a full- page refresh when the user presses the back button. Therefore, URLs such as the one shown above, which refers to the Dashboard resource on the server, and vary only in the content of the fragment identifier, do not result in multiple entries being added to the browser’s history list. When a user selects one of these links, the client-side handler for the click event can perform the necessary actions to update the user interface (UI), but the browser does not treat it as a different URL or add it to the history list. In some cases, however, it is necessary for URLs to be added to the history list even if they vary only in the content of the fragment identifier (and would not, therefore, be added automatically). Mileage Stats uses the Back Button & Query (BBQ) plug-in for jQuery to achieve this, as well as to help make the appropriate modifications to the URL where required. The BBQ Plug-in According to the BBQ project page (http://benalman.com/projects/jquery-bbq-plugin/), the BBQ plug-in “… leverages the HTML5 hashchange event to allow simple, yet powerful bookmarkable #hash history. In addition, jQuery BBQ provides a full deparam method, along with both hash state management, and fragment / query string parse and merge utility methods.” Note: The HTML5 hashchange event is raised from the window object each time any values in the fragment identifier of the current URL change; hashchange is supported in Windows® Internet Explorer® versions 8 and 9. The deparam method can extract the values of name/value pairs from the fragment identifier and coerce them into the appropriate types. Documentation for the BBQ plug-in is available at http://benalman.com/code/projects/jquery-bbq/docs/files/jquery-ba-bbq-js. html. Mileage Stats only uses a fraction of BBQ’s features. For some navigation scenarios, BBQ is used to parse and merge the fragment identifier values when creating or updating hyperlinks that include the fragment identifier. For hyperlinks that must change based on the state of the application, such as the selected vehicle link, BBQ is used in the click event handler to dynamically modify the URL. As you will see in “Responding to User Actions” later in the chapter, BBQ also helps when the browser doesn’t support the hashchange event. Modifying Hyperlinks Mileage Stats uses two different approaches to modify the URLs sent from the server. The approach depends on the lifetime of the hyperlink. If the URL of the hyperlink doesn’t change throughout the lifetime of the user’s session, such as the hyperlinks in the vehicle tiles (these look like buttons), the URL is modified in the anchor tag’s DOM element when the page first loads.
- 172. 139navigation Note: As you will see in the next section, this approach allows the application to support browsers that do not have JavaScript enabled. This causes the application to send a request for a full-page reload each time the user clicks a link. This is a form of progressive enhancement that provides an improved user experience when JavaScript is enabled. If the hyperlink’s URL is based on the current state of the application, such as the currently selected vehicle, the click event is handled and the URL is applied dynamically, as opposed to using the URL created on the server, which would cause a full-page post back. The following sections describe the way Mileage Stats implements these different approaches for managing navigation and browser history. Modifying URLs When the Application Loads Some of the links in Mileage Stats use a URL that does not change throughout the lifetime of the user’s session. These URLs include a fragment identifier that contains the identifier of the vehicle to which they apply. For browsers that do not support JavaScript, Mileage Stats supports a traditional static model of navigation, where every user interaction re- quires the server to create the updated page. To achieve this, each of the hyperlinks sent from the server refers to a specific resource on the server. For example, the URL that the Details view uses to display the details of the vehicle with identifier 4 is sent in the following REST-style format. HTTP URL http://mileagestats.com/Vehicle/Details/4 If the browser has JavaScript enabled, these hyperlinks are modified on the client to use the fragment identifier instead. This ensures the correct behavior of the back button. The link shown above will be converted into the following format so that all of the state information is included in the fragment identifier. “Dashboard” is the location Mileage Stats uses as its SPI. HTTP URL http://mileagestats.com/Dashboard#layout=details&vid=4 This approach means that deep linking, bookmarking, and the back button will continue to work as expected because you are changing the URL in a way the browser understands. The Details, Fill ups, and Reminders buttons on the individual vehicle tiles are examples of hyperlinks that must be updated only once, when the user starts the applica- tion. The code must convert the URL from the REST-style format delivered by the server to the format where the state information is included as name/value pairs in the fragment identifier. A section of the server-side code that creates the vehicle tiles is shown below. It uses the Url.Action method to generate the REST-style URLs for the links.
- 173. 140 chapter nine CSHTML <!-- Contained in _TemplateVehicleList.cshtml --> <a href="@Url.Action("List", "Reminder")/${VehicleId}" data-action="vehicle-reminders-selected" alt="Reminders" title="Reminders"> <div class="hover"></div> <div class="active"></div> <img alt="Reminders" src="@Url.Content("~/Content/command-reminders.png")" /> <div class="glass"></div> </a> This creates a URL for the hyperlink in the format http://mileagestats.com/ reminder/list/4. Notice that the hyperlink contains a data-action attribute, in this case with the “vehicle-reminders-selected” value. Note: Attributes that begin with the prefix data- are treated as metadata. The part of the name after the hyphen can be used for querying the value of the attribute using jQuery’s data method. The client-side code in Mileage Stats includes the _adjustNavigation function, part of which is listed below, to modify the URLs in hyperlinks. The code takes advantage of jQuery’s support for HTML5 data- attributes to retrieve the value of the data-action attribute and store it in a variable named action. Next, it obtains the identifier of the vehicle from the widget’s options collection, then uses the BBQ getState method to read the fragment identifier (if one exists) and store it in an object variable named state. If there is no fragment identifier (which will be the case when the application starts) it stores an empty object literal instead. JavaScript // Contained in mstats.vehicle.js _adjustNavigation: function () { var that = this; this.element.find('[data-action]').each(function () { var $this = $(this), action = $this.data('action'), vehicleId = that.options.id, state = $.bbq.getState() || {}, newUrlBase = mstats.getBaseUrl(); state.vid = vehicleId; switch (action) { case 'vehicle-details-selected': state.layout = 'details'; break; case 'vehicle-fillups-selected':
- 174. 141navigation state.layout = 'fillups'; break; case 'vehicle-reminders-selected': state.layout = 'reminders'; break; case 'vehicle-add-selected': state.layout = 'addVehicle'; state.vid = undefined; break; } $this.attr('href', $.param.fragment(newUrlBase, state)); }); }, The code then sets the value of a variable named newUrlBase by calling the get BaseUrl function. This is a helper function defined in mstats.utils.js that retrieves the current base URL without the fragment identifier. The value will usually be /Dashboard in Mileage Stats (but may change depending on how the site is deployed). Note: The base URL will be different if the site is deployed to a virtual directory versus being deployed to the root of the web server. For example, if the virtual directory is mstats, the base URL (without the domain name) would be /mstats/Dashboard. This is why relying on the server-side Url.Action function is essential, as it takes into account how the application is hosted. Next, the code sets the vid property of the state object to the vehicle’s ID, and then uses a switch statement to set the layout property (when adding a vehicle, the vid prop- erty is set to undefined). Finally, the code updates the href attribute of the hyperlink to the required URL using the BBQ fragment method (which extends jQuery.param) to merge the values in the state object with newUrlBase. The result is a URL that is changed from http://mileagestats.com/reminder/list/4 to http://mileagestats.com/dashboard# layout=reminders&vid=4. Modifying URLs When the User Activates a Link The preceding section showed how to use the BBQ plug-in and HTML5 data- attributes to modify hyperlinks so they include a fragment identifier that defines the state. This is fine if the links are not likely to change (or will not change very often). However, if the URL can be determined only when the link is activated, it is usually more appropriate to handle the click event. When a user activates one of these links, the client-side handler for the click event can perform the necessary actions to update the UI and prevent the default click behavior from sending the request to the server. Alternatively, if required, the code can initiate navigation and page reload by setting the location property of the browser’s window object within the event handler or in code that is executed from the event handler. The vertical accordion links for Details, Fill ups, and Reminders are examples of links that change each time a different vehicle is selected because they must include the
- 175. 142 chapter nine identifier of the selected vehicle. The following listing shows a section of the server-side code that creates the HTML for the hyperlink in the Fill ups view tab. CSHTML <!-- Contained in _TemplateFillups.cshtml --> <a class="trigger" href="@Url.Action("List", "Fillup")/${VehicleId}" data-info-nav="fillups"></a> This creates a URL for the hyperlink in the format http://mileagestats.com/fillup/ list/1. Notice that the hyperlink contains a data-info-nav attribute, in this case with the “fillups” value. The info pane widget that implements this section of the UI is responsible for han- dling the click event of these accordion links and initiating the required transition. The code in the _bindNavigation method (shown below) creates a delegate on the click event, which uses the widget’s name as the namespace, for all elements that include a data-info-nav attribute. Note: Using the widget’s name as the namespace and appending it to the event allows the delegation to automatically be cleaned up when the widget is destroyed. Inside the delegate, the code uses the jQuery data method to read the value of the data-info-nav attribute into a variable named action, and then passes this value to another method named _setHashLayout. It also prevents the default behavior of the hyperlink from initiating navigation. JavaScript // Contained in mstats.info-pane.js _bindNavigation: function () { var that = this; // closure for the event handler below this.element.delegate('[data-info-nav]', 'click.infoPane', function (event) { var action = $(this).data('info-nav'); that._setHashLayout(action); event.preventDefault(); }); }, The _setHashLayout method, also defined within the info pane widget, is responsible for setting the layout according to the user’s selection. It uses the BBQ getState method to retrieve the existing navigation details, which are stored as name/value pairs in the fragment identifier of the current URL, as an object named state. After setting the layout property for the new layout, it uses the pushState method to modify the fragment and update the browser’s address bar. The value 2, passed as the second argument, tells the pushState method to completely replace any existing fragment identifier values with the contents of the first argument.
- 176. 143navigation JavaScript // Contained in mstats.info-pane.js _setHashLayout: function (newLayout) { var state = $.bbq.getState() || {}; state.layout = newLayout; $.bbq.pushState(state, 2); }, The result is a URL that is changed from http://mileagestats.com/fillup/list/1 to http://mileagestats.com/dashboard#layout=fillups&vid=1. Although the server isn’t required to do anything special to support these URLs, the client must perform some specific steps to respond to user actions. Responding to User Actions At this point, as explained in the preceding sections of this chapter, the URLs in the hy- perlinks or in the click event handlers have been updated with the required fragment identifier values. Links where the URL does not change during the session have been updated by code that modifies the anchor tag’s href attributes when the main SPI page loads. Links where the URLs do change have a delegate attached to the click event, and this delegate updates the browser’s location with the modified URL. The next stage is to write code that responds when a user clicks on a link. This is done by handling the hashchange event, which is raised when the user clicks a link that con- tains a fragment identifier, or when code programmatically sets the location property of the window object, which is what BBQ’s pushState method does, as shown in the previ- ous code example. The hashchange event can be used for applications that need to maintain a history of user actions without reloading the complete page. Mileage Stats uses the BBQ plug-in to manage the browser’s history in a uniform manner that works across all browsers. When BBQ detects browser support for the hashchange event, it uses the browser’s implementation. When it doesn’t detect support for the hashchange event, it uses its own implementation of the event. Internet Explorer 8 and Internet Explorer 9 support the hashchange event. Note: In addition to the hashchange event, HTML5 also defines a mechanism for managing browser session history without using the fragment identifier, which adds pushState and replaceState methods to window.history. Internet Explorer 9 supports this mechanism. You should consider using a library such as Modernizr to determine if the browser supports the HTML5 history mechanism. The BBQ plug-in and similar libraries can still be used for browsers that do not support it. The hashchange event handler in Mileage Stats, shown below, is defined in mstats. layout-manager.js. When the hashchange event occurs, the handler uses BBQ’s deparam method to deserialize the name/value pairs in the fragment identifier into a state object. The true argument instructs the deparam method to coerce numbers true, false, null, and undefined to their actual values rather than the string equivalent. This avoids the need to use the parseInt function to convert the vid property from a string to a number.
- 177. 144 chapter nine JavaScript // Contained in mstats.layout-manager.js _subscribeToHashChange: function() { var that = this; $(window).bind('hashchange.layoutManager', function() { var state = $.deparam.fragment(true); that._changeLayout(state); }); }, The handler then updates the page to the required layout by calling the _change Layout method, shown next, which is also defined in mstats.layout-manager.js. This method uses the state argument that is passed to it to set the widget’s layout option and to navigate to the appropriate layout. JavaScript // Contained in mstats.layout-manager.js _changeLayout: function(state) { this._setOption('layout', state.layout || 'dashboard'); this._setupInfoPaneOptions(state); switch (this.options.layout) { case 'dashboard': this._header('option', 'title', 'Dashboard'); this._goToDashboardLayout(); break; case 'charts': this._header('option', 'title', 'Charts'); this._goToChartsLayout(); break; case 'details': this._setHeaderForSelectedVehicle('Details'); this._goToDetailsLayout(); break; case 'fillups': this._setHeaderForSelectedVehicle('Fill ups'); this._goToDetailsLayout(); break; case 'reminders': this._setHeaderForSelectedVehicle('Reminders'); this._goToDetailsLayout(); break; } },
- 178. 145navigation The call to the _setOption method uses either the layout that is passed in, or it defaults to the Dashboard if no layout is specified. The code then executes the _setup InfoPaneOptions method (not shown here), which sets the selectedVehicleId option on the vehicle list and info pane widgets, and sets the activePane option on the info pane widget. The code then uses a switch statement based on the value of the layout option to set the header text option of the widget (in some cases using a private method within the widget) and then it calls another private method to begin animating the transition to the required layout. You will see an example of these animation methods in the next section of this chapter. Animating Screen Transitions Mileage Stats uses a widget named layoutManager both for managing navigation and for controlling the animation sequences that are triggered by navigation. For example, if you are on the Dashboard and you select Details for a specific vehicle, you see an animated sequence that shifts the summary pane off the left side of the screen, moves the info pane onto the screen from the right, and adjusts the vehicle list so that the currently selected vehicle is prominently displayed. This requires coordination of the summary, info pane, and vehicle list widgets. Note: For applications that do not use animations, implementing a layout manager is unnecessary. However, animations can help provide a great user experience by making the application appear more responsive and by allowing users to maintain context as they navigate the application. The Layout Manager Early in the development of Mileage Stats, it became clear that something needed to have responsibility for coordinating between the dashboard, details, and charts layouts. With- out centralized coordination, each widget that makes up a particular layout would need to know the current layout and when to transition to the next layout. This central coor- dinator, the layout manager, knows how and when to instruct the appropriate widgets to move to the correct layout, which reduces coupling and simplifies the implementation. By using a layout manager widget, each of the other widgets only needs to know how to perform the transition, not when to do so or what the other widgets must do to complete the transition. The layout manager is initialized in mileagestats.js with references to all the necessary widgets (such as the summary pane, vehicle list, and info pane) and it knows when to take action based on subscriptions to the following two types of events: • Global events. These are events that are not constrained to an isolated part of the application. They are published to the publish/subscribe object and subscribed to with the layout manager’s _subscribeToGlobalEvents method. You can learn more about this method in “An Example of Publishing” in Chapter 8, “Communication.” • hashchange events. These events are raised through user navigation and handled in the _subscribeToHashChange method, as described in the previous section of this chapter.
- 179. 146 chapter nine When these events are raised, the layout manager uses its _changeLayout method, described in the previous section of this chapter, to invoke methods directly on the widgets that will take part in the animation, and to update the header widget with the appropriate title based on the layout and selected vehicle. To learn more about how the layout manager invokes these widgets, see “Method Invocation” in Chapter 8, “Communication.” Coordinating Transitions One of the more complex transitions is to and from the dashboard and details layouts. The remainder of this section deals with the specifics of this transition. Transitioning from dashboard to details The following code shows one of the methods that the layoutManager widget uses to update the layout in response to a navigation event. This example, the _goTo DetailsLayout method, is used to navigate to the vehicle details layout.
- 180. 147navigation JavaScript // Contained in mstats.layout-manager.js _goToDetailsLayout: function() { this._charts('moveOffScreenToRight'); this._summaryPane('moveOffScreen'); this._infoPane('moveOnScreenFromRight'); this._vehicleList('moveOnScreen'); this._vehicleList('goToDetailsLayout'); }, The code calls methods in each of the widgets to move them to the appropriate loca- tions on the page. These methods check the widget’s current state before doing anything. For example, calling moveOffScreenToRight on the charts widget won’t do anything if the chart is not currently displayed. The following figure doesn’t show all of the necessary widget interactions to com- plete the transition to details layout, but it illustrates the roles that the vehicle list, vehicle, and tile widgets play in the transition. Sequence diagram showing a portion of the transition from dashboard to details layout When the hashchange event occurs, the _goToDetailsLayout method of the layout manager calls the _goToDetailsLayout method of the vehicle list widget. The vehicle list widget is responsible for coordinating the animation of the list from a two-column to a one-column layout as it moves to the left side of the screen while, simultaneously, all but the selected vehicle widgets shrink to a compact size. The details of these interactions are addressed in the next section. Animating Vehicle Tiles During the transition to the details layout, the vehicle list widget directs the vehicle wid- get to collapse all unselected vehicles, and the tile widget to animate the tiles left and down.
- 181. 148 chapter nine As you can see in the previous diagram, the goToDetailsLayout method of the vehicle list (shown below) starts the process of animating the vehicle tiles. After defining some variables, it calls the private _checkSelectedVehicleId method. JavaScript // Contained in mstats.vehicle-list.js goToDetailsLayout: function () { var selectedVehicle, vid = 0, that = this, runningTop = 0, animationInfoArray, state = $.bbq.getState() || {}; this._checkSelectedVehicleId(); selectedVehicle = this.options.selectedVehicleId; ... }, The _checkSelectedVehicleId method compares the selectedVehicleId option with the vid property in the URL. If they are different, it calls the _setOption method to update the value. JavaScript // Contained in mstats.vehicle-list.js _checkSelectedVehicleId: function () { var vid, state = $.bbq.getState() || {}; if (state.vid) { vid = parseInt(state.vid, 10); if (vid !== this.options.selectedVehicleId) { this._setOption('selectedVehicleId', state.vid); } } }, When the selectedVehicleId option is set, code in the _setOption method calls the _expandVehicle and _collapseVehicles methods. JavaScript // Contained in mstats.vehicle-list.js _setOption: function (key, value) { $.Widget.prototype._setOption.apply(this, arguments); if (value <= 0) { return; } switch (key) { case 'layout':
- 182. 149navigation this._setLayoutOption(value); break; case 'selectedVehicleId': this._expandVehicle(value); this._collapseVehicles(); break; } }, The _expandVehicle method ensures that the selected vehicle is not collapsed. The _collapseVehicles method loops through all vehicles, comparing their id option with the selectedVehicleId option. When a vehicle’s id doesn’t equal the selected one, the collapse method is called on the vehicle widget. This is the vehicle widget interaction shown in the sequence diagram above. JavaScript // Contained in mstats.vehicle-list.js _collapseVehicles: function () { var selected = this.options.selectedVehicleId; this.element.find(':mstats-vehicle').each(function () { var $this = $(this); if ($this.vehicle('option', 'id') !== selected) { $this.vehicle('collapse'); } }); }, Going back to the goToDetailsLayout method, after _checkSelectedVehicleId executes, all vehicle tiles will be collapsed or expanded appropriately. The next step is to animate the tiles into position. The following is a more complete view of the goTo DetailsLayout method shown earlier. JavaScript // Contained in mstats.vehicle-list.js goToDetailsLayout: function () { var selectedVehicle, vid = 0, runningTop = 0, animationInfoArray, that = this, state = $.bbq.getState() || {}; this._checkSelectedVehicleId(); selectedVehicle = this.options.selectedVehicleId; if (!this.options.isCollapsed) { this.element.find(':mstats-tile').tile('beginAnimation');
- 183. 150 chapter nine this.element.find(':mstats-tile').each(function () { var $this = $(this); vid = $this.find('.vehicle').vehicle('option', 'id'); animationInfoArray = [{ position: { top: runningTop }, duration: animationLength }, { position: { left: 0 }, duration: animationLength }]; $this.tile('moveTo', animationInfoArray, function () { that.element.find(':mstats-tile').tile('endAnimation'); }); // calculate the runningTop for next time around if (vid === selectedVehicle) { runningTop += 321; } else { runningTop += 206; } }); this._narrowToSingleColumn(); } this._scrollToSelectedVehicle(); if (state && state.layout) { this.options.layout = state.layout; } this.options.isCollapsed = true; }, Not to be confused with the vehicle widget, the vehicle list widget also has an is Collapsed option that indicates if it is currently displayed as a single column (collapsed) or as two columns. If it is not collapsed, it immediately calls the beginAnimation method on all tile widgets, as you can see in the sequence diagram above. Note: The tile widget was created to reduce the complexity of the tile animations. Initially, the vehicle list and vehicle widgets contained all of the animation logic. Creating the tile widget freed up the vehicle widget to focus only on vehicle concepts. In contrast, the vehicle list widget still contains a significant amount of logic specific to the animations. A future refactoring might employ an additional widget that specializes in animating generic tiles between a one-column and two-column layout (or N-columns to N-columns).
- 184. 151navigation Calculating Coordinates Mileage Stats uses relative positioning for many elements, which means that an element’s position is based on that of the preceding element (an element’s positioning style, such as relative or absolute, is a CSS property). However, when elements are moving during an animation their position must be absolute so that their location values can be controlled. The beginAnimation method establishes the top and left CSS values based on the current top and left values. These values will be used when positioning is switched to absolute. JavaScript // Contained in mstats.tile.js beginAnimation: function () { var $element = this.element; $element.css({ top: $element.position().top + 'px', left: $element.position().left + 'px' }); }, Now that the tiles have been prepared, they can be instructed to move. The go ToDetailsLayout method loops through each of the tile widgets and constructs an animationInfoArray with properties for position and duration. The runningTop variable is updated within the loop to specify the top of the next tile. This helps with the process of collapsing the two-column list into a single column and ensures that the items in the resulting list do not visually overlap. The duration, animationLength, is defined in the file’s closure at the top of the file with the value 600 (milliseconds). To move the tiles, the moveTo method is called on all tile widgets with two arguments. These are the animationInfoArray, and a callback func- tion that executes when the moveTo method completes. The moveTo method is shown in the sequence diagram above. The moveTo method calls its _unlock method, which sets the position to absolute, and then loops over the animationInfoArray, calling _animate for each item in the array. JavaScript // Contained in mstats.tile.js moveTo: function (animationInfoArray, callback) { var that = this, arrayLength = 0; this._unlock(); // if this is an array, iterate over it if (animationInfoArray.length) { arrayLength = animationInfoArray.length; $.each(animationInfoArray, function (index, info) { if (index === arrayLength - 1) {
- 185. 152 chapter nine that._animate(info, callback); } else { that._animate(info); } }); } // otherwise just animate one step with the data else { this._animate(animationInfoArray, callback); } }, Next, the vehicles line up and form a single column. Although these actions seem to be two separate animations, they form a single animation that contains a 400ms delay that separates the two parts (height adjustment and the move left). When moveTo completes, the code calls the endAnimation method. This method sets the position attribute back to relative, as shown in the following code. JavaScript // Contained in mstats.tile.js endAnimation: function () { this.element .attr('style', '') .css({ top: 0, left: 0, position: 'relative', float: 'left' }); } This method also removes all style attributes, sets the top and left to zero because these values do not matter when using relative positioning, and sets float to left. This completes the animation sequence. Summary Even partially applying the SPI pattern to your application means that your client-side JavaScript must take some responsibility for handling navigation actions. Fortunately, with a little help, the browser is capable of performing most of the work. Depending on the nature of your hyperlinks, such as whether they change during a session, or are set only at the start of a session, and whether they should be added to the browser’s history, the URLs can either be sent from the server in the correct format or modified on the client once the DOM is ready. If the links are to be modified on the client, they can either be rewritten when the page loads, or modified dynamically when activated.
- 186. 153navigation Animations can be used to ensure that transitions don’t confuse or disorient the user by keeping them in context. However, animations should not be too slow or annoy the users through extended use of the application. Depending on the complexity of the ani- mation, you should look for opportunities to separate animation logic into modules. This will help with code readability and troubleshooting because the modules can be enabled or disabled easily, and they facilitate reusability. Further Reading For more information about the BBQ plug-in, see http://benalman.com/projects/ jquery-bbq-plugin/. For more information about Modernizr, see http://www.modernizr.com/. For the RFC 3986 Uniform Resource Identifier generic syntax, see http://www.ietf.org/ rfc/rfc3986.txt. To learn more about the layout manager’s _subscribeToGlobalEvents method and how the layout manager invokes widgets, see Chapter 8, “Communication.” To access web resources more easily, see the online version of the bibliography on MSDN: http://msdn.microsoft.com/en-us/library/hh404094.aspx.
- 188. 155 Introduction All web applications that users consider responsive have one thing in common: they pro- vide appropriate and timely feedback to the user. This feedback can come in many forms, including a save or success message following a completed task, subtle animations in re- sponse to a user interface (UI) gesture, a progress message for long-running tasks or input error messages displayed before a page is submitted. How the application displays notifications to the user is almost as important as the information itself. Intrusive message boxes, modal dialogs, and overlays (floating messages) that require the user to dismiss messages, can interrupt the user’s workflow, get in the way, and degrade the overall user experience. In addition to providing feedback during normal use, the website must also provide quality feedback when a non-recoverable error occurs. Quality feedback means providing understandable information about what has occurred, along with clear instructions on how to proceed. In this chapter you will learn: • How to provide unobtrusive user notification messages. • How to handle multiple simultaneous notification messages raised by the applica- tion. • The benefits of encapsulating the display and management of user notifications in a single JavaScript object. • How to display a helpful global error page. • How to set up a global error handler for Ajax requests. • Alternatives to modal dialogs for prompting users. • How to enable application notifications on the desktop with the Pinned Sites API. The technologies discussed in this chapter are jQuery UI Widgets and Pinned Sites in Windows® Internet Explorer® 9. For a comprehensive look at input validation error messages, see Chapter 11, “Server- Side Implementation.” Application Notifications10
- 189. 156 chapter ten Notifying the User Providing a high-quality application notification experience requires careful planning that emphasizes where notifications will be displayed, what events initiate a message, how potential multiple simultaneous messages will be handled, and how to decouple the message originator from the object that displays the message. During the design phase of the Mileage Stats application, the Project Silk team dis- cussed where and how notification messages would be displayed. We spent time prototyp- ing several different notification designs. Where notification messages are displayed is an essential part of the overall applica- tion user experience (UX) and UI design. Our initial design called for messages and prog- ress bars to be displayed within the boundaries of each jQuery UI widget. After building several prototypes and performing usability testing, the team determined that this design was unnecessary because the UI loaded quickly, eliminating the need for a loading progress bar. The team decided that displaying user messages in a single location made for a much better experience than having messages displayed within individual widgets. During the development cycle, the team relied on usability testing to refine their approach to generating user messages. Initially, the team displayed messages each time an Ajax request was invoked. This caused the UI to be too busy; we then used a time delay so that the message would only display if the request took longer than the delay. This too got messy, requiring a good deal of code that added little or no value to the application. In the end, the “less is more” principle triumphed, resulting in a good balance of informa- tive messages. Interactive and engaging applications such as Mileage Stats can execute multiple asynchronous operations. For example, the Dashboard page loads data for several jQuery UI widgets in addition to the chart widget. Each of these operations loads data for a re- gion of the UI. Any of these operations is a potential point of failure requiring an error message. It’s important that the application’s notification implementation be able to man- age multiple simultaneous or nearly simultaneous messages. From an architectural design perspective, it’s critical that message initiators not be responsible for determining how to coordinate the display of messages in the UI. Decoupling the message initiator from the rendering object allows both of them to evolve independently and to be tested in isolation. This section gave a glimpse into how the team worked together to maintain the deli- cate balance of UX, UI, and engineering concerns. It’s this type of designer-developer collaboration that enabled the team to deliver a successful notification feature. Where Notification Messages are Displayed Mileage Stats is composed of widgets. The decision to create and use a widget for display- ing notification messages is a natural architectural choice for this application. Widgets have flexible and powerful UI capabilities, provide for encapsulation of behavior, and can have external dependencies like the publish and subscribe (pub/sub) JavaScript object injected into their options object during creation.
- 190. 157application notifications Mileage Stats uses a single widget called status for displaying messages to the user. The status widget subscribes to the Mileage Stats status pub/sub message. It also handles the placement and rendering of messages as well as the coordination of multiple simulta- neous messages. Location of the status widget The status widget is rendered within the header widget UI, as pictured above. This top, semi-central location was chosen because it’s easier for the user to notice the mes- sage in this location, as opposed to a message area along the bottom of the browser window. The balance of easily noticed, easy-to-read, yet unobtrusive user notifications took time, patience, and usability testing, but the multiple design iterations were worth the extra investment of effort. How Notification Messages are Initiated Mileage Stats notification messages are initiated by widgets and communicated to the status widget using the pub/sub JavaScript object. Like other pub/sub messages, the status message has an associated payload object that is passed with the message. Notification messages passed using Pub/Sub The code snippet below is from the vehicleDetails widget. The _publishStatus method is responsible for making the pub/sub call. It’s called internally by other widget methods to initiate the display of a message. The status argument is the message payload and is forwarded in the publish call. The publish method was passed in the widget options object when the widget was created and points to the pubsub JavaScript object. The jQuery isFunction method verifies that publish is a valid JavaScript function object before it’s called.
- 191. 158 chapter ten JavaScript // Contained in mstats.vehicle-details.js _publishStatus: function (status) { this.options.publish(mstats.events.status, status); }, As stated earlier, Mileage Stats does not bother the user with data request messages. However, when initiating an Ajax operation such as a save or delete, it’s important to keep the user informed by updating the UI as the request proceeds and concludes. The following functions show how easy it is to initiate the display of a user message: • The _showDeletingMessage function is called after the user confirms his or her intent to delete the vehicle. This message is intended to inform the user that the vehicle deletion has been submitted to the server. • The _showDeletedMessage function is called after a successful deletion of the vehicle, informing the user that the deletion was successful. • The _showDeleteErrorMessage function is called if an error occurred while deleting the vehicle. JavaScript // Contained in mstats.vehicle-details.js _showDeletingMessage: function () { this._publishStatus({ type: 'saving', message: 'Deleting the selected vehicle ...', duration: 5000 }); }, _showDeletedMessage: function () { this._publishStatus({ type: 'saved', message: 'Vehicle deleted.', duration: 5000 }); }, _showDeleteErrorMessage: function () { this._publishStatus({ type: 'saveError', message: 'An error occurred deleting the selected vehicle. Please try again.', duration: 10000 }); }
- 192. 159application notifications Each function creates an object literal containing a type, message, and duration property. The type property is used by the status widget to prioritize multiple or overlap- ping display message requests. The message is the text of the message to display and the duration is how long the message should display. For detailed information on the inner workings of the Mileage Stats pub/sub imple- mentation, see Chapter 8, “Communication.” How Individual or Multiple Notification Messages are Displayed In the following _create method, the status widget subscribes to the status event. When this event is raised, the _statusSubscription method is invoked. The _statusSubscription method is responsible for displaying and hiding messages as well as managing multiple simultaneous messages. If a message is being displayed and another message with a higher priority arrives, the higher priority message will be shown. JavaScript // Contained in mstats.status.js _create: function () { // handle global status events this.options.subscribe(mstats.events.status, this._statusSubscription, this); }, ... _statusSubscription: function (status) { var that = this, current = this.currentStatus; status.priority = this._getPriority(status); // cancel displaying the current message if its priority is lower than // the new message. (the lower the int the higher priority) if (current && (status.priority < current.priority)) { clearTimeout(current.timer); } current = status; this.element.text(status.message).show(); // set the message for the duration current.timer = setTimeout(function () { that.element.fadeOut();
- 193. 160 chapter ten that.currentStatus = null; }, status.duration || this.options.duration); }, _getPriority: function (status) { return priorities[status.type]; }, User Session Timeout Notification Mileage Stats uses forms authentication, with a session time-out threshold of 20 minutes. If the session has timed out, the request (Ajax or non-Ajax) is redirected to the page specified by the forms authentication loginUrl in the web.config file. In traditional websites that perform page reloads between pages, it’s common to re- direct the user to a sign-in page when their session times out. Applications like Mileage Stats that make heavy use of Ajax calls to retrieve data perform few full-page reloads. Consequently, if a session timeout occurs, it’s usually during an Ajax request. Let’s exam- ine what happens when an Ajax request is redirected because of an authentication session timeout: 1. Ajax JavaScript Object Notation (JSON) data request initiated. 2. Forms authentication runtime detects an expired session and redirects the request to the sign-in page. 3. A parsing error occurs because the Ajax handler is expecting JSON data and not HTML. The HTML is the content of the sign-in page to which the request was redirected. 4. An Ajax error callback is invoked. 5. A global Ajax error callback is invoked. Errors that can occur anywhere in the application can often be handled in a central- ized location so that individual objects don’t need to repeat the same error handling code. Mileage Stats implements the global ajaxError method handler shown below to catch errors occurring during an Ajax request. In Mileage Stats, the primary purpose of this method is to identify whether the initiating Ajax request caused a session time-out error and, if so, to redirect the user to the sign-in page.
- 194. 161application notifications When looking at the code below, “jqXHR.status === 200” appears out of place or incorrect. Remember, this method is only executed when an Ajax error occurs. If the session times out and the request is redirected to the sign-in page, the response status code will be 200 because the redirect succeeded. In addition to checking for the response status code, this method also verifies that the returned HTML contains the sign-in page’s title. If both conditions are met, the browser is redirected to the sign-in page. JavaScript // Contained in mileagestats.js $(document).ajaxError(function (ev, jqXHR, settings, errorThrown) { if (jqXHR.status === 200) { if (jqXHR.responseText.indexOf('Mileage Stats Sign In') !== -1) { window.location.replace(mstats.getRelativeEndpointUrl('/Auth/SignIn')); } else if (jqXHR.responseText.indexOf('Mileage Stats | Accident!') !== -1) { window.location.replace(mstats.getRelativeEndpointUrl('/GenericError.htm')); } } }); Note: If the originating Ajax calling code also implements an error handler, the originating Ajax caller’s error handler will be called first, and then the above global Ajax error handler will be called. Website Error Notification ASP.NET allows you to specify a default error page that the ASP.NET runtime will redirect users to when an unhandled exception occurs. This error page is configured in the web. config file’s customErrors section. C# // Contained in web.config <customErrors defaultRedirect="GenericError.htm" mode="RemoteOnly" /> The error page should look and feel like it is part of the website, contain a brief ex- planation of why the user has been redirected to this page, and provide links that allow a user to continue using the site.
- 195. 162 chapter ten Mileage Stats GenericError.htm page Prompting Users During the design phase of Project Silk, the team had a goal of not prompting users with modal dialogs. Website UX designers are getting away from modal dialogs that ask the user questions like, “Are you sure?” Instead, designers prefer an undo feature that allows users to undo the previous task. The undo feature also enhances the application by ex- tending undo capabilities to tasks that did not require a confirmation dialog. Because Mileage Stats is only a sample application, it has limited functionality. The team wanted to implement the undo feature, but other features took priority. A production application could include it. The following code uses the JavaScript confirm function to validate the user’s request to fulfill a maintenance reminder.
- 196. 163application notifications JavaScript // Contained in mstats.reminders.js fulfillReminder: function (fulfillmentUrl) { var shouldfulfill = confirm('Are you sure you want to fulfill this reminder?'); if (shouldfulfill) { this._fulfillReminder(fulfillmentUrl); } }, Note: The jQuery UI dialog provides an alternative to using the JavaScript confirm dialog. If you are leveraging jQuery UI plug-ins, you should consider using the jQuery UI dialog for consistency in your UI. Desktop Notifications Given that modern web applications can provide excellent user experiences that rival desktop applications, the team wanted to take the next logical step and integrate the Mileage Stats application with the user’s desktop to provide dynamic user notifications. This integration was made possible by the Internet Explorer 9 Pinned Site API. Websites that implement the Pinned Site API can feel more like a native Windows application. They take advantage of the Microsoft® Windows® 7 taskbar capabilities and, when launched, the browser window is customized specifically for the website. The full Pinned Sites experience requires Internet Explorer 9 running on Windows 7. Windows Vista® has a reduced experience that provides: site pinning, customized reduced chrome, and the disabling of browser add-ons. Mileage Stats uses Pinned Sites to provide Windows 7 taskbar notifications that in- dicate whether the user has one or more overdue maintenance reminders. In addition, a dynamic jump list provides a direct link to each overdue maintenance reminder. Mileage Stats taskbar integration
- 197. 164 chapter ten Note: Jump list items will be available whether the site is opened in a browser or not. However, the notification icons are only displayed when the site is opened in the browser. The two images below contrast Mileage Stats running in a normal browser window and a customized Pinned Sites browser window. The Pinned Sites image shows the cleaner, pared down browser window with potentially distracting browser features re- moved, allowing the user to focus on the application features. Applications run in the customized browser window when they are launched from a taskbar or the Start Menu Pinned Sites icon. Mileage Stats without using Pinned Sites Mileage Stats using Pinned Sites In addition to a cleaner browser window, Pinned Sites also allows the developer to customize the color of the browser back and forward buttons, and the browser displays the website favicon to the left of the back button. This favicon is also a link to the website home page.
- 198. 165application notifications Implementing Pinned Sites Microsoft provides documentation for implementing Pinned Sites in their web applica- tions on MSDN®. The title of this topic is, “Pinned Sites Developer Documentation,” and is located at http://msdn.microsoft.com/en-us/library/gg491731(v=VS.85).aspx. Pinned Sites in Mileage Stats The following sections do not attempt to duplicate the MSDN documentation or cover every line of code pertaining to Pinned Sites. Instead, the Mileage Stats implementation will be explained, enabling you to understand the pieces, requirements, capabilities, and value of the Pinned Sites API. The Pinned Sites implementation in Mileage Stats includes feature detection, site pinning, dynamic jump list updating, and display of notification icons. These features are encapsulated in the mstats.pinnedSite JavaScript object that is contained in the mstats. pinnedsite.js file. The pinnedSite object is initialized differently depending on whether or not the user is signed in. This initialization will be described below. Feature Detection Pinned Sites feature detection is provided by the Internet Explorer 9 msIsSiteMode func- tion. Verifying that the page is opened as a pinned site before executing the Pinned Site API methods prevents unnecessary JavaScript errors. The msIsSiteMode function returns true if the current page is launched as a pinned site and false if it is not. The following isPinned function wraps the msIsSiteMode call and returns false if the page is not launched as a pinned site, or the browser is not Internet Explorer 9. JavaScript // Contained in mstats.pinnedsite.js isPinned: function () { try { return window.external.msIsSiteMode(); } catch (e) { return false; } } Enabling Website Pinning Unauthenticated users visiting the site are directed to the landing page, which is shown below. This page allows users to sign in, pin the site, and view the Mileage Stats video (not pictured). The Pinned Sites icon will glow when it is draggable, allowing the user to pin the site to the taskbar or Start Menu. The callout text displays for 5 seconds when the page loads. It will also show and hide the text as users move the mouse over or away from the Pinned Sites icon.
- 199. 166 chapter ten Note: Developers are not required to implement a draggable site icon as Mileage Stats does to enable site pinning. Providing a draggable icon gives the website more control over the pinning experience. Without a draggable icon, sites can still be pinned by dragging the tab or the favicon to the taskbar. Landing page The Pinned Sites JavaScript object is initialized when the above page loads with the following JavaScript function. CSHTML // Contained in Index.cshtml <script> $(function () { mstats.pinnedSite.intializePinnedSiteImage(); }); </script> If the browser is Internet Explorer 9 and the website is not currently pinned, the intializePinnedSiteImage method will attach appropriate event handlers for hiding and showing the callout text. It also adds the active CSS class to the Pinned Sites icon so that the icon appears to glow.
- 200. 167application notifications JavaScript // Contained in mstats.pinnedsite.js initializePinnedSiteImage: function () { // Do not enabled site pinning for non-Internet Explorer 9+ browsers // Do not show the callout if the site is already pinned if (!(!document.documentMode || this.isPinned())) { $('#pinnedSiteImage') .bind('mousedown mouseout', hideCallout) .bind('mouseover', showCallout) .addClass('active'); $('#pinnedSiteCallout').show(); setTimeout(hideCallout, 5000); } }, The following HTML snippet shows the required msPinSite class applied to the Pinned Sites icon. This class is used by Internet Explorer 9 to enable the user to drag the Pinned Sites icon to the taskbar or Start Menu and pin the site. CSHTML // Contained in Index.cshtml <img id="pinnedSiteImage" class="msPinSite" ... /> To call the user’s attention to the draggable Pinned Sites icon, the active CSS class below adds an attractive outer glow to it. CSS // Contained in static.css #pinnedSiteImage.active { cursor: pointer; box-shadow: 0px 0px 15px #6Dffff, inset 0px 0px 10px #6Dffff; border-radius: 12px; } The user can pin a website by dragging the Pinned Sites icon, browser tab, or favicon to the taskbar or Start Menu. Internet Explorer 9 integrates with the Windows shell to accomplish the pinning.
- 201. 168 chapter ten Dynamic Jump List Updating and Notification Icons Mileage Stats uses the jump list and notification icons to notify users of overdue mainte- nance reminders. When users click on the jump list entry, they will be taken to that re- minder. The notification overlay icon displays 1, 2, 3, or 3+ to provide a taskbar indication of outstanding reminders. Jump list and notification icon On the initial page load after the user authenticates, the client-side widgets and Ja- vaScript objects are invoked by code in the mileagestats.js file. The pinnedSite object is initialized by passing it a delegate to the data manager’s sendRequest method. JavaScript // Contained in mileagestats.js mstats.pinnedSite.intializeData(mstats.dataManager.sendRequest); The initializeData function saves the sendRequestFunc in the sendRequest prop- erty for future calls to the data manager by the requeryJumpList function. JavaScript // Contained in mstats.pinnedsite.js intializeData: function (sendRequestFunc) { sendRequest = sendRequestFunc; this.requeryJumpList(); },
- 202. 169application notifications The requeryJumpList function, shown below, is called when the pinnedSite object is initialized, and also by the layout manager widget when a reminder is fulfilled. It’s the layout manager’s call that initializes the dynamic updating of the jump list and notification icon. Note: Only the essential lines of code that demonstrate the loading of the jump list and updating of the notification icon are listed below. All of the following msSite functions are provided by Internet Explorer 9. After using feature detection to determine if the site is pinned, the jump list and overlay icon are cleared, and a new jump list is created. If the Ajax request is successful and the data.Reminders array has data, a URL will be constructed for each data item and added to the jump list. Next, the appropriate overlay icon is set. Finally, msSiteModeShowJumpList is called to update the jump list. JavaScript // Contained in mstats.pinnedsite.js requeryJumpList: function () { var getRelativeUrl = mstats.getRelativeEndpointUrl; try { if (this.isPinned()) { sendRequest({ url: '/reminder/overduelist/', contentType: 'application/json', cache: false, success: function (data) { try { var g_ext = window.external, ... g_ext.msSiteModeClearJumpList(); g_ext.msSiteModeCreateJumpList("Reminders"); g_ext.msSiteModeClearIconOverlay(); if (data.Reminders) { for (i = 0; i < numReminders; i += 1) { reminder = data.Reminders[i]; reminderUrl = getRelativeUrl('/reminder/details/' + reminder.Reminder.ReminderId.toString()); g_ext.msSiteModeAddJumpListItem(reminder.FullTitle, reminderUrl, faviconUrl, "self"); }
- 203. 170 chapter ten if (numReminders > 0) { iconOverlayUrl = '/content/overlay-' + numReminders + '.ico'; iconOverlayMessage = 'You have ' + numReminders.toString() + ' maintenance tasks that are ready to be accomplished.'; if (numReminders > 3) { iconOverlayUrl = '/content/overlay-3plus.ico'; } g_ext.msSiteModeSetIconOverlay(getRelativeUrl(iconOverlayUrl), iconOverlayMessage); } } g_ext.msSiteModeShowJumpList(); } ... This code demonstrates that with a small investment, you can deliver dynamic desk- top notifications in your websites. Requirement for Jump List Items to Appear The Windows 7 taskbar jump list items can be disabled by your users, preventing them from displaying even though the website has been pinned to the taskbar. If your website implements the jump list feature, you should provide this information to your users and advise them that the Store and display recently opened items in the Start menu and the taskbar property setting needs to be checked for the jump list items to appear. Taskbar and Start menu properties
- 204. 171application notifications In addition to be being able to disable jump list items, users can customize the number of jump list items displayed on their computers. The default value is 10 and can be changed in the Customize Start Menu dialog box below. This dialog box is opened by clicking the Customize button in the Taskbar and Start Menu Properties dialog box shown above. Customizing Start menu properties Summary Providing timely feedback that is uniformly displayed, context sensitive, and understand- able to your users without breaking their workflow takes planning by designers and de- velopers alike. Your users will appreciate this extra effort, which results in a polished UX. By encapsulating the display and management of user notifications in a single JavaScript object, your application will be easier to code, maintain, and test. You have also learned about integrating your website with the Windows 7 desktop to provide users with dy- namic notifications and jump list items, as well as allowing them to browse your site using a customized browser window.
- 205. 172 chapter ten Further Reading For a comprehensive look at input validation error messages, see Chapter 11, “Server-Side Implementation.” For detailed information on the inner workings of the Mileage Stats pub/sub implementation, see Chapter 8, “Communication.” For more information about the isFunction method, see jQuery.isFunction(): http://api.jquery.com/jQuery.isFunction/. For more information about Pinned Sites, see the Pinned Sites developer documentation: http://msdn.microsoft.com/en-us/library/gg491731(v=VS.85).aspx. To access web resources more easily, see the online version of the bibliography on MSDN: http://msdn.microsoft.com/en-us/library/hh404094.aspx.
- 206. 173 Server-Side Implementation11 Introduction Creating a well-architected web server application requires meeting the needs of the web client while properly factoring the Microsoft® .NET Framework code on the web server. A web server application is responsible for more than just returning HTML content. Web server applications also involve data models, data access and storage, security, communi- cation, resource management, and internationalization. This chapter covers ways you can integrate technologies in the Microsoft web platform into a coherent architecture that is reliable, testable, and capable of handling demanding web client applications. The following diagram shows the architecture of the Mileage Stats Reference Imple- mentation (Mileage Stats). In this chapter, the data access and repository layers are dis- cussed first, and then the Model View Controller (MVC) and business services layers. In the context of these layers, we also discuss the distinctions between data models, domain models, and view models. Lastly, you will learn how to provide asynchronous data and validation to web clients. Mileage Stats high-level architecture
- 207. 174 chapter eleven In this chapter you will learn: • How to use ADO.NET Entity Framework and the Microsoft SQL Server® Compact Edition to create a data model. • Techniques to separate concerns among your data model, business logic, and user interface (UI). • How to support interactive web clients with asynchronous data. • How to manage data validation at each level of the stack. The technologies discussed in this chapter are ASP.NET MVC 3, ADO.NET Entity Framework 4, SQL Server Compact Edition 4, and Unity Application Block 2.0. Creating a Data Access Layer Data access is a key part of your application. The choice of storage technology and data access patterns can affect the entire application. This section covers an approach that uses rapid modeling techniques and tools while allowing you to migrate to high-scale data storage in the future. A well-designed data access layer captures the essential structure of the data but omits conditional logic that is specific to the application. When you separate concerns that are specific to data access from those that are specific to the application’s logic, the application remains robust and maintainable as you add features over time. The typical concerns of a data access layer include the type of data, the relationships between enti- ties, and constraints. The data you store is often in a format that is optimized for the storage technology, such as a relational database. Frequently, this format is not convenient for consumption by the application. For example, duration may be stored as a number representing the number of computer clock ticks, but having an instance of a TimeSpan would be easier for the application to use. In this case the data access layer should encapsulate the trans- lation between the storage and in-memory formats. Ideally, the data access layer should not contain any UI or application logic and should fully abstract the underlying storage implementation. In Mileage Stats, the MileageStats.Model project contains the data model. The data model is part of the data access layer. The structure and strong typing of the classes in this project express the data types, relationships, and constraints inherent in the data. For example, the PricePerUnit property of the FillupEntry class is a double to allow for dollars and cents, the Fillups property of the Vehicle class is an ICollection<FillupEntry> to express a one-to-many relationship, and the DueDate property of the Reminder class is a nullable DateTime to allow it to be optional. When your application has significant complexity or conditional interaction with the data, you should consider creating a separate domain model that is distinct from your data model. See the “Composing Application Logic” section for guidance about whether or not to create a separate domain model.
- 208. 175server-side implementation Rapid Data Modeling Using the ADO.NET Entity Framework and SQL Server Compact The ADO.NET Entity Framework provides three ways for you to rapidly create a data model: • You can use the code-first approach to author standard classes that the ADO.NET Entity Framework uses to generate a database schema. • You can use the database-first approach, where the ADO.NET Entity Framework generates data model classes from an existing database. • You can choose to use the model-first approach, where an Entity Data Model (.edmx) can be used to generate the code and database. The code-first approach is well suited to scenarios like Mileage Stats where develop- ers are defining a new data model that will likely evolve as the application is written and there is no existing database. If you have an existing database, prefer to use stored proce- dures, or have a data architect on your team, then you may want to use more traditional database modeling techniques that let you generate the data model code from the data- base. Using SQL Server Compact with the ADO.NET Entity Framework allows you to use an on-disk database that can easily be recreated whenever your schema changes. It can be seeded with a small dataset for debugging and unit testing. SQL Server Compact has a small footprint and can be migrated to SQL Server Express, SQL Server, or SQL Azure™ when the application is deployed. Note: SQL Server Compact provides query and update functionality, but does not support conditional syntax (such as IF EXISTS), nor does it support stored procedures. Consider other SQL Server editions as your starting point if you need database-centric logic. Mileage Stats uses the code-first approach with the ADO.NET Entity Framework and SQL Server Compact. This approach allowed the data model to be built quickly and adapt to changes, and it minimized the day-to-day cost of database setup for the development team. The ADO.NET Entity Framework lets you seed your database with sample data each time the database is rebuilt. This gives you the opportunity to use realistic sample data while you develop the application. We discovered many issues early in the development process of Mileage Stats because the sample data forced the UI and application logic to work with realistic data. To use the code-first approach, you first create standard CLR object (POCO) classes. The ADO.NET Entity Framework then infers the database schema from your class struc- ture and your property types. In the following example, the FillupEntry class defines properties that the ADO.NET Entity Framework can map to a database schema.
- 209. 176 chapter eleven C# // Contained in FillupEntry.cs public class FillupEntry { ... public int FillupEntryId { get; set; } public int VehicleId { get; set; } public DateTime Date { get; set; } public int Odometer { get; set; } public double PricePerUnit { get; set; } public double TotalUnits { get; set; } public string Vendor { get; set; } public double TransactionFee { get; set; } public double TotalCost { get { return (this.PricePerUnit*this.TotalUnits) + this.TransactionFee; } } ... } The ADO.NET Entity Framework maps property types like double, string, and int to their equivalent SQL data type. Fields that represent unique entity identifiers, such as FillupEntryId and VehicleId, are automatically populated. Calculated properties, like TotalCost, that are not saved to the database can be added. The ADO.NET Entity Framework has three mechanisms for determining the database schema from the class definition: • Class Inspection. This is inspection of the classes to create a schema. Some of the decisions the ADO.NET Entity Framework makes are based on convention. For example, property names that end in Id are considered unique identifiers. They are auto-populated with database-generated values when records are inserted into the database. • Attribute Inspection. This involves inspection of data annotation attributes attached to properties. These attributes are found in the System.Component Model.DataAnnotations namespace. For example, the KeyAttribute indicates a unique entity identifier. Attributes such as RequiredAttribute and StringLength Attribute cause the ADO.NET Entity Framework to create column constraints in the database. • Explicitly using DbModelBuilder. This involves calls to the DbModelBuilder as part of the database creation. These methods directly determine the data types, entity relationships, and constraints for the database schema.
- 210. 177server-side implementation Note: Using the data annotation attributes with the ADO.NET Entity Framework affects how the ADO.NET Entity Framework generates the database schema and performs validation of values when the data is saved using DbContext.SaveChanges. However, using the DbModelBuilder only changes the database schema. Which approach you choose can change the error messages you see when invalid data is submitted as well as determine whether a database call is made. See the “Further Reading” section for the ADO.NET Entity Framework documenta- tion. It contains the detailed API reference and the steps required to apply each of these techniques. Mileage Stats used the DbModelBuilder approach to define the storage schema and did not apply any data annotation attributes to the data model classes. This prevented database-specific concerns from being incorporated into the data model and made it possible to change the database schema, if necessary, for other kinds of database deploy- ments. This approach was part of the decision to create a separate data model and domain model. See the “Creating a Business Services Layer” section for more information on this decision. The domain model in Mileage Stats uses data annotation attributes extensively. See the “Data Validation” section for details on using attributes for validation. Using the DbModelBuilder to Create a Data Model In Mileage Stats, the MileageStats.Data.SqlCE project contains the MileageStats DbContext class. A data model built using the ADO.NET Entity Framework has at least one class derived from DbContext. This class provides the starting point for accessing the data model. It is also used for defining the data model, which results in a database schema. The MileageStatsDbContext class overrides the OnModelCreating virtual method and uses the DbModelBuilder parameter to provide the ADO.NET Entity Framework with more information about the schema. The task of defining each entity is factored into separate methods that MileageStatsDbContext.OnModelCreating invokes. The follow- ing example is one of those methods. It builds the model for the Vehicle class. C# // Contained in MileageStatsDbContext.cs private void SetupVehicleEntity(DbModelBuilder modelBuilder) { modelBuilder.Entity<Vehicle>().HasKey(v => v.VehicleId); modelBuilder.Entity<Vehicle>().Property(v => v.VehicleId) .HasDatabaseGeneratedOption( DatabaseGeneratedOption.Identity); modelBuilder.Entity<Vehicle>().Property(v => v.Name) .IsRequired(); modelBuilder.Entity<Vehicle>().Property(v => v.Name) .HasMaxLength(100); modelBuilder.Entity<Vehicle>().Property(v => v.SortOrder);
- 211. 178 chapter eleven modelBuilder.Entity<Vehicle>().Property(v => v.MakeName) .HasMaxLength(50); modelBuilder.Entity<Vehicle>().Property(v => v.ModelName) .HasMaxLength(50); modelBuilder.Entity<Vehicle>().HasOptional(v => v.Photo); modelBuilder.Entity<Vehicle>().HasMany(v => v.Fillups); modelBuilder.Entity<Vehicle>().HasMany(v => v.Reminders); } DbModelBuilder allows you to chain calls together because each method returns an object that can be used in subsequent calls. The calls in the preceding example use the Entity<T> method to locate an entity based on the type of the class. The chained Property method locates a property for that entity. Lambda expressions like v => v.Vehicle EntryId allow the Property method to work without having to provide the name of the property as a string. The last method call defines the data model type, relationship, or constraint. It is possible for you to use data annotation attributes in conjunction with calls to DbModelBuilder. Data annotation attributes allow a decentralized approach where relationships and constraints are attached to individual properties on the class. The Db ModelBuilder approach gives you centralized control of the data model and a powerful set of modeling options. You should be careful to keep the constraints in sync when mixing approaches. For this reason, it is recommended that you use either data annotation attributes or the DbModelBuilder, and avoid mixing approaches. Note: There is an order of precedence in the ADO.NET Entity Framework when all three mechanisms are used: DbModelBuilder calls override data annotation attri- butes, which override convention by inspection. Creating the Database Once you define the data model in code, you need to create the database. When you use the code-first approach, the ADO.NET Entity Framework doesn’t create the database until the first request for data occurs. You should create the database on application startup rather than on the first request so that the first user isn’t forced to wait. Initial- izing during application startup also reduces the chance of a race condition during data- base creation. Note: Many web applications built using the ADO.NET Entity Framework contain the auto-generated WebActivatorAttribute code. This attribute automatically calls the database creation and initialization code. Mileage Stats forgoes this approach because the Unity dependency injection container controls the lifetime of the MileageStats- DbContext instance. In Global.asax.cs, the Application_Start method initializes the dependency injec- tion container and then initializes the database. The InitializeDatabase method uses the dependency injection container to resolve an instance of the IRepositoryInitializer and
- 212. 179server-side implementation then calls the Initialize method. In the following example, the constructor of the RepositoryInitializer configures the database connection and initializer, and the Initialize method requests some data to ensure that the database is created before user requests are processed. C# // Contained in RepositoryInitializer.cs public RepositoryInitializer(IUnitOfWork unitOfWork) { ... Database.DefaultConnectionFactory = new SqlCeConnectionFactory("System.Data.SqlServerCe.4.0"); Database.SetInitializer( new DropCreateIfModelChangesSqlCeInitializer<MileageStatsDbContext>()); } public void Initialize() { this.Context.Set<Country>().ToList().Count(); ... } Initializing the Database The ADO.NET Entity Framework lets you control how your database is created and ini- tialized through the IDatabaseInitializer<T> interface and the Database.SetInitializer method. You can write the initializer with the logic you need to create and populate your database. In Mileage Stats, the MileageStats.Data.SqlCe project contains three classes that can initialize the database: CreateIfNotExistsSqlCeInitializer, DropCreateAlways SqlCeInitializer, and DropCreateIfModelChangesSqlCeInitializer. All three inherit from the SqlCeInitializer base class that implements the IDatabaseInitializer<T> interface. Note: When you use NuGet to add the ADO.NET Entity Framework to your project, the package manager will generate some default initializers similar to those found in Mileage Stats. Mileage Stats classes are modified versions of the original generated classes. The modifications allow each initializer to share the database seeding code used to start the application with sample data. Each class implements a different strategy for creating the database. Mileage Stats defaults to the DropCreateIfModelChangesSqlCeInitializer to drop and create the database anytime the data model changes the schema. This can be very useful during product development when the data model is evolving and the database doesn’t contain real data.
- 213. 180 chapter eleven Depending on how your database is deployed, you may need to change the default initializer or use another mechanism for initializing the database. If you deploy a new version of the application where the schema needs to be upgraded, you would either need to write an initializer that upgrades the database, or run upgrade scripts before deploy- ment of the newer version. Otherwise, you would lose all the data stored in the database. Optimized Data Access Many application data models are hierarchical, with one-to-many and many-to-many re- lationships between entities. On the other hand, web applications are connectionless and stateless; they take a request and produce a response. You should avoid loading large model hierarchies for requests that only need a subset of the data. Loading more data than is necessary places additional processor, memory, and bandwidth pressure on the server and can limit scalability and performance. Fortunately, the ADO.NET Entity Framework provides powerful querying support in the DbSet class that allows you to return just the data you need. In Mileage Stats, the VehicleRepository class uses the Where and Include methods on the DbSet to control the data retrieved, as shown in the following code. C# // Contained in VehicleRepository.cs public Vehicle GetVehicle(int userId, int vehicleId) { return this.GetDbSet<Vehicle>() .Include("Fillups") .Include("Reminders") .Where(v => v.VehicleId == vehicleId && v.UserId == userId) .Single(); } The ADO.NET Entity Framework does not automatically populate ICollection<T> properties like Vehicles, Fill-ups, and Reminder, but does lazy load them when accessed. When lazy loading is turned off (as it is in Mileage Stats,) these properties must be in- cluded explicitly. Properties marked optional by data annotation attributes or DbModel Builder calls, such as the FillupEntry.Distance property, must also be included explicitly to be retrieved. The previous code sample is an example of calling Include explicitly. The ADO.NET Entity Framework has features that support lazy-loaded properties and change tracking. When using the code-first approach, lazy loading is done by applying the virtual keyword, and change tracking is done through having standard get and set methods along with using ICollection<T> for one-to-many relationships. The ADO.NET Entity Framework also supports these features by implementing the IEntityWithChange Tracker or IEntityWithRelationships interfaces. Implementing the Repository Pattern The Repository pattern assists in separating data storage concerns from the application logic. This pattern is especially beneficial when you use the ADO.NET Entity Framework because it allows you to hide ADO.NET Entity Framework-specific classes such as
- 214. 181server-side implementation DbContext and DbSet, to optimize the shape of the data returned to the application, to coordinate updates, and to unit test your application without requiring access to physical data storage. See the “Further Reading” section for a formal definition of the repository pattern. A repository is a set of interfaces and implementations providing methods for data access. The interfaces do not expose any types specific to data storage. You can choose how many repositories to create based on how granularly you want to control data access within your application. In Mileage Stats, the MileageStats.Data project contains the repository interfaces and the MileageStats.Data.SqlCe project contains the repository implementations. The Mile- age Stats repositories map closely to the data entities to match the usage pattern from the business services layer. The following code shows the IReminderRepository interface. C# // Contained in IReminderRepository.cs public interface IReminderRepository { void Create(int vehicleId, Reminder reminder); Reminder GetReminder(int reminderId); void Update(Reminder reminder); void Delete(int reminderId); IEnumerable<Reminder> GetRemindersForVehicle(int vehicleId); IEnumerable<Reminder> GetOverdueReminders(int vehicleId, DateTime forDate, int forOdometer); IEnumerable<Reminder> GetUpcomingReminders(int vehicleId, DateTime forStartDate, DateTime forEndDate, int odometer, int warningOdometer); } Note: The IReminderRepository interface returns collections as IEnumerable<T>, rather than IList<T> or ICollection<T>. This was an intentional design choice to prevent the direct addition of entities to the collections. To create a new reminder, the developer must use the Create method. In Mileage Stats, the implementation of the IReminderRepository calls ToList before returning the IEnumerable<T>. This is to ensure that the query is executed inside the repository. If ToList was not called, then the repository would return an IQueryable<T> and the database would not be accessed until something iterated over the IQueryable<T> object. The problem with returning an IQueryable<T> is that a developer consuming the API is likely to assume that the query has already executed and that you are working with the results. If you iterate over the query more than once, it will result in multiple calls to the database. If you specifically want your repository to return queries instead of results, use the IQueryable<T> on the interface in order to make your intention explicit.
- 215. 182 chapter eleven Because web applications and services follow a request/response pattern, incoming data is built from the POST form data. This means that the incoming object class was not retrieved from the DbContext and cannot be updated because it is not attached to the context. Using the repository pattern with the ADO.NET Entity Framework creates the proper place to deal with attached and detached entities and set entity state. In the following example, the Update method in the VehicleRepository is passed an entity that is not attached to the ADO.NET Entity Framework context. The Update method locates the corresponding attached entity, updates the attached entity, and ensures the attached entity state is set correctly. C# // Contained in VehicleRepository.cs public void Update(Vehicle updatedVehicle) { Vehicle vehicleToUpdate = this.GetDbSet<Vehicle>().Where(v => v.VehicleId == updatedVehicle.VehicleId).First(); vehicleToUpdate.Name = updatedVehicle.Name; vehicleToUpdate.Year = updatedVehicle.Year; vehicleToUpdate.MakeName = updatedVehicle.MakeName; vehicleToUpdate.ModelName = updatedVehicle.ModelName; vehicleToUpdate.SortOrder = updatedVehicle.SortOrder; vehicleToUpdate.PhotoId = updatedVehicle.PhotoId; this.SetEntityState(vehicleToUpdate, vehicleToUpdate.VehicleId == 0 ? EntityState.Added : EntityState.Modified); this.UnitOfWork.SaveChanges(); } Composing Application Logic Web client applications built for rich user interactivity are often more complex than those built for clients that post back synchronously on each mouse click and always display static HTML in response. Web applications that provide interactive behavior on a single page (via Ajax method calls, JavaScript templates, and secondary data requests) require careful composition of server application code. This section covers several techniques and considerations to help you create maintainable applications that provide a rich set of services to interactive clients. Factoring Application Code with ASP.NET MVC Because ASP.NET MVC is a web platform technology built around a design pattern, fol- lowing the MVC pattern is a key step in properly factoring your application logic. Well- designed MVC applications have controllers and actions that are small and views that are
- 216. 183server-side implementation simple. Keeping your application code DRY (Don’t Repeat Yourself) as the application is built is far easier than trying to clean it up later. Note: The routes you create in global.asax.cs define the URL hierarchy of your applica- tion. Defining your URL strategy, routes, and controller topology early in a project can help prevent having to change your client application code later. Because the majority of the application logic is contained within the models, MVC applications contain different kinds of models: • View models are built solely for a view to data-bind against. These models are contained within the MVC application and often follow the same composition hierarchy as the views. They are focused on presentation. That is, they are only concerned with presenting data in the UI. Sometimes a special type of view model, called a form model, is also used to represent the data coming into an application from the user. • Domain models are based on the solution domain. They are focused on handling the business logic of the application. They represent the logical behavior of the application independent of the UI and the storage mechanism. They may be annotated or extended to support some application features such as validation or authentication. Because these models need to be shared between the server and client browser, they are sometimes contained within view models. Domain models are sometimes referred to as application models or service models. • Data models are built for data services and storage. These are not exposed by the application and are often encapsulated by a services layer. Organizing your application into these categories is a way of separating concerns in your code. This separation becomes increasingly important as an application grows in complexity. If you find that changes to your application logic are affecting storage or presentation (or vice versa), you should factor the code into separate models. In some cases, the models may be very similar to one another. In other cases, the models may radically diverge. If your domain model and your data model are very similar, you can consider aggregating an instance of your data model class into your domain model class. If your domain and data models have a matching hierarchy and compatible interfaces, you can also consider using inheritance to derive your domain model classes from your data model classes. Note: Inheritance has the advantage of less coding because you reuse your data model as your domain model, but it is at the cost of tighter coupling. If you can ensure that you will not need to substitute a different data model and that the domain and data models will not diverge, inheritance can be effective. As you’re writing your controller actions, you should factor complex methods into helper methods or classes in your models and services layer. Use action filter attributes such as HttpPostAttribute to avoid writing conditional logic in each action that inspects the HttpContext. Also, use action filters for cross-cutting concerns such as authentica- tion (for example, AuthorizeAttribute) and error handling (for example, HandleError Attribute). Ideally, methods that handle GET should contain only a few method calls and
- 217. 184 chapter eleven should not contain much conditional logic; methods that handle POST should validate the incoming data, perform the update when the data is valid, and conditionally return a view depending on the success of the update. The following examples from Mileage Stats show two versions of the FillupController’s Add method (first the GET version, and then the POST version). In these examples, the generic method Using<T> is a helper method used to delegate logic to the classes in the services layer. C# // Contained in FillupController.cs public ActionResult Add(int vehicleId) { var vehicles = Using<GetVehicleListForUser>() .Execute(CurrentUserId); var vehicle = vehicles.First(v => v.VehicleId == vehicleId); var newFillupEntry = new FillupEntryFormModel { Odometer = (vehicle.Odometer.HasValue) ? vehicle.Odometer.Value : 0 }; var fillups = Using<GetFillupsForVehicle>() .Execute(vehicleId) .OrderByDescending(f => f.Date); var viewModel = new FillupAddViewModel { VehicleList = new VehicleListViewModel(vehicles, vehicleId) {IsCollapsed = true}, FillupEntry = newFillupEntry, Fillups = new SelectedItemList<Model.FillupEntry>(fillups), }; ViewBag.IsFirstFillup = (!fillups.Any()); return View(viewModel); } C# // Contained in FillupController.cs [HttpPost] [ValidateInput(false)]
- 218. 185server-side implementation [ValidateAntiForgeryToken] public ActionResult Add(int vehicleId, FillupEntryFormModel model) { var vehicles = Using<GetVehicleListForUser>() .Execute(CurrentUserId ); if (ModelState.IsValid) { var errors = Using<CanAddFillup>() .Execute(CurrentUserId, vehicleId, model); ModelState.AddModelErrors(errors, "AddFillup"); if (ModelState.IsValid) { Using<AddFillupToVehicle>() .Execute(CurrentUserId, vehicleId, model); TempData["LastActionMessage"] = Resources .VehicleController_AddFillupSuccessMessage; return RedirectToAction("List", "Fillup", new { vehicleId = vehicleId }); } } var fillups = Using<GetFillupsForVehicle>() .Execute(vehicleId) .OrderByDescending(f => f.Date); var viewModel = new FillupAddViewModel { VehicleList = new VehicleListViewModel(vehicles, vehicleId) { IsCollapsed = true }, FillupEntry = model, Fillups = new SelectedItemList<Model.FillupEntry>(fillups), }; ViewBag.IsFirstFillup = (!fillups.Any()); return View(viewModel); }
- 219. 186 chapter eleven Note: As you’re writing your controllers, injecting dependences through the controller’s constructor will benefit unit testing. In Mileage Stats, the controller depends on interfaces and not concrete implementations, so we were able to easily replace the actual dependencies with mock implementations. This allowed us to test just the code for the action and not the entire functional stack. For more information, see Chapter 13, “Unit Testing Web Applications.” After factoring your models and controller actions, your views will use the models to produce HTML. When building views, you should keep the amount of code to a minimum. Code contained in views is not easily testable. Errors in views are harder to debug because the exception occurs during the view engine’s rendering pass. However, some very simple logic in views is acceptable. For example, looping over items to build a repeating section of the UI or conditional logic for toggling the visibility of specific sections is fine. Any HTML that is repeated in multiple views is a candidate for being factored into a partial view. However, if you find that you need something more complicated, try to push that logic into the view model. If the logic is a cross-cutting concern, then consider placing that logic inside an HTML helper extension method. Examples of built-in HTML helper exten- sion methods in MVC include BeginForm, RenderPartial, and ActionLink. Examples of helper methods in Mileage Stats are AverageFuelEfficiencyText and AverageFuel EfficiencyMagnitude. Note: The MVC Razor syntax allows you to write code more compactly as well as easily mix code and markup. Don’t let this powerful view engine tempt you into writing a lot of code in your views. Instead, let it help you keep the code you do write clear and maintainable. Design Checklist for MVC Applications The following checklist is useful when reviewing your MVC web application code. Check When reviewing your MVC web application code, ensure that: ☐ Each controller handles a common set of concerns, either for a particular model type or a related set of interactions with the user. ☐ Action methods consist of a sequence of calls to helper methods, helper classes, and/or model classes. They do not contain complex branching conditional logic. They should be easy to unit test and self-documenting. ☐ The same code is not repeated in multiple action methods. Action filter attributes are used to handle cross-cutting concerns. ☐ The majority of the application logic is contained within the model or service layer. ☐ The hierarchy of model classes used by controller actions and views is effective for the application. If required, separate data model classes are contained within another assembly. ☐ Views contain only small conditional statements and calls to HTML helper methods. ☐ The same HTML is not repeated in multiple views. Commonly used HTML is factored into partial views. See the “Further Reading” section for links to more MVC best practices.
- 220. 187server-side implementation Creating a Business Services Layer As you factor your application code from your controllers’ action methods into helper methods and classes, you may find that there are classes and methods that help to prop- erly retrieve, validate, and update data in your data model. This business logic is distin- guished from the controller code because it encapsulates logical operations on the domain model and is not specific to any view. When you have a significant amount of business logic, you may need to create a business services layer. The business services layer is another layer of abstraction, and there is a cost to adding it to the application. However, creating this layer allows you to test the business logic in isolation, and it simplifies the tests for your controllers. Because the business services layer is unaware of the UI, you can also reuse it in the future when exposing additional interfaces such as a web service (using service technologies like Win- dows® Communication Foundation (WCF)). This allows you to support both desktop and mobile clients from a single business services layer. When deciding whether or not to create a business services layer, you should also consider whether or not to create a separate domain model. See the section “Factoring Application Code with ASP.NET MVC” for details on the different kinds of models and techniques for separating a domain model from a data model. Creating a separate domain model along with a business services layer is most beneficial when you need to fully en- capsulate your data model, your data model does not perform validation, and the domain model functionality will make it easier for you to write your controllers and views. How- ever, having a separate domain model and data model does incur a cost for transforming values between the two models. The services layer in Mileage Stats consists primarily of handlers and domain models. The handlers are a set of classes that implement the core behavior of the application. They are completely independent from and unaware of the UI. Reading over the names of the handler classes is like reading a list of the features of Mileage Stats. The domain models are a second set of classes in the services layer that differ from both the data models and the view models. The data models in Mileage Stats are primarily concerned with persisting data to the database. The view models are very specific to the needs of the UI. However, the domain models in the services layer are not concerned with either persistence or the UI. The handlers and the domain models in the services layer represent the business logic of the application. Together they provide validation, calculation of statistics, and other services. For more information on data validation, see the “Data Validation” section. The following illustration shows the high-level design of the services layer and data model.
- 221. 188 chapter eleven Mileage Stats service layer and data model The following example from Mileage Stats shows the Execute method from the AddFillupToVehicle handler. This handler is represented as a single class with a single public method. We chose the convention of naming the method Execute. The general dependencies of the handler are injected into the constructor of the handler. Any specific values that may be needed to invoke the handler are passed as arguments to the Execute method. Unity is responsible for managing and injecting the dependencies for the handler’s constructor, whereas the Execute method will be invoked by some consumer with the necessary arguments. In the case of Mileage Stats, the consumer is a controller action. Also note that the handler has two private helper methods: ToEntry and Adjust SurroundingFillupEntries. ToEntry is responsible for converting the data to the form needed by the data layer. CalculateInterFillupStatistics (which is called within Adjust SurroundingFillupEntries) is responsible for calculating the statistics. C# // Contained in AddFillupToVehicle.cs public virtual void Execute(int userId, int vehicleId, ICreateFillupEntryCommand newFillup) { if (newFillup == null) throw new ArgumentNullException("newFillup"); try { var vehicle = _vehicleRepository.GetVehicle(userId, vehicleId); if (vehicle != null)
- 222. 189server-side implementation { newFillup.VehicleId = vehicleId; var fillup = newFillup; var entity = ToEntry(fillup); AdjustSurroundingFillupEntries(entity); _fillupRepository.Create(userId, vehicleId, entity); // update calculated value newFillup.Distance = entity.Distance; } } catch (InvalidOperationException ex) { throw new BusinessServicesException(Resources .UnableToAddFillupToVehicleExceptionMessage, ex); } } In Mileage Stats, the handlers are responsible for implementing the core business logic of the application. The controllers have the responsibility of accepting the user’s input and invoking the handler. Controllers then take the results of invoking handlers and compose any data necessary for rendering views. This data frequently takes the form of classes that we call view models. Overall, the business services layer provides functionality that makes writing control- lers, actions, and views much easier. Supporting Interactive Web Clients Interactive web clients communicate asynchronously with the server and manipulate the document object model (DOM). Because multiple interactions can occur simultaneously, managing state and tracking events can be difficult. This section outlines ways the web application server can support web clients by providing services that reduce the complex- ity of the JavaScript. Providing HTML Structure Traditionally, the server in a web application returns HTML as content that the client’s browser renders directly. Because interactive web clients manipulate the HTML structure, you will need to focus less on the appearance of the HTML and more on providing a useful hierarchy for the client. You should think of the HTML structure as part of the contract between the client and the server. In order to modify the content, web clients first need to locate elements in the DOM. The jQuery library provides a selector syntax that can be used to locate elements in many ways (such as by ID, class, relative position, and so forth). If the web client depends on the
- 223. 190 chapter eleven hierarchical structure of the HTML you produce, you will likely break the client applica- tion when you modify the structure. To avoid tightly coupling the client JavaScript with the HTML structure, you can use data- (pronounced “data dash”) attributes in your HTML. The data- attributes are attri- butes whose names are prefixed with “data-” and represent metadata on elements. Many JavaScript developers use the id and class attributes to locate elements. The id attribute is limited because there can be only one per element and id values are generally expected to be unique within a page. The class attributes cause confusion because they are also used to apply layout and style to the element through Cascading Style Sheets (CSS). Because data- attributes are independent of the HTML structure, they allow you to restructure the HTML without impacting the client. See Chapter 6, “Client Data Manage- ment and Caching” and “Using Data- Attributes” in Chapter 7, “Manipulating Client-Side HTML” for more information on how clients can use data- attributes. Below are two data- attribute examples from Mileage Stats. In the first example, the data-vehicle-id attribute allows the client to locate the associated element. Notice that we are rendering the value for the data- attribute on the server and that it will be con- sumed by JavaScript on the client. HTML // Contained in ViewsVehicleList.cshtml <a class="list-item @(item.Reminder.IsOverdue ? "overdue" : null)" href="@Url.Action("Details", "Reminder", new { id = item.Reminder.ReminderId })" data-vehicle-id="@item.Vehicle.VehicleId"> ... </a> In the second example, the data-chart-url attribute provides the client a URL to use in an Ajax call. HTML // Contained in ViewsVehicleList.cshtml <div id="main-chart" class="article framed" data-chart-url="@Url.Action(“JsonGetFleetStatisticSeries", “Home")"> Ideally, your JavaScript should use only data- attributes to locate elements and to discover contextual data from the server. However, there are cases where using a selector to manipulate all elements having a given element name, unique ID, or class is a more practical approach. In both cases, you should write the JavaScript code to allow for the case where the set of selected elements is empty. Note: If you have a team of developers writing the web client independently of the web application, we strongly recommend you ensure agreement on the expected HTML structure before writing the web client JavaScript.
- 224. 191server-side implementation Using View Model and View Bag ASP.NET MVC 3 introduced the ViewBag. A ViewBag is a dynamic object that wraps the ViewData property that was present in previous versions of ASP.NET MVC. A ViewBag is a name/value keyed collection that lets you store loosely typed data. This differs from the Model property on the View, which contains strongly typed data. Having two ways to provide the view data can cause confusion about when to use View.Model versus ViewBag. The strongly typed View.Model property has several benefits over ViewBag. It en- ables IntelliSense® auto-complete in the view, and it provides type safety when generat- ing the view model from a controller action. In addition, many of the helpers are specifi- cally designed to work with a strongly typed model, and they can extract metadata from the model to help automatically construct a view. When you use the View.Model in a form element, you will have an associated con- troller action (marked with the HttpPostAttribute) that accepts the model as a param- eter. When the form is submitted, the MVC model binder uses the posted form data to construct and populate an instance of your view-model class. Often the view model representing the form that is passed into a controller action will be significantly different from the view model returned from the controller action. In those cases you can create a form model that contains only the data from the form. An example of this in Mileage Stats is the Add action on VehicleController. It has a param- eter of type VehicleFormModel and returns a view model of type VehicleAddView Model. The VehicleAddViewModel contains data such as the current user and a list of vehicles, as well as the original form model. If possible, create a view model for each of your views. This gives you complete control over the data sent to and from the client. It also reduces confusion by making the relationship between views and view models explicit. Likewise, using form models that are specific to views prevents the ASP.NET MVC model binder from setting properties that you didn’t expect to receive from the client. In many cases, if you follow this practice you will never need to use ViewBag. However, there can be cases when your view needs additional data that doesn’t be- long in your view model and you don’t want to make a round trip to the client. In these cases, consider placing the data in ViewBag. In Mileage Stats, the _ProfileForm partial view uses the User class as the View. Model. Part of the view is a drop-down list of countries. The following example shows the ViewBag used to populate the drop-down list. CSHTML //Contained in ViewsShared_ProfileForm.cshtml @model MileageStats.Domain.Models.User ... <div class="editor-label"> @Html.LabelFor(model => model.Country) </div> <div class="editor-field"> @Html.DropDownListFor(model => model.Country, ViewBag.CountryList as SelectList,
- 225. 192 chapter eleven "-- Select country --", new { @class = "editor-textbox" }) @Html.ValidationMessageFor(model => model.Country) </div> ... <div class="editor-commands"> <button data-action="profile-save" class="button generic small editor-submit" type="submit"> <img src="@Url.Content( "~/Content/button-save.png")" title="Save Profile" alt="Save" /> </button> </div> <div style="clear: both;"> </div> @Html.ValidationSummary(true) Mileage Stats could have had a separate view-model class containing the User and an ICollection<Country> object. However, doing so would make the partial view less reus- able because every view model in the hierarchy of views and partial views would have to contain the new view model. Providing Data Asynchronously Requesting data asynchronously is at the heart of a responsive, interactive web client. One option for requesting data asynchronously is to use WCF to expose a service API for the client. This is a good choice when the application is not responsible for serving the web UI. ASP.NET MVC web applications are a great endpoint for serving data to web clients when the application must also serve the site’s UI. You can use the same routing, controllers, security, and models for returning data that you use for returning HTML structure. This allows the web client to use the relative URLs you provided in the data- attributes as well as some knowledge of the site’s URL structure to create requests for data. Choosing a Data Format Web clients typically request data as HTML, JavaScript Object Notation (JSON), XML, or binary (for example, images and video) from the server. Each of these formats has its unique strengths. The JSON format is recommended when the web client needs to bind data to existing HTML elements, generate new HTML from the data, transform the data, or make logical decisions based on the data. JSON is a very concise format that has serialization support on the client and in ASP.NET MVC. Because JSON contains no markup, it helps separate UI and data service concerns. The HTML format is useful when the client makes minimal or no changes to the re- turned content and simply places the entire HTML result into a pre-determined area of the page. Examples of where HTML works well are advertisements, content aggregators, and content management systems.
- 226. 193server-side implementation The XML format is useful when the client receives data based on a pre-defined schema. XML is also used when working in open-standards formats such as RSS, Atom, and oData. Web clients can use the known schema structure to process the XML into HTML. Binary formats are generally employed for media. Images are the most common ex- ample; the server returns an img element with a src attribute, the browser makes a sec- ondary request to the server and then renders the binary result as an image. Note: Not all browsers send the same data to the server when requesting images and other resources. Some browsers will send authentication headers and cookies while others will not. If you have secondary requests that must be authenticated, you need to verify that those requests work on the browsers you intend to support. In addition, you should perform testing in both the ASP.NET development server and in a Microsoft Internet Information Services (IIS)-deployed web application. To support a particular format in ASP.NET MVC, return a JsonResult, ContentResult, or FileResult instead of a ViewResult from your action methods. The following example from Mileage Stats returns a JsonResult. The view model is created and then the Controller.Json method is called to convert the object into JSON for the response. C# // Contained in VehicleController.cs [Authorize] [HttpPost] public JsonResult JsonDetails(int id) { VehicleModel vehicle = Using<GetVehicleById>() .Execute(CurrentUserId, vehicleId: id); // we are limiting this to 3 reminders // after we retrieve the full set from the server var overdue = Using<GetOverdueRemindersForVehicle>() .Execute(id, DateTime.UtcNow, vehicle.Odometer ?? 0) .Take(3); var vm = ToJsonVehicleViewModel(vehicle, overdue); return Json(vm); } Note: Controller actions that return a JsonResult are easy to unit test because you can inspect the JsonResult.Data property directly. However, debugging a serialization issue with a JsonResult is harder because it requires you to inspect the returned data from the web service in the web client.
- 227. 194 chapter eleven Factoring Controller Actions for Ajax The same set of principles used to build controller actions in general still apply when those actions return JSON. If you decide to create a separate set of URLs for returning data (for example, if you create an independent data service API), you can create separate controllers and routes. This approach is beneficial when you expect multiple types of clients (for example, a web client and a Microsoft Silverlight® browser plug-in) to use the data actions, but only the web client to use the view-based actions. If your data actions are closely related to your view-based actions, you can put data actions in the same controller as the view-based actions. Mileage Stats is an example of this scenario because the data actions focus on the same domain models as the view- based actions. If your web client needs to use the same URL to request different data formats, you can extend your controller action methods by using the HttpRequestBase.IsAjax Request extension method to determine which to determine the format of the request and the data format to return. This is beneficial when you can reuse your view model as your JSON model. If you find that you have large if-else blocks in your controller actions, you should factor the view-based and JSON actions into different helper methods. Alter- natively, you can write a custom AjaxAttribute action filter that uses IsAjaxRequest. This action filter would provide overloaded action methods similar to those in HttpPost Attribute. When errors occur, your data actions can throw exceptions just like view-based ac- tions do. The jQuery library supports beforeSend, send, success, error, and complete handlers to handle server responses and failures. If you don’t want the friendly error page HTML content returned when a JSON data action throws an exception, you may need to apply a different HandleErrorAttribute value to your data actions. As you design your data actions, you should consider how many round trips to the server will be required for each interaction with the user. Every Ajax request requires separate threading on the client as well as resources for the connection, server response, data download, and client processing. If you create overly granular data actions, your web client may encounter performance issues because it must manage a large number of re- quests in order to satisfy a user action. If you create very large data actions, your web client and server may encounter performance issues because of both the creation and processing of large amounts of data. Note: You may find it helpful to use web browser debugging and tracing tools such as Windows Internet Explorer® F12 developer tools, Fiddler, and FireBug to see the relative cost of the different parts of each round trip to the server. Depending on the connection speed and distance between your users and your server, creating a connection can be much more costly than downloading the data once a connection is made. Many web applications that are used globally are designed to request larger chunks of data when that data cannot be cached closer to the user.
- 228. 195server-side implementation Data Validation Interactive web applications need to let users know when they have provided data that is invalid. Data validation checks need to happen in three places: on the client in the context of what the user is trying to accomplish, on the server to protect from untrust- worthy callers, and in the database to ensure data integrity. Having data validation occur at multiple levels in the stack makes creating common and consistent validation logic important to the user experience. This section covers data validation techniques you can use to validate your data on both the server and the client. Data Annotation Attributes Applying data annotation attributes to your model allows ASP.NET MVC and the ADO. NET Entity Framework to provide data validation at the server level. As mentioned in the “Creating a Data Model” section, the ADO.NET Entity Framework also inspects the data annotation attributes on your entity classes in order to create the database schema. You can find the standard data annotation attributes in the System.ComponentModel.Data Annotations namespace. In this section, data annotation attributes that provide valida- tion are referred to as validation attributes. The following example shows the validation attributes applied to the VehicleForm Model class in the MileageStats.Domain project. The attributes applied to the Vehicle FormModel.Name property validate that the name is not null, is not an empty string, is no more than 20 characters, and does not contain script injection characters. C# // Contained in VehicleModel.cs [StringLength(20, ErrorMessageResourceName = "VehicleNameStringLengthValidationError", ErrorMessageResourceType = typeof(Resources))] [TextLineInputValidator] [Required(AllowEmptyStrings = false, ErrorMessageResourceName = "VehicleNameRequired", ErrorMessageResourceType = typeof(Resources))] public string Name { get { return this.Vehicle.Name; } } Validation attributes also support localization. By using the resource names, the error messages are loaded from a RESX file. Validating Data in MVC The ASP.NET MVC default model binder uses the Validator and ValidationContext classes when parsing incoming data into an instance of your model class. These two classes work together to validate the data based on the validation attributes you have applied.
- 229. 196 chapter eleven If any of the validation fails, AddModelError is called on the ModelState class. ModelState.IsValid returns false when ModelState has one or more errors. Because all of this happens before your action is called, validating data in your controller actions is easy. The following example shows the FillupController using ModelState.IsValid before making the update. C# // Contained in FillupController.cs [HttpPost] [ValidateInput(false)] [ValidateAntiForgeryToken] public ActionResult Add(int vehicleId, FillupEntryFormModel model) { var vehicles = Using<GetVehicleListForUser>() .Execute(CurrentUserId ); if (ModelState.IsValid) { var errors = Using<CanAddFillup>() .Execute(CurrentUserId, vehicleId, model); ModelState.AddModelErrors(errors, "AddFillup"); if (ModelState.IsValid) { Using<AddFillupToVehicle>() .Execute(CurrentUserId, vehicleId, model); TempData["LastActionMessage"] = Resources .VehicleController_AddFillupSuccessMessage; return RedirectToAction("List", "Fillup", new { vehicleId = vehicleId }); } } ... var viewModel = new FillupAddViewModel { ... }; return View(viewModel); } In the previous example, invoking the handler CanAddFillup returns a Validation Result collection. These validation results are returned from the business services layer. The AddModelErrors extension method iterates over the ValidationResult collection and calls ModelState.AddModelError for each. This level of indirection keeps the business services layer from depending on ASP.NET MVC.
- 230. 197server-side implementation Note: The previous example turns off the ASP.NET-provided input validation of cookies, form data, and querystring properties by using the [ValidateInput(false)] attribute. This was done to allow certain characters that the default input validation does not allow. However, to prevent the user from using these characters to introduce malicious data into the system, the TextLineInputValidator data validation attribute is applied to the text properties of the FillupEntryFormModel class. It is recommended that you be very careful when disabling the default input validation and ensure that there are mitigations in place to stop malicious input. Creating Custom Validation Attributes When the standard validation attributes don’t provide what you need, you can write your own. All the standard validation attributes derive from the ValidationAttribute class that contains the abstract IsValid method. The following example validates a postal code. The implementation is much simpler than would be used in many applications, but it shows how a model object can validate one field based on the value of a different field. C# // Contained in PostalCodeValidatorAttribute.cs protected override ValidationResult IsValid(object value, ValidationContext context) { var userToValidate = context.ObjectInstance as User; var memberNames = new List<string>() { context.MemberName }; if (userToValidate != null) { if (string.IsNullOrEmpty(userToValidate.Country) && string.IsNullOrEmpty(userToValidate.PostalCode)) { return ValidationResult.Success; } if (string.IsNullOrEmpty(userToValidate.PostalCode)) { return ValidationResult.Success; } if (userToValidate.Country == Resources.UnitedStatesDisplayString) { if (USPostalCodeRegex.IsMatch(userToValidate.PostalCode)) { return ValidationResult.Success; } return new ValidationResult(Resources.USPostalCodeValidationErrorMessage, memberNames); } else
- 231. 198 chapter eleven { if (InternationalPostalCodeRegex.IsMatch(userToValidate.PostalCode)) { return ValidationResult.Success; } return new ValidationResult( Resources.InternationalPostalCodeValidationErrorMessage, memberNames); } } return ValidationResult.Success; } Handling Complex Data Validation You may have noticed in the earlier example that the FillupController.Add method calls ModelState.IsValid twice. The CanAddFillup handler in the following example contains validation logic that uses multiple objects in the domain model and requires additional database access. This validation logic is not suited for a single custom ValidationAttribute. It returns a collection of validation results that the controller uses to call ModelState. AddModelError. In cases like these you should factor complex validation logic into helper methods or a business services layer. C# // Contained in CanAddFillup.cs public virtual IEnumerable<ValidationResult> Execute(int userId, int vehicleId, ICreateFillupEntryCommand fillup) { var foundVehicle = _vehicleRepository.GetVehicle(userId, vehicleId); if (foundVehicle == null) { yield return new ValidationResult(Resources.VehicleNotFound); } else { var fillups = _fillupRepository.GetFillups(vehicleId); if (!fillups.Any()) yield break; var priorFillup = fillups .Where(f => f.Date < fillup.Date) .FirstOrDefault(); if ((priorFillup != null) && (priorFillup.Odometer >= fillup.Odometer))
- 232. 199server-side implementation { yield return new ValidationResult( "Odometer", string.Format(CultureInfo.CurrentUICulture, Resources.OdometerNotGreaterThanPrior, priorFillup.Odometer)); } } } Supporting Validation on the Client ASP.NET MVC supports client-side validation of data by sharing validation information from the server. This is done by implementing the IClientValidatable interface on your custom validation classes. IClientValidatable contains only the GetClientValidation Rules method that returns a ModelClientValidationRule collection. In the following example, the PostalCodeValidatorAttribute implements GetClient ValidationRules by returning a single ModelClientValidationRule. By setting the ValidationType property to “postalcode” the client will use the validation routine with the same name that is registered on the client. The validation parameters are added to provide the client-side code with the information it needs to implement the validation rule. C# // Contained in PostalCodeValidatorAttribute.cs public IEnumerable<ModelClientValidationRule> GetClientValidationRules( ModelMetadata metadata, ControllerContext context) { var rule = new ModelClientValidationRule() { ErrorMessage = Resources.InvalidInputCharacter, ValidationType = "postalcode" }; rule.ValidationParameters.Add("internationalerrormessage", Resources.InternationalPostalCodeValidationErrorMessage); rule.ValidationParameters.Add("unitedstateserrormessage", Resources.USPostalCodeValidationErrorMessage); rule.ValidationParameters.Add("internationalpattern", Resources.InternationalPostalCodeRegex); rule.ValidationParameters.Add("unitedstatespattern", Resources.USPostalCodeRegex); return new List<ModelClientValidationRule>() { rule }; }
- 233. 200 chapter eleven Note: In the previous example, you can see that the validation type and the names of the validation parameters are lowercase. These values are converted into HTML attributes and used by the client-side JavaScript code. Due to the limitations of this transformation, these values must contain only numbers, lowercase letters, and dashes. When MVC HTML helper extension methods such as TextBoxFor and EditorFor are called, MVC inspects the property definition for validation attributes. When a validation attribute implements IClientValidatable, MVC uses the client validation rules to include data-val attributes. The following HTML fragment shows the data-val attributes present on the postal code field in the registration form. HTML <!-- sent from server using Views/Shared/_ProfileForm.cshtml --> <div class="editor-field"> <input data-val="true" data-val-length="Postal code must be less than 10 characters." data-val-length-max="10" data-val-postalcode="Only alpha-numeric characters and [.,_-&#39;] are allowed." data-val-postalcode-internationalerrormessage= "Postal codes must be alphanumeric and ten characters or less." data-val-postalcode-internationalpattern="^[dw]{0,10}$" data-val-postalcode-unitedstateserrormessage= "United States postal codes must be five digit numbers." data-val-postalcode-unitedstatespattern="^[d]{5}$" data-val-textlineinput= "Only alpha-numeric characters and [.,_-&#39;] are allowed." data-val-textlineinput-pattern="^(?!.*--)[A-Za-z0-9.,'_ -]*$" id="PostalCode" maxlength="10" name="PostalCode" size="10" type="text" value="" /> <span class="field-validation-valid" data-valmsg-for="PostalCode" data-valmsg-replace="true"> </span> </div> The JavaScript that participates in MVC validation on the client side can be found in jquery.validate.js and jquery.validate.unobtrusive.js. These files include standard validation attributes, methods to register validation routines, and unobtrusive validation adapters. The following example shows the registration of the postalcode validation routine. Notice how it uses the params object to access the data-val attributes. JavaScript // Contained in mstats.validation.js $.validator.addMethod('postalcode', function (value, element, params) { if (!value) { return true; // not testing 'is required' here!
- 234. 201server-side implementation } try { var country = $('#Country').val(), postalCode = $('#PostalCode').val(), usMatch = postalCode.match(params.unitedStatesPattern), internationalMatch = postalCode.match(params.internationalPattern), message = '', match; if (country.toLowerCase() === 'united states') { message = params.unitedStatesErrorMessage; match = usMatch; } else { message = params.internationalErrorMessage; match = internationalMatch; } $.extend($.validator.messages, { postalcode: message }); return (match && (match.index === 0) && (match[0].length === postalCode.length)); } catch (e) { return false; } }); IClientValidatable helps you to share validation information, but you still have two copies of your validation logic to maintain. You may choose remote validators (that is, by implementing validation actions in your controller) and call them using Ajax from the client. However, the round trip to the server will not be as responsive as validating di- rectly on the client. Note: It is important to remember that client-side validation only helps improve the user experience and is not a substitute for proper validation and security on the server. Hackers won’t use your web client JavaScript or even the browser when maliciously posting data to the web application on the server, so you must ensure that any client- side validation is repeated on the server before any data changes occur. Unit Testing Validation Logic Because validation occurs at multiple levels of the stack, you may end up with duplicate validation attributes and validation logic to keep in sync. While proper factoring of your application logic, your models, and data validation information can help, you should always unit test each layer in isolation to make sure the validation works as expected.
- 235. 202 chapter eleven While you don’t need to unit test the standard validation attributes, you should test that the validation attributes are properly applied to your model and validate as expected (just as if you had written code inside the setter of your model property). The following example shows a unit test verifying that the Title of the Reminder is required. C# // Contained in ReminderFixture.cs [Fact] public void WhenTitleSetToNull_ThenValidationFails() { Reminder target = new Reminder(); target.Title = null; var validationContext = new ValidationContext(target, null, null); var validationResults = new List<ValidationResult>(); bool actual = Validator.TryValidateObject(target, validationContext, validationResults, true); Assert.False(actual); Assert.Equal(1, validationResults.Count); Assert.Equal(1, validationResults[0].MemberNames.Count()); Assert.Equal("Title", validationResults[0].MemberNames.First()); } Note: The true parameter at the end of the TryValidateObject call is important because it causes the validation of all properties on the target. This means your unit test must ensure all other properties are set to valid values when you verify that one invalid property fails validation. Other Considerations This section describes some other areas of server architecture you may want to consider. Dependency Injection Mileage Stats uses Unity for dependency injection. The unity.config file in the web ap- plication maps interfaces to concrete classes. It also determines the lifetime for each mapping. For example, Unity ensures that the VehicleController constructor receives implementations of the IUserServices, ICountryServices, IServiceLocator, and IChart DataService interfaces. In an effort to manage dependencies and improve testability in the MVC pattern, ASP. NET MVC also provides a dependency resolver. This gives ASP.NET MVC applications a designated place to resolve dependencies for framework-created objects such as control- lers and action filters. In the following example, Mileage Stats registers Unity as the MVC dependency resolver as part of initializing the dependency injection container for the application.
- 236. 203server-side implementation C# // Contained in global.asax.cs private static void InitializeDependencyInjectionContainer() { IUnityContainer container = new UnityContainerFactory() .CreateConfiguredContainer(); var serviceLocator = new UnityServiceLocator(container); ServiceLocator.SetLocatorProvider(() => serviceLocator); DependencyResolver.SetResolver(new UnityDependencyResolver(container)); } See the “Further Reading” section for more information on dependency injection and Unity. Unit Testing One of the main reasons ASP.NET MVC follows the MVC pattern is to allow for unit testing of the application logic. The System.Web.Abstractions assembly was introduced primarily to allow substitution of mocked instances of classes like HttpContextBase during unit testing. You should unit test as much of your application logic as possible; it will not only help ensure the quality of your application but will also help identify design issues early when they are less expensive to fix. Mileage Stats uses the xUnit.net unit test framework as well as Moq for mocking interfaces. The application is unit tested at the data model, business services, and control- ler layers. As mentioned in the “Composing Application Logic” section, keeping controller actions simple and factoring application logic into a business services layer makes unit testing much easier. In Mileage Stats, unit testing was much easier because interfaces like IUserServices could be mocked. For more information on unit testing see Chapter 13, “Unit Testing Web Applications.” Error Management Web clients expect proper HTTP status code responses when a web application cannot fulfill a request. This means you should avoid hiding errors like a resource not being found (404), failure to authorize (403), and internal server errors (500+). When an exception is thrown from a controller action, ASP.NET MVC will respond with the correct HTTP status code. There may be cases where you need to catch an exception from a call and throw a different exception type. Generally, users don’t want to see all the developer details for an exception, and showing more than is needed is not recommended from a security standpoint. ASP.NET MVC provides a HandleErrorAttribute that provides a friendly error page when an ex- ception occurs. The friendly page displayed is determined in the web.config customErrors section. Mileage Stats applies the HandleErrorAttribute to all controller actions in the RegisterGlobalFilters method in Global.asax.cs. Although friendly errors are an improvement, the user experience shouldn’t be inter- rupted with an HTTP error if the user enters an invalid value. Use the Post/Redirect/Get pattern (PRG) when handling a POST action. When the user submits invalid data, you
- 237. 204 chapter eleven should return the same view as the GET action populated with the incoming data. When a POST action succeeds, it can redirect. In the following example, if a ReminderFormModel doesn’t pass data validation, the Add view result is returned populated with the reminder data that was passed into the action method. C# //Contained in ReminderController.cs [HttpPost] public ActionResult Add(int vehicleId, ReminderFormModel reminder) { if ((reminder != null) && ModelState.IsValid) { var errors = Using<CanAddReminder>() .Execute(CurrentUserId, reminder); ModelState.AddModelErrors(errors, "Add"); if (ModelState.IsValid) { Using<AddReminderToVehicle>() .Execute(CurrentUserId, vehicleId, reminder); return RedirectToAction("Details", "Reminder", new { id = reminder.ReminderId }); } } var vehicles = Using<GetVehicleListForUser>() .Execute(CurrentUserId); var vehicle = vehicles.First(v => v.VehicleId == vehicleId); var reminders = Using<GetUnfulfilledRemindersForVehicle>() .Execute(CurrentUserId, vehicleId, vehicle.Odometer ?? 0) .Select(r => new ReminderSummaryModel(r, r.IsOverdue ?? false)); var viewModel = new ReminderAddViewModel { VehicleList = new VehicleListViewModel(vehicles, vehicleId) { IsCollapsed = true }, Reminder = reminder, Reminders = new SelectedItemList<ReminderSummaryModel>(reminders), }; return View(viewModel); }
- 238. 205server-side implementation Concurrency Because Mileage Stats tracks vehicles per user account, concurrency conflict detection and management was not a scenario for the application. Even though we chose not to implement it, the ADO.NET Entity Framework does support optimistic concurrency by adding time stamps to the data model and taking appropriate action when handling the DbUpdateConcurrencyException. Summary Hopefully you now have a frame of reference for architecting your server-side web ap- plication. There are many choices you will make to structure your site, factor code, and model data. Successful architectures provide the layers of abstraction required to solve the problem at hand while affording a way to accommodate future features and tech- nologies. The key points made in this chapter are: • Understand your web client needs and build a contract for the HTML structure, URL structure, and data formats between the client and server early in the process. • Decide whether or not to create a business services layer and whether or not to create separate domain and data models. • Create small controllers by placing the majority of your application logic in your domain models, a services layer, or helper classes and methods. • Keep application logic simple and partitioned. • Provide a data API that allows web clients to consume data asynchronously in the right format and with the right granularity for the application. • Structure your validation logic to support validation both on the client and on the server. Further Reading Evans, Eric. Domain-Driven Design: Tackling Complexity in the Heart of Software. Addison-Wesley Professional, 2003. Nilsson, Jimmy. Applying Domain-Driven Design and Patterns: With Examples in C# and .NET. Addison-Wesley Professional, 2006. ADO.NET Entity Framework on MSDN®: http://msdn.microsoft.com/library/bb399572.aspx The Repository Pattern on MSDN: http://msdn.microsoft.com/en-us/library/ff649690.aspx Unit of Work Pattern: http://www.martinfowler.com/eaaCatalog/unitOfWork.html Catalog of Patterns of Enterprise Application Architecture: http://martinfowler.com/eaaCatalog/
- 239. 206 chapter eleven Understanding Models, Views, and Controllers on ASP.NET: http://www.asp.net/mvc/tutorials/understanding-models-views-and-controllers-cs Best Practices for ASP.NET MVC: http://blogs.msdn.com/b/aspnetue/archive/2010/09/17/second_2d00_post.aspx Dependency Injection in MSDN Magazine: http://msdn.microsoft.com/en-us/magazine/cc163739.aspx Unity Application Block on MSDN: http://www.msdn.com/unity Post/Redirect/Get Pattern: http://en.wikipedia.org/wiki/Post/Redirect/Get For more information on how clients can consume and use data- attributes, see Chapter 6, “Client Data Management and Caching” and “Using Data- Attributes” in Chapter 7, “Manipulating Client-Side HTML.” For more information on unit testing see Chapter 13, “Unit Testing Web Applications.” To access web resources more easily, see the online version of the bibliography on MSDN: http://msdn.microsoft.com/en-us/library/hh404094.aspx.
- 240. 207 Introduction This chapter addresses security-related topics for the Mileage Stats Reference Implemen- tation (Mileage Stats) and is divided into three sections. The first section introduces se- curity threats relevant to Mileage Stats. The second section gives a guided tour of Mileage Stats security features that provide countermeasures against those threats. The third section describes possible security modifications to consider if you make changes to the deployment environment and to the security requirements for the application. After read- ing this chapter, you should understand how relevant security threats are mitigated in Mileage Stats and what some of its extensibility points are. In this chapter you will learn about: • Major security threats that you should address in any web application, including unauthorized access, malicious input, content injection, cross-site scripting, eaves- dropping, message tampering, message replay, and cross-site request forgery. • Security features in Mileage Stats that provide countermeasures against the rel- evant threats, including authentication, input validation, anti-forgery measures, and ways to prevent JavaScript Object Notation (JSON) hijacking. • Security modifications to accommodate changes in the deployment environment and to the security requirements for the application. This chapter will also cover some security features of ASP.NET and ASP.NET MVC, and OpenID. Security Threats The section describes some security threats that need to be addressed in any web applica- tion. If you’re already familiar with these security threats and how to mitigate them, skip to the “Mileage Stats Application Security” section where the security features for Mileage Stats are described. Security12
- 241. 208 chapter twelve Unauthorized Access To prevent the wrong people from entering your website and changing its data, you need to limit who can access it. This is typically accomplished by requiring users to authenti- cate. The most common form of authentication requires a user to provide his or her user name and password as credentials. Once verified, the user has access. If the credentials are not recognized by the website, the user does not have access. Malicious Input – Content Injection and Cross-Site Scripting There are a variety of ways to corrupt content by uploading malicious input to your website. Such attacks can not only corrupt the data but can even make your website unusable. If links can be uploaded to a website, malicious users can potentially execute a cross-site scripting (XSS) attack, enabling them to collect potentially sensitive form data and security information. A common way to prevent the uploading of malicious input to a website is to limit the length and type of input that users are allowed to provide. Remov- ing the ability to submit tags by filtering out tag characters (“<” and “>”) goes a long way towards preventing malicious users from submitting scripts or HTML tags. As a rule of thumb, acceptable input to the website should be as limited as possible based on ex- pected length, content, and data type for a particular data field. Eavesdropping, Message Tampering, and Message Replay Eavesdropping, message tampering, and message replay are grouped together because they are often detected and mitigated by similar measures. A common and relatively simple way to exploit a web application through eavesdropping is to use a network data capture utility to find and record HTTP requests and responses between a website and a client. Without protection from eavesdropping and tampering, an attacker can alter the contents of a captured HTTP request and re-submit it to the website. This type of attack is commonly referred to as a message replay attack. Even if the website requires authen- tication, it processes the request as if it came from the client because it contains a legiti- mate security token. HTTP requests can be altered to cause the website to behave unde- sirably, to delete data, to change data, or to cause large numbers of transactions to be executed. A common way to mitigate message replay in web applications using HTTP is by requiring communication via Secure Sockets Layer (SSL). When you use SSL in a non- anonymous mode, you prevent the ability to replay messages back to the server. Two additional and very important benefits of using SSL are that it prevents any sensitive content in the HTTP traffic from being disclosed to eavesdroppers and prevents message tampering. Cross-Site Request Forgery Cross-site request forgery (CSRF, often pronounced as “sea surf”,) occurs when malicious commands are sent to a website from the browser of a trusted user. An attacker con- structs a seemingly harmless HTML element on a different website that surreptitiously calls the target website and attempts to do something malicious while posing as a trusted user. CSRF has great potential to damage the website being exploited; an attacker can potentially tamper with or delete data, or execute large numbers of unwanted transac- tions on the targeted website.
- 242. 209security This section is an introductory overview and not a substitute for more comprehensive guidance or a threat model. For more information on ASP.NET security, see the ASP.NET Web Application Security reference at the end of this chapter. Web Platform Security This section describes some of the out-of-the-box security features that are built into the various components of the web application platform. MVC View Encoding The Razor syntax uses the @ operator in Model-View-Controller (MVC) views to specify Microsoft® .NET Framework code. Any output written to the client in the view from code that uses the @ operator is automatically HTML encoded for you. This traps mali- cious content by preventing it from being rendered back to the client. Trapping malicious content goes hand-in-hand with input filtering, because you should never assume that any data that comes from users or other applications is safe. ASP.NET Input Filtering Starting with version 1.1, ASP.NET has provided input filtering out of the box as a secure default. Any attempt to submit a request containing bracketed tags (“<” or “>”) in any of its form data, query string parameters, or cookies results in an error page indicating that malicious input has been detected. The following figure is a screenshot of the default ASP. NET input validation failure page. Input validation failure
- 243. 210 chapter twelve While the default ASP.NET input filtering is good, it is very basic. You should still validate user input in your application. Protecting Application-Specific Data Sometimes applications host their own data sources instead of accessing them from a centrally hosted location. Whenever you create an application-specific data source, it should be hosted in the App_Data subdirectory. For example, if you add a SQL member- ship provider for a specific application, the Microsoft SQL Server® Express .mdf file should be created in the App_Data directory. ASP.NET protects application-specific data in a few ways. Files stored in the App_Data folder cannot be accessed directly by clients because, by default, the folder is protected from browsing. An additional layer of protection for application-specific data files is configured using HTTP handlers in the machine’s web.config file. Requests for certain file types are routed to the ASP.NET HttpForbiddenHandler by default. The following code shows the con- figuration to handle HTTP requests for .mdf and .mdb files that are used by SQL Server Express and Microsoft Access®, respectively, via the HttpForbiddenHandler in the ma- chine’s web.config file: XML <!-- Contained in machine's default web.config --> <add path="*.mdf" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" /> <add path="*.ldf" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" /> Note that the HTTP handlers defined above are for standard ASP.NET applications. Handlers for an ASP.NET MVC application are defined via route mappings in the applica- tion’s Global.asax.cs file. All .mdf and .mdb files are normally inaccessible when using ASP. NET MVC unless you explicitly create a route mapping for them; you can also configure ASP.NET MVC to ignore routing for the file types and let ASP.NET handle the file types using the settings described above. Neither approach is recommended for ASP.NET MVC applications because the files should be protected from client browsing by routing all requests to the MVC controllers. For more information on MVC routing best practices, see the reference on “Best Practices for ASP.NET MVC” on the ASP.NET and Web Tools Developer Content Team’s blog at the end of this chapter. Mileage Stats Application Security This section explains security measures implemented in Mileage Stats that mitigate secu- rity threats against it. Authentication Mileage Stats implements authentication using a third-party authentication provider (OpenID) and ASP.NET forms authentication tickets to prevent unauthorized access. Whenever an unauthenticated user attempts to access the site, he or she is redirected to the login URL via ASP.NET forms authentication. The following diagram depicts the logical flow for user authentication in Mileage Stats.
- 244. 211security Third-party user authentication 1. The user attempts to access the site without authenticating first and is redi- rected to the Mileage Stats home page. 2. The user navigates from the Mileage Stats home page to the OpenID sign-in page to authenticate. 3. An authentication result is attached to the response by OpenID and picked up by Mileage Stats for processing. 4. Mileage Stats converts a successful authentication result from OpenID to an encrypted ASP.NET forms authentication ticket and caches it client-side as a session cookie in the web browser. 5. The user accesses the site successfully with a valid forms ticket. Whenever a request is processed with a valid authentication ticket, the expiration time of the ticket is reset to provide a sliding expiration window. The significance of this authentication model is that a third party (OpenID) is respon- sible for managing and validating the user’s credentials as opposed to more commonly
- 245. 212 chapter twelve encountered authentication models in which the owner of the website is the same party that maintains and validates the user’s credentials. While out-of-the box ASP.NET forms authentication is not being used, encrypted forms authentication tickets and forms ticket validation are being leveraged program- matically. Forms ticketing is an effective mechanism that you can leverage to work with OpenID authentication instead of creating a security ticketing mechanism from the ground up. There are several configuration settings and segments of code responsible for imple- menting authentication end-to-end in Mileage Stats. Let’s take a look at how configura- tion works, and at the major components that make up the authentication mechanism. Configuration While the forms tickets are generated manually in Mileage Stats, the code still leverages the configuration settings used for configuring out-of-the-box forms authentication. The following configuration snippet in the Mileage Stats web.config file is responsible for configuring the application for forms authentication and setting the login redirect URL. XML <!-- Contained in web.config --> <authentication mode="Forms"> <forms loginUrl="~/Auth/SignIn" timeout="20" /> </authentication> The relying party class validates a user’s credentials with an authentication provider, then uses them to create a forms authentication ticket. The relying party implementation is configured in the unity.config file. XML <!-- Contained in unity.config --> <!-- NOTE: This is a real openId authentication mechanism --> <type type="MileageStats.Web.Authentication.IOpenIdRelyingParty, MileageStats.Web" mapTo="MileageStats.Web.Authentication.DefaultOpenIdRelyingParty, MileageStats.Web"> <lifetime type="perRequest" /> </type> There are two unity.config files available, and the one used by Mileage Stats depends on which solution configuration is selected when you compile the application. The one shown above is used with the Release solution configuration. When Debug is selected, a different unity.config file is used that contains a mock authentication relying party class that can be used to get the application up and running. The mock authenticator will put the user through a mock authentication workflow that does not validate any credentials. To deploy the application, we strongly recommend that you compile the application using the Release solution configuration in order to use the actual relying party class that does validate the user credentials.
- 246. 213security Both the mock authenticator and the OpenID relying party class implement the IOpenIdRelyingParty interface, which acts as a wrapper around the DotNetOpenAuth interfaces to expose only what is required to interact with the authentication provider and to process the results. Implementing IOpenIdRelyingParty enables you to configure a different relying party implementation if your application requirements change. AuthController AuthController is an MVC controller in Mileage Stats that is responsible for handling the user redirect for authentication and converting the response from a successful authenti- cation attempt into an ASP.NET forms authentication ticket. The AuthController uses the relying party implementation specified in the unity.config file. AuthController’s Sign InWithProvider method is invoked to redirect the user to the authentication provider’s sign-in page. The following code snippet shows the SignInWithProvider method. C# // Contained in AuthController.cs public ActionResult SignInWithProvider(string providerUrl) { if (string.IsNullOrEmpty(providerUrl)) { return this.RedirectToAction("SignIn"); } var fetch = new FetchRequest(); var returnUrl = this.Url.Action("SignInResponse", "Auth", null, this.Request.Url.Scheme); try { return this.relyingParty.RedirectToProvider(providerUrl, returnUrl, fetch); } catch (Exception) { this.TempData["Message"] = Resources.AuthController_SignIn_UnableToAuthenticateWithProvider; return this.RedirectToAction("SignIn"); } } The AuthController’s SignInResponse method is invoked to process the response from the user’s authentication attempt with the authentication provider. SignInResponse calls the GetResponse method on the relying party class and processes the result. If the result is a successful authentication, AuthController creates an ASP.NET forms authen- tication ticket and attaches it to the response. If anything other than a successful authen- tication result is returned from the authentication provider, the user is redirected back to the authentication provider’s sign-in page.
- 247. 214 chapter twelve C# // Contained in AuthController.cs public ActionResult SignInResponse(string returnUrl) { var response = this.relyingParty.GetResponse(); switch (response.Status) { case AuthenticationStatus.Authenticated: var user = this.userServices.GetOrCreateUser(response.ClaimedIdentifier); this.formsAuthentication.SetAuthCookie(this.HttpContext, UserAuthenticationTicketBuilder.CreateAuthenticationTicket(user)); return this.RedirectToRoute("Dashboard"); case AuthenticationStatus.Canceled: this.TempData["Message"] = "Cancelled Authentication"; return this.RedirectToAction("SignIn"); case AuthenticationStatus.Failed: this.TempData["Message"] = response.Exception.Message; return this.RedirectToAction("SignIn"); default: this.TempData["Message"] = Resources.AuthController_SignInResponse_Unable_to_authenticate; return this.RedirectToAction("SignIn"); } } The following sequence diagram shows the calls made in AuthController.SignIn Response to authenticate the user with the relying party and to attach the encrypted forms ticket as a cookie if the authentication attempt was successful.
- 248. 215security Authentication sequence diagram 1. AuthController calls the GetResponse method of its referenced IOpenId RelyingParty implementation to get the authentication result from the authentication provider. 2. AuthController calls the GetOrCreateUser method of its referenced IUserServices implementation. 3. AuthController calls the SetAuthCookie method of its referenced IFormsAuthentication implementation. 4. AuthController invokes its own RedirectToRoute method and sends the user to its landing page after a successful authentication. Let’s take a closer look at the relying party implementation used in Mileage Stats. DefaultOpenIdRelyingParty DefaultOpenIdRelyingParty implements IOpenIdRelyingParty, which is a façade for the OpenIdRelyingParty class provided as part of DotNetOpenAuth that validates the user’s credentials with OpenID. The following code snippet shows the Redirect ToProvider method on the DefaultOpenIdRelyingParty class, which is responsible for redirecting the user to the authentication provider’s login page. C# // Contained in DefaultOpenIdRelyingParty.cs public ActionResult RedirectToProvider(string providerUrl, string returnUrl, FetchRequest fetch) { IAuthenticationRequest authenticationRequest = this.relyingParty.CreateRequest(providerUrl, Realm.AutoDetect,
- 249. 216 chapter twelve new Uri(returnUrl)); authenticationRequest.AddExtension(fetch); return new OutgoingRequestActionResult(authenticationRequest.RedirectingResponse); } Forms Authentication Sliding Expiration Sliding expiration of the forms authentication ticket in Mileage Stats is accomplished by resetting the expiration time of the ticket whenever the user makes a new request to the server. Normally, the reset is enabled by setting the slidingExpiration attribute to true on the forms security configuration in the web.config file; however, because the ticket is being manually created and attached to the response in the AuthController, the ticket needs to be refreshed manually. A custom handler for the HttpApplication.Post AuthenticateRequest event implements the sliding expiration for the forms ticket. C# // Contained in Global.asax.cs private void PostAuthenticateRequestHandler(object sender, EventArgs e) { HttpCookie authCookie = this.Context.Request.Cookies[FormsAuthentication.FormsCookieName]; if (IsValidAuthCookie(authCookie)) { var formsAuthentication = ServiceLocator.Current.GetInstance<IFormsAuthentication>(); var ticket = formsAuthentication.Decrypt(authCookie.Value); var mileageStatsIdentity = new MileageStatsIdentity(ticket); this.Context.User = new GenericPrincipal(mileageStatsIdentity, null); // Reset cookie for a sliding expiration. formsAuthentication.SetAuthCookie(this.Context, ticket); } } The advantage of using a forms ticket with a sliding expiration is that it does not force the user to authenticate again if he or she maintains a reasonable level of activity in the application. Otherwise, the user would be redirected to the authentication page after a fixed amount of time had elapsed after the original authentication. While sliding expira- tion greatly enhances the usability of the application, it is also a potential security risk because the user’s authenticated session can be kept alive indefinitely by submitting re- quests to the server before the sliding expiration time on the forms ticket has passed. This risk can be mitigated by introducing an additional timeout value that does not slide, after which the ticket will expire regardless of user activity. While this approach is effective, it
- 250. 217security was not implemented in Mileage Stats because it would add complexity to the forms ticket handling that is beyond the scope of the application. Input Validation One of the primary ways of preventing an application from accepting malicious content is validating any input before it is accepted by the application. While out-of-the-box ASP. NET input validation does a good job of preventing script or HTML injection, it is not always practical to use this mechanism in an ASP.NET MVC application. In Mileage Stats, this mechanism is disabled to handle input validation directly within the MVC model classes. If you don’t implement your own input validation and rely on the built-in ASP.NET input validation instead, two things will happen. First, the input will not be validated until after the controller has processed it and before the view has rendered. Next, you will get the default “yellow screen of death” input validation page, which is not a pleasant user experience. When the out-of-the box ASP.NET input validation is disabled, you also lose HTML encoding on your input. To account for this, the @ operator in Razor syntax auto- matically HTML-encodes output that is rendered in an MVC view. Although input validation can be done on the client side to reduce round trips to the server, it must also be performed on the server because client-side validation can be by- passed by an attacker. One of the advantages of ASP.NET MVC is that it can be configured to render client-side validation based on server-side validation attributes defined on MVC model properties. This provides a single point in the application to define and maintain data validation rules. For example, in Mileage Stats, the _ProfileForm view is configured to use the MileageStats.ServicesModel.User class as its MVC model via the @model directive. If you look at the DisplayName property on the class, you will see attributes that limit the length of the value, that require a value for the property, and that use a custom text input validator that filters input using a regular expression. C# // Contained in User.cs [StringLength(15, ErrorMessageResourceName = "UserDisplayNameStringLengthValidationError", ErrorMessageResourceType = typeof(Resources))] [TextLineInputValidator] [Required(AllowEmptyStrings = false, ErrorMessageResourceName = "UserDisplayNameRequired", ErrorMessageResourceType = typeof(Resources))] [Display(Name = "UserDisplayNameLabelText", ResourceType = typeof(Resources))] public string DisplayName { get; set; } Here is the custom input validator class that is behind the TextLineInputValidator attribute. C# //Contained in TextLineValidatorAttribute.cs public class TextLineInputValidatorAttribute : RegularExpressionAttribute, IClientValidatable
- 251. 218 chapter twelve { public TextLineInputValidatorAttribute() : base(Resources.TextLineInputValidatorRegEx) { this.ErrorMessage = Resources.InvalidInputCharacter; } public IEnumerable<ModelClientValidationRule> GetClientValidationRules(ModelMetadata metadata, ControllerContext context) { var rule = new ModelClientValidationRule() { ErrorMessage = Resources.InvalidInputCharacter, ValidationType = "textlineinput" }; rule.ValidationParameters.Add("pattern", Resources.TextLineInputValidatorRegEx); return new List<ModelClientValidationRule>() { rule }; } } The TextLineInputValidatorAttribute class uses a set of regular expressions it loads from the resources file. If any of the regular expression patterns are matched in the input, it fails validation. The regular expression pattern used to validate text input is ^(?!.*--) [A-Za-z0-9.,’_ -]*$. This limits the text assigned to the property to alphanumeric char- acters and allows only a limited range of punctuation characters. Notice that the regular expression pattern is used to validate legitimate characters rather than to exclude invalid characters. By default, anything not explicitly defined in the regular expression is ex- cluded from the application data. The list that limits input by only allowing what is known to be valid is commonly referred to as a safe list. The advantage of safe lists is that anything that falls outside of the valid set of characters is not allowed; you don’t have to worry about accidentally omitting a character from the regular expression that shouldn’t be allowed in the application input. What’s nice about this validation mechanism is that the client-side validation for these properties is generated for you based on the server-side validation defined in the MVC model when the HTML for the MVC view is rendered. The following code shows you what the rendered client-side validation looks like for the user display name form field when you view the HTML source for the page. HTML <!-- Rendered HTML in the client browser --> <input data-val="true" data-val-length="Display name must be less than 15 characters." data-val-length-max="15" data-val-required="Display name is required." data-val-textlineinput="Only alpha-numeric characters and [.,_-&#39;] are allowed."
- 252. 219security data-val-textlineinput-pattern="^(?!.*--)[A-Za-z0-9.,'_ -]*$" id="DisplayName" maxlength="15" name="DisplayName" type="text" value="Sample User" /> Note: If you want to accept HTML tags or other types of input that would normally be rejected by simple input validation, you can leverage the regular expression/input validation mechanism to do it. However, you will need to create more sophisticated patterns to allow the input you want to be accepted while still excluding the input that you don’t want submitted to your application. Anti-Forgery As previously explained in the “Security Threats” section, CSRF has a high damage poten- tial and should be prevented. ASP.NET MVC has a simple yet effective mechanism for mitigating CSRF attacks. In your MVC view content, add an @Html.AntiForgeryToken directive to the view, as shown here. CSHTML <!-- Contained in _ProfileForm.cshtml --> @model MileageStats.ServicesModel.User @Html.AntiForgeryToken() When the view HTML is rendered to the client, MVC places a unique value for the user in a hidden form field and in a session cookie. The form field in the rendered HTML might look like this. HTML <!-- Rendered HTML in the client browser --> <input name="__RequestVerificationToken" type="hidden" value="H4zpQFvPdmEdGCLsFgeByj0xg+BODBjIMvtSl5anoNaOfX4V69Pt1OvnjIbZuYrpgzWxWHIjbn zFOLxP5SzVR4cM9XZeV78IPi8K4ewkM3k2oFkplrXL4uoAqy+aoSOg8s1m1qxrE7oeBBtvezEHCAs6nKE h2jAwn3w0MwmhkcDQiJfJK7hGvN0jXA4d7S8x7rbLxp4Y8IJZS9wka2eOLg==" /> There’s another piece to implementing the anti-forgery tokens in ASP.NET MVC. You must also put a ValidateAntiForgeryToken attribute on corresponding MVC controller actions that you want to protect. The following code is an example of the attribute decorating the edit action on the ProfileController class. C# // Contained in ProfileController.cs [HttpPost] [ValidateInput(false)] [ValidateAntiForgeryToken] public ActionResult Edit(User updatedUser)
- 253. 220 chapter twelve When ASP.NET MVC checks for a request forgery, it verifies that the request verifica- tion token form field and cookies are present and that the values match each other. If either the cookie or the form field values are missing, or the values don’t match, ASP.NET MVC does not process the action and returns an authorization failure instead. Note: MVC anti-forgery tokens do not work using HTTP GET requests because the _RequestVerificationToken value from the client needs to be sent as a posted value. Therefore, it is important to make sure that you only accept client requests that use HTTP POST when you want to implement anti-forgery tokens. This shouldn’t be an issue because you should already be using HTTP POST only for data updates, and using HTTP GET exclusively for read-only operations. If you want to implement more tightly controlled anti-forgery measures so that the tokens will only validate to a particular set of MVC views and actions, you can pass a salt as a parameter to the @Html.AntiForgeryToken directive in the MVC model. A salt is a value combined with a cryptographic key to make the output of an encryp- tion algorithm more random and less susceptible to attack. Make sure that you are using the same salt values in the @Html.AntiForgeryToken directive in the MVC model and in the parameter for the ValidateAntiForgeryToken attribute on the MVC controller action; otherwise, the anti-forgery token will not validate properly when the MVC action is called. For more information about using a salt with an MVC anti-forgery token, see the reference to “Prevent Cross-Site Request Forgery (CSRF) using ASP.NET MVC’s AntiForgeryToken() helper” at the end of the chapter. JSON Hijacking Prevention In some situations, it may be possible for an attacker to access data via a JSON request by using an attack that closely resembles a CSRF attack. If an attacker can get a user to click on a malicious link that makes a JSON request via HTTP GET and returns a JSON array, it may dump the contents of the array in the response, making it accessible to the attacker. The mitigation for JSON hijacking is fairly straightforward: either you can make sure to never return JSON arrays in a response, or you can restrict JSON requests to respond only to requests that use the HTTP POST action. To configure a JSON action on an MVC controller to respond to requests only via HTTP POST, add the HttpPost attribute to it. The following code shows the HttpPost attribute on the ProfileController’s JsonEdit action. C# // Contained in ProfileController.cs [HttpPost] [ValidateInput(false)] public ActionResult JsonEdit(User updatedUser) This may not be an issue if you don’t care whether or not someone can gain unauthor- ized access to data that is not sensitive; however, as a general practice you should protect your JSON calls against hijacking. For more information, see the reference to JSON Hijacking in the “Further Reading” section at the end of the chapter.
- 254. 221security Additional Security Considerations This section describes other security issues to consider when deploying and configuring Mileage Stats. Securing communication between the client and the server is critical for protecting the data that goes back and forth between them. You may also want to use a different method of authenticating users for the application, whether that means using a different relying party for the existing authentication mechanism or switching to an ASP. NET membership provider. If you expand the functionality of your application, you may want to restrict different levels of functionality to a limited subset of application users. In some cases, you may want to deploy the data tier to SQL Server or SQL Server Express instead of running it on SQL Server Compact Edition. Securing Communication between Client and Server When properly configured, Secure Sockets Layer (SSL) is an effective way to prevent eavesdropping, session hijacking, message replay and tampering between the client and the server. Mileage Stats does not use SSL out of the box because the use of SSL depends on your infrastructure and not on the application itself. There’s already a lot of documen- tation on how to set up SSL on your server, so the specifics won’t be covered here. For more information, see the reference on “How to Set Up SSL on IIS 7” in the “Further Reading” section at the end of this chapter. Make sure that when you configure SSL on your server that you do not configure anonymous SSL. Otherwise, communication be- tween the client and server will still be susceptible to several different attacks. Warning: When communicating with the server via SSL, a client verifies the identity of the server with which it is communicating by checking the host name provided in the SSL certificate against the URL of the server. Sometimes the client does not have a certificate that can be used to identify the server, and sometimes the server is config- ured to use SSL protocols that do not incorporate identification of the server; these are examples of anonymous SSL. Anonymous SSL can be configured intentionally on some web servers but not on others. It can be “ forced” intentionally by breaking the mecha- nisms inherent to SSL that tie a host to the identity specified in an SSL certificate. While this provides protection against tampering and eavesdropping, it does not protect against message replay or spoofing attacks, where one party can pose as someone else during the communication. Once SSL has been set up in your environment, there are two changes to the web. config file that you’ll need to make in Mileage Stats. The first change is to require that ASP.NET forms authentication use SSL. To do this, the requireSSL attribute needs to be added to the forms element. XML <!-- Contained in web.config --> <authentication mode="Forms"> <forms loginUrl="~/Auth/SignIn" timeout="20" requireSSL="true"/> </authentication>
- 255. 222 chapter twelve The default timeout for a forms authentication ticket is 20 minutes. However, you can adjust this value to a reasonable time that preserves the usability of the sliding expira- tion but minimizes the security risk of indefinitely authenticated users. The second change is for OpenID to require an SSL-encrypted communication with the relying party. XML <!-- Contained in web.config --> <openid> <relyingParty> <security requireSsl="true" /> The value of requireSsl needs to be set to true. That way you can ensure that the authentication provider will only attempt to communicate with your application via HTTPS. Any use of the UrlHelper.Action method that specifies a protocol (such as HTTP) in your application for constructing URLs will need to be updated to HTTPS for any URL references that are now secured via SSL. For more information on the UrlHelper.Action method, see the reference on the UrlHelper.Action method at the end of the chapter. Protecting Connection Strings If you change data sources for the application, you will likely end up changing the connec- tion string in the web.config file. As a good practice, you should protect these connection strings from discovery. For more information on protecting connection strings, see the reference on Protecting Connection Information (ADO.NET) at the end of the chapter. Deploying to a Shared Environment In situations where you are deploying your web application to a server that is being shared by multiple parties, you may want to protect your application from the other applications that are hosted on the server. In addition to protecting sensitive information in the web. config file, ensure that the application pools on the server are configured to run per web application and that the temporary ASP.NET files cached on the server are in a location that is not shared with the other web applications on the server. For more information, see “How To: Secure an ASP.NET Application on a Shared Server” on MSDN®. Summary This chapter provided an overview of security threats that impact Mileage Stats. These include: unauthorized access, malicious input (content injection and cross-site scripting), eavesdropping, message tampering, message replay, and cross-site request forgery. The chapter also described how these threats are mitigated through various security features. Finally, a few ideas were suggested for extending or changing security for Mileage Stats to accommodate different deployment environments and security requirements.
- 256. 223security Further Reading “ASP.NET Web Application Security” on MSDN: http://msdn.microsoft.com/en-us/library/330a99hc.aspx “How to set up SSL on IIS 7”: http://learn.iis.net/page.aspx/144/how-to-set-up-ssl-on-iis-7/ “UrlHelper.Action Method” on MSDN: http://msdn.microsoft.com/en-us/library/dd505232.aspx “Understanding the Forms Authentication Ticket and Cookie” on Microsoft Support: http://support.microsoft.com/kb/910443 “Authenticating Users with Forms Authentication” on ASP.NET: http://www.asp.net/mvc/tutorials/authenticating-users-with-forms-authentication-cs Protecting Connection Information (ADO.NET) on MSDN: http://msdn.microsoft.com/en-us/library/89211k9b(v=VS.100).aspx “How To: Secure an ASP.NET Application on a Shared Server” on MSDN: http://msdn.microsoft.com/en-us/library/ms228096.aspx “A Guide to Claims–based Identity and Access Control” on MSDN: http://msdn.microsoft.com/en-us/library/ff423674.aspx “OWASP Top 10 Project” on OWASP.org: https://www.owasp.org/index.php/Category:OWASP_Top_Ten_Project “JSON Hijacking” on Phil Haack’s blog: http://haacked.com/archive/2009/06/25/json-hijacking.aspx “Best Practices for ASP.NET MVC” on the ASP.NET and Web Tools Developer Content Team’s blog: http://blogs.msdn.com/b/aspnetue/archive/2010/09/17/second_2d00_ post.aspx “Prevent Cross-Site Request Forgery (CSRF) using ASP.NET MVC’s AntiForgeryToken() helper” on Steve Sanderson’s blog: http://blog.stevensanderson.com/2008/09/01/prevent-cross-site-request-forgery-csrf- using-aspnet-mvcs-antiforgerytoken-helper/ “Hack Proofing Your Microsoft ASP.NET Web Forms and MVC Applications” by Adam Tuliper on Channel 9: http://channel9.msdn.com/Events/TechEd/NorthAmerica/2011/ DEV333 To access web resources more easily, see the online version of the bibliography on MSDN: http://msdn.microsoft.com/en-us/library/hh404094.aspx.
- 258. 225 Introduction Unit testing, sometimes referred to as developer testing, focuses on testing small pieces of code, such as a class, that a developer is writing. These tests are critical for helping you ensure that the pieces you build work as expected and will operate correctly when com- bined with other parts of the application. Such testing helps support management of the application over time by ensuring that changes you make don’t inadvertently affect other parts of the system. This chapter shows you how to get started unit testing JavaScript as well as server- side code, but does not cover all aspects of unit testing. References to more detailed discussions about unit testing can be found at the end of this chapter. While the unit tests for the Mileage Stats application were written using Test-First Development (or Test-Driven Development), this chapter will only cover the test-oriented aspects of unit testing, not the design aspects. This chapter does not cover other important aspects of testing, such as performance, stress, security, automation, deployment, localization, and globalization. Nor does it dis- cuss other important aspects to consider when testing the client side, such as cross- browser compatibility or usability. However, these areas are important for you to con- sider when testing your web application. In this chapter you will learn: • How to get started unit testing your JavaScript and ASP.NET MVC code. • The arrange-act-assert unit test structure. • Techniques to isolate your tests and components. • Things you should consider when testing your jQuery UI widgets. The technologies discussed in this chapter are QUnit, used to test your JavaScript and jQuery client-side code, and xUnit.net and Moq, for testing your server-side, ASP.NET MVC code. Unit Testing Web Applications13
- 259. 226 chapter thirteen JavaScript Unit Testing Unit testing, functional testing, and performance testing of the client-side portion of a web application present different challenges than server-side testing presents. In addition to testing the structural layout of a page and basic application functionality, you may want to verify that animations execute properly, that a page with a large amount of Java Script has no memory leaks, and that the application maintains its functional and perfor- mance expectations across multiple browsers. As a web application developer, you will use JavaScript for the user interface (UI) logic in your application to dynamically build the structure, to enable or disable portions of your UI, or to load data in the background. Some of this functionality may rely on libraries you adopt, such as jQuery. You’ll want to be sure that each piece operates as you expect so that the application as a whole works as planned. Unit testing allows you to verify that individual pieces work as you expect and pro- vides a way for you to verify that they continue to work as libraries or tools evolve. For example, you may build a jQuery UI widget to manage a piece of your UI. When the next version of jQuery is released, you can quickly and easily verify that your widget is still working by executing the unit tests using the new jQuery libraries. While unit testing isn’t difficult, the learning curve can be somewhat steep for those unfamiliar with it. One common objection to adopting unit testing is the perception that it takes extra time to write unit tests. While it is true that it will take longer to build something with unit tests than without (after all, you need to write the unit tests), what is often not considered is the time you will save later in tracking down bugs or verifying that things still work after changing the code or upgrading to a new version of a library. For the uninitiated, it can also be difficult to determine what should be tested or how to approach testing for a particular behavior. Unit testing can be a complicated topic. This section seeks to provide you with the basics to get started. It will give you an idea of what to test and provide some approaches to solving common challenges in unit testing Java Script in your application. Getting Started with Unit Testing The Project Silk team decided to use the QUnit unit testing framework to help with unit testing their JavaScript components, which rely heavily on jQuery and the jQuery UI widget framework, which also use QUnit. The QUnit unit testing framework can be found on the jQuery website at http://docs.jquery.com/QUnit. The site provides examples, documentation, and links to the download. To set up QUnit, you will typically create an HTML page containing specific QUnit elements with certain class attributes specified, and add and reference the qunit.js and qunit.css files. In Mileage Stats, these were added to the tests folder under the Scripts folder.
- 260. 227unit testing web applications QUnit files in project Once this structure is in place, you will create a test JavaScript file for each set of tests you want to run. A set is typically focused on a specific JavaScript object. For ex- ample, in Mileage Stats there is a JavaScript test file for each of the jQuery UI widgets that the application implements. Each of these JavaScript test files and the JavaScript file of the item being tested are referenced from the test.htm file so the QUnit framework can locate and execute the tests. HTML <!-- Contained in test.htm --> <!-- Code under test --> <script src="../Debug/mstats.utils.js"></script> <script src="../Debug/mstats.events.js"></script> <script src="../Debug/mstats.pubsub.js"></script> ... <!-- Unit tests --> <script src="mstats.utils.tests.js"></script> <script src="mstats.pubsub.tests.js"></script> <script src="mstats.data.tests.js"></script> ... These unit tests can be run by viewing the test HTML file in a browser. From the Microsoft® Visual Studio® development system, you can right-click the test HTML file and select View in Browser. For Mileage Stats, the output would look like this while executing the tests.
- 261. 228 chapter thirteen QUnit test run output Creating Unit Tests There are typically multiple unit tests in one file and they are often grouped around a particular topic or type of test. In QUnit, the module function is used to denote a group of tests. JavaScript module('Test Group'); test('Test one', function () { // Test logic goes here }); test('Test two', function () { // Test logic goes here }); Let’s look at the structure of a typical test. This is a test from mstats.data.test.js to test a data caching component within the solution. JavaScript // Contained in mstats.data.test.js test('When data is saved, then it can be retrieved', function () { expect(1); // Arrange
- 262. 229unit testing web applications var value = 'some-data'; // Act mstats.dataStore.set(' /some/url', value); // Assert equal( mstats.dataStore.get(' /some/url'), value, 'mstats.datastore saved and returned ' + value); }); The test, expect, and equal methods are specific to QUnit. Most unit tests follow an arrange-act-assert pattern, a common test pattern em- ployed when unit testing. Its purpose is to make a clear distinction between the set up for the test, the action that is to be tested, and the evaluation of the results. In most unit tests, arrange, act, and assert occur in that order. In the above code example, the “act” step ensures the value can be set in the store and the “assert” verifies that the value was appropriately set. The QUnit framework pro- vides a number of functions to help with assertions. The equal assertion is shown in the example, but ok (which performs a Boolean check) is also frequently used. Notice that we execute a single assertion in this test. In general, keep the number of assertions low (preferably to a single assertion) for smaller, more focused unit tests. Writ- ing unit tests in this manner encourages you to write code that is also small and focused. This tends to lead to code that is more composable because each piece of code has a single responsibility. Each unit test should generally take one action and make one asser- tion. However, there are cases in which a group of similar assertions will be made, such as when verifying the property values on a deserialized JavaScript Object Notation (JSON) object. The QUnit framework provides the expect function, which verifies that the proper number of expected assertions ran. At the beginning of the test you will see that expect(1) was called to let QUnit know how many assertions should be run. If QUnit does not encounter that number of assertions, then it will produce an error in its output. What to Test Now that you know how to write a unit test, the really important question concerns what should be tested. Generally, in a unit test you are trying to verify the functionality of a relatively small component, such as a JavaScript object or a jQuery UI widget. Each test verifies independent pieces such as whether a calculation happened correctly or whether the proper document object model (DOM) modification occurred. When you are testing UI widgets, you may be uncertain about what should be tested. The basic rule of thumb is to test anything a designer would not change. Logic that drives
- 263. 230 chapter thirteen the UI might be tested to determine, for example, that the proper navigation action was invoked, that an element had the proper class attribute applied (or removed), or that the correct event was raised. But, you would not test that a specific font value was set or a specific background color of an element was used. Isolating Your Tests Often your object under test will rely on other objects, functions, or libraries. You may have an object that makes Ajax calls to retrieve data. If you attempt to make Ajax calls when running the unit tests you might get unpredictable results because the server re- sponding to the calls may be unavailable when you run your tests. Generally, you want to isolate your component from these types of problems. When testing, you will also want to isolate your component from other objects you build within your system. In Mileage Stats, many jQuery UI widgets rely on a publish- subscribe object for communication. When you test objects with dependencies, you do not want to invoke the actual dependencies. If you did, you would be testing more than one thing at a time. Instead, it is important to test that the component attempts to invoke a dependency. The typical strategy for isolating your component under test is to supply an alternative component or function that the component calls instead of the real com- ponent. These alternatives may be referred to as fakes, doubles, stubs, or mocks. As it turns out, the ability to isolate your component in this manner also helps the overall de- sign of your application because you will tend to create smaller, more focused compo- nents. With a substitute object employed, you can verify that the correct calls were made with the right values. For example, when testing that the Mileage Stats data cache com- ponent makes an Ajax call with the appropriate URL, a mock ajax function is supplied for testing in the jQuery object (represented as the dollar sign in the example). In this alter- nate, we verify that the expected URL is invoked by the component. JavaScript // Contained in mstats.data.tests.js test('when sendRequest is called, then the url from options is used', function () { expect(1); // Arrange $.ajax = function (options) { // Assert equal(options.url, '/url', 'Url was properly set'); }; // Act mstats.dataManager.sendRequest({ url: '/url' }); });
- 264. 231unit testing web applications Note also that this somewhat changes the typical arrange-act-assert order of the test structure because the assertion is in the supplied Ajax function. It is important to use the expect function at the beginning of your tests to help ensure that all the expected asser- tions are made. When providing these alternative functions or components, it is also imperative to capture and restore the original values to avoid interfering with any other test that may have relied on these values. In QUnit this can be done when defining the test module where the setup and teardown functions can be supplied. JavaScript // Contained in mstats.data.tests.js module( 'MileageStats DataManager sendRequest Tests', { setup: function () { this.savedAjax = $.ajax; ... }, teardown: function () { $.ajax = this.savedAjax; ... } } ); jQuery UI Widget Testing When unit testing jQuery UI widgets, there are some additional considerations. Since a widget is attached to a DOM element, you will need to create these elements either in the test or, if they are more complicated, in the setup for a module. In Mileage Stats, be- cause many of the widgets interact with a section of the DOM, some of that structure needs to be created during the test setup. For example, the setup for the header widget test recreates that portion of the DOM structure it manipulates. JavaScript // Contained in mstats.header.tests.js module('Header Widget Tests', { setup: function () { $('#qunit-fixture').append( '<div class="header" id="header">' + '<div><div><h1>Dashboard</h1>' + '<div id="notification"></div>' + '<div class="nav">' + '<span id="welcome">Welcome <b>Sample User</b></span>' +
- 265. 232 chapter thirteen '[ <a id="dashboard-link" href="/Dashboard">Dashboard</a>' + '| <a id="charts-link" href="/Chart/List">Charts</a>' + '| <a id="profile-link" href="/Profile/Edit">Profile</a>' + '| <a id="login-link" href="/Auth/SignOut">Sign Out</a> ]' + '</div>' + '</div></div>' + '</div>' ); } }); In QUnit, any DOM elements added for your test should be added to the element with the id attribute containing qunit-fixture, as shown above. You should only add the minimal amount of structure needed to appropriately simulate your test needs as this will make the structural dependencies of the test clearer. When testing jQuery UI widgets you will also often need to supply an alternate im- plementation of dependent functions or objects. Because you don’t control the creation of the jQuery UI widgets directly, you will typically do this as part of the options object passed into the widget (See Chapter 3, “jQuery UI Widgets” for more details about the use of an options object). For example, when testing the Mileage Stats vehicle details widget, an alternative implementation for the event publisher is supplied as part of the options. JavaScript // Contained in mstats.vehicle-details.tests.js test('when loading data errors out, then triggers error status', function () { expect(2); var eventType = 'loadError', details = $('#details-pane').vehicleDetails({ templateId: '#testTemplate', sendRequest: function (options) { options.error({}); }, publish: function (event, status) { if (status.type === eventType) { ok(status, 'status object passed to publisher'); equal(status.type, eventType, 'status is of type : ' + eventType); } } }); // force a data refresh details.vehicleDetails('option', 'selectedVehicleId', 1); });
- 266. 233unit testing web applications Server-Side Unit Testing Unit testing code on the server typically involves many more interactive pieces than what you encounter when testing client-side JavaScript. In an ASP.NET MVC application, con- trollers will interact with services or repositories to handle each request. As each piece is built, these interactions can be tested using unit tests to instill confidence that the system continues to work as new features are added or new versions of dependent libraries are supplied. This section is intended to provide you with enough information to get started unit testing your server-side application. Since each application is different, illustrating all test- ing scenarios is not possible. To find out more about unit testing your applications, see the “Further Reading” section. Getting Started with Unit Testing There are a number of unit testing frameworks to choose from when unit testing server-side Microsoft .NET Framework components. Most unit testing frameworks are conceptually similar, and any one of them can be a reasonable choice. Microsoft offers two technologies that can be used for writing unit tests: Microsoft Test and xUnit.net. Microsoft Test is supplied with certain versions of Visual Studio, and xUnit.net is a Micro- soft developed, open-source unit testing framework available on CodePlex and NuGet. Regardless of your unit testing framework choice, unit tests are placed in a separate assembly that the unit testing framework can discover and use to execute the tests. A typical Visual Studio solution organization includes all the unit test files under a single solution folder with an appropriate name. For example, the Mileage Stats solution has its test projects in a Unit Tests solution folder. Unit test location in the MileageStats project
- 267. 234 chapter thirteen There is a unit test project for the Services, ServicesModel, SqlCe, and Web projects. Some projects don’t have a corresponding unit tests project primarily because these proj- ects contain only shared interfaces and data transfer classes that do not have significant logic to test. The team chose xUnit.net as the unit testing framework for the Mileage Stats project. While you can accomplish unit testing with either Microsoft Test or xUnit.net, the team chose xUnit.net because it was built specifically for developer unit testing. The remainder of this section discusses unit testing using examples in xUnit.net, but you can readily im- plement the same approaches with Microsoft Test or another unit testing framework, although some of the exact mechanics may be different. To create a new unit test project, add a C# or Microsoft Visual Basic® Class Library project, and reference the xUnit.net assemblies. In the test project, there will be a class to contain all the related tests for a particular component. For example, the MileageStats. Web.Tests project contains a test class for each controller in the Web project. They generally have the same name as the controller name with the term “Fixture” appended. To write a test, create a method with the Fact attribute specified. The xUnit.net framework searches for these attributes and executes these methods. Each test should follow the arrange-act-assert pattern. In this pattern all the setup for the test is done first (arrangement), then the action to be tested is executed (act), and then the validation is done (assert). C# //Contained in ReminderFixture.cs [Fact] public void WhenReminderIsNotOverdue_ThenIsOverdueReturnsFalse() { // Arrange var reminder = new ReminderFormModel() { Title = "future reminder", DueDate = DateTime.UtcNow.AddDays(2), DueDistance = 10000 }; reminder.UpdateLastVehicleOdometer(10); // Act bool isOverdue = reminder.IsOverdue; // Assert Assert.False(isOverdue); }
- 268. 235unit testing web applications In addition to Assert.False, xUnit.net supplies a number of other built-in asserts available on the Assert static class. After the tests have been built, you can execute them using the xUnit.net test runner to see if they pass. The test runner is located where you unpackaged the xUnit.net con- tents retrieved from CodePlex. After you add the test assembly into the runner, you can run all the tests to see if they succeed. Running unit tests If a test fails, a message appears in the console.
- 269. 236 chapter thirteen Running unit tests with errors Alternatively, you can run tests by using TestDriven.Net or Resharper, which run the tests from within Visual Studio. For more details on how to do this, see http://xunit. codeplex.com. What to Test On the server side, you should create unit tests for any classes and components that contain logic or must interact with other components. You should not write unit tests for generated code or code you don’t own. The team wrote unit tests for classes in each of the major layers. Repository Layer. The repository layer provides the basic persistence for information throughout the system. In Mileage Stats, this relies heavily on Entity Framework Code- First and Microsoft SQL Server® Compact Edition. Many of the tests written against this layer verify that the persistence and retrieval implementations for the various repositories produce the correct results. These tests, because they are writing to an actual database, cannot strictly be considered unit tests, but are useful in verifying that the persistence mechanism for all the models works as expected. Often, these are referred to as integra- tion tests. These tests were also useful because the Entity Framework Code-First library was adopted before its final release, so these tests helped demonstrate that the expectations around Entity Framework were maintained between releases.
- 270. 237unit testing web applications Business Logic Layer. The business logic layer is invoked by the controllers in the Web Layer in order to execute business rules and store data in the repository. Unit tests for the business logic layer focus on verifying the business rules and their interactions with the repository layer. The tests do not actually store data in the repository, but use a fake repository and verify that the business services layer uses it correctly. The models in the business logic layer often contain validation logic that is also verified in unit tests. Web Layer. The actual controllers that respond to requests have unit tests to verify that they interact with the services and models appropriately and return correctly built View Models for the Views or jQuery template. Isolating Your Components It is common for the classes you are testing to rely on other classes. For example, a class may rely on a repository to persist a model. During testing, you want to isolate the inter- action of your class with these other objects to ensure that only the behavior of the class in question is tested. Additionally, it can sometimes be painful to set up these other classes appropriately. For example, if the class calls a web service, it would be unrealistic to expect that the web service be available when you want to run your unit test. Instead of trying to create the actual context for the class under test, you supply it with alternative implementations of the object it depends on. These alternatives may also be called fakes, doubles, stubs or mocks. Using these alternative implementations has the side effect of also helping separate the responsibilities of your classes. To provide this separation, instead of creating a class that depends on a specific tech- nology, you can provide an abstraction for the class to depend on. This allows you to provide different implementations of the dependency at different times, such as at unit test time. Often this abstraction could be an interface definition, but it could also be a base or abstract class. For example, suppose you had a class to test that needed to store values somewhere. Instead of tying the class directly to a specific store implementation, it can depend on an IStore abstraction. C# public interface IStore { void Persist(string item); } public class ClassToTest { private IStore store; public ClassToTest(IStore store) { this.store = store; } public void Save(string value)
- 271. 238 chapter thirteen { ... store.Persist(value); ... } } When you write a test for this class that depends on IStore, you can then provide an alternative implementation. C# [Fact] public void WhenSaving_ThenSendsValueToStore() { var mockStore = new StoreMock(); var classToTest = new ClassToTest(mockStore); classToTest.Save("Test"); Assert.Equal(mockStore.ValueSaved, "Test"); } private class StoreMock : IStore { public string ValueSaved { get; set; } public void Persist(string item) { ValueSaved = item; } } The StoreMock object captures the saved item to verify that ClassToTest sends the correct value to the store. Instead of making these mocks by hand, as shown above, the team relied on Moq—a mocking framework—when writing Mileage Stats tests. The test shown above would look like this using Moq. C# [Fact] public void WhenSaving_ThenSendsValueToStore() { var mockStore = new Mock<IStore>(); var classToTest = new ClassToTest(mockStore.Object); classToTest.Save("Test"); mockStore.Verify(s => s.Persist("Test")); }
- 272. 239unit testing web applications Moq dynamically builds the objects needed for testing, and in the case of the Verify method can automatically verify that methods or properties were called with the correct values. For more information about using Moq, see the Moq CodePlex site at http:// moq.codeplex.com. There are times when you don’t control the class that you want to mock. For instance, if you use a static class built into the .NET Framework library, such as FormsAuthentication, you do not have control over that class. In these cases, you will often create an interface for just the functionality you use and provide a default implementation for run-time use and a mock implementation to use at test time. This was the approach employed with Mileage Stats when using the DotNetOpenAuth library. This is a third-party library used by Mileage Stats to handle various authentication protocols. To isolate the components and make them more testable, the IOpenIdRelyingParty interface was created. C# // IOpenIdRelyingParty.cs public interface IOpenIdRelyingParty { ActionResult RedirectToProvider( string providerUrl, string returnUrl, FetchRequest fetch); IAuthenticationResponse GetResponse(); } Mileage Stats has a default implementation that uses the real DotNetOpenAuth library at run time and a mock implementation when testing the AuthController MVC controller. At run time, all these pieces are connected using a technique known as dependency injection. See “Dependency Injection” in Chapter 11, “Server-Side Implementation” to better understand how this works. Testing Your ASP.NET MVC Controllers ASP.NET MVC was designed to support the testability of the controllers, filters, and ac- tions that developers typically write when developing a Model-View-Controller (MVC) application. Since each controller is responsible for handling a request, and MVC auto- matically maps input from the query string or from form data to the data types on your controller’s methods, you can easily write tests for your controllers and simply supply them with the necessary inputs. For instance, the ReminderController’s Add method takes an integer value for the vehicle identifier, and a Reminder object. C# // Contained in ReminderController.cs public ActionResult Add(int vehicleId, ReminderFormModel reminder) { ... return View(viewModel); }
- 273. 240 chapter thirteen In a unit test, it is very simple to provide these parameter values during testing of the Add method. The example below demonstrates how you would supply the reminder and vehicle ID directly in the test. C# // Contained in ReminderControllerFixture.cs [Fact] public void WhenAddReminderWithValidReminder_ThenReturnsToReminderDetailsView() { ... var result = (RedirectToRouteResult)controller.Add(vehicle.VehicleId, formModel) ; Assert.NotNull(result); Assert.Equal("Details", result.RouteValues["action"]); Assert.Equal("Reminder", result.RouteValues["controller"]); } While many unit tests for controllers can use this approach, there are still cases in which the controllers require access to the HttpContext. Providing alternate implementa- tions of HttpContext is usually very difficult, making certain scenarios very hard to test. But because the MVC base controller class, Controller, relies on the abstract Http ContextBase class instead of HttpContext itself, it can be substituted much more easily. Mileage Stats uses a mock HttpContextBase in many of its controller tests to ensure that the HttpContextBase.User property is set appropriately. To do this, Mileage Stats uses an MvcMockHelpers class that wraps the building of a Moq object that substitutes HttpContext information. This controller context is then set on the controller under test by calling the static SetFakeControllerContext extension method in the MvcMockHelpers class. The RemindersControllerFixture sets this when it builds a testable controller. C# // Contained in ReminderControllerFixture.cs private ReminderController GetTestableReminderController() { var controller = new ReminderController(_mockUserServices.Object, _serviceLocator.Object); controller.SetFakeControllerContext(); controller.SetUserIdentity(new MileageStatsIdentity(_defaultUser.AuthorizationId, _defaultUser.DisplayName, _defaultUser.UserId)); return controller; }
- 274. 241unit testing web applications The fake context creates a series of Moq objects that the controller will interact with under test. If you want to adjust what they’re doing, you can recover the mock and change its behavior. The static SetUserIdentity extension method above does this for a control- ler to set an identity context for the test into the HttpContext. C# // Contained in ControllerMockHelpers.cs public static void SetUserIdentity(this Controller controller, IIdentity identity) { Mock.Get(controller.HttpContext) .Setup(x => x.User) .Returns(new GenericPrincipal(identity, null)); } The types of tests you typically write around your controller include: • View Models. You will want to test that the controller provides the correct model data for a specific view. • Navigation. You will want to test that the controller will provide the correct redirection when it is finished processing the request or when there is an error processing the request. • Interaction. You will want to test that the controller makes the appropriate calls to your repository or service layers (which will be mocked in the tests). You will also want to test that your controller appropriately handles the situation when the model data supplied to a controller is in an invalid state. • JSON Endpoints. If you have JSON data endpoints, you want to make sure these return appropriate JSON results for the call. Summary You should make a conscious decision about whether or not you are going to unit test your code. Unit testing is not difficult, but it does require an investment of time to learn and apply. However, the time initially spent writing unit tests will save time over the life of your project and deliver better quality code. Frameworks that help you write unit tests are available for most languages and platforms. Visual Studio includes unit test support for C# and Visual Basic, among other languages, and you can readily find them for lan- guages such as JavaScript.
- 275. 242 chapter thirteen Further Reading Meszaros, Gerard. xUnit Test Patterns: Refactoring Test Code. Addison-Wesley, 2007. Kaner, Cem, Jack Falk, and Hung Q. Nguyen. Testing Computer Software, 2nd Edition. Wiley, 1999. patterns & practices Acceptance Test Engineering Guidance on CodePlex: http://testingguidance.codeplex.com/ Performance Testing Guidance for Web Applications on MSDN®: http://msdn.microsoft.com/en-us/library/bb924375.aspx Guidance for Build, Deploy and Test Workflows on MSDN: http://msdn.microsoft.com/en-us/library/ff972305.aspx QUnit unit testing framework on the jQuery website: http://docs.jquery.com/QUnit xUnit.net on CodePlex: http://xunit.codeplex.com Moq on CodePlex: http://moq.codeplex.com “Testing the User Interface with Automated UI Tests” on MSDN: http://msdn.microsoft.com/en-us/library/dd286726.aspx “How to: Create a Coded UI Test” on MSDN: http://msdn.microsoft.com/en-us/library/dd286681.aspx Resharper: http://www.jetbrains.com/resharper/ TestDriven.NET: http://testdriven.net For more information on dependency injection in Mileage Stats, see Chapter 11, “Server-Side Implementation.” For more information about testing in Project Silk, see the following: • “How to: Check UIElement Properties Using Coded UI Test” on MSDN: http://msdn.microsoft.com/en-us/library/hh404081.aspx. • “How to: Create an Automated Negative Test Case Using Coded UI Test” on MSDN: http://msdn.microsoft.com/en-us/library/hh404089.aspx. • “How to: Create a Web Client UI Test Using Coded UI Test” on MSDN: http://msdn.microsoft.com/en-us/library/hh404082.aspx. To access web resources more easily, see the online version of the bibliography on MSDN: http://msdn.microsoft.com/en-us/library/hh404094.aspx.
- 276. 243 Widget QuickStart14 This Widget QuickStart illustrates the way Project Silk uses the jQuery UI Widget Factory to create maintainable widgets that implement client-side behavior. Business Scenario Our team has been asked to enable cross-browser keyword lookup capabilities in our web pages by hyperlinking select keywords to popular websites. This feature will need to be added dynamically to all company web pages. Another team has been tasked with tagging the keywords in the web pages. The words will be tagged dynamically, based on server-side business logic driven by agree- ments with third parties. The focus of this QuickStart is to enable the client-side behavior for the tagged keywords. When a user hovers over a keyword, the browser will display a pop-up list of popular links for that keyword from the Delicious.com bookmarking service. Walkthrough Project Silk includes the source code for the Widget QuickStart. To run the QuickStart, ensure you have an Internet connection and follow the steps below: 1. If you have not already installed Project Silk, download it from the Microsoft Download Center at http://www.microsoft.com/download/en/details. aspx?id=27290. To extract the download, run the .exe file. This will extract the source code and documentation into the folder of your choice. 2. Open the default.htm file from the {silk}QuickStartsDeliciousWidget QuickStart folder using Windows® Internet Explorer® 9. After the file’s content is displayed, you’ll need to click on the Allow blocked content button at the bottom of the browser window to enable scripts to run. Blocking active content by default is a security feature of Internet Explorer 9.
- 277. 244 chapter fourteen Widget QuickStart (default.htm) 3. After allowing blocked content, you’ll notice that the keywords are displayed in a new color and have been underlined with a dashed line, as pictured below.
- 278. 245widget quickstart Widget QuickStart after scripts are unblocked 4. Using your mouse, hover over an underlined keyword. A pop-up list with the ten most popular links for that keyword will be displayed. Notice that the keyword has been repeated in the title of the pop-up list. 1. One second after moving your mouse away from the keyword, the pop-up list will close unless your mouse is within the boundaries of the pop-up list. 2. If the keyword is on the left side of the page, the pop-up list will open to the right of the cursor. If the keyword is on the right side of the page, the pop-up list will open to the left of the cursor, as in the image below.
- 279. 246 chapter fourteen Pop-up list for the keyword “jQuery” 5. Move your mouse over the pop-up list. You can now click on a link, which will open in a new browser window. Links from Delicious.com in the pop-up list 6. Moving your mouse outside the boundaries of the pop-up list will cause the pop-up list to close.
- 280. 247widget quickstart Conceptual View This section illustrates the relationship of the jQuery UI widgets to the HTML page. A single infobox widget is attached to the page’s body element. After it’s attached, it cre- ates a <div> element and dynamically adds it to the page’s <body> element. Additionally, a tagger widget is attached to each keyword. Relationship of the jQuery UI widgets to the HTML page The HTML below reveals a keyword tagging strategy that takes advantage of HTML5 data attributes. Each of the keywords has been wrapped in a span tag with the data-tag attribute applied. In this scenario, the keyword wrapping was accomplished on the server side. HTML <!-- Contained in default.htm --> <!DOCTYPE html> <html> <head ...> <body>
- 281. 248 chapter fourteen <div id="container"> <img src="projectsilk.png" /> <h1>Project Silk Overview</h1> <p> Project Silk provides guidance and example implementations that describe and illustrate recommended practices for building next generation web applications using web technologies like <span data-tag>HTML5</span>, <span data-tag>jQuery</span>, <span data-tag>CSS3</span> and Internet Explorer 9. The guidance will be taught in the context of real-world development scenarios rather than focusing on <span data-tag>technology</span> features.</p> Attaching Widgets Once created, the widget is attached to an HTML element and its options can be set. JavaScript // Contained in startup.js (function ($) { var infobox = $('body').infobox({ dataUrl: 'http://feeds.delicious.com/v2/json/popular/' }); $('span[data-tag]').tagger({ activated: function (event, data) { infobox.infobox('displayTagLinks', event, data.name); }, deactivated: function () { infobox.infobox('hideTagLinks'); } }); } (jQuery)); The code above demonstrates how the infobox widget is attached to the body ele- ment. The dataUrl option value will be used when performing popular keyword link lookups. The jQuery selector span[data-tag] returns a jQuery wrapped set that contains all span tags with a data-tag attribute. A tagger widget will be attached to each of the span tags in the returned collection. The tagger widget has activated and deactivated options that are used as callbacks. These callbacks are used to handle events raised when the mouse hovers over the tag.
- 282. 249widget quickstart Widget Initialization When a widget is created (attached), the jQuery UI widget factory will call the private method _create. This method provides the developer an opportunity to perform widget setup actions. Examples include building and injecting markup, adding CSS classes, and binding events. JavaScript // Contained in jquery.qs.infobox.js _create: function () { var that = this, name = that.name; that.infoboxElement = $('<div class="qs-infobox" />'); that.infoboxElement.appendTo('body') .bind('mouseenter.' + name, function () { mouseOverBox = true; }) .bind('mouseleave.' + name, function () { mouseOverBox = false; that.hideTagLinks(); }); }, The code snippet above first creates a variable for this called that within the closure, so the widget can be referenced within the mouseenter and mouseleave event handlers. Recall that the infobox widget is attached to the body element. The element div. qs-infobox will contain the UI for this widget. It is stored in that.infoboxElement, at- tached to the body element, and bound to some events. The name variable holds the name of the widget and is appended to the name of the event it’s binding to. This is a recommended practice when using jQuery; the reasons why will be explained later in the QuickStart. Note: Most of the time, widgets are attached to the element that they will control; however, there are times when a widget will need to create additional elements. In the above _create function, the infobox widget creates a div to hold the list of links. The default.htm HTML page could have been modified to include the div in the first place, making it unnecessary for the widget to add an additional structure. However, the code was written this way to illustrate a widget adding UI elements to an existing HTML structure. Widget Interactions An interesting challenge in this scenario is giving the user enough time to click the links without showing the pop-up list longer than needed. The implementation requires coor- dination between the two widgets.
- 283. 250 chapter fourteen Mouse Entering a Keyword Span When the mouse enters the keyword span, the mouseenter event handler in the tagger widget is invoked. The name being appended to the event name is the name of the widget and is used as a namespace for the event binding. This is a recommended practice. Any string can be used as the namespace, but using the name of the widget allows you to tap into a feature of the widget factory described later in the QuickStart. JavaScript // Contained in jquery.qs.tagger.js .bind('mouseenter.' + name, function (event) { clearTimeout(timer); that._trigger('activated', event, {name: tag}); }) The clearTimeout call uses the timer variable, which is defined outside of the widget prototype and set in the handler for mouseleave, discussed in the next section. This means there will be only one timer created and shared among all instances of the tagger widget. The next line raises the tagactivated event. It doesn’t raise the taggeractivated event because the widget sets the widgetEventPrefix property, as shown in the next code snippet. It also doesn’t raise the activated event, as you may have suspected, because the widget factory changes the name of raised events by prepending the name of the widget to the name of the event being triggered. JavaScript // Contained in jquery.qs.tagger.js $.widget('qs.tagger', { widgetEventPrefix: 'tag', options: { When the tagactivated event is raised, the displayTagLinks method is called on the infobox widget. As you will notice from having a look at jquery.qs.infobox.js, it never binds to this event. Doing so would create a dependency between the widgets. A better option is to follow a recommended pattern that takes advantage of a related jQuery UI feature. It is recommended that a widget provide callback options for all of the events it raises. JavaScript // Contained in jquery.qs.tagger.js options: { activated: null, deactivated: null },
- 284. 251widget quickstart The jQuery UI widget factory will automatically call any option with the same name as the event being raised. This feature allows the event handlers to be associated with the event by setting the value of the option. The QuickStart does this in the startup file. JavaScript // Contained in startup.js $('span[data-tag]').tagger({ activated: function (event, data) { infobox.infobox('displayTagLinks', event, data.name); }, deactivated: function () { infobox.infobox('hideTagLinks'); } }); This approach is also a nice way to avoid having to know if the event is called tag activated or taggeractivated or something else. The displayTagLinks method accepts a browser event and the name to look up. The first part of the method sets up enclosed variables to be used in the second part of the method. JavaScript // Contained in jquery.qs.infobox.js displayTagLinks: function (event, tagName) { var i, html, that = this, options = that.options, elem = that.infoboxElement, top = event.pageY + offsetY, left = event.pageX + offsetX, url = options.dataUrl + tagName + '?count=' + options.maxItems, displayResult = function () { elem.html(html); elem.css({top: top, left: left}); elem.show(); }; if (event.pageX > window.screenWidth / 2) { left = event.pageX + leftSideAdjustment; } After the closure is prepared, left is adjusted in case the tag is on the right-hand side of the page. The second part of the displayTagLinks method is an Ajax call to the url, constructed above, for the Delicious bookmarking service.
- 285. 252 chapter fourteen JavaScript // Contained in jquery.qs.infobox.js $.ajax({ url: url, dataType: 'jsonp', success: function (data) { if (data != null) { html = '<h1>Popular Links for ' + tagName + '</h1><ul>'; for (i = 0; i < data.length - 1; i += 1) { html += '<li><a href="' + data[i].u + '" target="_blank">' + data[i].d + '</a></li>'; } html += '</ul>'; } else { html = '<h1>Data Error</h1><p>[snipped]</p>'; } displayResult(); }, error: function (jqXHR, textStatus, errorThrown) { html = '<h1>Ajax Error</h1>' + '<p>The Ajax call returned the following error: ' + jqXHR.statusText + '.</p>'; displayResult(); } }); The local displayResult function is scoped only to the displayTagLinks method since it was needed for both success and error conditions and nowhere else. This is the meth- od that applies the result to the element for the user to see. Mouse Leaving a Keyword Span When the mouse leaves the tag’s span, a similar coordination occurs. The tagger widget has a namespaced event bound to the span’s mouseleave event. JavaScript // Contained in jquery.qs.tagger.js .bind('mouseleave.' + name, function () { timer = setTimeout(function () { that._trigger('deactivated'); }, hideAfter); }); The timer is set to raise the tagdeactivated event after 1000 milliseconds, which is the value of hideAfter.
- 286. 253widget quickstart When the tagger widget was applied to the span elements, a function was supplied to the deactivated callback, as you also saw earlier in the QuickStart. JavaScript // Contained in startup.js $('span[data-tag]').tagger({ activated: function (event, data) { infobox.infobox('displayTagLinks', event, data.name); }, deactivated: function () { infobox.infobox('hideTagLinks'); } }); The function invokes the hideTagLinks method on the infobox widget. JavaScript // Contained in jquery.qs.infobox.js hideTagLinks: function () { !mouseOverBox && this.infoboxElement.hide(); }, The infobox is only hidden if the mouse is not over it. Effectively, the 1000 ms delay provides the user time to move the mouse from the keywords to the links. Mouse Entering the Pop-up List Internally, the infobox widget uses the mouseOverBox variable to maintain state indicat- ing whether or not the mouse is over the pop-up list. This variable is defined in the closure created by the self-executing anonymous function wrapping the file. JavaScript // Contained in jquery.qs.infobox.js (function ($) { var offsetX = 20, offsetY = 20, mouseOverBox = false, leftSideAdjustment = -270; $.widget(‘qs.infobox’, { When the mouse enters the infobox, mouseOverBox is set to true. JavaScript // Contained in jquery.qs.infobox.js: _create .bind('mouseenter.' + name, function () { mouseOverBox = true; })
- 287. 254 chapter fourteen Mouse Leaving the Pop-up List When the mouse leaves the pop-up list, mouseOverBox is set to false and hideTagLinks is invoked. JavaScript // Contained in infobox.js .bind('mouseleave.' + name, function () { mouseOverBox = false; that.hideTagLinks(); }); hideTagLinks: function () { !mouseOverBox && this.infoboxElement.hide(); }, Further Reading For more information about the jQuery UI widget factory, see the following resources: • Chapter 3, “jQuery UI Widgets” • “jQuery UI API Developer Guide” on jQuery UI: http://jqueryui.com/docs/Developer_Guide • “Widget factory” on the jQuery UI wiki: http://wiki.jqueryui.com/w/page/12138135/Widget-factory • “Tips for Developing jQuery UI 1.8 Widgets” on Eric Hynds’ blog: http://www.erichynds.com/jquery/tips-for-developing-jquery-ui-widgets/ • “Understanding jQuery UI widgets: A tutorial” on bililite.com: http://bililite.com/blog/understanding-jquery-ui-widgets-a-tutorial/ To access web resources more easily, see the online version of the bibliography on MSDN: http://msdn.microsoft.com/en-us/library/hh404094.aspx.
- 288. 255 Glossary arrange-act-assert pattern. A common pattern employed when writing unit tests. Its purpose is to make a clear distinction between the setup for the test, the action that is to be tested, and evaluation of the results. In most unit tests the arrange-act-assert occur in the order of arrange, act, and then assert. However, when unit testing Java Script it is common to define the assert in a callback function that may be defined before the act. authentication provider. The party responsible for validating a user’s credentials and issuing a token that can be used to access other sites. This is the web site you visit to do the actual authentication. content injection. In a web application that accepts data input from users, content injection refers to the act of an attacker attempting to insert HTML or client script content that will be processed by a client browser, or SQL commands that the server may process. If successful, content injection of HTML or client scripts will cause the website to behave undesirably for any user that views the injected content because it’s being processed by their browser as legitimate HTML or client script. Content injection can result in many undesirable effects, such as causing parts of a web page to disappear, diverting user requests to a malicious location, or allowing an attacker to eavesdrop. SQL injection does not affect the client browser, but if a web application accepts user input and uses it to dynamically create a SQL query without verifying the content, an attacker can inject syntax into the SQL query to manipulate the database and even the database server if it’s not locked down properly. This type of attack can lead to deleted data, dropped databases, or even allow operating system commands to run as if you were typing them at the command line. closures. A JavaScript feature that ensures that an inner function always has access to the variables and parameters of its outer function, even after the outer function has returned. For a good explanation of closures, see “A Graphical Explanation of JavaScript Closures in a jQuery Context” by Ben Nadel at http://www.bennadel.com/blog/1482- A-Graphical-Explanation-Of-Javascript-Closures-In-A-jQuery-Context.htm. Appendix A
- 289. 256 appendix a cross-site scripting (XSS). An attack whereby scripts from a malicious source are executed on a client browser as part of a trusted web page. Websites that build pages with data elements originating from other sources, such as user input or shared data- bases, are vulnerable to XSS attacks. cross-site request forgery (CSRF). An attack in which a client browser is manipulated into performing malicious actions on a server with which the client has some form of trusted relationship through authentication, HTTPS, or IP filtering. An attacker embeds a link or a script in a piece of untrusted content that does something on the trusted site to which the user is currently authenticated. A simple example is an image element embedded in an HTML email that includes a URL query string, which performs a malicious action. If users click the image, they unknowingly initiate the act on the site where they are authenticated. data- attributes. HTML5 attributes that provide metadata for HTML elements. They can be used to provide additional information for the JavaScript application, and provide a mechanism for selecting HTML elements via JavaScript without negatively impacting the page’s visual design. Data Model. An object that represents an entity built for data storage services. These are not available for use outside the boundaries of the application and are often encap- sulated behind a services layer. Domain Model. An object that represents an entity in the problem domain, which may also be annotated or extended to support some application features such as validation or authentication. Because these models need to be shared between the server and client browser, they are sometimes contained within view models and used directly for data-binding in HTML forms. Application models and service models are variations of domain models. eavesdropping. Exploiting a web application using a network data capture utility to find and record HTTP requests and responses between a website and a client. Eaves- dropping can lead to disclosure of sensitive information such as passwords, personal, or financial information, and can potentially allow the execution of spoofing, tampering and message replay attacks. flow diagram. A diagram that defines the pages in the site, actions available on those pages, and navigation between pages. This diagram reflects the user stories identified in the requirements. Forms authentication. Forms authentication enables user and password validation for web applications that do not require Windows authentication. Form Model. An entity that represents all of the fields in an HTML form that is specific to a controller action. It contains only the data that is passed into the action. Generally, this corresponds to whatever form is posting back to the server. Form Models (some- times called Request Models) are a special case of View Models. View Models are more generic in that they may also include additional data needed to render a page. A Form Model might end up being a property on another View Model.
- 290. 257glossary fragment identifier. The portion of a URL identified by the hash (#). With regard to browser navigation, hyperlinks include them to make the hyperlink unique. When used in conjunction with the hashchange event, page content is able to change without performing a full-page reload. full-page reload. When a user operation such as clicking a hyperlink causes the browser to load an entirely new page from the server. This is in contrast to using Ajax to request data from the server so the client-side JavaScript can update only the parts of the page that should change. functional mockup. Functioning HTML pages that include CSS and possibly JavaScript. These pages are autonomous and don’t yet interact with the server and use fake data when needed. They give you the chance to balance browser capabilities with HTML, CSS, images, and JavaScript before integrating the pages with the server-side implemen- tation. given-when-then template. A helpful template for defining acceptance criteria that include the context of the test (given), the action being tested (when), and the ex- pected outcome (then). This template provides clear and concise documentation that can be understood by team members and can be used to generate both manual and automated test scripts. hybrid-design web application. Web application with the same characteristics as the server-rendered web application, except that it relies heavily on client-side JavaScript to deliver an engaging experience. This type of application has pages that act as islands of interactivity that do not require full-page reloads as well as pages that do require a full-page reload. Mileage Stats is an example of a hybrid design. integrator. A role on the team building a web application that is responsible for combin- ing the images, HTML, CSS, and JavaScript with the server-side technologies in a way that closely represents the final implementation. The person responsible for this role may not be a specialist in design or development, but has a solid grasp of all technolo- gies involved. jQuery selectors. A syntactical aspect of jQuery that allows you to select all DOM elements based on specific criteria (tag name, id, attribute name, value, and more). Once the selection is made, jQuery is used to operate on the selected elements. jQuery templates. HTML markup with inline JavaScript expressions that are used to populate values in the markup. The jQuery Template plug-in applies data to the tem- plate and renders the output into the DOM. Jump List. List of commonly used tasks and destinations, enabling easy user access to destinations by eliminating the need to launch the browser and then load the relevant content. Also allows users to perform common tasks without launching the web application in advance. This is a feature of Windows® Internet Explorer® 9. JSON hijack. If an attacker gets a user to click on a malicious link that makes a Java Script Object Notation (JSON) request via HTTP GET and that request returns a JSON
- 291. 258 appendix a array, the attacking code within the link may gain access to the contents of the array in the response, which may become accessible to the attacker. malicious input. Bad data that causes your system to behave undesirably and/or corrupts data. message replay attack. An attack that alters the contents of a captured HTTP request and re-submits it to the website. message tampering. When an attacker maliciously alters the content of request and/or response messages flowing between two parties across a network. For example, if a customer submits an order for 100 widgets to an online merchant, an attacker might alter the order request to order 10,000 widgets instead. Message tampering can be part of a message replay attack or a man-in-the-middle attack. mock. The typical strategy for isolating your component under test is to supply an alter- native component or function that the component calls instead of supplying the real component. These alternative components may also be referred to as fakes, doubles, or stubs. mockup. A visual representation that shows what the site will eventually look like. Mockups contain details such as typography, color, gradients, images, and transparency, but no functionality. Mockups should communicate all necessary details of the UI. To do so, multiple mockups for a single page may be required to convey details of the different states of the application. mood board. A visual collage made up of images and color palettes from a variety of sources that communicate the emotional connection the application aims to have with the users. persona. A representation of a particular type of user the team can identify with. A persona is a user in context that embodies work style, role, motivation, skills, and goals. If you have a complicated or large application, some features might target multiple personas. pinned site. A feature of Windows Internet Explorer 9 that integrates your website with the Windows 7 desktop. Pinned sites enable easy access to favorite websites and add shortcut functionality similar to shortcuts in Microsoft® Windows applications. With pinned sites enabled for a website, users can pin the site to the Windows 7 taskbar or add the site to the desktop or Start menu. With this feature, you can add site metadata, create custom jump lists, notification icons, and Thumbnail Preview toolbar controls for the websites you develop. polyfill. Polyfills and shims consist of JavaScript, HTML, and CSS code that helps to provide the technology and functionality that you expect the browser to provide natively. In simple terms, they provide support for missing features. With polyfills, the code tries to replicate the real, standards-based API, making it easier to port your applications once a standard feature is included in a future version of a browser. This makes it easier to “future-proof” your code since you shouldn’t have to change anything
- 292. 259glossary for the new feature to work. For more information about polyfills, see “Making HTML4 and CSS3 work with polyfills and shims” by Rey Bango in .net magazine at http://www. netmagazine.com/features/making-html5-and-css3-work-polyfills-and-shims. Plain Old CLR Object (POCO). Refers to a class in the Microsoft .NET Framework that does not have any dependencies on external libraries such as the Entity Framework. For example, if a class inherits from a base class provided in an external library, it is not a POCO. progressive enhancement. Adds features to the client-side experience based on browser capabilities. prototype. A prototype is a JavaScript object from which other objects inherit their members. Every object has a prototype and any object can be used as a prototype for creating new objects. For more information on prototypes, see “Prototypes and Inheri- tance in JavaScript” by Scott Allen on Script Junkie at http://msdn.microsoft.com/ en-us/scriptjunkie/ff852808. Publish/Subscribe pattern (pub/sub). A messaging pattern that enables loose commu- nication between publishers and subscribers. A pub/sub object manages communica- tion, relieving the publishers and subscribers from having direct knowledge of one another. relying party. The party trying to validate a user based on a security token that was issued by an authentication provider. repository. A set of interfaces and implementations providing methods for data access. Repository pattern. This pattern assists the data model in separating data storage concerns from the application logic. The interfaces do not expose any data storage- specific types and the implementation classes use them. You can choose how many repositories to create based on how granular you want to factor the methods and the expected data access pattern from your application. rule of thirds. This is a rule of thumb for visual composition that states that an image should be imagined as divided into nine equal parts by two equally-spaced horizontal lines and two equally-spaced vertical lines. Important compositional elements should be placed along these lines or their intersections. safe list. A list that limits input by only allowing what is known to be valid. The advan- tage of safe lists is that anything that falls outside of the valid set of characters is not allowed. salt. A salt is a value combined with a cryptographic key to make the output of an encryption algorithm more random and less susceptible to attack. sandboxing. Technique that allows components of the application to be tested before the entire application is complete. It also makes testing more robust by preventing software defects in one module from blocking or affecting the testing of other modules.
- 293. 260 appendix a server rendered web application. Web application where the server dynamically assembles each page from one or more source files and incorporates data and calculated values during the rendering. The client-side script in these applications might perform some data validation or simple hover effects, but few Ajax calls. As each page is navi- gated to, the browser performs a full-page reload. ASP.NET applications that don’t make heavy use of client-side JavaScript are examples of server rendered web applica- tions. Single-Page Interface (SPI) pattern. A pattern for web applications that reduces the number of full-page reloads during user navigation. When a user performs an action, such as selecting a hyperlink, which traditionally requires the site to load a new web page, the application instead modifies the current web page without reloading it. single-page interface web application. Web application where the user is only required to perform a full-page load once. From that point on, all page changes and data loading is performed without a full-page reload. Hotmail, Office Live, and Twitter are examples of single-page interface web applications. shim. Polyfills and shims consist of JavaScript, HTML, and CSS code that helps to provide the technology and functionality that you expect the browser to provide natively. In simple terms, they provide support for missing features. Shims offer features that are not available in the standard implementation and no polyfill is available. For more information about shims, see “Making HTML4 and CSS3 work with polyfills and shims” by Rey Bango in .net magazine at http://www.netmagazine.com/features/ making-html5-and-css3-work-polyfills-and-shims. sliding expiration. A pre-determined amount of time where an authenticated user can use the site. The amount of time is reset whenever the user makes a new request to the server. The advantage of using a sliding expiration is that it does not force the user to authenticate again if he or she maintains a reasonable level of activity in the application. Otherwise, the user would be redirected to the authentication page after a fixed amount of time had elapsed after the initial authentication. static web application. Web sites consisting of static HTML pages, CSS, and images. As each page is navigated to, the browser performs a full-page reload. structure. The HTML of the page as it relates to the hierarchy of elements that make up the page, rather than the visual appearance or layout of the UI. topic. The message between the publisher and subscriber in a pub/sub environment. This message, also often referred to as an event, represents the contract between the sender and receiver, and is made up of a name and an optional message body. user gestures. A specific action that a user takes in order to interact with an applica- tion. Traditionally, gestures include mouse clicks and keys presses. However, many modern applications also employ interactions in which a user acts more directly on an application. For example, they may touch a screen to swipe, pinch, or pull content.
- 294. 261glossary ViewBag. The name/value keyed collection that lets you store any loosely typed data. ASP.NET MVC 3 introduced the ViewBag (called ViewData in previous versions) in addition to View.Model. View Models. Models contained within the MVC application which are built solely for a view to data-bind against. They often follow the same composition hierarchy as the views and partial views. widget. An object attached to a page element that supplies services for managing lifetime, state, inheritance, theming, and communication with other widgets or Java Script objects. A widget is a jQuery plug-in. widget method. The method that represents the primary interface for applying the widget to elements and using the widget after it’s applied. The widget method is named after the name of the widget. wireframe. A diagram that depicts rough placement of the text, data, and basic controls of a UI. These diagrams are tools used to help organize the page’s information. A wireframe does not show details of the page. wrapped set. A wrapped set is the result of a query that uses a jQuery selector to find elements in the DOM. To call a method on a wrapped set of elements, a selector is used to select elements in the DOM. For example, to add the listing CSS class to all ul elements directly inside a div element, you can use $(‘div ul’).addClass(‘listing’).
- 296. 263 This topic presents a road map that will help you locate the appropriate guidance topics within Project Silk: Client-Side Web Development for Modern Browsers. About the Topic Areas To help you find relevant content, this document divides the topics into particular areas, and then drills down into each of them. It provides a brief overview of the topic area, followed by considerations and recommendations for each topic area and the location of the relevant guidance content. The high-level topic areas are: • Immersive Web Applications • Technology Choices • Mileage Stats • Widgets • UI and UX Design • Modularity • Data • Client-Side HTML • Communication • Navigation • Application Notifications • Server-Side Implementation • Security • Unit Testing • Automated Acceptance Testing Project Silk Road MapAppendix B
- 297. 264 appendix b The following sections describe the content and reference materials for each of these topic areas. Immersive Web Applications There is a spectrum of web applications being built today. While there are many types of modern web applications that address many different needs, they all have some common characteristics. What are the different kinds of web applications? • “Spectrum of Web Applications” on page 2 in Chapter 1, “Introduction” and online at http://msdn.microsoft.com/en-us/library/ hh404096.aspx. • “Characteristics of Modern Web Applications” on page 3 in Chapter 1, “Introduction” and online at http://msdn.microsoft.com/en-us/library/ hh404096.aspx. Technology Choices The Project Silk team built the Mileage Stats Reference Implementation (Mileage Stats) using JavaScript, jQuery, jQuery UI, the BBQ plug-in, the jqPlot plug-in, Ajax, Modernizr, QUnit, ASP.NET MVC, xUnit.net, Moq, the Entity Framework, Unity Application Block, HTML5, and CSS3. What are the technology choices I should consider when building a web application? • “Technologies” on page 4 in Chapter 1, “Introduction” and online at http://msdn.microsoft.com/en-us/library/hh404096.aspx. • “Architectural Alternatives” on page 29 in Chapter 2, “Architecture” and online at http://msdn.microsoft.com/en-us/library/hh404097.aspx. What do jQuery and jQuery UI offer? • “Introduction” on page 33 in Chapter 3, “jQuery UI Widgets” and online at http://msdn.microsoft.com/en-us/library/hh404085.aspx. Mileage Stats Mileage Stats is a comprehensive sample application demonstrating a real-world, interac- tive, cross-browser, consumer-facing, rich web application. This reference implementation is intentionally incomplete, but does illustrate the core concepts, design patterns, coding patterns, security requirements, web technologies, and unit testing necessary to be suc- cessful. Below you will find the locations of material that will answer the following ques- tions. What is Mileage Stats? • “Exploring the Mileage Stats Reference Implementation” on page 8 in Chapter 1, “Introduction” and online at http://msdn.microsoft.com/ en-us/library/hh404096.aspx.
- 298. 265project silk road map • “Introduction” on page 21 in Chapter 2, “Architecture” and online at http://msdn.microsoft.com/en-us/library/hh404097.aspx. How do I install Mileage Stats? • Readme on page xxi and online at http://msdn.microsoft.com/en-us/ library/hh404100.aspx. How did the design of Mileage Stats evolve? • “Designing the Mileage Stats Reference Implementation” on page 60 in Chapter 4, “Design and Layout” and online at http://msdn.microsoft. com/en-us/library/hh404087.aspx. How does Mileage Stats implement modularity? • “JavaScript Module Implementations” on page 89 in Chapter 5, “Modularity” and online at http://msdn.microsoft.com/en-us/library/ hh404079.aspx. How does Mileage Stats manage and centralize application data requests? • “Data Request” on page 99 in Chapter 6, “Client Data Management and Caching” • “Providing Data Asynchronously” on page 192 in Chapter 11, “Server- Side Implementation” and online at http://msdn.microsoft.com/en-us/ library/hh404093.aspx. How does Mileage Stats cache data? • “Data Cache” on page 104 in Chapter 6, “Client Data Management and Caching” and online at http://msdn.microsoft.com/en-us/library/ hh404101.aspx. How does Mileage Stats use data- attributes? • “Using Data- Attributes” on page 112 in Chapter 7, “Manipulating Client-Side HTML” and online at http://msdn.microsoft.com/en-us/ library/hh404083.aspx. • “Providing HTML Structure” on page 189 in Chapter 11, “Server-Side Implementation” and online at http://msdn.microsoft.com/en-us/ library/hh404093.aspx. How does Mileage Stats generate HTML dynamically? • “Generating HTML Dynamically with JavaScript and jQuery” on page 116 in Chapter 7, “Manipulating Client-Side HTML” and online at http://msdn.microsoft.com/en-us/library/hh404083.aspx. How does Mileage Stats generate jQuery templates? • “Server-Side Rendering and jQuery Templates” on page 120 in Chapter 7, “Manipulating Client-Side HTML” and online at http://msdn. microsoft.com/en-us/library/hh404083.aspx. How does Mileage Stats choose between various communication options? • “Finding the Right Balance” on page 133 in Chapter 8, “Communication” and online at http://msdn.microsoft.com/en-us/ library/hh404091.aspx.
- 299. 266 appendix b How does Mileage Stats implement direct method invocation between widgets? • “A Helper for Method Invocation” on page 125 in Chapter 8, “Communication” and online at http://msdn.microsoft.com/en-us/ library/hh404091.aspx. • “Method Invocation in Mileage Stats” on page 124 in Chapter 8, “Communication” and online at http://msdn.microsoft.com/en-us/ library/hh404091.aspx. How does Mileage Stats raise and handle events? • “Raising and Handling Events” on page 127 in Chapter 8, “Communication” and online at http://msdn.microsoft.com/en-us/ library/hh404091.aspx. How does Mileage Stats implement pub/sub? • “Pub/Sub in Mileage Stats” on page 129 in Chapter 8, “Communica- tion” and online at http://msdn.microsoft.com/en-us/library/ hh404091.aspx. How does Mileage Stats keep users within a single-page interface? • “Supporting the Single-Page Interface Pattern” on page 136 in Chapter 9, “Navigation” and online at http://msdn.microsoft.com/en-us/ library/hh404077.aspx. How does Mileage Stats modify the URLs sent from the server? • “Modifying Hyperlinks” on page 138 in Chapter 9, “Navigation” and online at http://msdn.microsoft.com/en-us/library/hh404077.aspx. How does Mileage Stats respond to the user clicking on a link? • “Responding to User Actions” on page 143 in Chapter 9, “Navigation” and online at http://msdn.microsoft.com/en-us/library/hh404077.aspx. How does Mileage Stats manage the browser’s history? • “Responding to User Actions” on page 143 in Chapter 9, “Navigation” and online at http://msdn.microsoft.com/en-us/library/hh404077.aspx. How does Mileage Stats coordinate widget transitions between the various layouts? • “The Layout Manager” on page 145 in Chapter 9, “Navigation” and online at http://msdn.microsoft.com/en-us/library/hh404077.aspx. How does Mileage Stats animate screen transitions? • “Animating Screen Transitions” on page 145 in Chapter 9, “Navigation” and online at http://msdn.microsoft.com/en-us/library/hh404077.aspx. How does Mileage Stats implement Pinned Sites? • “Pinned Sites in Mileage Stats” on page 165 in Chapter 10, “Application Notifications” and online at http://msdn.microsoft.com/ en-us/library/hh404084.aspx.
- 300. 267project silk road map What does Mileage Stats server-side architecture look like? • “Introduction” on page 173 in Chapter 11, “Server-Side Implementation” and online at http://msdn.microsoft.com/en-us/ library/hh404093.aspx. How does Mileage Stats implement the Repository Pattern? • “Implementing the Repository Pattern” on page 180 in Chapter 11, “Server-Side Implementation” and online at http://msdn.microsoft. com/en-us/library/hh404093.aspx. How are data annotation attributes used in Mileage Stats? • “Data Annotation Attributes” on page 195 in Chapter 11, “Server-Side Implementation” and online at http://msdn.microsoft.com/en-us/ library/hh404093.aspx. How does Mileage Stats implement authentication? • “Authentication” on page 210 in Chapter 12, “Security” and online at http://msdn.microsoft.com/en-us/library/hh404095.aspx. How does Mileage Stats validate input? • “Input Validation” on page 217 in Chapter 12, “Security” and online at http://msdn.microsoft.com/en-us/library/hh404095.aspx. What security measures were implemented in Mileage Stats? • “Mileage Stats Application Security” on page 210 in Chapter 12, “Security” and online at http://msdn.microsoft.com/en-us/library/ hh404095.aspx. What tools were used to facilitate unit testing in Mileage Stats? • “Introduction” on page 225 in Chapter 13, “Unit Testing Web Applications” and online at http://msdn.microsoft.com/en-us/library/ hh404088.aspx. What is an example of a unit test on the client side in Mileage Stats? • “Creating Unit Tests” on page 228 in Chapter 13, “Unit Testing Web Applications” and online at http://msdn.microsoft.com/en-us/library/ hh404088.aspx. What is an example of a unit test on the server side in Mileage Stats? • “Testing Your ASP.NET MVC Controllers” on page 239 in Chapter 13, “Unit Testing Web Applications” and online at http://msdn.microsoft. com/en-us/library/hh404088.aspx.
- 301. 268 appendix b Widgets When building rich, client-side web applications, some of the visual elements on the page will naturally take on roles, responsibilities, and state. A concept that is central to jQuery UI is the widget. What is a widget? • “Introduction” on page 33 in Chapter 3, “jQuery UI Widgets” and online at http://msdn.microsoft.com/en-us/library/hh404085.aspx. What is an example of a widget? • Chapter 14, “Widget QuickStart” on page 243 and online at http://msdn.microsoft.com/en-us/library/hh404102.aspx. • “Factors That Influence a Modular Design” on page 80 in Chapter 5, “Modularity” and online at http://msdn.microsoft.com/en-us/library/ hh404079.aspx. • “Using Widgets as Modules” on page 91 in Chapter 5, “Modularity” and online at http://msdn.microsoft.com/en-us/library/hh404079.aspx. How do I define and apply widgets? • “Defining a Widget” on page 35 in Chapter 3, “jQuery UI Widgets” and online at http://msdn.microsoft.com/en-us/library/hh404085.aspx. • “Using a Widget” on page 35 in Chapter 3, “jQuery UI Widgets” and online at http://msdn.microsoft.com/en-us/library/hh404085.aspx. How do I manage the lifetime of widgets? • “Managing Lifetime” on page 36 in Chapter 3, “jQuery UI Widgets” and online at http://msdn.microsoft.com/en-us/library/hh404085.aspx. How do I define default options that permit overrides and change notifications? • “Defining Options” on page 38 in Chapter 3, “jQuery UI Widgets” and online at http://msdn.microsoft.com/en-us/library/hh404085.aspx. How do I decouple widget behavior? • “Functions as Options” on page 40 in Chapter 3, “jQuery UI Widgets” and online at http://msdn.microsoft.com/en-us/library/hh404085.aspx. How do I define and use public methods, properties, and events? • “The Widget Method” on page 41 in Chapter 3, “jQuery UI Widgets” and online at http://msdn.microsoft.com/en-us/library/hh404085.aspx. How do I use private methods to improve the readability of the code? • “Private Members” on page 43 in Chapter 3, “jQuery UI Widgets” and online at http://msdn.microsoft.com/en-us/library/hh404085.aspx. How do I define a variable that’s available to all instances of the widget, but nowhere else? • “Static Members” on page 44 in Chapter 3, “jQuery UI Widgets” and online at http://msdn.microsoft.com/en-us/library/hh404085.aspx. How should widgets communicate with each other? • “Events” on page 46 in Chapter 3, “jQuery UI Widgets” and online at http://msdn.microsoft.com/en-us/library/hh404085.aspx.
- 302. 269project silk road map How do I inherit from a base widget? • “Inheritance” on page 48 in Chapter 3, “jQuery UI Widgets” and online at http://msdn.microsoft.com/en-us/library/hh404085.aspx. UI and UX Design The design process includes the collaboration of stakeholders and team members with different skills and perspectives. If your team invests in a design process, you are more likely to create an application that users enjoy, find useful, and continue to use. Your user experience (UX) design specifies the site’s structure, the web pages it uses, what actions users can perform on each page, and the transitions that can occur after a user performs an action. Your user interface (UI) design should be unified and provide a visual signal to your audience that all your elements belong together. What is the value of design? • “Design is a Worthwhile Investment” on page 51 in Chapter 4, “Design and Layout” and online at http://msdn.microsoft.com/en-us/library/ hh404087.aspx. What are the designer roles? • “Web Project Designer Roles” on page 52 in Chapter 4, “Design and Layout” and online at http://msdn.microsoft.com/en-us/library/ hh404087.aspx. What are UX and UI design artifacts? • “Design Prototyping” on page 53 in Chapter 4, “Design and Layout” and online at http://msdn.microsoft.com/en-us/library/hh404087.aspx. What are UX considerations? • “User Experience Design Considerations” on page 54 in Chapter 4, “Design and Layout” and online at http://msdn.microsoft.com/en-us/ library/hh404087.aspx. What are UI considerations? • “User Interface Design Considerations” on page 57 in Chapter 4, “Design and Layout” and online at http://msdn.microsoft.com/en-us/ library/hh404087.aspx. What are some guidelines for assigning IDs to elements and naming CSS classes? • “CSS Organization” on page 70 in Chapter 4, “Design and Layout” and online at http://msdn.microsoft.com/en-us/library/hh404087.aspx. What are vendor-prefixed attributes? • “Vendor-Prefixed Attributes” on page 71 in Chapter 4, “Design and Layout” and online at http://msdn.microsoft.com/en-us/library/ hh404087.aspx. How do I debug CSS styles? • “Debugging” on page 72 in Chapter 4, “Design and Layout” and online at http://msdn.microsoft.com/en-us/library/hh404087.aspx.
- 303. 270 appendix b Modularity A modular design can make it easier for you to develop, test, deploy, and extend your application. Modular designs also have well-understood benefits that help you unit test your applications and make them easier to maintain over time. However, achieving a modular design in a complex JavaScript application requires specific techniques that may not be immediately obvious. What are the benefits of modularity when building hybrid-designed web applications? • “Modularity” on page 24 in Chapter 2, “Architecture” and online at http://msdn.microsoft.com/en-us/library/hh404097.aspx. • “Benefits of Modularity for Hybrid-Design Web Applications” on page 78 in Chapter 5, “Modularity” and online at http://msdn.microsoft.com/en-us/library/hh404079.aspx. What are the factors that influence a module’s boundaries? • “Factors that Influence a Modular Design” on page 80 in Chapter 5, “Modularity” and online at http://msdn.microsoft.com/en-us/library/hh404079.aspx. What are the types of modules to consider in your application? • “Functional Roles and Categories for Modules” on page 88 in Chapter 5, “Modularity” and online at http://msdn.microsoft.com/en-us/library/hh404079.aspx. When should I use a JavaScript object, a jQuery plugin, or a jQuery UI Widget? • “JavaScript Module Implementations” on page 89 in Chapter 5, “Modularity” and online at http://msdn.microsoft.com/en-us/library/hh404079.aspx. Data In rich, interactive, client-centric applications, users expect the application to respond quickly to mouse gestures, page transitions, and the saving of form data. Delays caused by data retrieval or saving data can negatively impact the user’s experience and enjoyment of the site. Therefore, carefully managed data retrieval and caching is critical to today’s web applications. How can a loosely coupled data layer simplify caching for client-side data requests? • “Data” on page 28 in Chapter 2, “Architecture” and online at http://msdn.microsoft.com/en-us/library/hh404097.aspx. • Chapter 6, “Client Data Management and Caching” on page 97 and online at http://msdn.microsoft.com/en-us/library/hh404101.aspx. Why do I need a client-side data management strategy? • “Introduction” on page 97 in Chapter 6, “Client Data Management and Caching” and online at http://msdn.microsoft.com/en-us/library/hh404101.aspx.
- 304. 271project silk road map What are the benefits of a client-side data manager and the abstraction of data requests? • “Benefits of the Data Manager Abstraction” on page 99 in Chapter 6, “Client Data Management and Caching” and online at http://msdn.microsoft.com/en-us/library/hh404101.aspx. How do I improve application performance by caching and prefetching data? • “Client-Side Data Design” on page 98 in Chapter 6, “Client Data Management and Caching” and online at http://msdn.microsoft.com/en-us/library/hh404101.aspx. Client-Side HTML Both hybrid and single-page interface web applications that do not perform full-page post backs in order to change the rendered UI must use client-side techniques for manipulating the document object model (DOM). The three client-side technologies you can use when implementing these techniques are HTML, cascading style sheets (CSS) and JavaScript. What are options and strategies for getting the right HTML to the client? • “Structure” on page 23 in Chapter 2, “Architecture” and online at http://msdn.microsoft.com/en-us/library/hh404097.aspx. • Chapter 7, “Manipulating Client-Side HTML” on page 107 and online at http://msdn.microsoft.com/en-us/library/hh404083.aspx. What are the roles and responsibilities of HTML, CSS, and JavaScript within a client application? • “The Roles and Responsibilities of Client-Side Languages” on page 107 in Chapter 7, “Manipulating Client-Side HTML” and online at http://msdn.microsoft.com/en-us/library/hh404083.aspx. How do I use jQuery to select and manipulate HTML elements? • “Selecting and Manipulating Existing HTML Elements” on page 110 in Chapter 7, “Manipulating Client-Side HTML” and online at http://msdn.microsoft.com/en-us/library/hh404083.aspx. How do I use jQuery to generate new HTML within the client? • “Generating and Loading New HTML in a Page” on page 116 in Chapter 7, “Manipulating Client-Side HTML” and online at http://msdn.microsoft.com/en-us/library/hh404083.aspx. How do I use jQuery Templates to generate new HTML within the client? • “Using Templates to Retrieve and Generate HTML” on page 118 in Chapter 7, “Manipulating Client-Side HTML” and online at http://msdn.microsoft.com/en-us/library/hh404083.aspx. How do I choose the most appropriate option when manipulating HTML? • “Structure, Appearance, and Behavior” on page 108 in Chapter 7, “Manipulating Client-Side HTML” and online at http://msdn.microsoft.com/en-us/library/hh404083.aspx.
- 305. 272 appendix b Communication In a client-side application composed of discrete objects, many of those objects need to communicate with one another. You have a few options when choosing how they do this. Generally, your options are direct method invocation, and an indirect communication mechanism such as events. What are the options for communicating between objects? • “Communication” on page 26 in Chapter 2, “Architecture” and online at http://msdn.microsoft.com/en-us/library/hh404097.aspx. • Chapter 8, “Communication” on page 123 and online at http://msdn.microsoft.com/en-us/library/hh404091.aspx. How can the Publish/Subscribe (pub/sub) pattern be used for loosely coupled communication? • “Loose Communication” on page 27 in Chapter 2, “Architecture” and online at http://msdn.microsoft.com/en-us/library/hh404097.aspx. • “Publishing and Subscribing” on page 128 in Chapter 8, “Communication” and online at http://msdn.microsoft.com/en-us/library/hh404091.aspx. How do I implement direct method invocation between widgets? • “Direct Method Invocation” on page 124 in Chapter 8, “Communication” and online at http://msdn.microsoft.com/en-us/library/hh404091.aspx. What are the advantages and disadvantages of direct method invocation? • “Direct Method Invocation” on page 124 in Chapter 8, “Communication” and online at http://msdn.microsoft.com/en-us/library/hh404091.aspx. How do I implement event triggering and handling between widgets? • “Raising and Handling Events” on page 127 in Chapter 8, “Communication” and online at http://msdn.microsoft.com/en-us/library/hh404091.aspx. How do I control dependencies between the objects triggering events and those handling them? • “Publishing and Subscribing” on page 128 in Chapter 8, “Communication” and online at http://msdn.microsoft.com/en-us/library/hh404091.aspx. When should I use the Publish/Subscribe (pub/sub) pattern? • “Finding the Right Balance” on page 128 in Chapter 8, “Communication” and online at http://msdn.microsoft.com/en-us/library/hh404091.aspx. How do I use pub/sub to manage multiple handlers and reduce coupling? • “Publishing and Subscribing” on page 128 in Chapter 8, “Communication” and online at http://msdn.microsoft.com/en-us/library/hh404091.aspx.
- 306. 273project silk road map Navigation When a user performs an action such as selecting a hyperlink or clicking a button, the application modifies the current web page without reloading the entire page, resulting in a more responsive, less jarring experience. Adherence to the Single-Page Interface pattern presents a number of navigation challenges. These challenges include managing the browser’s history mechanism so that the back button works as expected, providing direct access to a specific layout or state of the page (deep linking), and implementing anchors that allow users to bookmark the application so that it displays in a specific state. How do I solve browser history and back-button problems when the site doesn’t perform full-page reloads? • “Navigation” on page 27 in Chapter 2, “Architecture” and online at http://msdn.microsoft.com/en-us/library/hh404097.aspx. • Chapter 9, “Navigation” on page 135 and online at http://msdn.microsoft.com/en-us/library/hh404077.aspx. How do I keep users within a single-page interface? • “Supporting the Single-Page Interface Pattern” on page 136 in Chapter 9, “Navigation” and online at http://msdn.microsoft.com/en-us/library/hh404077.aspx. How do I manage hyperlinks and respond to user actions? • “Modifying Hyperlinks” on page 138 in Chapter 9, “Navigation” and online at http://msdn.microsoft.com/en-us/library/hh404077.aspx. • “Responding to User Actions” on page 143 in Chapter 9, “Navigation” and online at http://msdn.microsoft.com/en-us/library/hh404077.aspx. When do I rewrite URLs and when should I handle the click event? • “Modifying Hyperlinks” on page 138 in Chapter 9, “Navigation” and online at http://msdn.microsoft.com/en-us/library/hh404077.aspx. How do I ensure that deep linking, bookmarking, and the back button work as expected? • “Browser History and the Back Button” on page 137 in Chapter 9, “Navigation” and online at http://msdn.microsoft.com/en-us/library/hh404077.aspx. How do I coordinate and animate screen transitions? • “Animating Screen Transitions” on page 145 in Chapter 9, “Navigation” and online at http://msdn.microsoft.com/en-us/library/hh404077.aspx.
- 307. 274 appendix b Application Notifications Web applications that users consider responsive have one thing in common: they provide appropriate and timely feedback to the user. How the application displays the notifica- tions to the user is almost as important as the information itself. How do I provide unobtrusive user notification messages? • “Where Notification Messages are Displayed” on page 156 in Chapter 10, “Application Notifications” and online at http://msdn.microsoft.com/en-us/library/hh404084.aspx. How do I handle multiple simultaneous notification messages raised by the application? • “How In dividual or Multiple Notification Messages are Displayed” on page 159 in Chapter 10, “Application Notifications” What are the benefits of encapsulating the display and management of user notification in a single JavaScript object? • “Where Notification Messages are Displayed” on page 156 in Chapter 10, “Application Notifications” and online at http://msdn.microsoft.com/en-us/library/hh404084.aspx. How do I display a helpful global error page? • “Website Error Notification” on page 161 in Chapter 10, “Application Notifications” and online at http://msdn.microsoft.com/en-us/library/hh404084.aspx. How do I set up a global error handler for Ajax requests? • “User Session Timeout Notification” on page 160 in Chapter 10, “Application Notifications” and online at http://msdn.microsoft.com/en-us/library/hh404084.aspx. What are alternatives to modal dialogs for prompting users? • “Prompting Users” on page 161 in Chapter 10, “Application Notifications” and online at http://msdn.microsoft.com/en-us/library/hh404084.aspx. How do I enable application notifications on the desktop with the Pinned Sites API? • “Desktop Notifications” on page 163 in Chapter 10, “Application Notifications” and online at http://msdn.microsoft.com/en-us/library/hh404084.aspx.
- 308. 275project silk road map Server-Side Implementation Crafting a well-architected web server application requires meeting the needs of the web client while properly factoring the Microsoft® .NET Framework code on the web server. A web server application is responsible for more than just returning HTML content. Web server applications also involve data models, data access and storage, security, communi- cation, and resource management. How do I use ADO.NET Entity Framework and the Microsoft® SQL Server® Compact Edition to create a data model? • “Rapid Data Modeling Using the ADO.NET Entity Framework and SQL Server Compact” on page 175 in Chapter 11, “Server-Side Implementation” and online at http://msdn.microsoft.com/en-us/library/hh404093.aspx. How do I store loosely typed data? • “Using View Model and View Bag” on page 191 in Chapter 11, “Server-Side Implementation” and online at http://msdn.microsoft.com/en-us/library/hh404093.aspx. How do I separate concerns between my data model, business logic, and user interface? • “Composing Application Logic” on page 182 in Chapter 11, “Server-Side Implementation” and online at http://msdn.microsoft.com/en-us/library/hh404093.aspx. What are the different kinds of models in an MVC application? • “Factoring Application Code with ASP.NET MVC” on page 182 in Chapter 11, “Server-Side Implementation” and online at http://msdn.microsoft.com/en-us/library/hh404093.aspx. What are the things I should think about when designing my MVC application? • “Design Checklist for MVC Applications” on page 186 in Chapter 11, “Server-Side Implementation” and online at http://msdn.microsoft.com/en-us/library/hh404093.aspx. Should I create a business services layer? • “Creating a Business Services Layer” on page 187 in Chapter 11, “Server-Side Implementation” and online at http://msdn.microsoft.com/en-us/library/hh404093.aspx. How do I support interactive web clients with asynchronous data? • “Providing Data Asynchronously” on page 192 in Chapter 11, “Server-Side Implementation” and online at http://msdn.microsoft.com/en-us/library/hh404093.aspx. What are the different types of data that web clients request from the server and what are the differences between these types? • “Choosing a Data Format” on page 192 in Chapter 11, “Server-Side Implementation” and online at http://msdn.microsoft.com/en-us/library/hh404093.aspx.
- 309. 276 appendix b How do I manage data validation at each level of the stack? • “Data Validation” on page 195 in Chapter 11, “Server-Side Implementation” and online at http://msdn.microsoft.com/en-us/library/hh404093.aspx. How do I create custom validation attributes? • “Creating Custom Validation Attributes” on page 197 in Chapter 11, “Server-Side Implementation” and online at http://msdn.microsoft.com/en-us/library/hh404093.aspx. What other things should I consider when designing my server-side architecture? • “Other Considerations” on page 202 in Chapter 11, “Server-Side Implementation” and online at http://msdn.microsoft.com/en-us/library/hh404093.aspx. Security You should think about security threats that need to be addressed in any web application and what you should do to mitigate these threats. What are key security threats that I should address in my web application? • “Security Threats” on page 207 in Chapter 12, “Security” and online at http://msdn.microsoft.com/en-us/library/hh404095.aspx. What security features are built into ASP.NET MVC? • “Web Platform Security” on page 209 in Chapter 12, “Security” and online at http://msdn.microsoft.com/en-us/library/hh404095.aspx. How do I protect my application from Cross-Site Request Forgery (CSRF)? • “Anti-Forgery” on page 219 in Chapter 12, “Security” and online at http://msdn.microsoft.com/en-us/library/hh404095.aspx. How do I protect my application against JSON hijacking? • “JSON Hijacking Prevention” on page 220 in Chapter 12, “Security” and online at http://msdn.microsoft.com/en-us/library/hh404095.aspx. How do I secure communication between the client and server? • “Securing Communication between Client and Server” on page 221 in Chapter 12, “Security” and online at http://msdn.microsoft.com/en-us/library/hh404095.aspx. What are security modifications I should think about to adjust for changes in the deployment environment and security requirements for the application? • “Additional Security Considerations” on page 221 in Chapter 12, “Security” and online at http://msdn.microsoft.com/en-us/library/hh404095.aspx.
- 310. 277project silk road map Unit Testing Unit testing, sometimes referred to as developer testing, focuses on testing small pieces of code, such as a class, that a developer is writing. These tests are critical for helping you ensure that the pieces you build work as expected and will operate correctly when com- bined with other parts of the application. Such testing helps support management of the application over time by ensuring that changes you make don’t inadvertently affect other parts of the system. How do I get started unit testing my JavaScript code? • “JavaScript Unit Testing” on page 226 in Chapter 13, “Unit Testing Web Applications” and online at http://msdn.microsoft.com/en-us/library/hh404088.aspx. How do I get started unit testing my ASP.NET MVC code? • “Server-Side Unit Testing” on page 233 in Chapter 13, “Unit Testing Web Applications” and online at http://msdn.microsoft.com/en-us/library/hh404088.aspx. What is the arrange-act-assert unit test structure? • “Creating Unit Tests” on page 228 in Chapter 13, “Unit Testing Web Applications” and online at http://msdn.microsoft.com/en-us/library/hh404088.aspx. What are techniques to isolate my tests and components? • “Isolating Your Tests” on page 230 in Chapter 13, “Unit Testing Web Applications” and online at http://msdn.microsoft.com/en-us/library/hh404088.aspx. • “Isolating Your Components” on page 237 in Chapter 13, “Unit Testing Web Applications” and online at http://msdn.microsoft.com/en-us/library/hh404088.aspx. What are things I should consider when testing my jQuery UI Widgets? • “jQuery UI Widget Testing” on page 231 in Chapter 13, “Unit Testing Web Applications” and online at http://msdn.microsoft.com/en-us/library/hh404088.aspx. What are things I should consider when testing my ASP.NET MVC controllers? • “Testing Your ASP.NET MVC Controllers” on page 239 in Chapter 13, “Unit Testing Web Applications” and online at http://msdn.microsoft.com/en-us/library/hh404088.aspx.
- 311. 278 appendix b Automated Acceptance Testing Automated acceptance tests are tests that use code to implement a manual test. Auto- mated acceptance tests are usually written at the user interface level and can validate a high-level of functionality. How do I ensure that the UIElement properties are displayed with the correct values? • How to: Check UIElement Properties Using Coded UI Test online at http://msdn.microsoft.com/en-us/library/hh404081.aspx. How do I test the error handling capability of the application at the user level? • How to: Create an Automated Negative Test Case Using Coded UI Test online at http://msdn.microsoft.com/en-us/library/hh404089.aspx. How do I create an automated test for my web application using Coded UI Test in Microsoft Visual Studio® 2010 Premium or Ultimate edition? • How to: Create Web Client UI Test Using Coded UI Test online at http://msdn.microsoft.com/en-us/library/hh404082.aspx.
- 312. 279 Index A _applyTemplate method, 119 _statusSubscription method, 159‑160 _TemplateVehicleList template, 120 _trigger method, 47 abstraction, 99 accessibility, 60 ADO.NET Entity Framework, 175‑182 Ajax described, 5 performing requests, 101‑103 animations, 81, 85‑86 anti-forgery, 219‑220 appearance, and behavior, 108 appendix A: glossary, 255‑261 appendix B: Project Silk road map, 263‑278 application notifications, 274 automated acceptance testing, 278 client-side HTML, 271 communication, 272 data, 270‑271 immersive web applications, 264 mileage stats, 264‑267 modularity, 270 navigation, 273 security, 276 server-side implementation, 275‑276 technology choices, 264 UI and UX design, 269 unit testing, 277 widgets, 267‑268 application notifications, 155‑172 appendix B: Project Silk road map, 274 Customize Start Menu dialog box, 171 desktop notifications, 163‑171 displaying, 159‑160 initiation, 157‑159 jump list and notification icon, 168 message display, 156‑157 Pinned Sites, 164‑171 Pinned Sites feature detection, 165 Pinned Sites in Mileage Stats, 165‑171 requirement for jump list items to appear, 170‑171 user notifications, 156‑162 user prompting, 162‑163 user session timeout notification, 160‑161 website error notification, 161‑162 website pinning, 165‑167 applications, 3 immersive web applications, 264 initialization, 79 logic, 182‑186 spectrum of web applications, 2 see also application notifications; unit testing web applications application-specific data, 210 _applyTemplate method, 119 architecture, 21‑31 alternatives, 29‑30 client-side data, 98 ASP.NET input filtering, 209‑210 ASP.NET MVC controllers, 239‑241 server-side implementation, 182‑186 ASP.NET MVC Razor, 7, 186 asynchronous data, server-side implementation, 192‑194 attribute inspection, 176 AuthController, 213‑215 authentication, 210‑212 authentication sequence diagram, 215 automated acceptance testing, 278
- 313. 280 selecting and manipulating existing HTML elements, 110‑115 server-side rendering, 120‑121 showing and hiding content, 113‑114 structure, appearance, and behavior, 108 templates, 118‑121 code base maintenance, 80 color, 58 communication, 26‑27, 123‑134 appendix B: Project Silk road map, 272 direct communication, 123‑124 direct method invocation, 124‑127 loose communication, 27 loosely coupled communication, 123 method invocation helper, 125‑127 Mileage Stats, 124‑125 between modules, 94 overview, 22 Publish/Subscribe pattern, 128 Publish/Subscribe pattern example, 131‑133 Publish/Subscribe pattern in Mileage Stats, 129‑131 pubsub object, 130‑131 raising and handling events, 127‑128 securing between client and server, 221‑222 widget references, 124 community support, xxxi, 18 complex data validation, 198‑199 component isolation, 237‑239 concurrency, 205 configuration external, 93 modularity, 79 security, 212‑213 connection strings, 222 consistency, 54‑55, 60 content, 113‑114 context, 79 contributors and reviewers, xix controller actions for Ajax, 194 copyright, iv creation, 36‑37 CSS, 59, 70‑71 Customize Start Menu dialog box, 171 custom validation attributes, 197‑198 B balance and symmetry, 59 Bango, Rey, xvii‑xviii behavior, 108 behavioral modules, 88 binding handlers, 46 bridge method, 49 building considerations, 3‑7 business logic layer, 237 business services layer, 187‑189 C caching see client data management and caching callbacks, 47‑48 Charts page, 14‑15 checklist for MVC applications, 186 choice limiting, 57 class inspection, 176 client architecture technology map, 30 client data management and caching, 97‑106 abstraction, 99 Ajax request performing, 101‑103 client-side data design, 98‑99 data cache, 104‑105 data cache adding and retrieving, 104 data cache item removal, 105 data manager, 99 data request options, 100‑101 data request performing, 101 data requests, 99‑101 client-side data design, 98‑99 client-side HTML, 107‑122 adding interactive behavior to an application, 108‑109 appendix B: Project Silk road map, 271 context, 111 data- attributes, 112‑113 element attribute updating, 114‑115 fragment retrieval, 117‑118 generating and loading new HTML in a page, 116‑121 with JavaScript and jQuery, 116 JavaScript library to manipulate the DOM, 109‑110 jQuery templates, 118‑121 Mileage Stats, 117‑118 roles and responsibilities of client-side languages, 107‑109
- 314. 281index D dashboard, 12‑13 dashboard layout, 83‑84 data, 28‑29 appendix B: Project Silk road map, 270‑271 application-specific, 210 choosing a format, 192‑193 client-side data design, 98‑99 complex data validation, 198‑199 optimized data access, 180 overview, 22 providing asynchronously, 192‑194 refreshing data, 81, 87 requests, 99‑101 validation, 195‑202 validation in MVC, 195‑197 data access layer, 174‑182 data annotation attributes, 195 data- attributes, 110‑113, 190 databases creating, 178‑179 initializing, 179‑180 data cache, 104‑105 adding and retrieving, 104 item removal, 105 data management see client data management and caching data manager, 99 dataStore object, 104 DbModelBuilder parameter, 176‑178 debugging, 72 decoupled interactions, 79 DefaultOpenIdRelyingParty, 215‑216 dependency injection, 202‑203 described, 7 design checklist for MVC applications, 186 hybrid-design, 2, 78 implementing, 67‑72 prototyping, 53‑54 tools, 73 UI design considerations, 57‑60 useful design tools, 73 UX design considerations, 54‑60 web project designer roles, 52‑54 design and layout, 51‑75 accessibility, 60 anticipating usability issues, 57 balance and symmetry, 59 color, 58 consistency, 54‑55, 60 converting a mockup to HTML, 67‑70 CSS, 70‑71 debugging, 72 designing the Mileage Stats reference implementation, 60‑72 design prototyping, 53‑54 familiar metaphors, 55 flow diagrams to prototype the UX, 61‑62 functional mockups, 54 globalization, 60 image-based mockups, 54 implementing the design, 67‑72 layout aspect, 81 limit the choices, 57 localization, 60 Mileage Stats user stories, 60‑61 mood boards, 53 personas, 53 responsiveness, 55 simplicity, 60 site mockups, 64‑67 streamlining the experience, 55‑57 typography, 58‑59 UI design considerations, 57‑60 useful design tools, 73 user stories, 60‑61 UX design considerations, 54‑60 vendor-prefixed attributes, 71 web project designer roles, 52‑54 wireframes, 54 wireframes to prototype the UX, 63‑64 design tools, 73 desktop notifications, 163‑171 details layout, 84‑85 Details view, 13‑14 direct communication, 27, 123‑124 direct method invocation, 124‑127 displayTagLinks method, 40‑41 documentation, 8 exploring, 16‑18 doubleSizeMe plug-in, 91 downloading and installation, xxii-xxiv
- 315. 282 E element attribute updating, 114‑115 error management, 203‑204 events, 46 naming, 47 raising and handling, 127‑128 F familiar metaphors, 55 feedback and support, xxxi flow diagrams to prototype the UX, 61‑62 form model, 191 forms authentication sliding expiration, 216‑217 forewords, xv‑xviii fragment identifier, 137‑138 fragment retrieval, 117‑118 frameworks, 78 functional mockups, 54 functions as options, 40‑41 further reading, xxxi G getRelativeEndpointUrl method, 102‑103 getting started, xxi-xxv given-when-then template, 60‑61 globalization, 60 glossary, 255‑261 goToDetailsLayout method, 147‑149 guide exploring, 8‑15 how to use, 16-17 H hash, 137‑138 hideTagLinks method, 40‑41 Hostetler, Mike, xv‑xvi how to use this guide, 16-17 HTML generating and loading in a page, 116‑121 selecting and manipulating existing elements, 110‑115 structure, 189‑190 see also client-side HTML hybrid-design, 2, 78 I image-based mockups, 54 immersive web applications, 264 “in context”, 79 infrastructure modules, 88‑89 inheritance, 48‑49 initialization jQuery UI widgets, 38 modularity, 93‑94 input validation, 217‑219 installation, xxii-xxiv instance reuse, 42‑43 interactive behavior to an application, 108‑109 interactive web clients, 189‑192 introduction, 1‑19 IStore abstraction, 237‑238 J JavaScript described, 5 and jQuery, 116 library to manipulate the DOM, 109‑110 module implementations, 89‑92 objects, 89‑90 unit testing, 226‑232 jqPlot, xxiii jQuery, 6 and JavaScript, 116 plug-ins, 78, 89‑91 templates, 23‑24, 118‑121 jQuery UI Widget Pattern, xvi jQuery UI widgets, 32‑50 binding handlers, 46 creation, 36‑37 defining, 35‑36 defining options, 38‑43 described, 34 destruction, 38 event naming, 47 events, 46 functions as options, 40‑41 fundamentals, 34‑35 inheritance, 48‑49 initialization, 38 instance reuse, 42‑43 managing lifetime, 36‑38 modularity, 78, 89
- 316. 283index options as callbacks, 47‑48 private members, 43‑44 private methods, 43 properties, 44 pseudo selector, 43 public methods, 41‑42 static members, 44‑45 testing, 231‑232 using, 36 when options change, 39‑40 widget method, 41 JSON hijacking prevention, 220 JsonResult, 193 jump lists and notification icon, 168 requirements, xxix‑xxx K known issues, xxx L layout see design and layout layoutManager widget, 145‑146 legal, iv lifetime, 36‑38 localization, 60 loose communication, 27 loosely coupled communication, 123 M message display, 156‑157 metaphors, 55 method invocation helper, 125‑127 Microsoft, iv Mileage Stats about, xxi‑xxix appendix B: Project Silk road map, 264‑267 application security, 210‑220 client architecture technology map, 30 client-side HTML, 117‑118 communication, 124‑125 downloading, xxii high-level architecture, 173 main widgets, 92 overview, 1 user stories, 60‑61 Mileage Stats reference implementation exploring, 8 overview, 8 project and unit tests, 9 mockups converting to HTML, 67‑70 functional, 54 image-based, 54 site mockups, 64‑67 Modernizr, 6 modularity, 24‑26, 77‑96 animations, 85‑86 appendix B: Project Silk road map, 270 application initialization, 79 behavioral modules, 88 code base maintenance, 80 communicating between modules, 94 configuring, 79 in context, 79 dashboard layout, 83‑84 decoupled interactions, 79 details layout, 84‑85 externally configuring, 93 frameworks, 78 hybrid-design web applications, 78 influences on, 80‑81 infrastructure modules, 88‑89 initializing, 93‑94 JavaScript module implementations, 89‑92 JavaScript objects, 89‑90 jQuery plug-ins, 78, 89‑91 jQuery UI widgets, 78, 89 overview, 22 page layout, 81‑85 refreshing data, 87 sandboxing, 80 team-oriented development, 79 testing, 94‑95 troubleshooting and debugging, 80 UI modules, 88 widgets, 91‑92 mood boards, 53 Moq, 238‑239 mouse entering a keyword span, 250‑252 entering the pop-up list, 253 leaving a keyword span, 252‑253 leaving the pop-up list, 254 MVC view encoding, 209
- 317. 284 N navigation, 27‑28, 135‑153 animating screen transitions, 145‑152 animating vehicle tiles, 147‑150 appendix B: Project Silk road map, 273 BBQ plug-in, 138 browser history and back button, 137‑138 coordinates, 151‑152 coordinating transitions, 146‑147 hyperlinks, 138‑139 layout manager, 145‑146 modifying URLs, 139 modifying URLs when application loads, 139‑141 modifying URLs when link activated, 141‑143 overview, 22 SPI Pattern, 136‑138 user actions, 143‑145 newsgroup support, xxxi notifications desktops, 163‑171 errors, 161‑162 users, 156‑162 user session timeout, 160‑161 see also application notifications NuGet packages, xxiii O optimized data access, 180 options, 39‑40 as callbacks, 47‑48 P personas, 53 Pinned Sites, 164‑171 feature detection, 165 in Mileage Stats, 165‑171 prerequisites, xxii‑xxiv, 2 private members, 43‑44 private methods, 43 ProfileController class, 219 Project Silk, 1 downloading, xxii Project Silk road map see appendix B: Project Silk road map properties, 44 pseudo selector, 43 public methods, 41‑42 Publish/Subscribe pattern communication, 128‑131 example, 131‑133 pubsub object, 130‑131 Q QUnit, xxiv QUnit unit testing framework, 226‑228 R Razor, 7, 186 ReadMe, xxi‑xxxi repository layer, 236 Repository pattern, 180‑182 requirements, xxii for jump list items to appear, 170‑171 resetData method, 105 resources and further reading, xxxi responsiveness, 55 reviewers, xix roles, 4 web project designer roles, 52‑54 S safe lists, 218 Secure Sockets Layer (SSL), 221‑222 security, 207‑223 anti-forgery, 219‑220 appendix B: Project Silk road map, 276 ASP.NET input filtering, 209‑210 AuthController, 213‑215 authentication, 210‑212 authentication sequence diagram, 215 communication between client and server, 221‑222 configuration, 212‑213 DefaultOpenIdRelyingParty, 215‑216 deploying to a shared environment, 222 forms authentication sliding expiration, 216‑217 input validation, 217‑219 JSON hijacking prevention, 220 Mileage Stats application, 210‑220 MVC view encoding, 209 protecting application-specific data, 210 protecting connection strings, 222 safe lists, 218
- 318. 285index threats, 207‑209 web platform, 209‑210 server rendered applications, 2 server-side implementation, 173‑206 ADO.NET Entity Framework, 175‑182 appendix B: Project Silk road map, 275‑276 application logic, 182‑186 ASP.NET MVC, 182‑186 asynchronous data, 192‑194 business services layer, 187‑189 choosing a data format, 192‑193 complex data validation, 198‑199 concurrency, 205 controller actions for Ajax, 194 custom validation attributes, 197‑198 data access layer, 174‑182 data annotation attributes, 195 database creation, 178‑179 database initializing, 179‑180 data validation, 195‑202 data validation in MVC, 195‑197 DbModelBuilder parameter, 177‑178 dependency injection, 202‑203 design checklist for MVC applications, 186 error management, 203‑204 HTML structure, 189‑190 interactive web clients, 189‑192 Mileage Stats high-level architecture, 173 optimized data access, 180 Repository pattern, 180‑182 unit testing, 203 unit testing validation logic, 201‑202 validation on the client, 199‑201 ViewBag object, 191‑192 View.Model property, 191‑192 server-side rendering, 120‑121 server-side unit testing, 233‑241 shared environment, 222 simplicity, 60 single-page interface applications, 2 Single-Page Interface Pattern, 136‑138 site mockups, 64‑67 spectrum of web applications, 2 SPI Pattern, 136‑138 static members, 44‑45 static sites, 2 _statusSubscription method, 159‑160 streamlining the experience, 55‑57 structure, 23‑24 overview, 22 structure, appearance, and behavior, 108 support and feedback, xxxi system requirements, xxii T tagger widget, 40‑41 Taskbar and Start menu properties, 170‑171 team, xix team skills, 4‑5 technical support, xxxi technologies, 5‑7 choices, 264 templates, 118‑121 _TemplateVehicleList template, 120 test isolation, 230‑231 tools, 73 _trigger method, 47 typography, 58‑59 U UI design considerations, 57‑60 and UX design, 269 unit testing, 203 appendix B: Project Silk road map, 277 creation, 228‑229 validation logic, 201‑202 unit testing web applications, 225‑242 ASP.NET MVC controllers, 239‑241 component isolation, 237‑239 JavaScript unit testing, 226‑232 jQuery UI widget testing, 231‑232 QUnit unit testing framework, 226‑228 server-side unit testing, 233‑241 test isolation, 230‑231 unit test creation, 228‑229 what to test, 229‑230, 236‑237 URLs, 141‑143 usability issues, 57 useful design tools, 73 user notifications, 156‑162 users actions, 143‑145 session timeout notification, 160‑161 stories, 60‑61 UX design considerations, 54‑60
- 319. 286 V validation on the client, 199‑201 complex data validation, 198‑199 custom validation attributes, 197‑198 input validation, 217‑219 validation in MVC, 195‑197 validation logic, 201‑202 vendor-prefixed attributes, 71 ViewBag object, 191‑192 View.Model property, 191‑192 W walkthrough, 243‑246 web applications building considerations, 3-7 characteristics of, 3 spectrum of, 2 see also unit testing web applications web layer, 237 web platform security, 209‑210 web project designer roles, 52‑54 websites error notification, 161‑162 pinning, 165‑167 widgetEventPrefix property, 47 widget method, 41 Widget QuickStart, 243‑254 attaching widgets, 248 business scenario, 243 conceptual view, 247‑248 exploring, 16 mouse entering a keyword span, 250‑252 mouse entering the pop-up list, 253 mouse leaving a keyword span, 252‑253 mouse leaving the pop-up list, 254 overview, 8 walkthrough, 243‑246 widget initialization, 249 widget interactions, 249‑254 widgets, 33‑36, 248 appendix B: Project Silk road map, 267‑268 initialization, 249 interactions, 249‑254 Mileage Stats, 92 references, 124 wireframes, 54 to prototype the UX, 63‑64 X xUnit.net, 234‑236