Humble Code: February 2011

Tuesday, February 15, 2011

Dynamic management of JavaScript file resources in ASP.NET

JavaScript file resource management in "classic" ASP.NET (in my case, ASP 3.0 and .NET Framework 4.0) can be tricky. Ideally, JavaScript files are loaded only when needed and often must be loaded in a specific sequence to avoid null reference errors. Without careful management, JavaScript files can be loaded in the wrong sequence because the load order can be at the mercy of the .NET Framework.

Consider a scenario where there is a MasterPage with a ScriptManager, a Web Form with a Script tag and a ScriptManagerProxy, and finally a UserControl on that page with a ScriptManagerProxy. The concept is that the MasterPage ScriptManager loads JavaScript resources required by every page (e.g., jQuery), but the WebForm and UserControl load JavaScript resources only when needed. The concept has merit but in this case the design is flawed, because the .NET Framework loads the JavaScript resources in the wrong order – the JavaScript methods for the UserControl will run only if the load order is jQuery, Utilities, Root, WebPage, and CustomControl.

A good solution is to dynamically load all JavaScript resources from the MasterPage ScriptManager control. This provides fine-grained control over when and in what sequence the JS resources are loaded. The above scenario is refactored so that the MasterPage still has the ScriptManager and always loads the jQuery and Root JS resources, and the WebForm and UserControl load their JS resources in code instead of by using ScriptManagerProxy and/or Script tag controls.

Master Page design:

 <%@ Master Language="C#" AutoEventWireup="true" CodeBehind="Site1.master.cs" Inherits="ScriptManagerDemo.Site1" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>
    <asp:ContentPlaceHolder ID="head" runat="server">
    </asp:ContentPlaceHolder>
</head>
<body>
    <form id="form1" runat="server">
    <asp:ScriptManager ID="MasterPageScriptManager" runat="server">
        <Scripts>
            <asp:ScriptReference Path="~/Scripts/jquery-1.4.1.min.js" />
            <asp:ScriptReference Path="~/Scripts/Root.js" />
        </Scripts>
    </asp:ScriptManager>
    <div>
        <asp:ContentPlaceHolder ID="ContentPlaceHolder1" runat="server">
        </asp:ContentPlaceHolder>
    </div>
    </form>
</body>
</html>
 

Master Page code-behind:

 using System;
using Utilities;
 
namespace ScriptManagerDemo
{
    public partial class Site1 : System.Web.UI.MasterPage
    {
        public ScriptReferenceCollectionAdapter ScriptReferences
        {
            get { return new ScriptReferenceCollectionAdapter(this.MasterPageScriptManager.Scripts); }
        }
    }
}
 

Web Form design:

 <%@ Page Title="" Language="C#" MasterPageFile="~/Site1.Master" AutoEventWireup="true" CodeBehind="Working.aspx.cs" Inherits="ScriptManagerDemo.Working" %>
<%@ MasterType TypeName="ScriptManagerDemo.Site1" %>
<%@ Register src="WebUserControlWorking.ascx" tagname="WebUserControlWorking" tagprefix="uc1" %>
<asp:Content ID="Content1" ContentPlaceHolderID="head" runat="server">
</asp:Content>
<asp:Content ID="Content2" ContentPlaceHolderID="ContentPlaceHolder1" runat="server">
    <h1>This page is working</h1>
    <uc1:WebUserControlWorking ID="WebUserControlWorking1" runat="server" />
</asp:Content>
 

Web Form code-behind:

 using System;
namespace ScriptManagerDemo
{
    public partial class Working : System.Web.UI.Page
    {
        protected void Page_Load(object sender, EventArgs e)
        {
            this.Master.ScriptReferences.AddScriptAssembly("Utilities", "Utilities.Utilities.js", "jquery-1.4.1.min.js");
            this.Master.ScriptReferences.AddScriptPath("~/Scripts/WebPage.js", "Root.js", true);
            this.Master.ScriptReferences.AddScriptPath("~/Scripts/CustomControl.js", "WebPage.js", true);
        }
    }
}
 

ScriptReferenceCollectionAdapter class:

 using System;
using System.Text;
using System.Collections.ObjectModel;
using System.Web.UI;
using System.Reflection;
 
namespace Utilities
{
    public class ScriptReferenceCollectionAdapter
    {
        private Collection<ScriptReference> ScriptReferences { get; set; }
        private static readonly string _version = Assembly.GetExecutingAssembly().GetName().Version.ToString();
 
        public ScriptReferenceCollectionAdapter(Collection<ScriptReference> scriptReferences)
        {
            ScriptReferences = scriptReferences;
        }
 
        public void AddScriptPath(string path, string afterReferenceName = null, bool forceCacheRefresh = true)
        {
            AddScript(path, null, null, new string[] { afterReferenceName }, forceCacheRefresh);
        }
 
        public void AddScriptPath(string path, string[] afterReferenceNames = null, bool forceCacheRefresh = true)
        {
            AddScript(path, null, null, afterReferenceNames, forceCacheRefresh);
        }
 
        public void AddScriptAssembly(string assembly, string name, string afterReferenceName = null)
        {
            AddScript(null, assembly, name, new string[] { afterReferenceName });
        }
 
        public void AddScriptAssembly(string assembly, string name, string[] afterReferenceNames)
        {
            AddScript(null, assembly, name, afterReferenceNames);
        }
 
        private void AddScript(string path, string assembly, string name, string[] afterReferenceNames, bool forceCacheRefresh = false)
        {
            if (afterReferenceNames == null || afterReferenceNames.Length == 0)
                ScriptReferences.Add(CreateScriptReference(path, assembly, name, forceCacheRefresh));
            else
            {
                ScriptReference scriptRef;
                int si, ai = 0, idx = 0;
                string refName;
                do
                {
                    refName = afterReferenceNames[ai];
                    si = 0;
                    while (si < ScriptReferences.Count && idx == 0)
                    {
                        scriptRef = ScriptReferences[si];
                        if (scriptRef.Name.Contains(refName) || scriptRef.Path.Contains(refName))
                            idx = ScriptReferences.IndexOf(scriptRef) + 1;
                        si++;
                    }
                    ai++;
                } while (ai < afterReferenceNames.Length && idx == 0);
                idx = idx == 0 ? ScriptReferences.Count : idx;
                ScriptReferences.Insert(idx, CreateScriptReference(path, assembly, name, forceCacheRefresh));
            }
        }
 
        private static ScriptReference CreateScriptReference(string path, string assembly, string name, bool forceCacheRefresh)
        {
            if (string.IsNullOrEmpty(path))
                return new ScriptReference(name, assembly);
            else
            {
                if (forceCacheRefresh)
                {
                    path = string.Format("{0}?ver={1}", path, _version);
                }
                return new ScriptReference(path);
            }
        }
    }
}
 

Key Points:

Expose an instance of the ScriptReferenceCollectionAdapter class as a public property of the MasterPage (Site1) class.
Add a MasterType directive to the WebForm ASPX to gain access to the MasterPage's properties.
Load the JavaScript resources in the proper order during the WebForm's Page_Load event.
The ScriptReferenceCollectionAdapter provides the necessary methods and logic to load the JS resources in a specific sequence.
These code samples can be refactored easily into the MVP design pattern.

A bonus feature to this approach is each JS resource can be loaded with a URL query string to prevent browser caching. In the code sample above, the query value is set to be the version of the loading assembly, which should change each time the application is deployed. I got the idea for how to prevent browser caching from this nice blog post Prevent Js and Css Browser Caching Issues with ASP.NET with additional information from this Stack Overflow forum.

Get a code sample of a Visual Studio 2010 .NET 4.0 web application containing all of the above code and additional resources.

Wednesday, February 9, 2011

Javascript Module Pattern and Augmentation

I have been learning about the Module Pattern for JavaScript and have a few notes to share. Ben Cherry's post on the subject was extremely helpful and my intent here is merely to clarify a few points he made and add the concept of function augmentation.

Consider this code, which demonstrates Global Import, Module Export, and Loose Augmentation per Ben Cherry's post:

 /*global jQuery*/
var EXAMPLE = (function (my, $) {
    var _private_string = 'this string is private';
    var _privateFunc;
 
    _privateFunc = function () {
        alert('heads up: ' + _private_string);
    };
 
    my.public_string = 'this string is public';
 
    my.publicFunction = function (input) {
        alert('heads up: ' + my.public_string + input);
    };
 
    return my;
} (EXAMPLE || {}, jQuery));
 
var EXAMPLE = (function (my_root, $) {
    my_root.MyClass = {};
    my_root.MyClass.MySubClassOne = (function () {
        var my = {};
        var _sub_class_one_private = 'very private';
        my.subClassOnePublicFunction = function () {
            return 'public subclass 1';
        };
        return my;
    } ());
    my_root.MyClass.MySubClassTwo = (function () {
        var my = {};
        var _sub_class_two_private = 'also very private';
        my.subClassTwoAugmentation = EXAMPLE.publicFunction;
        EXAMPLE.publicFunction = function (input) {
            my.subClassTwoAugmentation(input);
            alert('EXAMPLE.publicFunction has been augmented');
        };
        return my;
    } ());
    return my_root;
} (EXAMPLE || {}, jQuery));
 

The first block sets up the EXAMPLE module and the second block uses Loose Augmentation to add additional functions and classes, mimicking the namespacing conventions I am comfortable with from C# development.

Notice the subClassTwoAugmentation method. This demonstrates how to augment the existing EXAMPLE.publicFunction function with additional code that will run after the original EXAMPLE.publicFunction code has completed. I needed to learn this trick so that I could chain additional functionality onto an existing event handler in my production code. I got the idea for this method from Douglas Crockford's JavaScript: The Good Parts in Chapter 4, Augmenting Types, and also from this forum post.

Tuesday, February 8, 2011

Load a Script file from any Location

My organization is developing an ASP.NET application consisting of a parent WAP project with multiple WAP sub-projects. I ran into a problem loading JavaScript files located in the parent WAP Scripts folder – the sub-project WAPs were not able to load the scripts.

There are two solutions to this problem. One answer is to use a declarative path in the script tag:

 <script type="text/javascript" language="javascript" src="<%=ResolveUrl("~/Scripts/MyScript.js")%>"></script>
 

A second answer is to use a ScriptManager (or ScriptManagerProxy) control:

 <asp:ScriptManagerProxy ID="ScriptManagerProxy1" runat="server">
    <Scripts>
        <asp:ScriptReference Path="~/Scripts/MyScript.js" />
    </Scripts>
</asp:ScriptManagerProxy>
 

Either solution appears to work for any page in the parent or any sub-project WAP. However, the ScriptManager solution is a more reliable way to ensure that all scripts are loaded in the correct sequence.

Monday, February 7, 2011

7 Javascript Best Practices I Have Learned

In a previous post I listed three books that have been great resources for learning JavaScript. Here are seven important things I have learned so far in no particular order:

Global variables can quickly become a major design problem in JavaScript. As a C# developer, at first glance I would assume this code would result in a global object with two private members:

 var MyModule = (function () {
    myPrivateProperty = 1;
    myPrivateFunction = function () {
        alert('private');
    };
} ());
 

In reality, myPrivateProperty and myPrivateFunction both are global variables. This code properly declares both variables as private:

 var MyModule = (function () {
    var myPrivateProperty = 1;
    var myPrivateFunction = function () {
        alert('private');
    };
} ());
 

There are style conventions to follow in JavaScript. The ones I list here come from the JavaScript Patterns book by Stoyan Stefanov.

Use consistent indentation (typically 4 spaces) to make your code readable.
Put the opening curly bracket on the same line as the previous statement to avoid unexpected behavior from implied semicolons.
Capitalize constructors using TitleCase, variables and functions using camelCase (or lower_case for variables to make it easier to distinguish from functions), private variables and functions using an opening underscore (e.g., _camelCase), and use all caps for CONSTANT_VALUES.

Comment your code using an API documentation format. This will allow for auto-generation of code documentation. I have adopted the YUIDoc tool conventions.

For loops must be coded carefully for maximum efficiency. As a C# developer, the following code looked good to me:

 function forLoopExample() {
    var item;
    var anArray = document.getElementsByClassName('my_class');
    for (i = 0; i < anArray.length; i++) {
        alert(item = anArray[i]);
    }
}
 

In reality there are several problems with this design:

The i variable is an implied global
The for loop queries the live DOM on every pass because it checks the element collection's length repeatedly
The use of ++ promotes "excessive trickiness"

Here is a much-improved design:

 function forLoopExample() {
    var item, i, max;
    var anArray = document.getElementsByClassName('my_class');
    for (i = 0, max = anArray.length; i < max; i += 1) {
        alert(item = anArray[i]);
    }
}
 

Eval is evil. The Javascript eval function is a security risk because it grants too much authority to the evaluated string. A better approach is to use Douglas Crockford's JSON library to evaluate text with JSON.parse() or by using the jQuery.parseJSON() method.

Minify production JavaScript using a tool like Douglas Crockford's JSMin or an online YUICompressor which removes whitespace, comments, etc. thereby significantly reducing the size of your JavaScript file.

Check your JavaScript code using JSLint which is a code quality tool that checks for many common violations such as implied globals, missing semi-colons, unused variables, unreachable code, and many more.

Good Javascript References

I have been learning Javascript as quickly as I can, focusing in particular on best practices and adaptations for .NET development including AJAX via WebMethods. I have found these three O'Reilly books to be particularly helpful:

JavaScript: The Good Parts by Douglas Crockford – great introduction to the most critical core functionality of JavaScript along with tips on what to adopt and what to avoid.
JavaScript Patterns by Stoyan Stefanov – design patterns for JavaScript. The "Gang of Four" Design Patterns book was paramount to making me a better C# developer and I'm hoping that this book will have the same impact on my JavaScript.
JQuery Cookbook by Cody Lindley – a perfect complement to the other two books, giving me real-world solutions to many common scenarios while simultaneously bringing me some familiarity with the jQuery library.

Happy reading!