Dot Comments iBlog Tutorial

This tutorial shows how to integrate .mac comments using iBlog, my weblog editor of choice. If you use a different weblog editor, please see the general tutorial.

Step 1: Add HTML structure to your weblog entry pages

You'll probably want separate comments for each entry on your weblog. To do this, navigate to ~/Library/Application Support/iBlog/TemplateSets/ , where ~ is your home folder. Now is a good time to choose which template set you'll want to modify.

If you've never modified a template set before, then simply duplicate one of the folders in the TemplateSets folder. You'll probably want to duplicate the one that you're already using. To find out which one that is, launch iBlog, and double-click on the folder for your blog in the source list on the left. Then switch to the "Display Settings" tab, and the template set you are currently using will show up in the second popup from the bottom.

Once you figure out which template set you're going to modify, go back to the TemplateSets folder in the Finder and open up the folder for the template set you're going to modify. Then, open the file named "EntryPage.txt". Place the following code in the HEAD tag of each entry for which you want to use comments:

<script language="javascript" type="text/javascript"><!--
  var GUID = '<$EntryCategoryUUID$>-<$EntryUUID$>';
  var commentsActivated = true;
--></script>

The GUID variable doesn't actually do anything (as far as I can tell), but the commentsActivated variable tells .mac to enable comments for the current page. These variables will be used by the JavaScript that powers the commenting system.

The following HTML markup is where comments actually get rendered. You'll notice that it's just a bunch of div tags. The JavaScript that powers the commenting system dynamically gets references to the div tags here and renders the comments when the JavaScript code is called. You'll need to place the following code somewhere within the BODY tag of your EntryPage.txt file. Typically, this will fall somewhere within the DIV tag that has an id of "main_content".

	<div>
		<div id="comment_layer">
			<div id="comment_title">
				<div class="graphic_textbox_style_default" id="id2">
					<div>
						<div class="graphic_textbox_layout_style_default">
							<div class="paragraph Comment_Count"><span><span id="count_0"></span></span><span> </span><span id="manage_comments_0" class="light"></span></div>
						</div>
					</div>
				</div>
			</div>
			<div id="comment_list"></div>
			<div id="comment_footer">
				<div class="graphic_textbox_style_default" id="id3">
					<div>
						<div class="graphic_textbox_layout_style_default">
							<div class="paragraph Comment_Add_A_Comment"><span id="post_link_0"></span></div>
						</div>
					</div>
				</div>
			</div>
		</div>
	</div>

Finally, the body tag needs to be include the following onload function:

<body onload="initComments();">

Save your EntryPage.txt file.

Step 2: Add HTML structure to your main weblog page

Many main weblog pages include comment counters, showing how many comments have been written for the entry, even if the comments don't directly appear on the main page. To accomplish this, you'll need to modify the HTML of your main weblog page. To do this, go back to the folder for your template set, and open the file called "BlogPage.txt".

Do a search for the "ForEachEntry" tag. The following code needs to be placed somewhere within the starting ForEachEntry tag and the ending ForEachEntry tag:

<script language="JavaScript" type="text/javascript">var entryURLs = {
    'index.html' : {}
};
writeScriptLink('<$EntryCategoryUUID$>/<$EntryUUID$>/index.html');</script>
<script language="JavaScript" type="text/javascript"> initSummaryComments('<$EntryCategoryUUID$>/<$EntryUUID$>/index.html');</script>

Step 3: Add supporting JavaScript routines to your template files.

Now you need to add certain functions to the JavaScript file that iBlog uses for your weblogs. To do this, navigate to ~/Library/Application Support/iBlog/Javascript/ in the Finder. Open up the file named "CommonLib.js". You might want to make a backup copy of CommonLib.js before you modify it.

Now, go to the URL http://www.mac.com/1/up/comments/scripts/comments.js and copy the entire contents of this file. Paste it to the bottom of your CommonLib.js file. (This step is necessary if you plan to publish your weblog to the homepage.mac.com URL; that is, if your weblog folder resides within the "Sites" folder on your iDisk. If you want to use the newer web.mac.com subdomain and put your weblog files inside the "Web" folder on your iDisk, you can simply link to the script file on the mac.com server directly. Please note, using the web.mac.com subdomain is not advised.)

Once you've pasted the contents of comments.js into your CommonLib.js file, you have to make two small tweaks. Find the following line:

var commentsURL = location.pathname + '?wsc=entry.js&ts=' + new Date().getTime();

Change it to this:

var commentsURL = 'http://web.mac.com' + location.pathname + '?wsc=entry.js&ts=' + new Date().getTime();

Then find this line:

JSONScript.setAttribute('src',location.pathname + '?wsc=entry.js&ts=' + new Date().getTime());

and change it to this:

JSONScript.setAttribute('src','http://web.mac.com' + location.pathname + '?wsc=entry.js&ts=' + new Date().getTime());

This will allow your weblog on the homepage.mac.com URL to retrieve comments from the web.mac.com subdomain, the only subdomain of mac.com that the comments system currently supports.

Now, add the following code to the bottom of the CommonLib.js file as well:

var time = new Date().getTime();

var entryURLs = {
    'index.html' : {}
};

var commentsActivated = true;

function writeScriptLink(url)
{
	var location_array = location.pathname.split('/');
	var amended_location_string = '';
	var i = 0;
	var count = location_array.length;
	for (i = 0; i < (count-1); i++) {
		if (location_array[i] != '') amended_location_string = amended_location_string + location_array[i] + '/';
	}
	document.write('<script src="' + 'http://web.mac.com/' + amended_location_string + url + '?wsc=summary.js&ts=' + time + '" type="text/javascript"></script>');
}

function initSummaryComments(url) 
{
	setLocale();
	var commentCount;
	if (entryURLs['index.html'].comments) {
		if (commentCount !== null) {
				document.write('<a href="' + url + '#comment_layer">' + commentCountString(entryURLs['index.html'].count) + '</a>');
		} 
		commentCount = null;
	}
}

This code powers the main weblog page and allows you to show comment counters even if the comments aren't directly shown on the main page.

Step 4: Publish your weblog

Open iBlog. Double-click your weblog folder in the source list on the left. Switch to the "Display Settings" tab, and then choose your new template set from the second-from-bottom popup menu. Press the "Save" button.

Now, go to the Blogs menu and choose "Reset Preview State and Preview". Once iBlog opens your local weblog in your web browser, switch back to iBlog and select "Reset Publish State and Publish" from the Blogs menu. Select the weblog for which you're activating .mac comments. Note that it is imperative that you publish your weblog before you activate .mac comments for that entry.

In the future, you do not need to reset the preview or publish states. Just publish as usual. But you need to publish before going on to the next step.

Also, note that if you have the local iDisk activated, you will need to sync your iDisk before your weblog gets published.

Step 5: Activate .mac comments for each URL

You'll need to activate .mac comments once per entry. So if you have three entries on which you want comments enabled, you'll need to activate .mac comments three times. This is where Dot Comments comes in.

Please note, I'm assuming you access your weblog using a "homepage.mac.com" URL. If you're instead using the newer "web.mac.com" URL, I strongly advise you switch back to the older "homepage.mac.com" URL if you want to use .mac comments. The reason is explained in the next section. However, this step is identical regardless of which subdomain you use.

Assuming you've completed step 4 (which is necessary before completing step 5), visit the webpage for the entry for which you want to activate comments. You want the "homepage.mac.com" or "web.mac.com" URL, not the file:/// URL. Copy this URL to the clipboard.

Now open Dot Comments. Put your .mac username in the top field, your .mac password in the second field, and paste in the URL you just copied to the third field. Now all you have to do is click the "Activate Comments" button.

At this point, if you have local iDisk synching activated, you again need to sync your iDisk to the .mac servers.

Once that's done, you can test the comments for that entry. Just click the "Add a Comment" button, and a page will open that will allow you to enter comments. If the comments form comes up, all is well. If all is not well, you will see an error message displayed on the page rather than a comments form.

That's it, you're done! Remember, you need to activate comments for each entry URL.

What are the caveats with using .mac comments?

Well, there's only one, really. As I mentioned before, I strongly encourage you to use the homepage.mac.com domain rather than the web.mac.com domain. This is because of the details behind the .mac comments system.

iWeb publishes its blog pages to the web.mac.com subdomain. (If you use iWeb, you should see a "Web" folder at the root level -- iWeb publishes to this folder, and they are accessed via the web.mac.com subdomain.) The .mac comments system uses the URL of the page to activate comments. If an HTML file exists at the URL, then .mac comments will be enabled. If the HTML file does not exist at that location, .mac comments will remain disabled whether or not you activate them via Dot Comments.

Unfortunately, if you even touch the contents of the HTML file after it has been activated, any comments that have been associated with that entry will be obliterated. Gone. You won't be able to bring them back. So, if you publish your weblog to the web.mac.com subdomain (by placing your HTML files in the "Web" folder of your iDisk), you'll only get one shot: if you want to modify the page later, you'll lose all your comments for that entry.

This is obviously unacceptable in many situations, so Dot Comments works around that. When you copy in a homepage.mac.com URL to Dot Comments and click the "Activate Comments" button, Dot Comments places a dummy HTML file at the appropriate web.mac.com URL. That way, the .mac comments system will think there is a valid HTML file at the URL and will activate the comments for that entry. (So basically, Dot Comments will place an appropriate dummy file in the "Web" folder of your iDisk.) Furthermore, you'll be able to modify the HTML file in the homepage.mac.com subdomain at will, without fear of losing any existing comments. (That means your weblog pages should reside in the "Sites" folder of your iDisk, which are accessed via the homepage.mac.com URL.)

You can publish your weblog to the "Web" folder if you wish, and Dot Comments will happily accept web.mac.com URLs for comment activation. (With web.mac.com URLs, no dummy file is created.) But given the above caveat, I strongly recommend against publishing to the "Web" folder of your iDisk.

Sample Demonstration

If you want to see a sample weblog with .mac comments activated, look no further than my own weblog, Technological Supernova (no longer working). I just recently switched over to .mac comments, and you're welcome to browse around and see how it looks.

Alternatively, you can add a .mac comment directly to this tutorial. Just click the "Add a Comment" link below.