Notes to myself

Looking for ko.utils.cloneNodes - knockout debug vs release versions

Mon, 16 Mar 2015 21:19:00 GMT

Completely my fault. I used knockout.js uility method ko.utils.cloneNodes despite the fact that it is not exported using ko.exportSymbol in the source code of the library.

Result? The mehtod name is obfuscated and is not accessible in minified version of the library. And I got a script error complaining of undefined method. Luckily it is just a development environment.

Must be more careful to not repeat the same error again. And there is even a special note regarding exactly the issue I stumbled upon on the knockout download page at http://knockoutjs.com/downloads/: ".... Don't use it for normal application development, because it exposes additional unsupported private APIs."

Visual Studio 2008 “Format Document/Selection” command and a function named “assert” in JavaScript code

Thu, 01 Apr 2010 09:32:00 GMT

Just have found some funny behavior of the Visual Studio 2008 editor. Sorry if it is already well known bug.

If you happened to have a JavaScript function named “assert” in your code (and there is pretty high likelihood in my opinion), for example something like:

function assert(x, message) {
    if (x) console.log(message);
}

then when either Format Document (Ctrl + K, Ctrl + D) or Format Selection (Ctrl + K, Ctrl + F) command is applied to the document/block containing the function, the result of the formatting will be:

functionassert(x, message) {
    if (x) console.log(message);
}

That’s it. function and assert are now joined into one solid word.

So be aware of the fact in case you suddenly start receiving strange exception in your JavaScript code: missing ; before statement functionassert(x, message)

And no, it is not an April Fool's joke. Just try for yourself.

jQuery Templates Proposal – dissecting plugin code

Sat, 20 Mar 2010 12:59:00 GMT

As you’ve probably heard, it was announced during the second-day MIX keynote that Microsoft is going to contribute to jQuery project. As a part of the contribution templating proposal was written and experimental plugin code is already available.

Having spent some time playing with the plugin, I will try in this post to dissect its code and look at how it works internally.

But why would you need to understand how it works in the first place?

Let me present my own motives (unfortunately I do not have any others):

1) Just from pure curiosity. It is a great opportunity to learn at least one templating solution from the ground up while it is simple and extremely small in its infancy. You have a rare ability to have your own pet templating plugin to bring up. Of course it is jQuery and Microsoft teams who will actually feed it, but the pleasure to see it growing and maturing will be all yours.

2) In my opinion, if you do not understand how some JavaScript framework or tool works - you must be very brave person to use it in any application that has a chance to be released to production some day. And this plugin looks like very promising templating solution to employ.

Convinced?

Then, just for starters let’s articulate the ultimate goal of the code which we are going to digest. According to the proposal we must be able to define HTML markup on our page interspersed with inline expressions and code blocks using following syntax:

    <script id="template" type="text/html">	    
	<div> 
	    Title: <span class='title'>{%= title %}</span>
    	    <hr />
		{%= 'Pages: ' + pages + '; Year: ' + year %}
	    <div class='price'>
		price: {%= price %}
	    </div>
	    Reviews: 
	    <ul>
		{% for (var i=0,review; review=reviews[i++];) { %}
		    <li class='review'>
			{%= review %}
		    </li>
		{% } %}
	    </ul>
	</div> 
    </script>

We should be able to bind either single data object or collection (JavaScript array instance) to the template and have it rendered whenever we like in any container we will specify.

I will use following sample data for the examples shown in this post:

    var books = [
	  { title: "JavaScript the Bad Parts", year: 2010, pages: 1760, price: 77.99,
	      reviews: ["Awesome", "Fantastic", "Always knew there were no good parts"]
	  },
          { title: "jQuery for plumbers", year: 2010, pages: 150, price: 10.75,
              reviews: ["The missing manual I looked for for years", "Many thanks", "What the ...!?"]
          },
	  { title: "jQuery Templates 4.0 Reference Guide",
	      year: 2012, pages: 1540, price: 40.99, reviews: []
	  }
        ];

With the template markup defined and data available we can use following command to render the template and insert generated HTML into the DOM tree:

jQuery(".container").append("#template", books);

or as one of the available alternatives:

jQuery("#template").render(books).appendTo(".container");

You can click here to see the results of template rendering.

Now, we are ready to look at the plugin code. It is available at http://github.com/nje/jquery-tmpl.

Let’s define terminology that will be used throughout the post. I will use the term jQuery wrapped set or just wrapped set to refer to the set of elements selected using jQuery function and upon which we can operate using jQuery commands. Otherwise when jQuery function or jQuery object terms are used – jQuery function itself is meant, that is the object containing static utility methods like jQuery.trim(). Ok? Great.

I am going to decompose the plugin into smaller distinctive parts to digest them bit by bit. The general outline, on which we will elaborate till the end of the post, looks like the following:

(function(jQuery) {
	// 1) prepare environment

	// 2)extend wrapped element set methods
	jQuery.fn.extend({
		// new/overridden wrapped set methods
	});

	// 3) extend static utility members
	jQuery.extend({
		// additional utility members needed
		// for the templating functionality
	});
})(jQuery);

It is not at all that scary so far. Following jQuery guidelines, plugin implementation is wrapped in anonymous function. The function is executed immediately and its only parameter is the jQuery function itself. The name of the parameter is also jQuery so we do not take advantage of the ability to define custom alias for the jQuery method – one of the purposes with which such anonymous function is usually used:

(function ($) {
    // here we can safely use $ alias in place of jQuery
})(jQuery);

But, even without the benefit of a shorter alias, having such function helps us to prevent polluting global namespace with our local variables defined within plugin body.

The code of the function can be separated into three major parts:

1) common variables’ declarations;

2) extending jQuery.fn object (i.e. prototype object for jQuery wrapped element set) with plugin-specific methods;

3) extending jQuery function itself with static utility members specific to the templating functionality

Prepare environment

The first section, which I designated as "prepare environment", is actually just a declaration of two variables: oldManip and htmlExpr:

	// Override the DOM manipulation function
	var oldManip = jQuery.fn.domManip,
	htmlExpr = /^[^<]*(<[\w\W]+>)[^>]*$/;

oldManip variable serves as a backup for original jQuery wrapped set method named domManip(). We will talk about the method later. For now it is sufficient to say that within the plugin implementation the method will be overridden, but we still need to call its original version. So we have to store the reference to the original domManip() implementation in the variable named oldManip.

htmlExpr variable is a regular expression instance which serves as a test whether the string contains HTML markup or not:

htmlExpr = /^[^<]*(<[\w\W]+>)[^>]*$/

Maybe the expression is not entirely bullet proof, but hey, if it is ok for John Resig we will use it without a moment's hesitation.

These simple steps complete our environment initialization.

Now we can move on to the second section of the template. It is where we are going to extend jQuery wrapped element set with our own methods.

Extending jQuery wrapped set

The only new method the API introduces named render(). Here we need to clarify what our instance of jQuery wrapped set refers to when the render() method is called. Is it a set of templates or a set of containers where the template will be rendered? That is who is the subject of the render() method? It is an important point and may not be immediately clear.

The syntax defined in the proposal is:

	jQuery("#template").render(data, options);

That is, according to the API, it is the template that we are rendering and the wrapped set refers to the set of templates (or, in most cases, just a single one) that we need to render using specified data and options. Later we can add the rendered template to the container were we want the resulting HTML to come to rest.

The render() method is defined as following:

	render: function( data, options ) {
		return this.map(function(i, tmpl){
			return jQuery.render( tmpl, data, options );
		});
	},

We do not have a chance at this point to dive into internals of the template rendering. It turned out, that all the actual logic is delegated to the new static utility method which is also named render(). But I promise to get to the bottom of it in due course.

For now, just take into account, that when the set of templates is rendered, each template is passed to the static utility method jQuery.render() along with the given data and options.

There is another jQuery wrapped set method which is introduced in this section of the plugin. The one we’ve touched briefly earlier. The method is named domManip() and method with such name already exists. In order to understand why we need to override it, we have to understand what its original version does.

The domManip() is a generic helper method which is used internally by several DOM manipulation methods, namely append(), prepend(), before() and after(). Majority of the work these methods need to perform before the DOM tree can actually be modified is the same regardless of the particular DOM action:

Generate document fragment node (nodeType == 11) which will contain all the nodes that should be inserted into the DOM.
Calculate valid container for the fragment. For example if we use append() method to add a <tr /> element to a table, then we have to use <tbody /> element of this table as a container for the row. Also, if we have a set of containers, then we also need to clone the fragment to stamp its content into each and every container of the set.
Take care of browsers’ bugs related to cloning the document fragment (ok, it is finally WebKit instead of long-suffering IE which is to blame in this case).

This chunk of common code is extracted into separate method named domManip(). It takes a callback method as its third parameter to carry out DOM modifications specific to the particular public method of a wrapped set. As always it is easier just to look into the code. For example, the append() method definition looks like the following:

	append: function() {
		return this.domManip(arguments, true, function( elem ) {
			if ( this.nodeType === 1 ) {
				this.appendChild( elem );
			}
		});
	},

As you can see, the method internally just calls the domManip() method with anonymous function passed as its third argument. The function is a callback method which domManip() invokes to actually perform required DOM action after the document fragment was generated and proper container for the action selected. In this case the action is as simple as appendChild.

Now we know what domManip() method does. But it still is not clear why we need to override it? The answer is - for the sake of convenience that templating API provides to the end user. The authors of the jQuery templates proposal decided that it may be useful if we could revert the point of view when we want to render the template and start our query not from the template but from the container of the resulting HTML. Thus, if we have a wrapped set of container element(s) and we need to render template somewhere within, before or after the element we can write something like:

          jQuery(".myContainer").append("#template", data, options);

Voila. The template specified by “#tempate” selector is appended to the containers specified by “.myConainer” selector using the data and options passed as second and third arguments respectively.

The same is true for the three other methods which consume domManip() internally: prepend(), before() and after().

To make this magic happen we need to hook up to the domManip() method and following code does just that:

    // This will allow us to do: .append( "template", dataObject )
    domManip: function( args ) {
	    // This appears to be a bug in the appendTo, etc. implementation
	    // it should be doing .call() instead of .apply(). See #6227
	    if ( args.length > 1 && args[0].nodeType ) {
		    arguments[0] = [ jQuery.makeArray(args) ];
	    }

	    if ( args.length >= 2 && typeof args[0] === "string" && typeof args[1] !== "string" ) {
		    arguments[0] = [ jQuery.render( args[0], args[1], args[2] ) ];
	    }
    	
	    return oldManip.apply( this, arguments );
    }

The first three lines of code have no direct relation to the plugin functionality. It just so happened that at the time when the plugin has been written the bug which affects domManip() method was discovered and fixed.

These three lines of code in our new domManip() method is just a temporary patch for the bug which is already fixed in jQuery repository.

If you are curious, what bug the code fixes, then we need to look at the definition of the following set of jQuery commands: appendTo, prependTo, insertBefore, insertAfter. They are all defined using exactly the same code (parameterized using method name) mapped to the so called “original” methods.

Just look at the following mappings:

{
	appendTo: "append",
	prependTo: "prepend",
	insertBefore: "before",
	insertAfter: "after",
	replaceAll: "replaceWith"
}

“Oiginal” methods’ names (in terms of the code) are values of the properties. When, for example, appendTo() method is called, some intermediate code just replaces the subject of the action with the object of the action (the wrapped set which should be appended with the the wrapped set which is appended to) and then the original method (append() in this case) is invoked.

That is instead of

jQuery(".myElements").appendTo(".myContainer");

we will have

jQuery(".myContainer").append(jQuery(".myElements"));

Isn’t it clever? Without writing a single line of code we can introduce a whole bunch of new methods. Ok, it is not entirely true. There actually are several lines of code to wrap this functionality. One of them, the one that performs the call looks like the following:

jQuery.fn[ original ].apply( jQuery(insert[i]), elems );

And it is where the bug was hidden. Since the apply() method is used here, the array of elements passed as a parameter to the original method will be scattered across separate arguments . That is the append() method, for example, will be called as

append(elem1, elem2, elem3, …, elemN)

while it should be

append([elem1, elem2, elem3, …, elemN]);

To fix the issue, the first three lines of the overridden domManip() method just gather all the scattered arguments back into one array wrapped in another array:

    if ( args.length > 1 && args[0].nodeType ) {
	    arguments[0] = [ jQuery.makeArray(args) ];
    }

The outer array is needed because at the end of the new domManip() method, the array is consumed by apply() method once the original version of domManip() is called:

return oldManip.apply( this, arguments );

But, as I said, this fix does not have any relation to the code of the plugin. Just wanted to ensure that you understand the mechanics under the hood (even if it is just a bug fix).

Now, eventually, lets concentrate on the code within the domManip() which enables templating API:

if ( args.length >= 2 && typeof args[0] === "string" && typeof args[1] !== "string" ) {
    arguments[0] = [ jQuery.render( args[0], args[1], args[2] ) ];
}

As you can see it is really straightforward. Since the domManip() receives all the arguments passed to one of the methods in question (append, prepend, before or after), then we can deduce that template rendering was intended by the number of the arguments (>=2) and their respective types. The first one should be either selector or HTML template string, and the second one must be a data object - array or object but definitely not a string.

Once again, as in the code of the instance render() method for a wrapped set, we see that the template rendering is performed using static utility method of jQuery function:

arguments[0] = [ jQuery.render( args[0], args[1], args[2] ) ];

and then, as I showed earlier, original version of oldManip() is called which now receives already rendered template:

return oldManip.apply( this, arguments );

That’s all for the second part of our journey through the plugin code.

I hope you are not tired yet, since now begins the part of the template that actually does something. And it is the joy of analyzing this part I wanted to share with you when started writing this post.

Extending jQuery function

Since this section of the code is relatively verbose (though still under 150 lines) we are going to dissect it the same way we did for the code of the entire plugin:

	jQuery.extend({
		render: function( tmpl, data, options ) {
			// instantiate template if it does not exist
			// and render it
		},
		
		// pre-built template functions' cache
		templates: {},

		// helper methods for template rendering 
		tmplFn: {
			html: function() { /* ... */ },
			text: function() { /* ... */ },
		},

		_: null, // string builder 
		
		// generate template function
		tmpl: function tmpl(str, data, i, options) {
			// ...
		}
	});

First, let’s define what “template” and “rendering” terms mean when used in the code and comments. If you still remember, our goal is to parse HTML markup that represents our template. The result of the parsing should be suitable for data binding. It would be better if we could reuse the template later without overhead of parsing initial HTML markup of the template again and again.

The template solves this task by generating (we will also use terms “compiling” or “building”) JavaScript function from the provided HTML markup. The function takes jQuery method and context object as its parameters and returns an array of DOM elements.

The context object has the following properties: data, dataItem, index and options: data is just that – data passed to the template rendering function; dataItem – item of the data collection which is currently being rendered; index – the index of the current data item; options – object containing custom parameters passed to the template. By default two events can be specified using the options object: rendering and rendered. We will look at the code that makes this happen later. For now it is important to note that data object can be either an array or a single object. In case single object is passed to the template rendering function, then data and dataItem properties of the context will reference the same object. index property in this case contains 0.

Plugin extends jQuery function with utility method named tmpl() for the purpose of generating reusable function (pre-built template). The code of the function is shown below:

    tmpl: function tmpl(str, data, i, options) {
	    // Generate a reusable function that will serve as a template
	    // generator (and which will be cached).

	    var fn = new Function("jQuery","$context",
		    "var $=jQuery,$data=$context.dataItem,$i=$context.index,_=$._=[];_.context=$context;" +

		    // Introduce the data as local variables using with(){}
		    "with($.tmplFn){with($data){_.push('" +

		    // Convert the template into pure JavaScript
		    str.replace(/[\r\t\n]/g, " ")
			    // protect single quotes that are within expressions
			    .replace(/'(?=[^%]*%})/g,"\t")
			    // escape other single quotes
			    .split("'").join("\\'")
			    // put back protected quotes
			    .split("\t").join("'")
			    // convert inline expressions into inline parameters
			    .replace(/{%=(.+?)%}/g, "',($1),'")
			    // convert start of code blocks into end of push()
			    .split("{%").join("');")
			    // and end of code blocks into start of push()
			    .split("%}").join("_.push('")

		    + "');}}return $(_.join('')).get();");

	    return data ? fn( jQuery, { data: null, dataItem: data, index: i, options: options } ) : fn;
    }

Are you scared? You should not be. All we need is to debug the method using the example template and data presented at the beginning of the post.

As you can see, the method creates JavaScript function by means of Function() constructor. When the tmpl() method is called, its first argument contains string with HTML markup. All the other arguments are provided for “currying”. If you are not familiar with the term then do not worry, we will talk about it later.

Now we are interested only in the first parameter – str which contains markup of the template and is used to compose the body of the compiled template (anonymous function).

To begin with, let’s see how the function would look without any markup specified:

	var fn = new Function("jQuery","$context",
		"var $=jQuery,$data=$context.dataItem,$i=$context.index,_=$._=[];_.context=$context;" +
		// Introduce the data as local variables using with(){}
		"with($.tmplFn){with($data){_.push('" +
			/// parsed markup goes here ...
		"');}}return $(_.join('')).get();");

It is not particularly intuitive, but the code actually results in the following simple function definition:

	var fn = function(jQuery, $context) {
				var $ = jQuery, 
					$data = $context.dataItem,
					$i = $context.index,
					_ = $._ =[]; 
					_.context = $context;
				
				with ($.tmplFn) { 
					with ($data) {
						_.push('');
					}
				}
				return $(_.join('')).get();
			}

Much better, and nobody is frightened. But several comments are still necessary. The function takes jQuery and context objects as its parameters. jQuery is stored in variable $. context object properties are distributed into variables $data and $i. Another important variable is the one named _ (underscore). It is initialized with an instance of array and copied to the property of jQuery object of the same name _(underscore). It is this array that will accumulate parts of HTML markup we are about to parse.

The second important part of the method is the two successive with statements. As a result of these statements objects jQuery.tmplFn and $data are added to the front of the scope chain and, since identifiers are resolved against the scope chain, we can address the members of jQuery.tmplFn and $data objects as if they were just local variables. If, for example, our data item had property named title then we could simply write:

				with ($.tmplFn) { 
					with ($data) {
						html(title);
					}
				}

html() method is defined on jQuery.tmplFn object which is also on the scope chain.

If you are still with me, my congratulations, since we’ve approached the culmination of our research and going to decipher how it is possible to get reusable templating function from HTML string. We’ve just learned that parts of the resulting template will be stored in the array named _ (underscore). Let’s track how it is being filled. This part of code (with comments removed for brevity) is shown below:

				str.replace(/[\r\t\n]/g, " ")
					.replace(/'(?=[^%]*%})/g, "\t")
					.split("'").join("\\'")
					.split("\t").join("'")
					.replace(/{%=(.+?)%}/g, "',($1),'")
					.split("{%").join("');")
					.split("%}").join("_.push('")

We are going to replace HTML string str with a sequence of _.push() calls. What is actually pushed in the array depends on the type of the markup we are dealing with.

a) If it is plain HTML markup, then we just take the text as is, enclosed within single quotes, and put it into the array.

b) If it is an inline expression marked with {%= %} characters, then we take the content of the expression as is – it is not a string any more, but executable code that should result in some HTML markup.

c) If it is a code block delimited with {% %} characters, then we do not push anything explicitly. We just finish previous push() call and start another. It is the code within the code block which will decide whether it needs something to be rendered in this part of the template or not. It can contain inner inline expression or call helper methods (text() or html()) explicitly to modify content of the templating array being built.

I know, it is not very clear so far, but once you see the algorithm in action you’ll get it at once (or slightly later).

Several preparatory tasks are needed though. First we are going to replace each of the following special characters \r\t\n with spaces. They are insignificant, besides, we will use the \t character later for our own needs. This replacement is what the first line of the code does.

	str.replace(/[\r\t\n]/g, " ")

And then, since we chose single quotes to delimit our string literals, we need to escape single quotes that may be present within our markup. There is just one subtlety. If the single quote is within inline expression or code block, it does not deserve any special treatment and should be left unescaped. To do this, we perform following sequence of steps:

1) Replace all single quotes that happen to be within inline expression or code blocks with \t character;

2) Escape all outstanding single quotes;

3) Get those single quotes within expressions back – replace \t with quote

As you can see, these preparatory steps occupy more than a half of the entire replacement sequence:

				str.replace(/[\r\t\n]/g, " ")
					.replace(/'(?=[^%]*%})/g, "\t")
					.split("'").join("\\'")
					.split("\t").join("'")

But wait, at this point you may be wondering why I am talking about replacements and escaping while there are actually just strange chain of split() and join() calls? No? Great! Because I assume that your knowledge of JavaScript is sufficient to understand that using split() + join() sequentially we’ll get an equivalent of replace() method when it used with static content (string literal) as a pattern to replace.

But it is still valid question why in the same block of code we use replace() in some cases and split()/join() in others. See below the answer provided by the author of the code (John Resig):

"... If you're searching and replacing through a string with a static search and a static replace it's faster to perform the action with .split("match").join("replace") - which seems counter-intuitive but it manages to work that way in most modern browsers. (There are changes going in place to grossly improve the performance of .replace(/match/g, "replace") in the next version of Firefox - so the previous statement won't be the case for long.)"

You can find this answer in the following post: http://ejohn.org/blog/javascript-micro-templating/. If you read through the post you can also find out where the actual roots of this “experimental plugin” are concealed (surprise, surprise).

But back to our code. As always it all becomes clearer with one simple example. Let’s use the first thee lines of the HTML template presented at the beginning of the post:

	    title: <span class='title'>{%= title %}</span>
    	    <hr />
		{%= 'pages: ' + pages + '; year:' + year %}

and execute the lines of code we already understand using this template. The resulting string is

Title: <span class=\'title\'>{%= title %}</span>           <hr />    {%= 'Pages: ' + pages + '; Year:' + year %}

No magic so far. We now have a string with some single quotes escaped and some (the ones within expressions) left as is. But we are ready for the real things and can take care of the inline expressions:

					.replace(/{%=(.+?)%}/g, "',($1),'")

As a result of this additional replacement, our sample string starts resembling JavaScript code that we can push in array:

'Title: <span class=\'title\'>',( title ),'</span>           <hr />    ',( 'Pages: ' + pages + '; Year:' + year ),'  '

and if we combine it with the rest of the code of our compiled template the result will be:

	var fn = function(jQuery, $context) {
				var $ = jQuery, 
					$data = $context.dataItem,
					$i = $context.index,
					_ = $._ =[]; 
					_.context = $context;
				
				with ($.tmplFn) { 
					with ($data) {
						_.push('Title: <span class=\'title\'>',
						( title ),
						'</span>           <hr />    ',
						( 'Pages: ' + pages + '; Year:' + year ),
						'  ');
					}
				}
				return $(_.join('')).get();
			}

It makes sense in the end. HTML markup is stored in the array as is, and expressions are calculated using properties of our data item and also pushed into the array.

The last step in the process of generating our pre-built templating function is to deal with code blocks delimited by {% %} characters. It is the last two replacement patterns that achieve the goal:

					.split("{%").join("');")
					.split("%}").join("_.push('")

The code first closes previous push() statement using "');" sequence once the opening characters of the code block {% are encountered. We always have this previous push() statement in place even if the template begins with the code block. It is because the first push() is hardcoded in the function body right after the inner with statment:

"with($.tmplFn){with($data){_.push('" +

And then we start another push statement using "_.push('" sequence when closing characters of the code block %} are encountered. Again, we do not need to worry that some push() statement might stay open since our template generation code closes the last push() explicitly:

+ "');}}return $(_.join('')).get();");

Because the whole generation code is now revealed, we are ready to process the entire template with it. If you remember, our original version of the template was:

    <script id="template" type="text/html">	    
	<div> 
	    Title: <span class='title'>{%= title %}</span>
    	    <hr />
		{%= 'Pages: ' + pages + '; Year:' + year %}
	    <div class='price'>
		price: {%= price %}
	    </div>
	    Reviews: 
	    <ul>
		{% for (var i=0,review; review=reviews[i++];) { %}
		    <li class='review'>
			{%= review %}
		    </li>
		{% } %}
	    </ul>
	</div> 
    </script>

It contains HTML markup, inline expressions and code blocks. As a result of compiling this template we will have pre-built template rendering function ready to use:

    var fn = function(jQuery, $context) {
		    var $ = jQuery, 
			    $data = $context.dataItem,
			    $i = $context.index,
			    _ = $._ =[]; 
			    _.context = $context;
		    
		    with ($.tmplFn) { 
			    with ($data) {
				    '_.push('          <div>        Title: <span class=\'title\'>',
				    ( title ),
				    '</span>           <hr />    ',
				    ( 'Pages: ' + pages + '; Year:' + year ),
				    '       <div class=\'price\'>    Price: ',
				    ( price ),
				    '       </div>       Reviews:        <ul>    '); 
				    
					for (var i=0,review; review=reviews[i++];) { 
					    _.push('        <li class=\'review\'>     ',
					    ( review ),
					    '        </li>    '); 
				       } 
				    _.push('       </ul>   </div>       ');
			    }
		    }
		    return $(_.join('')).get();
	    }

Isn’t it beautiful?!

But we still have the last line of our tmpl() function to talk about. It is where the term “currying” comes into existence:

            // Provide some basic currying to the user
            return data ? fn(jQuery, { data: null, dataItem: data, index: i, options: options }) : fn;

As you can see, the tmpl() function can either return the generated template function, or - in case data parameter is provided - the result of the template function execution using the following context object:

{ data: null, dataItem: data, index: i, options: options }

The comment for the line states that the code provides “…some basic currying to the user”.

The term “currying” basically means that we want to bind some arguments to a function and have a new function as a result which we can call later. The technique is achieved using closures. If you’ve ever used Function.prototype.bind() method of the prototype.js framework with more than one arguments applied, then you should know what I am talking about. Otherwise I will be better off to refer to the best minds of Generation JavaScript. Please use the source you are more comfortable with:

http://ejohn.org/blog/partial-functions-in-javascript/

http://www.dustindiaz.com/javascript-curry/

http://yuiblog.com/assets/pdf/zakas-projs-2ed-ch18.pdf

Frankly speaking this last line of tmpl() method code is not entirely clear to me. The reason for my doubts is that we do not actually have partially applied (curried) function in case these additional arguments are provided. We have the result of the function execution returned – the set of DOM elements. Such behavior – different types of results returned from the same method does not look accurate to me. But maybe I just did not get the higher motives of the code.

Now you should have complete understanding of how the heart of the jQuery templating plugin operates. I can only add that the best way to play with the template generation procedure is to feed different HTML templates to the jQuery.tmpl() function using Firebug console. Just start with something as simple as

jQuery.tmpl("<div>{%=title%}</div>").toString()

and, thanks to the toString() method, you’ll get complete picture of what your compiled template really is.

The last part of our journey will not require any additional mental efforts from your side. We have only one static utility method of jQuery function to talk about: jQuery.render(). On the other hand, it is the most important method from the API point of view. The code of the method is shown below:

		render: function( tmpl, data, options ) {
			var fn, node;
 
			if ( typeof tmpl === "string" ) {
				// Use a pre-defined template, if available
				fn = jQuery.templates[ tmpl ];
				if ( !fn && !htmlExpr.test( tmpl ) ) {
					// it is a selector
					node = jQuery( tmpl ).get( 0 );
				}
			} else if ( tmpl instanceof jQuery ) {
				node = tmpl.get( 0 );
			} else if ( tmpl.nodeType ) {
				node = tmpl;
			}
 
			if ( !fn && node ) {
				var elemData = jQuery.data( node );
				fn = elemData.tmpl || (elemData.tmpl = jQuery.tmpl( node.innerHTML ));
			}
 
			// We assume that if the template string is being passed directly
			// in the user doesn't want it cached. They can stick it in
			// jQuery.templates to cache it.
 
			fn = fn || jQuery.tmpl( tmpl );
 
			var rendering,
				rendered,
				context = {
					data: data,
					index: 0,
					dataItem: data,
					options: options || {}
				};
			if ( options ) {
				rendering = options.rendering;
				rendered = options.rendered;
			}
 
			function renderItem() {
				var dom = null;
				if ( !rendering || rendering( context ) !== false) {
					var dom = fn( jQuery, context );
					if ( rendered ) 
						rendered( context, dom );
				}
				return dom;
			}
 
			if ( jQuery.isArray( data ) ) {
				return jQuery.map( data, function( data, i ) {
					context.index = i;
					context.dataItem = data;
					return renderItem( );
				});
 
			} else {
				return renderItem( );
			}
		}

The first part of the code handles various possible types of the tmpl parameter:

			if ( typeof tmpl === "string" ) {
				// Use a pre-defined template, if available
				fn = jQuery.templates[ tmpl ];
				if ( !fn && !htmlExpr.test( tmpl ) ) {
					// it is a selector
					node = jQuery( tmpl ).get( 0 );
				}
			} else if ( tmpl instanceof jQuery ) {
				node = tmpl.get( 0 );
			} else if ( tmpl.nodeType ) {
				node = tmpl;
			}

This parameter can be interpreted in several different ways. If the argument is of string type, then we first assume that it is a key for the templates’ cache that can be found in new static member of jQuery object - jQuery.templates. You can manually precompile a template and cache it using jQuery.template property for future use:

jQuery.templates["books"] = jQuery.tmpl(jQuery("#template").html());

Now the template “books” can be consumed by jQuery.render() method like this:

jQuery(".titles").append(jQuery.render("books", books))

But let’s return to jQuery.render() method code. If tmpl argument is a string and jQuery.template object does not contain the property of the same name then htmlExpr regular expression is used to check whether the string contains HTML markup or not. If no traces of HTML is detected within the string then the string must contain valid selector which points to the node containing desired template markup:

node = jQuery( tmpl ).get( 0 );

If tmpl argument is not a string then we need to check whether it is an instance of jQuery wrapped element set. In such a case we just get the first element of the set as a potential container of the HTML markup:

node = tmpl.get( 0 );

Otherwise we check if tmpl references DOM element or not. If so, then again, it must be the required template container:

    } else if ( tmpl.nodeType ) {
	    node = tmpl;
    }

In case precompiled template was not found within jQuery.templates cache and we succeeded in interpreting tmpl argument as a DOM node we will try to build and cache the template using following code:

    if ( !fn && node ) {
	    var elemData = jQuery.data( node );
	    fn = elemData.tmpl || (elemData.tmpl = jQuery.tmpl( node.innerHTML ));
    }

Here the code retrieves data storage object associated with the given DOM element. If the storage already contains precompiled template (tmpl property of the data object), then this precompiled template will be used. Otherwise we generate the templating function by means of jQuery.tmpl() method using inner HTML of the template container node. In the latter case the generated template is cached in tmpl property of the data storage object associated with the DOM element for future use.

But there is still one missing case when tmpl argument passed to jQuery.render() method is a string, but it does contain HTML markup directly. The case is handled by the following line of code:

		fn = fn || jQuery.tmpl( tmpl );

The template is compiled from the HTML markup using jQuery.tmpl() method. In this case we do not cache the generated templating function since, according to comments, we assume that user does not want it cached.

The rest of the code is used to prepare context object, populate rendering and rendered variables with handler functions that can be supplied using options argument and finally render the template. Inner function renderItem() is defined to form a closure. It makes it possible for the function to gain access to the context, rendering and rendered variables when it runs:

			function renderItem() {
				var dom = null;
				if ( !rendering || rendering( context ) !== false) {
					var dom = fn( jQuery, context );
					if ( rendered ) 
						rendered( context, dom );
				}
				return dom;
			}

There is almost nothing to comment regarding the renderItem() function itself. It fires rendering and rendered events in due course. But it is still important to note that it is possible to cancel the rendering phase completely in case the rendering handler explicitly returns false.

Finally the renderItem() function is executed either for each data item in the data collection (in case data object is an instance of Array) or only once otherwise:

			if ( jQuery.isArray( data ) ) {
				return jQuery.map( data, function( data, i ) {
					context.index = i;
					context.dataItem = data;
					return renderItem( );
				});
 
			} else {
				return renderItem( );
			}

In the former case the context object is adjusted to contain correct dataItem and index prior to each iteration.

We are almost done. The only member we left untouched is tmplFn object containing pre-built functions which are available within our compiled templating function. The reason why the members of tempFn object are available within the context of generated template is the same why properties of data item can be accessed directly. By virtue of with statement. Do you remember such line in the body of the compiled template?

				with ($.tmplFn) {

It is the line that does the trick. There are currently two pre-built functions available: html() and text(). Both of them serve as a means to modify resulting templating string - push() method is called on the instance of the templating string storage:

jQuery._.push.apply( jQuery._, arguments );

In case you do not remember, we stored the reference to jQuery._ array at the beginning of the code of our generated templating function:

	var fn = function(jQuery, $context) {
				var $ = jQuery, 
					$data = $context.dataItem,
					$i = $context.index,
					_ = $._ =[]; 
					_.context = $context;

We can also access the context object within our pre-built helper functions using jQuery._.context.

The only difference between html() and text() functions is that the text() was meant to provide encoding of HTML entities:

			text: function() {
				jQuery._.push.apply( jQuery._, jQuery.map(arguments, function(str) {
					return document.createTextNode(str).nodeValue;
				}) );
			}

At the moment of this writing it does not serve its purpose because obviously

document.createTextNode(str).nodeValue

returns exactly the same text as str argument had initially. It still is not encoded.

As far as I know, plugin authors are aware of this bug.

For the time being, before some really efficient encoding algorithm is suggested we can always resort to the plain old:

return jQuery("<div>").text(str).html();

That’s all. Nothing to add. Well, actually there is but this post already exceeded all reasonable limits.

Hope this helps,

Alexei

Lazy HTML attributes wrapping in Internet Explorer

Tue, 16 Mar 2010 13:42:00 GMT

Having encountered this Internet Explorer (all versions) behavior several times previously, I eventually decided to share this most probably useless knowledge. Excuse my lengthy explanations because I am going to show the behavior along with a very simple case when one can come across it inadvertently.

Let's say I want to implement some simple templating solution in JavaScript. I wrote an HTML template with an intention to bind data to it on the client side:

Please note, that name of the “sys-template” class is just a coincidence. I do not use any ASP.NET AJAX code in this simple example.

As you can see we need to replace placeholders (property name wrapped with curly braces) with actual data. Also, as you can see, many of the placeholders are situated within attribute values and it is where the danger lies.

I am going to use <a /> element HTML as a template and replace each placeholder pattern with respective properties’ values with a little bit of jQuery like this:

You can find complete code along with the contextFormat() method definition at the end of the post.

Let’s assume that value for the name property (that we want to put in the title attribute) of the first data item is “first tooltip”. So it consists of two words. When the replacement occurred, title attribute should contain the “first tooltip” text which we are going to see as a tooltip for the <a /> element.

But let’s run the sample code in Internet Explorer and check it out. What you’ll see is that only the first word of the supposed “title” attribute’s content is shown. So, were is the rest of my attribute and what happened?

The answer is obvious once you see the result of jQuery(“.sys-template”).html() line for the given HTML markup. In IE you’ll get the following

<A id={id} class={cssClass} title={name} href="{source}" myAttr="{attr}">Link to {source}</A>

See any difference between this HTML and the one shown earlier? No? Then look carefully. While the original HTML of the <a /> element is well-formed and all the attributes are correctly quoted, when you take the same HTML back in Internet Explorer (it doesn’t matter whether you use html() method from jQuery library or IE’s innerHTML directly), you lose attributes’ quotes for some of the attributes.

Then, after replacement, we’ll get following HTML for our first data item. I marked the attribute value in question with italic:

<A id=1 class=first title=first tooltip href="first.html" myAttr="firstAttr">Link to first.html</A>

Now you can easily imagine for yourself what happens when this HTML is inserted into the document and why we do not see the second (and any subsequent words if any) of our title attribute in the tooltip.

There are still two important things to note.

The first one (and it actually the reason why I named the post “lazy wrapping” is that if value of the HTML attribute does contains spaces in the original HTML, then it WILL be wrapped with quotation marks.

For example, if I wrote following on my page (note the trailing space for the title attribute value)

<a href="{source}" title="{name} " id="{id}" myAttr="{attr}" class="{cssClass}">Link to {source}</a>

then I would have my placeholder quoted correctly and the result of the replacement would render as expected:

The second important thing to note is that there are exceptions to the lazy attributes wrapping rule in IE.

As you can see href attribute value did not contain spaces exactly as all the other attributes with placeholders, but it was still returned correctly quoted
Custom attribute myAttr is also quoted correctly when returned back from document, though its placeholder value does not contain spaces either.

Now, on account of the highly unlikely probability that you found this information useful and need a solution to the problem the aforementioned behavior introduces for Internet Explorer browser, I can suggest a simple workaround – manually quote the mischievous attributes prior the placeholder pattern is replaced. Using the code of contextFormat() method shown below, you would need to add following line right before the return statement:

result = result.replace(/=({([^}]+)})/g, '="$1"');

Below please find original sample code:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
   <title>Lazy attributes wrapping</title>
   <style type="text/css"> .sys-template { display: none; } </style>
   <script type="text/javascript" src="jquery-1.4.2.js"></script>
<script type="text/javascript">
  String.prototype.contextFormat = function(context) {
    var result = this.valueOf(), reParam = /{([^}]+)}/g;
    /// result = result.replace(/=({([^}]+)})/g, '="$1"'); // fix
    result = result.replace(reParam, function(match, prop) {
      return context.hasOwnProperty(prop) ? context[prop] : match;
    });
    return result;
  };

  var data = [
   { source: "first.html", name: "first tooltip", id: 1, attr: "firstAttr", cssClass: "first" },
   { source: "second.html", name: "second tooltip", id: 2, attr: "secondAttr", cssClass: "second" },
   { source: "third.html", name: "third tooltip", id: 3, attr: "thirdAttr", cssClass: "third" }
  ];

  jQuery(document).ready(function() {
   var list = jQuery("<ul />").appendTo(document.body),
    html = jQuery(".sys-template").html();

   jQuery.each(data, function(index) {
    jQuery("<li />").html(html.contextFormat(this)).appendTo(list);
   });

  });
</script>
</head>
<body>
<div class="sys-template">
  <a href="{source}" title="{name}" id="{id}" myAttr="{attr}"
   class="{cssClass}">Link to {source}</a>
</div>
</body>
</html>

Hook up to arbitrary HttpModule event in global.asax

Wed, 03 Mar 2010 16:59:00 GMT

First of all, if you are already aware of the technique you can use to bind an event handler to the arbitrary event of the arbitrary HttpModule registered within your application using global.asax file, then, I am terribly sorry - there is most probably nothing new in this post for you (while still you may find subtleties you did not know previously).

Otherwise, if you are like me and from time to time you stumble upon the task when you want to handle some event of some HttpModule and can't easily find a way to do it, then read on.

So, you need to handle an event (let's name it MyEvent) of some HttpModule (let's name it MyModule). Let's also assume that the event takes event arguments instance of custom type MyEventArgs.

You may find that one of the solutions suggested for the task (for example in "Pro ASP.NET 3.5 in C# 2008" book from Apress) is to register event handler within an Init() method of another HttpModule:

public void Init(HttpApplication httpApp)
{
MyModule module = httpApp.Modules["MyModule"];
module.MyEvent += MyEventHandler;
}

But there is another approach I'd like to share with you.

Of course you already know that you may handle HttpApplication instance's events using global.asax file. For example you may use Application_Start method within the file to handle Start event of HttpApplication instance.

What you might not be aware of is that using the same syntax you may handle ANY event of ANY HttpModule registered for your application. In our case it is enough to write following code in global.asax to handle event named MyEvent of HttpModule named MyModule:

protected void MyModule_MyEvent(object sender, MyEventArgs e) {
// handler implementation
}

There are several subtleties to note:

MyModule is not the name of the HttpModule class. It is the name under which the HttpModule is registered in configuration file (web.config);
Name of the module is not case sensitive within the name of the method;
Second part of the method name (name of the event - MyEvent) is not case sensitive either;
You may, if you wish, add "on" prefix (also is not case sensitive) to event name within the method name.

Let me illustrate the three last statements with examples. All the following are perfectly valid declarations for such method:

protected void MyMODULE_MyEvent(object sender, MyEventArgs e) { }

protected void MyModule_myEvent(object sender, MyEventArgs e) { }

protected void MyModule_OnMyEvent(object sender, MyEventArgs e) { }

protected void mymodule_onmyevent(object sender, MyEventArgs e) { }

And the last piece of information I wanted to share is what actually makes this magic possible. All the related logic can be found within following methods: HttpApplicationFactory.ReflectOnMethodInfoIfItLooksLikeEventHandler and HttpApplication.HookupEventHandlersForApplicationAndModules. Names of the classes and methods are self-explanatory.

Hope this helps.

Where is my Microsoft Ajax 3.5 library standalone download?

Sat, 26 Sep 2009 10:31:00 GMT

Today I visited http://www.asp.net/ajax/downloads/ page to download standalone version of Microsoft Ajax 3.5 client library and used "Download the AJAX Library" button as I surely did many times previously. The landing page contained only the following: "This page has been removed. Please visit the ASP.NET Developer Center home page for further information." But I could not find any relevant "further information" on the ASP.NET Developer Center home page. Only a link to the same http://www.asp.net/ajax/downloads/ page I came from. Could someone explain me what happened to this download?

Firefox 3. XSLT Processing Engine bug?

Fri, 20 Jun 2008 21:21:00 GMT

I stumbled upon really strange issue while researching unexpected behavior of existing web application under Firefox 3.

So, there are ultimately simplified steps to reproduce:

1. XML document:

<?xml version="1.0"?>
<items>
    <item>
        <id>1</id>
    </item>
    <item>
        <id>2</id>
    </item>
    <item>
        <id>3</id>
    </item>
</items>

2. XSL stylesheet:

<?xml version="1.0"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <xsl:output method="html" />
    <xsl:template match="item">
        <tr id="{id}">
            <td>
                <xsl:value-of select="id" />
            </td>
        </tr>
    </xsl:template>
</xsl:stylesheet>

3. Load these XML and XSL documents to Document instances.

4. Transform this XML document using given XSL stylesheet with the following code:

            var processor = new XSLTProcessor();
            processor.importStylesheet(xsl);
            var doc = processor.transformToDocument(xml);

In Firefox 2 we would get following document as a result of this utterly ordinary code:

<transformiix:result xmlns:transformiix="http://www.mozilla.org/TransforMiix">
   <TR id="1">
       <TD>1</TD>
   </TR>
   <TR id="2">
       <TD>2</TD>
   </TR>
   <TR id="3">
       <TD>3</TD>
   </TR>
</transformiix:result>

Since we used transformToDocument and there is no root node in the resulting XML fragment then we have wrapping <transformiix:result /> document element node.

But, as I said, in Firefox 3 result differs. I got following document:

<transformiix:result xmlns:transformiix="http://www.mozilla.org/TransforMiix">
   <transformiix:result>
        <TR id="1">
            <TD>1</TD>
        </TR>
        <TR id="2">
            <TD>2</TD>
        </TR>
   </transformiix:result>
   <TR id="3">
        <TD>3</TD>
   </TR>
</transformiix:result>

Do you see the difference? There is unexpected (at least to me) <transformiix:result /> element wrapping first two <tr /> elements in the resulting document.

And it gets event more interesting with an increase of the number of items in the original document. For example with four items we would get:

<transformiix:result xmlns:transformiix="http://www.mozilla.org/TransforMiix">
    <transformiix:result>
        <transformiix:result>
            <TR id="1">
                <TD>1</TD>
            </TR>
            <TR id="2">
                <TD>2</TD>
            </TR>
        </transformiix:result>
        <TR id="3">
            <TD>3</TD>
        </TR>
    </transformiix:result>
    <TR id="4">
        <TD>4</TD>
    </TR>
</transformiix:result>

And so on...

This behavior starts when the number of elements is equal to or grater than 3.

Any thoughts?

.NET Framework 1.1 Service Pack 1 and Page.RegisterStartupScript

Sat, 17 May 2008 12:36:00 GMT

First, if you are are developing exclusively ASP.NET 2.0+ applications, sorry, there is nothing interesting for you in this post.

Second, if you are involved in some ASP.NET 1.1 projects and have no plans to install new development environment, then, sorry again, there is probably no reason for you to read on either. Ok, I've done all I could to warn you against reading it. Don't blame me for wasting you time, because I am going to start from the very beginning.

One of my current projects is ASP.NET 1.1 Web Application. It is already released and rather stable. And yesterday I got new development machine on my workplace and migrated all my data to it. .NET Frameworks 1.1, 2.0, 3.0, 3.5 were preinstalled before I first logged in (thanks to our system administrators). I installed VS 2003 and SP1 for it, VS 2008, SVN client, some other necessary utilities and components. Then, updated sources from source control for the mentioned ASP.NET 1.1 Web Application and started it. Bang! Script error - some variable is undefined.

Actually there were a bunch of such errors on the page. As I intentionally mentioned earlier, the application is stable. And this particular page was not changed for quite some time.

Brief research of the generated HTML source, code-behind class and respective web controls revealed the cause of the exception: there was a sequence of similar Page.RegisterStartupScript statements which went in pairs. The first one in a pair registered some JavaScript object, and the second one - used the object in another declaration.

First I checked source control's log - no related changes. Then, the next suspect - application configuration changes that could cause such behavior. But no, all the related controls' declarations on the page are static.

Ok, code was not changed, application is working fine on QA environment. So, something is wrong with my new machine. But what?

I had a dim recollection that there is something wrong with the sequence of script registration in ASP.NET 1.1. But common sense told me that if something wrong could happen then it would had happened long ago.

Still, I opened Reflector and found such code inside RegisterScriptBlock method of System.Web.UI.Page class:

     if (scriptBlocks == null)
    {
        scriptBlocks = new HybridDictionary();
    }

As you probably well aware of, HybridDictionary changes its internal storage from ListDictionary to Hashtable starting from its ninth element. So, of course we cannot rely on any specific order of script registrations if script blocks are stored in HybridDictionary. But how did it work earlier and how the same code works on development server and QA environment without any bugs reported?

So, I copied Reflector to the development server and found following code in the same RegisterScriptBlock method that I reviewed on my machine:

    if (scriptBlocks == null)
    {
        scriptBlocks = new ListDictionary();
    }

The code was fixed. But where did the fix come from? I recalled that there is a service pack for .NET 1.1 that I installed on my old development machine several years ago. Google promptly gave me a link.

File name: NDP1.1sp1-KB867460-X86.exe, Version: 1, Date Published: 8/30/2004, Download Size: 10.2 MB

Why am I presenting all this information here? Because the fix did not help, though I was almost certain that it should. The same HybridDictionary.

That's was fiasco. My working day was over several hours ago. Finish.

But today I decided to reproduce the issue at home. Fortunately I had a virtual machine with Windows XP and fortunately the copy of .NET 1.1 System.Web.dll had the same version as the one at work (i.e. HybridDictionary is used in RegisterScriptBlock).

So I started googling again and found the second service pack. Strangely enough it has the same name (i.e. .NET Framework 1.1 Service Pack 1) though with a lengthy suffix (.NET Framework 1.1 Service Pack 1 SYSTEM.WEB.DLL and MSCOREE.DLL Security Update for Windows 2000, Windows XP, Windows 2003 Server x64/IA64 and Windows 2003 Server R2 x64/IA64) .

Like the previous service pack that I found, description for this one states that its purpose - security improvements. No mentions of ASP.NET-specific modifications. I could not find any documentation which describes the changes in detail.

But the main thing is that this second "Service Pack 1" done what I wanted. Eventually I had my ListDictionary back.

The summary is:

1) there are at least TWO patches called ".NET 1.1 Service Pack 1";

2) both of them state that they are focused on security improvements, but

3) one of them changes at least one fundamental aspect of ASP.NET 1.1 behavior.

Thank you for reading. Good luck.

Array.prototype.slice vs manual array creation

Sun, 17 Feb 2008 22:22:00 GMT

In a constant pursuit of new and more effective ways to implement common JavaScript code patterns I've recently found out (sorry for such probably trivial finding but it was a real news for me) that Array.prototype.slice method can be easily used to make instance of Array from an arguments object.
I instantly decided to use it in my current projects. Currently the same task is performed by simple iteration through members of the arguments object and filling in respective members of a new Array instance.
I was pretty sure that performance of the new variant will be significantly better. It is a native method call after all instead of interpreted JavaScript code. Nevertheless, I wanted to run simple comparison tests and wrote following code:

The code is self-explanatory. I used four arguments for method calls. 10000 iterations. An alias for Array.prototype.slice method was added to avoid unnecessary lookup.

The results were surprising. You can see them on the screenshot below.

Of the four major browsers that I tested the code against, (FF 3.0b3, IE7, Opera 9.50 Alpha and Safari 3.0.4 (Windows)) only Safari proved my initial expectations.
Why is that? Did I make some error in my test code that I can't notice?

By the way, Opera 9.5 is really fast.