Automating the HTML5 Manifest

Jake Drew

5.00/5 (2 votes)

10 Aug 2012GPL35 min read

21.8K

How to automate the HTML5 Manifest

I have recently been working on a fairly complex web application which has the requirement to function both online and off-line. For both off-line web pages and content, the HTML5 Manifest is the best way to go for off-line functionality. However, I quickly realized that maintaining a list of all individual content items for a complex website can become very cumbersome. To address this challenge, I have automated the process of creating the manifest file. However, the file is only generated when the website is running in DEBUG mode. Once the site has been published in release mode, this process only uses the last version of the Manifest file that was created. This enhances the performance of the published website while ensuring that the manifest is up to date with all your latest website content modifications when working in DEBUG mode. In addition, the process includes several features for including or excluding certain website content by both directory and file. Manifest versioning can also be handled manually or in automated fashion depending on your requirements.

For those of you who have never experienced making an ASP.NET or MVC application available off-line before, here are the basic steps:

1. Create A Manifest File

The Manifest file is mostly a text file containing a list of all the website content (i.e. pages, images, scripts, etc.) which are required to make the website function off-line. Basically, everything contained in the Manifest will be cached on the user’s local computer so the website will function when it is not connected to the internet. My intent with this article is not to go into detail on how to manually create a Manifest file or spend a lot of time explaining each section of the Manifest file. Suffice it to say that itemizing every piece of content on your website can be very time consuming and error prone.

A Typical Manifest File Might Look Something Like This

However, if you have 500 items of content in your website, your list would be 500 items long. I will propose an automated solution to this problem later in the article.

2. Add the mime Type "text/cache-manifest" to Your Website

There are several ways to accomplish this. Two direct approaches are using C# in a Generic Handler or by adding a few lines to your web.config file that "declare" or add the mime-type. I chose the Generic Handler for this particular solution, because I was able to use the same Generic Handler to create an automated solution for generating and serving the Manifest file.

3. Add a Reference to the Manifest on any Web Page that You Would Like to be Available Off-line

The Manifest reference should be added to the <html> tag for all web pages that will be functional off-line. This was the easiest part of the process. My reference was created by pointing to the Generic Handler which is responsible for serving up the Manifest file. However, if you chose to add the Manifest mime-type to your web.config file, I believe you could also point directly at a text file which contained a valid Manifest as well. Here is what the <html> manifest tag looks like:

HTML

<html manifest="Manifest.ashx">

Manifest.ashx above is the name of the Generic Handler I created in my ASP.NET project. (Right click on your Visual Studio project name, add new item, select Generic Handler from within the Web template list).

A Simple Solution for Automating Creation of the Manifest

The following solution automates the process of creating a Manifest file and keeping it up to date. It basically works like this:

Add an empty text file to your project named Manifest.txt
Add a Generic Handler to your project named Manifest.ashx
Add the <html manifest="Manifest.ashx"> to each web page that you want to make available off-line. Once the above components have been added to your ASP.NET website, we can now begin to automate the process of managing the Manifest file.

Here’s How the Rest of the Process Will Work

We will add code to the Manifest.ashx Generic Handler file that executes each time a web page is served with the <html manifest="Manifest.ashx"> tag.

The following property with the Manifest.ashx Generic Handler class will determine if the web site is running in DEBUG or RELEASE mode.

public static bool IsDebug
{
get
{
bool debug = false;
try
{
#if DEBUG
  debug = true;
#endif
}
catch
{
debug = false;
}
return debug;
}
}

If the website is running in DEBUG mode, the program will go through every directory in the website and document each file / script / image /content item within the Manifest.txt file in the correct format.
I have also added a few "bells and whistles" to this code so we can control Manifest versioning, include only certain directory folders, exclude specific files by name, or just get everything each time a Manifest.txt file is created.
For optimal performance, I also made sure that when the web is in RELEASE mode (i.e. pushed out to your server in production for the world to see), the Generic Handler Manifest.ashx will only serve up the manifest currently located in the Manifest.txt text file. This serves two purposes:
1. Some web hosting companies (such as GoDaddy basic accounts) will not allow programs to write to files located in the website’s directory
2. There is no need to dynamically create the same Manifest file over and over again. Once the website is released, the manifest file should not change again until the next time the website is modified.

The code for the Generic Handler Manifest.ashx is located here:

http://www.jakemdrew.com/blog/manifestcode.htm

IMPORTANT

It is important to note that this project will not function optimally (or possibly at all), if you accidentally compile and publish your website in DEBUG mode and then deploy it to your web server. Be sure to publish your final results in Release mode, or the project will dynamically generate the site Manifest each time time an off-line page is accessed. This will typically slow down your website response times, and it may not work at all if your web hosting service does not give your programs write access to the website directory (this is typically the case with GoDaddy).

License

This article, along with any associated source code and files, is licensed under The GNU General Public License (GPLv3)