• Home
• Blog
• Projects

Comments on parts of a web page

By Tom on 14-02-2007 11:00

Idea

Letting users place comment on an article of a website is nothing new. In the current age of Web 2.0, it is almost mandatory to give the visitors of your website a means to express their thoughts on what you publish on your site.

While browsing the Internet, on my quest for new mental nourishment, I came across the site of Jack Slocum, a YUI wizard (Yahoo! UI library). Instead of the regular system, where visitors put comments underneath the article, he presented them with the possibility to comment each line of his blog.

Instead of having to quote the piece of text you’re referring to, you can just place a comment next to it. Great idea. Like Borat would say: I like!

That’s why I decided to build a similar system. Here’s a link to the demo: http://www.encapsulated.org/tests/comments.htm

Functionality

On Jack Slocum’s blog, you can place a comment next to each line of text. You do so by clicking left of the line, and then a popup appears where you can enter your comment.

My system will be slightly different because I’m a bit lazy. Instead of allowing comments on each line, I only allow comments on blocks of HTML: paragraphs, pieces of code, titles, tables, lists,…

Also, instead of clicking left of the block of HTML, you simply double click on the text of the block. Then, a popup will appear.

Conditions

Minimize additional server-side code

Since I already have a working commenting system on my website, I don’t feel like writing a whole new set of PHP pages to process the input of this new commenting system. That’s why I will only allow a very minimum of new PHP code to be written. If you want to make use of (parts of) my code, you won’t have to change much to your existing code.

Unobtrusive Javascript

The biggest part of this new system will be written in Javascript. Since I’m really in favor of functionality for every visitor, the new code has to be degradable, unobtrusive… When you don’t have Javascript turned on, you should just receive the old commenting system, which works without Javascript enabled.

Approaching Jack Slocum’s system

I like how he worked with these fade in and fade out effects when a new window appears on your screen. These effects are not mandatory to create such a system, but it will be nicer for the eye. For this, I will make use of the Prototype library, in combination with Script.aculo.us.

Layout independency

The code has to be sturdy. If you make a new template for your site, with different colours, then the comments have to adjust automatically. This can be accomplished by reading all relevant CSS from the page, without hard-coding any colours.

Modifications to the original code

Identifying each block

The biggest nut to crack was how to identify each block of HTML, without making modifications to the original published text. If a visitor makes a comment on a certain paragraph, then the system has to be able to display this comment on the correct spot for all subsequent visits. Modifying the published text could lead to abuse (or extensive testing), so I don’t want to allow that.

After thinking very hard, I came with a solution: using the MD5 hash of the block as an identifier. This is how it works:

• you make a comment on a block of HTML
• in the database where the comments are saved, we also save the MD5 hash of the inner HTML of that block
• for each page load, we travel the DOM, and check if the MD5 of that element corresponds with a given MD5 hash. If this is the case, we know there was a comment for this block.

Creating an MD5 hash for an HTML block

MD5 hashes have a very low probability of collision. The chance that 1 page of my site will contain two identical MD5 hashes for 2 different blocks of HTML is incredibly small. Hence I think this is a good system to identify each HTML block, without having to modify the original HTML.

There is a drawback though. If a certain block has any comments, and you decide to change something in that block, then the MD5 hash will change. The old comments won’t be seen anymore after you updated your page, because their associated MD5 hash won’t be found anymore.

Changes in the database

The comments are stored in a database. The only update there is an extra field “mdid” to store the MD5 of the HTML block the comment reffers to. In my database design, I have also a field with the page name of my blog post. In my Javascript code, I make use of this page name. The combination of the page name and the MD5 is a good identifier for a comment on a specific block of HTML on a specific page.

Changes in the PHP code

To process the submitted comment, I call the page “postcomment.php”. There I made some changes so this page also stores the MD5 hash (mdid) in the database. If no mdid is given to the page, I assume the comment wasn’t posted via the new system, but via the old form. This is a good way to check what output I should give. I won’t give the entire code for “postcomment.php”, just some relevant parts.

Getting the mdid:

$cmdid = "";
if (isSet($_POST["mdid"]))
	$cmdid = $_POST["mdid"];

Saving it to the database (makes use of PEAR DB abstraction):

$query = "INSERT INTO " . CONFIG_tableprefix . "comments (`postid`,`creation`,`name`,`email`,`homepage`,`title`,`content`,`spam`,`mdid`) VALUES (?,?,?,?,?,?,?,?,?)";
$qvals = Array($cpostid,date("YmdHi"),$cname,$cemail,$chomepage,$ctitle,$ccontent,0,$cmdid);
$qprep = $conn->prepare($query);
$conn->execute($qprep,$qvals);

Make a distinction between regular output, and output for the AJAX calls in the Javascript:

if ($cmdid == "")
	header("Location: http://www.encapsulated.org/post/" . $urlname);
else
	die("");

Writing the code

Part 1: Loading the existing comments

Load all hashes for a page

After the page has loaded, the Javascript we’re about to write, should kick in. The first thing it should do, is load all the blocks with comments attached into an array. For this, we need to query the database, so logically we’ll have to make use of AJAX to accomplish this.

I always write an init() function. When the page is loaded, this is the first function that’s being called. Everything else starts from init().

I also try to use the singleton notation as much as possible. This means that all functionality is stored into one single Javascript variable. The advantage of this is encapsulation: all data and functions are encapsulated into one namespace, so it won’t interfere with already existing Javascript.

Here’s how the first lines look like:

var Comments = {
	init:function(){
	}
}

Init() still is empty. We’ll fill it up. Remember we’re using already existing functionality. My already existing comment form is placed inside a DIV, with id “commentform”. The already existing comments are in a DIV with id “commentlist”. So firstly we need to hide these two DIV’s from the public’s eye.

Secondly, we will load all the MD5 hashes of this page. For this we create a new function load(), and we call it in init().

Lastly, we attach an eventlistener to the body of this HTML page. The eventlistener listens for a doubleclick event on the page. When a doubleclick is detected, we show the commentform.

Code:

init:function(){
	// hide regular comments & form
	$("commentlist").hide();
	$("commentform").hide();
				
	// load all comments:
	Comments.Load();

	// attach doubleclick event:
	Comments.addEvent(document,"dblclick",Comments.detectElement);
}

The load() function will make an XMLHTTPRequest to a PHP page that will return a list of all the MD5 hashes with associated comments for this page. We save these hashes in the array comel. For this, we pass the name of the current page to the PHP page.

Load:function(){
	// 1. load MD5's of all commented blocks on this page
	var url = window.location.toString();
	url = url.split("/").last().split("#").first().split("?").first();
	new Ajax.Request("ajax_commentmds.php",{postBody:"post=" + url,onComplete:function(req){
		Comments.comel = eval('([' + req.responseText + '])');
						
		// 2. travel the DOM, and attach markers where there are comments
		Comments.travelNodes(document.documentElement.lastChild);
	}});
}

Ajax.Request, last(), first() and $ are Prototype functionality. Other Prototype functionality will be used throughout this script. I will notify you every first time I use a function from Prototype.

The code for ajax_commentmds.php looks like this:

<?php
	// configuration info
	include("config.inc.php");
	
	if (isSet($_POST["post"]))
	{
		$page = $_POST["post"];
		
		// Performing SQL query
		$query = "SELECT id FROM " . CONFIG_tableprefix . "posts WHERE urlname='" . $page . "'";
		$result = mysql_query($query) or die('Query failed: ' . mysql_error());
		$line=mysql_fetch_array($result,MYSQL_ASSOC);
		$postid = $line["id"];
		
		$query = "SELECT DISTINCT(mdid) AS mdid FROM " . CONFIG_tableprefix . "comments WHERE postid=$postid";
		$result = mysql_query($query) or die('Query failed: ' . mysql_error());
		$mdids = "";
		while($line=mysql_fetch_array($result,MYSQL_ASSOC))
		{
			if ($mdids == "")
				$mdids = "\"" . $line["mdid"] . "\"";
			else
				$mdids .= ",\"" . $line["mdid"] . "\"";
		}
		die($mdids);
	}
?>

What this code does, is selecting all the different MD5 hashes that are in the database for this specific page. Each MD5 hash represents a block of HTML code. It’s up to the Javascript to check which MD5 hash belongs to which block of HTML.

In case you’re wondering about my config file. Here is a censored version.

<?php
	/* DATABASE */
	$db_hostname = "localhost";
	$db_user = "*********";
	$db_pwd = "*********";
	$db_database = "********";
	// Connecting, selecting database
	$link = mysql_connect($db_hostname, $db_user, $db_pwd)
	   or die('Could not connect: ' . mysql_error());
	mysql_select_db($db_database) or die('Could not select database');

	@define("CONFIG_sitename","Encapsulated.org");
	@define("CONFIG_tableprefix","enc_");
?>

Search corresponding parts of the page

We now have an array with all the MD5 hashes of this page. We now need to check the DOM to know where a comment was made. For this, I made a recursive function that travels each node of the DOM, and checks if its inner HTML corresponds to an MD5 hash in our array. If so, we know that a comment was made on that specific block of HTML. In Javascript, this results to the following code:

travelNodes:function(el){
	if (el.innerHTML)
	{
		var elMD5 = MD5(el.innerHTML);
		if (Comments.comel.indexOf(elMD5) >= 0)
		{
			// use AJAX to find out the amount of comments for this MD5 marker:
			var url = window.location.toString();
			url = url.split("/").last().split("#").first().split("?").first();
			new Ajax.Request("ajax_commentcount.php",{postBody:"md=" + elMD5 + "&post=" + url,onComplete:function(req){
				Comments.createMarker(elMD5,el,req.responseText);
			}});
		}
		if (el.childNodes.length > 0)
		{
			for (var i=0;i<el.childNodes.length;i++)
			{
				Comments.travelNodes(el.childNodes[i]);
			}
		}
	}
}

travelNodes() receives a DOM element as input. The first time, we input the “body” tag, because all other elements can be found by recursively traveling the DOM from that point.

The first thing we do, is take the MD5 hash of that element’s inner HTML. A Javascript implementation of MD5 can be found on http://pajhome.org.uk/crypt/md5/md5src.html. Then we check if that MD5 is in our array of all the hashes. The function indexOf() is part of the Prototype library.

If the MD5 is found in the array, we use AJAX to find out how many comments were made on that block of HTML. And then we insert a marker with the function createMarker(). More about this function later on.

Then for each child of the current element, we need to travel it’s DOM to find more comments. This is the recursive part of the function. It calls itself.

Insert a comment marker

A comment marker looks like this: 

I have placed it left of the block of HTML it’s associated with. The “2” indicates the amount of comments on this particular block of HTML. For simplicity, I just made an image that represents a speech bubble. It is however possible to make this entirely with Javascript and CSS, using Curvy Corners.

Previously, we made an AJAX call to ajax_commentcount.php. This is the code for this page:

<?php
	// configuration info
	include("config.inc.php");
	
	if (isSet($_POST["md"]) && isSet($_POST["post"]))
	{
		$md = $_POST["md"];
		$page = $_POST["post"];
		
		// Performing SQL query
		$query = "SELECT id FROM " . CONFIG_tableprefix . "posts WHERE urlname='" . $page . "'";
		$result = mysql_query($query) or die('Query failed: ' . mysql_error());
		$line=mysql_fetch_array($result,MYSQL_ASSOC);
		$postid = $line["id"];
		
		$query = "SELECT COUNT(*) AS amount FROM " . CONFIG_tableprefix . "comments WHERE postid=$postid AND mdid='" . $md . "'";
		$result = mysql_query($query) or die('Query failed: ' . mysql_error());
		$line=mysql_fetch_array($result,MYSQL_ASSOC);
		die($line["amount"]);
	}
?>

It simply returns a number: the amount of comments for a specific page and specific MD5 hash.

The Javascript function to insert the marker on the page, needs to know 3 things: the MD5 hash of that block, the specific element in the DOM where the comment belongs to, and the amount of comments.

createMarker:function(diggest,par,amount){
	var newel = document.createElement("span");
	var elPos = Position.cumulativeOffset(par);
	newel.style.cssText = "position:absolute;top:" + (elPos[1]-5) + "px;left:" + (Element.getStyle($("main"),"margin-left").replace("px","")*1-20) + "px;font-size:10px;font-family:Verdana;font-weight:normal;text-decoration:none;background:url('../templates/theme1/images/cbal.gif') no-repeat left center;padding:3px 3px 3px 5px;cursor:pointer;width:25px;";
	newel.innerHTML = amount;
	newel.setAttribute("id",diggest);
	newel.className = "comtag";
	Comments.addEvent(newel,"click",Comments.showComments);
	document.documentElement.lastChild.appendChild(newel);
}

What we do is:

• We create a SPAN element
• We figure out the top-left position of the commented HTML code with the Prototype function Position.cumulativeOffset()
• We set some CSS for the marker, where we use Prototype functionality to fill up the property “left”. “Top” is filled up by previously mentioned Position.cumulativeOffset()
• We set the innerHTML of the marker to the amount of comments
• The ID of the marker is the MD5 hash of the commented block of HTML
• We attach a click event listener to the marker
• Lastly, we append the marker to the DOM

This is how I’ve done it to position the marker. For me it was the easiest way, because I’m already used to Prototype.

So far, we can already load all comments from the database, and insert a marker at the appropriate block of HTML. The next step is to show the corresponding comments when you click a marker.

Displaying comments

Showing comments

showComments:function(){
	var mdid = this.getAttribute("id");
	
	// if the comment form is displayed for this block, hide it first:
	var f = document.forms["addcomment"];
	if (typeof f.elements["mdid"] != "undefined")
	{
		if($("addcomment"))
		{
			if (f.elements["mdid"].value == mdid && Element.getStyle($("addcomment"),"opacity")*1 > 0)
				Comments.hideDiv((Element.getStyle($(mdid),"left").replace("px","")*1),'addcomment');
		}
	}
	
	var url = window.location.toString();
	url = url.split("/").last().split("#").first().split("?").first();
	var div;
	if (!$("showcomment"))
		div = document.createElement("div");
	else
		div = $("showcomment");
	
	div.style.cssText = "position:absolute;width:" + (Element.getStyle(document.documentElement.lastChild,"width").replace("px","")*1 / 2) + "px;height:350px;background-color:" + Element.getStyle(document.documentElement.lastChild,"background-color") + ";border:1px solid " + Element.getStyle($("main"),"border-color") + ";top:" + Element.getStyle($(mdid),"top") + ";left:" + Element.getStyle($(mdid),"left") + ";display:block;filter:alpha(opacity=0);-moz-opacity:0;opacity:0;overflow:auto;";
	
	new Ajax.Request("ajax_commentdisplay.php",{postBody:"mdid=" + mdid + "&page=" + url,onComplete:function(req){
		div.innerHTML = "<img src=\"../templates/theme1/images/btnClose.gif\" border=\"0\" title=\"close\" style=\"float:right;clear:both;margin-right:10px;cursor:pointer;\" onclick=\"Comments.hideDiv(" + (Element.getStyle($(mdid),"left").replace("px","")*1) + ",'showcomment');\" />" + req.responseText;
		if (!$("showcomment"))
		{
			document.documentElement.lastChild.appendChild(div);
			div.setAttribute("id","showcomment");
		}
		//Comments.displayComments($(mdid));
		Comments.displayDiv($(mdid),'showcomment');
	}});
}

This function creates a DIV element, with all the comments for that particular block of HTML. We create the DIV only once, and re-use it when we want to display the comments for other blocks. In the style of the DIV, we set the opacity to 0. This way, the block is created, but not yet visible. We need this for the visual effects later on.

• We first check if the comment form is displayed. If this is the case, we hide that form.
• Then we check if the DIV with comments already exists. If not, we need to create it.
• For the CSS, we use Prototype functionality to fill up certain properties.
• An AJAX request is made to fetch all the comments from the database.
• We set the inner HTML of the comment DIV: we add a “close” button, and then we display the comments.
• If this is the first creation of the comment DIV, we append it to the DOM.
• Lastly, we apply some visual effects to display the DIV.

The AJAX call to ajax_commentdisplay.php receives all the comments that are associated with a given MD5 hash from the database:

<?php
	// configuration info
	include("config.inc.php");
	
	if (isSet($_POST["page"]) && isSet($_POST["mdid"]))
	{
		$page = $_POST["page"];
		$md = $_POST["mdid"];
		
		// Performing SQL query
		$query = "SELECT id FROM " . CONFIG_tableprefix . "posts WHERE urlname='" . $page . "'";
		$result = mysql_query($query) or die('Query failed: ' . mysql_error());
		$line=mysql_fetch_array($result,MYSQL_ASSOC);
		$postid = $line["id"];
		
		$query = "SELECT * FROM " . CONFIG_tableprefix . "comments WHERE postid=$postid AND mdid='" . $md . "'";
		$result = mysql_query($query) or die('Query failed: ' . mysql_error());
		$output = "";
		$teller = 0;
		while($line=mysql_fetch_array($result,MYSQL_ASSOC))
		{
			$commentcolor = "1";
			if ($teller%2)
				$commentcolor = "2";
				$datum = $line["creation"];
				$datum = $datum[6] . $datum[7] . "-" . $datum[4] . $datum[5] . "-" . $datum[0] . $datum[1] . $datum[2] . $datum[3] . " " . $datum[8] . $datum[9] . ":" . $datum[10] . $datum[11];	
			$output .= 	"<div class=\"comment$commentcolor\"><h4>" . stripslashes($line["title"]) . "</h4>" . stripslashes($line["content"]) . "<p class=\"caption\">by " . stripslashes($line["name"]) . " on $datum</p></div>";
		}
		die($output);
	}
?>

example of how the displayed comments look like

When you hit the close button, the function hideDiv() will be called. Some effects will be applied to hide the comments. In the next section I’ll talk about the effects.

Adding effects

It is possible to simply hide and show the comments. But one of my goals was to mimic the effects of Jack Slocum’s system. For this, I am using the script.aculo.us library, which can be found on http://script.aculo.us.

The original behavior can be broken down to 3 basic steps in the script.aculo.us library:

• Fade in
• Resize
• Move

All of them have to run in parallel, thus at the same time. With script.aculo.us, this can be accomplished like this:

displayDiv:function(marker,divid){
	var xmov = (Element.getStyle(document.documentElement.lastChild,"width").replace("px","")*1 / 4)-(Element.getStyle(marker,"left").replace("px","")*1);
	new Effect.Parallel(
		[ new Effect.MoveBy($(divid), 0, xmov,
			{ sync: true,transition:Effect.Transitions.slowstop }),
		  new Effect.Opacity($(divid), 
			{ sync: true, to: 0.9, from: 0.0 } ),
		new Effect.Scale($(divid), 1000, {sync:true,scaleContent:false,scaleMode: { originalHeight: 35, originalWidth: (Element.getStyle(document.documentElement.lastChild,"width").replace("px","")*1 / 20) }})],
		{ duration: 0.7,afterFinish:function(effect){
			// scroll to the div
			$(divid).scrollTo();
		}}
	  );
}

We first determine the amount of pixels that the comment DIV has to move (from the marker to a centered position on the screen).

Then, in parallel, we apply the effects. When they are finished, 0.7 seconds later, we let the page automatically scroll to the DIV, by using the Prototype function scrollTo().

I won’t explain the syntax for script.aculo.us here. If you need more information, you can always visit their site, and consult the wiki. Everything is explained thoroughly there.

To hide the comments, we simply use a reversed functionality. This function however, doesn’t need the marker element, but the “left” property of its CSS:

hideDiv:function(markerleft,divid){
	var xmov = 0-((Element.getStyle(document.documentElement.lastChild,"width").replace("px","")*1 / 4)-markerleft);
	new Effect.Parallel(
		[ new Effect.MoveBy($(divid), 0, xmov,
			{ sync: true,transition:Effect.Transitions.slowstop }),
		  new Effect.Opacity($(divid), 
			{ sync: true, to: 0.0, from: 0.9 } ),
		new Effect.Scale($(divid), 0.001, {sync:true,scaleContent:false,scaleMode: { originalHeight: Element.getStyle($(divid),"height").replace("px","")*1, originalWidth: Element.getStyle($(divid),"width").replace("px","")*1 }})],
		{ duration: 0.7,afterFinish:function(effect){
			$(divid).hide();
		}}
	  );
}

We will re-use these effects for displaying and hiding the comment form.

Adding comments to the page

Display the comment form

The comment form should be shown whenever someone double clicks on a block of HTML. Either this block already has comments attached, or it is the first one we attach now. In init(), we already attached an event listener to the document. After a double click, the function detectElement() is executed:

detectElement:function(e){
	if (!e) var e = window.event;
	var targ;
	if (e.target) targ = e.target;
	else if (e.srcElement) targ = e.srcElement;
	if (targ.nodeType == 3) // defeat Safari bug
		targ = targ.parentNode;
	
	var blockElements = ["address","blockquote","center","code","div","dir","h1","h2","h3","h4","h5","h6","hr","pre","p","table","ol","ul","dl"]
	if (blockElements.indexOf(targ.nodeName.toLowerCase()) >= 0)
		Comments.detectComment(targ,targ);
	else
	{
		// if target = subelement of a blockElement => detect blockElement
		var targ2;
		var par = targ;
		while(targ = targ.parentNode)
		{
			if (blockElements.indexOf(targ.nodeName.toLowerCase()) >= 0)
			{
				targ2 = par;
				break;
			}
		}
		Comments.detectComment(targ,targ2);
	}
}

In the first part of the code, we try to detect which element the user clicked on. This piece of code was found on Quirksmode. I used it because it gives cross-browser code to detect the clicked element.

Next, I defined a list of block elements. Only block elements can contain comments. This is to make sure there are no in-line markers. If the clicked element (or target) is not a block element, we go back in the DOM tree, and try to find the containing block element.

Once we are sure we have a block element, the function detectComment() is called. Here, we check if the block of HTML already has comments or not:

detectComment:function(orig,par){
	if (typeof par != "undefined")
	{
		var elMD5 = MD5(par.innerHTML);
		if (!$(elMD5))
			Comments.createMarker(elMD5,par,0);
		Comments.insertComment($(elMD5));
	}
}

If it doesn’t, we first create a marker (explained in a previous section), and then we call insertComment() to show the comment form.

insertComment:function(marker){
	// check if the comment div is not displaying for this block:
	if($("showcomment"))
	{
		if (Element.getStyle(marker,"top") == Element.getStyle($("showcomment"),"top") && Element.getStyle($("showcomment"),"opacity")*1 > 0)
			Comments.hideDiv(Element.getStyle(marker,"left").replace("px","")*1,'showcomment');
	}
	
	if (!$("addcomment"))
	{
		var div = document.createElement("div");
		div.style.cssText = "position:absolute;width:" + (Element.getStyle(document.documentElement.lastChild,"width").replace("px","")*1 / 2) + "px;height:350px;background-color:" + Element.getStyle(document.documentElement.lastChild,"background-color") + ";border:1px solid " + Element.getStyle($("main"),"border-color") + ";top:" + Element.getStyle(marker,"top") + ";left:" + Element.getStyle(marker,"left") + ";display:block;filter:alpha(opacity=10);-moz-opacity:.10;opacity:.10;overflow:hidden;";
		div.setAttribute("id","addcomment");
		// append a hidden input field with the MD5 of this marker
		var f = $("commentform").getElementsByTagName("form")[0];
		var h = document.createElement("input");
		h.setAttribute("type","hidden");
		h.setAttribute("name","mdid");
		h.setAttribute("value",marker.getAttribute("id"));
		f.appendChild(h);
		// catch the submission of the form:
		for(var i=0;i<f.elements.length;i++)
		{
			if (f.elements[i].name == "btnSubmit")
			{
				f.elements[i].setAttribute("type","button");
				f.elements[i].onclick = "Comments.catchSubmit();";
				f.elements[i].setAttribute("onclick","Comments.catchSubmit()");
			}
		}
		
		div.innerHTML = "<img src=\"../templates/theme1/images/btnClose.gif\" border=\"0\" title=\"close\" style=\"float:right;clear:both;margin-right:10px;cursor:pointer;\" onclick=\"Comments.hideDiv(" + (Element.getStyle(marker,"left").replace("px","")*1) + ",'addcomment');\" />" + $("commentform").innerHTML;
		
		// otherwise there's two times the comment form, and the invisible one gets submitted (it's the first one in the dom)
		$("commentform").parentNode.removeChild($("commentform"));
		
		document.documentElement.lastChild.appendChild(div);
		//Comments.displayCommentForm(marker);
		Comments.displayDiv(marker,'addcomment');
	}
	else
	{
		var div = $("addcomment");
		div.style.cssText = "position:absolute;width:" + (Element.getStyle(document.documentElement.lastChild,"width").replace("px","")*1 / 2) + "px;height:350px;background-color:" + Element.getStyle(document.documentElement.lastChild,"background-color") + ";border:1px solid " + Element.getStyle($("main"),"border-color") + ";top:" + Element.getStyle(marker,"top") + ";left:" + Element.getStyle(marker,"left") + ";display:block;filter:alpha(opacity=0);-moz-opacity:0;opacity:0;overflow:hidden;";
		// update the hidden field with the MD5
		var f = div.getElementsByTagName("form")[0]; // the form already exists, so we need to modify it
		f.elements["mdid"].value = marker.getAttribute("id");
		//Comments.displayCommentForm(marker);
		Comments.displayDiv(marker,'addcomment');
	}
}

On the page, we already had a comment form, but one of our first actions was to hide the form. We will now copy the entire form to a new div, and remove the old one. We need to add a hidden field that contains the MD5 hash of the commented HTML block. To achieve this, insertComment() does the following:

• Hide the comments, in case they were being displayed
• If this is the first time we show a comment form, we create the containing div
• We set some CSS properties to correctly position the DIV
• We find the original comment form, and insert a hidden field with the MD5 hash
• We change the submit button to a regular button, and attach our own function
• We copy the form to the DIV we created, and we add a close button
• We delete the original form so there is no confusion in Javascript
• Lastly, we append the form to the DOM, and use visual effects to display the form
• If it was not the first time we show the form, we reposition it, change the MD5 in the hidden field, and then apply the visual effects

We make use of Prototype to correctly position the DIV, and assign the correct colors.

Catch form submission

When we click the button to submit the form, we the function catchSubmit() is triggered.

catchSubmit:function(){
	var f = document.forms["addcomment"];
	var Qstring = f.serialize();
	new Ajax.Request(f.getAttribute("action"),{postBody:Qstring,onComplete:function(req){
		if (req.responseText == "")
		{
			f.reset();
			// update the marker:
			var mdid = f.elements["mdid"].value;
			$(mdid).innerHTML = ($(mdid).innerHTML*1 + 1);
			
			// if this is the first comment of this block, then update the array with all MD5s:
			if (Comments.comel.indexOf(mdid) < 0)
				Comments.comel.push(mdid);
			
				Comments.hideDiv((Element.getStyle($(mdid),"left").replace("px","")*1),'addcomment');
		}
		else
		{
			if (req.responseText == "spam")
				location = "http://www.encapsulated.org/spam.php";
			else
				alert(req.responseText);
		}
	}});
}

Prototype has a handy function to create a correct query string from a form: form.serialize(). Now that we have the querystring, we submit it to our original PHP page to handle the form. This address is not hard coded in the function, but the function detects the correct URL from the original form.

After the comment is submitted, we add the new MD5 hash to our list in “comel”. Then we hide the form, using hideDiv(), and we increment the counter in our marker. I also added some extra code because my PHP page is able to detect spam. Well, in most cases it is.

Visual effects

We re-use the functions we implemented for showing and hiding the comments on a page.

Entire code

var Comments = {
	comel:Array(),
	init:function(){
		// hide regular comments & form
		$("commentlist").hide();
		$("commentform").hide();
		
		// load all comments:
		Comments.Load();

		// attach doubleclick event:
		Comments.addEvent(document,"dblclick",Comments.detectElement);
	},
	Load:function(){
		// 1. load MD5's of all elements of this page
		var url = window.location.toString();
		url = url.split("/").last().split("#").first().split("?").first();
		new Ajax.Request("ajax_commentmds.php",{postBody:"post=" + url,onComplete:function(req){
			if (req.responseText != "")
			{
				Comments.comel = eval('([' + req.responseText + '])');
				
				// 2. travel the DOM, and attach markers where there are comments
				Comments.travelNodes(document.documentElement.lastChild);
			}
		}});
	},
	travelNodes:function(el){
		if (el.innerHTML)
		{
			var elMD5 = MD5(el.innerHTML);
			if (Comments.comel.indexOf(elMD5) >= 0)
			{
				// use AJAX to find out the amount of comments for this MD5 marker:
				var url = window.location.toString();
				url = url.split("/").last().split("#").first().split("?").first();
				new Ajax.Request("ajax_commentcount.php",{postBody:"md=" + elMD5 + "&post=" + url,onComplete:function(req){
					Comments.createMarker(elMD5,el,req.responseText);
				}});
			}
			if (el.childNodes.length > 0)
			{
				for (var i=0;i<el.childNodes.length;i++)
				{
					Comments.travelNodes(el.childNodes[i]);
				}
			}
		}
	},
	detectElement:function(e){
		if (!e) var e = window.event;
		var targ;
		if (e.target) targ = e.target;
		else if (e.srcElement) targ = e.srcElement;
		if (targ.nodeType == 3) // defeat Safari bug
			targ = targ.parentNode;
		
		var blockElements = ["address","blockquote","center","code","div","dir","h1","h2","h3","h4","h5","h6","hr","pre","p","table","ol","ul","dl"]
		if (blockElements.indexOf(targ.nodeName.toLowerCase()) >= 0)
			Comments.detectComment(targ,targ);
		else
		{
			// if target = subelement of a blockElement => detect blockElement
			var targ2;
			var par = targ;
			while(targ = targ.parentNode)
			{
				if (blockElements.indexOf(targ.nodeName.toLowerCase()) >= 0)
				{
					targ2 = par;
					break;
				}
			}
			Comments.detectComment(targ,targ2);
		}
	},
	detectComment:function(orig,par){
		if (typeof par != "undefined")
		{
			var elMD5 = MD5(par.innerHTML);
			if (!$(elMD5))
				Comments.createMarker(elMD5,par,0);
			Comments.insertComment($(elMD5));
		}
	},
	createMarker:function(diggest,par,amount){
		var newel = document.createElement("span");
		var elPos = Position.cumulativeOffset(par);
		newel.style.cssText = "position:absolute;top:" + (elPos[1]-5) + "px;left:" + (Element.getStyle($("main"),"margin-left").replace("px","")*1-20) + "px;font-size:10px;font-family:Verdana;font-weight:normal;text-decoration:none;background:url('../templates/theme1/images/cbal.gif') no-repeat left center;padding:3px 3px 3px 5px;cursor:pointer;width:25px;";
		newel.innerHTML = amount;
		newel.setAttribute("id",diggest);
		newel.className = "comtag";
		Comments.addEvent(newel,"click",Comments.showComments);
		document.documentElement.lastChild.appendChild(newel);
	},
	insertComment:function(marker){
		// check if the comment div is not displaying for this block:
		if ($("showcomment"))
		{
			if (Element.getStyle(marker,"top") == Element.getStyle($("showcomment"),"top") && Element.getStyle($("showcomment"),"opacity")*1 > 0)
				Comments.hideDiv(Element.getStyle(marker,"left").replace("px","")*1,'showcomment');
		}
		
		if (!$("addcomment"))
		{
			var div = document.createElement("div");
			div.style.cssText = "position:absolute;width:" + (Element.getStyle(document.documentElement.lastChild,"width").replace("px","")*1 / 2) + "px;height:350px;background-color:" + Element.getStyle(document.documentElement.lastChild,"background-color") + ";border:1px solid " + Element.getStyle($("main"),"border-color") + ";top:" + Element.getStyle(marker,"top") + ";left:" + Element.getStyle(marker,"left") + ";display:block;filter:alpha(opacity=10);-moz-opacity:.10;opacity:.10;overflow:hidden;";
			div.setAttribute("id","addcomment");
			// append a hidden input field with the MD5 of this marker
			var f = $("commentform").getElementsByTagName("form")[0];
			var h = document.createElement("input");
			h.setAttribute("type","hidden");
			h.setAttribute("name","mdid");
			h.setAttribute("value",marker.getAttribute("id"));
			f.appendChild(h);
			// catch the submission of the form:
			for(var i=0;i<f.elements.length;i++)
			{
				if (f.elements[i].name == "btnSubmit")
				{
					f.elements[i].setAttribute("type","button");
					f.elements[i].onclick = "Comments.catchSubmit();";
					f.elements[i].setAttribute("onclick","Comments.catchSubmit()");
				}
			}
			
			div.innerHTML = "<img src=\"../templates/theme1/images/btnClose.gif\" border=\"0\" title=\"close\" style=\"float:right;clear:both;margin-right:10px;cursor:pointer;\" onclick=\"Comments.hideDiv(" + (Element.getStyle(marker,"left").replace("px","")*1) + ",'addcomment');\" />" + $("commentform").innerHTML;
			
			// otherwise there's two times the comment form, and the invisible one gets submitted (it's the first one in the dom)
			$("commentform").parentNode.removeChild($("commentform"));
			
			document.documentElement.lastChild.appendChild(div);
			//Comments.displayCommentForm(marker);
			Comments.displayDiv(marker,'addcomment');
		}
		else
		{
			var div = $("addcomment");
			div.style.cssText = "position:absolute;width:" + (Element.getStyle(document.documentElement.lastChild,"width").replace("px","")*1 / 2) + "px;height:350px;background-color:" + Element.getStyle(document.documentElement.lastChild,"background-color") + ";border:1px solid " + Element.getStyle($("main"),"border-color") + ";top:" + Element.getStyle(marker,"top") + ";left:" + Element.getStyle(marker,"left") + ";display:block;filter:alpha(opacity=0);-moz-opacity:0;opacity:0;overflow:hidden;";
			// update the hidden field with the MD5
			var f = div.getElementsByTagName("form")[0]; // the form already exists, so we need to modify it
			f.elements["mdid"].value = marker.getAttribute("id");
			//Comments.displayCommentForm(marker);
			Comments.displayDiv(marker,'addcomment');
		}
	},
	catchSubmit:function(){
		var f = document.forms["addcomment"];
		var Qstring = f.serialize();
		new Ajax.Request(f.getAttribute("action"),{postBody:Qstring,onComplete:function(req){
			if (req.responseText == "")
			{
				f.reset();
				// update the marker:
				var mdid = f.elements["mdid"].value;
				$(mdid).innerHTML = ($(mdid).innerHTML*1 + 1);
				
				// if this is the first comment of this block, then update the array with all MD5s:
				if (Comments.comel.indexOf(mdid) < 0)
					Comments.comel.push(mdid);
				
				Comments.hideDiv((Element.getStyle($(mdid),"left").replace("px","")*1),'addcomment');
			}
			else
			{
				if (req.responseText == "spam")
					location = "http://www.encapsulated.org/spam.php";
				else
					alert(req.responseText);
			}
		}});
	},
	displayDiv:function(marker,divid){
		var xmov = (Element.getStyle(document.documentElement.lastChild,"width").replace("px","")*1 / 4)-(Element.getStyle(marker,"left").replace("px","")*1);
		new Effect.Parallel(
			[ new Effect.MoveBy($(divid), 0, xmov,
				{ sync: true,transition:Effect.Transitions.slowstop }),
			  new Effect.Opacity($(divid), 
				{ sync: true, to: 0.9, from: 0.0 } ),
			new Effect.Scale($(divid), 1000, {sync:true,scaleContent:false,scaleMode: { originalHeight: 35, originalWidth: (Element.getStyle(document.documentElement.lastChild,"width").replace("px","")*1 / 20) }})],
			{ duration: 0.7,afterFinish:function(effect){
				// scroll to the div
				$(divid).scrollTo();
			}}
		  );
	},
	hideDiv:function(markerleft,divid){
		var xmov = 0-((Element.getStyle(document.documentElement.lastChild,"width").replace("px","")*1 / 4)-markerleft);
		new Effect.Parallel(
			[ new Effect.MoveBy($(divid), 0, xmov,
				{ sync: true,transition:Effect.Transitions.slowstop }),
			  new Effect.Opacity($(divid), 
				{ sync: true, to: 0.0, from: 0.9 } ),
			new Effect.Scale($(divid), 0.001, {sync:true,scaleContent:false,scaleMode: { originalHeight: Element.getStyle($(divid),"height").replace("px","")*1, originalWidth: Element.getStyle($(divid),"width").replace("px","")*1 }})],
			{ duration: 0.7,afterFinish:function(effect){
				$(divid).hide();
			}}
		  );
	},
	showComments:function(){
		var mdid = this.getAttribute("id");
		
		// if the comment form is displayed for this block, hide it first:
		var f = document.forms["addcomment"];
		if (typeof f.elements["mdid"] != "undefined")
		{
			if ($("addcomment"))
			{
				if (f.elements["mdid"].value == mdid && Element.getStyle($("addcomment"),"opacity")*1 > 0)
					Comments.hideDiv((Element.getStyle($(mdid),"left").replace("px","")*1),'addcomment');
			}
		}
		
		var url = window.location.toString();
		url = url.split("/").last().split("#").first().split("?").first();
		var div;
		if (!$("showcomment"))
			div = document.createElement("div");
		else
			div = $("showcomment");
		
		div.style.cssText = "position:absolute;width:" + (Element.getStyle(document.documentElement.lastChild,"width").replace("px","")*1 / 2) + "px;height:350px;background-color:" + Element.getStyle(document.documentElement.lastChild,"background-color") + ";border:1px solid " + Element.getStyle($("main"),"border-color") + ";top:" + Element.getStyle($(mdid),"top") + ";left:" + Element.getStyle($(mdid),"left") + ";display:block;filter:alpha(opacity=0);-moz-opacity:0;opacity:0;overflow:auto;";
		new Ajax.Request("ajax_commentdisplay.php",{postBody:"mdid=" + mdid + "&page=" + url,onComplete:function(req){
			div.innerHTML = "<img src=\"../templates/theme1/images/btnClose.gif\" border=\"0\" title=\"close\" style=\"float:right;clear:both;margin-right:10px;cursor:pointer;\" onclick=\"Comments.hideDiv(" + (Element.getStyle($(mdid),"left").replace("px","")*1) + ",'showcomment');\" />" + req.responseText;
			if (!$("showcomment"))
			{
				document.documentElement.lastChild.appendChild(div);
				div.setAttribute("id","showcomment");
			}
			//Comments.displayComments($(mdid));
			Comments.displayDiv($(mdid),'showcomment');
		}});
	},
	addEvent:function(obj,type,fn ){
		if ( obj.attachEvent ) {
			obj["e"+type+fn] = fn;
			obj[type+fn] = function() { obj["e"+type+fn]( window.event ); }
			obj.attachEvent( "on"+type, obj[type+fn] );
		} else {
		  if (obj.addEventListener)
			obj.addEventListener( type, fn, false );
		}
	},
	removeEvent:function( obj, type, fn ){
		if (obj.removeEventListener)
			obj.removeEventListener( type, fn, false );
		else if (obj.detachEvent)
		{
			obj.detachEvent( "on"+type, obj[type+fn] );
			obj[type+fn] = null;
			obj["e"+type+fn] = null;
		}
	}
};

Comments.addEvent(window,"load",Comments.init);

That’s it, the whole 247 lines. You will notice 2 functions at the bottom: addEvent and removeEvent. I won’t explain how these work. I just found them on Quirksmode, and they have been very useful to me.

Final thoughts and restrictions

Nested block elements

I usually don’t have nested block elements on my blog posts. So this script doesn’t take this situation in consideration. If you want to do this, you need to modify detectElement(), so it travels back in the DOM until it reaches the body of your document.

Restrict comments

The current script lets you place comments on undesired places too: the banner of your page, the menu, … It is possible to create restrictions in the script, but I haven’t implemented them, because this is only a tutorial/demonstration. I don’t intend on using this script on my current commenting system. If, however, I decide to use this, I’ll adjust it, and report all modifications back to my blog.

Opening and closing comment form

This causes a marker with 0 comments to be placed next to a specific block of HTML. To perfect the code, we should detect if an actual comment is placed. If not, we remove the marker again.

Commenting via regular form

The comments that are entered via the regular form, won’t display in the Javascript enhanced page. This is because those comments don’t have an MD5 hash associated with them. To make the script better, all these comments should be attached to the title of the article.

But I was happy I got everything working, and then I got lazy. So it isn’t implemented (yet).

Conclusion

The new system is unobtrusive. If you don’t have Javascript functionality in your browser, the regular form will still work, even after you modified your PHP pages to handle MD5 hashes.

The server side code that had to be written was kept to a minimum. Only some queries to fetch comments, and comment counts. All this could have been written in one larger file, but I chose not to do this, for demonstration purposes.

While not all of Jack Slocum’s functionality was implemented, I think I did a good job at mimicking the visual effects to show or hide the comments.

The system is only partially layout independent. Normally the colors are not hard coded, but some other CSS properties are. With some extra efforts, everything can be made independent too.

While the goals are mostly reached, some other conclusions are important too. The first one I consider is the use of Prototype and script.aculo.us.

Both these libraries are quite “big”, and they provide a lot of functionality you don’t really need. But I have to admit that once you learn working with them, you can do some fast coding. These libraries take away certain (difficult?) tasks, so you can concentrate better on what you want to do. This is very important for me.

Then there is the issue of the usefulness of this script. You can always find pros or cons for this kind of functionality. If you decide to implement this, you need to consider the context. For lengthy documents, I think it is good to make use of a script like this.

All things considered, this was a useful exercise, and maybe in the future I will use an updated version of this script. If you have any remarks, feel free to leave them (in the old comment form).

Sources and credits

• Jack Slocum's blog
• Prototype library
• Script.aculo.us
• Quirksmode
• MD5 implementation

A link to the demonstration page can be found here: http://www.encapsulated.org/tests/comments.htm