Readme

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 MVC3.

To illustrate this guidance, the project includes the Mileage Stats Reference Implementation (Mileage Stats) that enables its users to track various metrics about their vehicles and fill ups. Much of the effort in building Mileage Stats was applied to the usability 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.

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 which cannot be included in the download. 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 here.
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 explained in the steps below.

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 jqPlot, 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}\MileageStats\MileageStats.Web\Scripts 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}\MileageStats\MileageStats.Web\Content folder.
5. Copy the following .js files from the \dist\plugins folder in the above folder into the {silk}\MileageStats\MileageStats.Web\Scripts folder:
   • jqplot.cursor.min.js
   • jqplot.dateAxisRenderer.min.js
   • jqplot.canvasAxisTickRenderer.min.js
   • jqplot.canvasTextRenderer.min.js

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}\MileageStats\MileageStats.Web\Scripts\tests folder.

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}\MileageStats\MileageStats.Web\Scripts\tests folder.
3. Build and run Mileage Stats, and navigate to https://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 visualize data about your cars.

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. At this point, you only have 1997,2003, 2010, 2011 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.

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:
   • 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 Scripts\MileageStats.min.js will be available.
4. Press Ctrl+F5. When you run the app, the new minified file will be served up. 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 available.

About Mileage Stats

Mileage Stats is a multi-page interactive web application whose pages are rendered without 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.

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 maintenance tasks.

Notification icon in Internet Explorer 9

Mileage Stats contains a rich chart page that allows the user to select three charts, vehicles, begin and end date, and data.

Charts in Mileage Stats

For more information about Mileage Stats, see the Silk.chm.

Written Guidance

This guidance includes a book called Project Silk: Client-side Web Development for Modern Browsers. This book covers 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. See Silk.chm for details.

View a two minute video on Mileage Stats here.

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.

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 reset the IIS Application pool configuration so it is no longer the latest. You will need to navigate to C:\Windows\Microsoft.NET\Framework64\v4.0.30319 on 64-bit computers and C:\Windows\Microsoft.NET\Framework\v4.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 DotNetOpenAuth -Project MileageStats.Web

• When upgrading from a community version of the Mileage Stats, you may encounter problems where a cached version of the JavaScript is used. If so, clear the browser's cache. In some browsers this can be accomplished with Crtl+F5.

Community

Project Silk's community site is https://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.

Next | Previous | Home | Community