The problem

The problem we’re trying to solve is how to debug a topic in a CHM file where you’ve got JavaScript that dynamically changes the HTML at runtime (i.e. when the topic is displayed in the Microsoft HTML Help viewer). If you’re debugging issues in WebHelp output you have the fabulous Firebug plugin that allows you (amongst other things) to click on objects in the output page and see what their HTML looks like right now. But unfortunately you can’t add Firebug to the help viewer. Or can you?

Online solution

This is the best solution, but it relies on you having:

• Internet access
• JavaScript enabled (a safe assumption as it’s probably JavaScript you’re debugging here)
• No firewall settings that might block code being downloaded from getfirebug.com (unlikely)

If any of the above aren’t true then you’ll need to use the offline solution (below).

The online solution uses the Firebug Lite bookmarklet to add much of the functionality of the Firebug plugin for Firefox to the browser pane within the HTML Help Viewer.

1. Do one of the following (these are just alternative ways of copying the same JavaScript to the clipboard): 

   Either: Right-click this link – Firebug Lite – and copy the link location (“Copy Shortcut” in IE).

   Or: Copy the following code:

   javascript:(function(F,i,r,e,b,u,g,L,I,T,E){if(F.getElementById(b))return;E=F[i+'NS']&&F.documentElement.namespaceURI;E=E?F[i+'NS'](E,'script'):F[i]('script');E[r]('id',b);E[r]('src',I+g+T);E[r](b,u);(F[e]('head')[0]||F[e]('body')[0]).appendChild(E);E=new%20Image;E[r]('src',I+L);})(document,'createElement','setAttribute','getElementsByTagName','FirebugLite','4','firebug-lite.js','releases/lite/latest/skin/xp/sprite.png','https://getfirebug.com/','#startOpened');

2. Right-click the title bar of the HTML Help Viewer.

3. Choose Jump to URL.

   

4. In the Jump to URL dialog box, paste the text you copied in step 1.

   

5. Click OK.

   After a moment (while it downloads files) the Firebug panes are displayed across the bottom of the browser pane in the HTML Help viewer.

6. Click Inspect, then click an object in the topic pane.

   The HTML for this object (including any dynamic modifications) is displayed in the HTML tab of the main Firebug pane:

   

Note: External JavaScript and CSS files aren’t recognised because they reside at another domain. So, when you click the CSS tab all you’ll see it “There are no rules in this stylesheet” and in the Script tab you’ll get “Access to restricted URI denied”. However, the functionality of the HTML tab is enough to make this technique extremely valuable for debugging.

Offline solution

The alternative is just to display the current, dynamically modified HTML in the browser pane. You can then select and copy/paste it into an editor for debugging.

To do this, copy and paste the following JavaScript into the Jump to URL dialog box:

javascript:'<xmp>'+window.document.documentElement.outerHTML+'</xmp>';

Note: The xmp element is deprecated and you shouldn't generally use it. However, in this case we know that we're using it in IE (the browser part of the HTML Help viewer) and IE, as of writing, still supports this element. If this stops being the case in future, the following is a less elegant (but standards-compliant) way of doing the same thing:

javascript:'<pre>'+window.document.documentElement.outerHTML.replace(/</g,'&lt;')+'</pre>';

The two I’ve been using recently are jsbin and pastebin.

For example:

• http://jsbin.com/ejoye4/edit – click Preview to see the output
• http://pastebin.me/6ddbefe3185f806d5903c7ab5664a673 – click EDIT CODE to see the code

In this post I describe how (with the help of jQuery’s $.ajax() function) to use the existence of a file on the server as a switch to determine behaviour in the browser.

Case study

In my case, the problem I had was that I use Madcap Flare to generate WebHelp output, and sometimes I want to build a customer version of the WebHelp and other times I want to build an internal version that has issue reporting functionality turned on. This adds little icons to the page that call some PHP for reporting, listing or searching for issues for the current page in the help system.

The issue reporting functionality is governed by a Javascript file, and I want to use a Flare condition to turn that functionality on or off. Flare can’t condition lines within a Javascript file to be included or not included in the output, but you can use Flare conditions to determine which files end up in the output. So I wanted a little bit of Javascript that said: if a particular file exists on the server turn on the issue reporting functionality, otherwise leave it turned off.

As with so many things Javascript, jQuery makes this easy.

Code

Here’s the jQuery code. Obviously you can replace the alert statements with something more useful.

$.ajax({
    url:'/somedirectory/onyourserver/filetofind.html', 
    type:'HEAD',
    error:
        function(){
            alert("ERROR: File not found. \n:-(");
        },
    success:
        function(){
            alert("Nice one! File found. \n8-)");
        }
});

Note: The file isn’t important. It’s purely being used as a switch. The file I use as the switch is actually the barest of bare-bones HTML files that is valid XHTML (which Flare demands). The type:'HEAD' statement in the code tells browsers just to request the HTTP response header for the file, not the contents of the file. However, as this is not supported on all browsers, you should only use this method if you know that the file being used as the switch is either empty of very small.

Try it out

To try this out, go to:
http://jsbin.com/avalo4/2/edit

Click Preview to see the output. You should see the “File found” message.

Click Code, change the file name in the Javascript and click Preview again and this time (assuming the file doesn’t exist on the jsbin.com Web site) you’ll get the error message.

And with formatting and styling it’s pretty much the same story. By using CSS, you have a high degree of control over the look and feel of your output. For example, I’m working on a WebHelp system right now and it’s been fairly straightforward to get most of the output looking more or less how I want it to look. The simple things like changing the background colours, the fonts, the icons, and so on are easily done from within the Flare application. And there are other things you can achieve by using Javascript to inject a CSS file dynamically on page load, if you want to override things in the Flare stylesheets that are injected into your output files at build time.

However, I’m painfully reminded, working with Flare again today, that one of the reasons I’m not 100% of a Flare fan is that Madcap fell short of making the styling of output 100% configurable via stylesheets.

Things like the Related Topics popups rely on Javascript, triggered by an onClick event, to add elements to the topic. This is perfectly standard, but whoever coded this decided in their wisdom to embed style information directly into those HTML elements, rather than giving everything a class name and controlling the styles from a stylesheet. In the hierarchical system that is CSS, nothing gets to overrule styles applied directly within the style attribute of an element in the HTML, so if the coder coded:

color="black"

then you you can have any colour you want, as long as it’s black – that is, you don’t get to modify the colour in your stylesheet to something more subtle, you’re stuck with the coder’s idea of what looks best for your output.

So my particular example today was that I was trying to beautify the Related Topics popup a little. Here’s what it looks like out of the box:

And I managed to modify most of it. But I just couldn’t get at that close button. It’s added directly by the Javascript. If it was in a Madcap CSS file – for example, as the background image on a div – then I could have overridden it with my own close button. But in the end I thought: sod it, if I can’t replace it I’ll just remove it. So here’s what I ended up with:

I know I’m biased, but I think it’s a big improvement. A little close button would have been nice, but I think most users know, or will quickly work out, that clicking away from the popup box makes it go away.

To style this up I used the following Javascript to add an override CSS file, which allows me to get at some of those hard-to-read Madcap styles:

$(document).ready(function(){
    ...
    //Append a link to the CSS file
    var newCSSlink=document.createElement('link');
    newCSSlink.setAttribute("href","Resources/StyleSheets/MCstylesOverrider.css");
    newCSSlink.setAttribute("rel","stylesheet");
    newCSSlink.setAttribute("type", "text/css");
    headElement = document.getElementsByTagName("head")[0];
    headElement.appendChild(newCSSlink);
    ...
});

This first line of the above code gives away that I’m using jQuery as an easy way to select and modify elements in the HTML. This just requires an extra Javascript file reference in the head of each page. If you use Javascript and you’re not familiar with jQuery, I’d strongly advise you have a look at it now!

Within my MCstylesOverrider.css file, the bit of CSS that removes the div containing the close button is:

div.MCKLinkBody div
{
    display: none;
}

Flare presents you with the old 80:20 rule. To get to a state where you’d be happy with the styling and behaviour of everything, you’d spend 20% of your time and effort getting 80% there, and then you’d spend the remaining 80% of the time finishing things off. For us pernickety perfectionists, Madcap could have made life a whole lot easier by making everything accessible and easy to change.

Message to software developers: when it comes to look and feel, less of the hard coding – please!

This might be a handy way of creating little apps to do personal stuff. I'm going to have to go back and investigate the example applications when I've got some time:

http://code.google.com/apis/gears/sample.html

right-click > Web Developer > View Source > View Generated Source

This shows you the HTML as it is at this moment in time, rather than the original HTML that came down the pipe.

Microsoft's Internet Explorer Developer Toolbar provides some useful functionality for the Web developer, but it doesn't have a View Generated Source option. However, I remembered an old posting (from March 2004) that had a way of viewing dynamically modified source for IE:

www.itauthor.com/notes/archives/2004/03/viewing_dynamic.html

The trick is to paste the following into the IE address bar:

javascript:void(window.open("javascript:document.open(\"text/plain\");document.write(opener.document.body.parentNode.outerHTML)"))

This opens a new window or tab and shows the generated source. I've been using it in IE7 and it's a God-send.

BTW: to get the Internet Explorer Developer Toolbar, visit:
www.microsoft.com/downloads/

If you're likely to find this useful, a handy tip is to create a shortcut. For example, from a Web page (not the JavaScript-generated page), drag the icon in the address bar to IE's Links toolbar. Right-click the new shortcut and choose Properties. In the Properties dialog box, change the name of the shortcut to "View Generated Source" and the URL to the JavaScript in the box above.

Now whenever you're browsing in IE, you can click this link to see the generated source.

In this example I'm just displaying a message, in real life you could use this to change what's displayed on the page. For example, I'm using similar code in a linked JavaScript file to show or hide a div on the page. I use this in a Flare Help project so that, when a topic is viewed as a standalone page a link is displayed allowing the user to view the page within the 3-frame Web Help (i.e. topic frame, navigation frame and toolbar frame).

<script language="javascript">
<!--
function showHideHelpLink() {
   if (location.href == parent.location.href)  {
     alert("single page");
   }
   else {
     alert("I'm in a frame");
   }
}
// -->
</script>

I have a set of complex web pages that are built in a frameset within a frameset (not my idea - this is WebHelp I've output from RoboHelp and that's how it comes out). Fortunately, the JavaScript provided by RoboHelp includes a convenient way of calling a particular page within one of the embedded frames, using parameter values in the URL. For example, if the outermost page is called mainpage.html and the inner page you want to show is called mytopic.html then you can show this topic by calling up mainpage.html#mytopic.html

This provides a way of bookmarking the current page within a complex frameset. But to do this we need 3 things:

1) The complete URL of the main page (which is the grandparent frame of the frame that contains the page you want to bookmark).

2) The file name of the page you want to bookmark.

3) The title of the page you want to bookmark.

The following button shows information about the page. On this page the values for the current page
and the grandparent page are the same, because this page isn't in a frameset. You'll just have to take my word for it
that this works when the current page is embedded in a frame of a frameset that is itself within a frameset.

We can use the information shown in the alert box for the above button, to
build the parameter values that we need to pass to the bookmark function. The following button displays the 'Add Bookmark' or 'Add Favorite' dialog box with the details for this page. Try clicking it - but if you use Firefox I'd recommend you don't actually add the bookmark, because the resulting bookmark will display a framed version of this page.

Here's the bookmark function:

<script language="javascript" type="text/javascript">
<!--
function bookmark(url, title){
  if ((navigator.appName == 'Microsoft Internet Explorer') && (parseInt(navigator.appVersion) >= 4))
  {
    window.external.AddFavorite(url, title);
  }
  else if (navigator.appName == 'Netscape')
  {
    window.sidebar.addPanel(title, url, '');
  }
  else
  {
    alert('Press CTRL-D(Netscape) or CTRL-T(Opera) to Bookmark');
  }
}
//-->
</script>

View the source code to see the onclick values that call this function.

--------------------

I've just had another look at this. OK, so it's a pretty useless example because this page isn't framed. You just have to take my word for it that if this page was in a frame of a frameset within a frameset, clicking the second button would create a bookmark with a URL like: http://domain/path/mainpage.html#mytopic.html

A point to note is that this doesn't work if the file is hosted locally, rather than on a Web server. For this reason, you probably want to hide the button by default and then test the protocol value onload (see the first alert box), and display the button if the protocol is "http:".

I put the contents of the document into a variable called root and then did:

alert(root.childNodes.length);

Here's my XML file:

<?xml version="1.0" ?>

<relatedtopics>

	<topic id="createrolegroup" href="createrolegroup.html">Create a role group</topic>
	<topic id="usesettingseditor" href="usesettingseditor.html">Use the Settings editor</topic>
	<topic id="turnonuserfriendlydatesinsearchqueries" href="turnonuserfriendlydatesinsearchqueries.html">Turn on user-friendly dates in search queries</topic>
	<topic id="systempicklistsindetail" href="systempicklistsindetail.html">The system picklists in detail</topic>
	<topic id="shutdownserver" href="shutdownserver.html">Shut down a server</topic>

</relatedtopics>

What number do you think gets displayed by the alert?

The answer is different depending on which browser you use. In IE you get 5 (which is what I had expected), but in Firefox you get 11. Why?

The answer is that Firefox covertly adds a #text node for each area of whitespace between the child nodes that are visible in your XML. So in the above XML there's actually an invisible child node before the first topic element, another one between each topic element, and another after the last topic element - making 11 nodes in total.

If I'd written the XML like this:

<?xml version="1.0" ?>

<relatedtopics><topic id="imadmin_createrolegroup" href="createrolegroup.html">Create a role group</topic><topic id="imadmin_usesettingseditor" href="usesettingseditor.html">Use the Settings editor</topic><topic id="imadmin_turnonuserfriendlydatesinsearchqueries" href="turnonuserfriendlydatesinsearchqueries.html">Turn on user-friendly dates in search queries</topic><topic id="imadmin_systempicklistsindetail" href="systempicklistsindetail.html">The system picklists in detail</topic><topic id="imadmin_shutdownserver" href="shutdownserver.html">Shut down a server</topic></relatedtopics>

I would have got 5 in both browsers.

This is nicely explained, with a useful diagram, in an article called "Whitespace in the DOM" at http://developer.mozilla.org/en/docs/Whitespace_in_the_DOM.

function copycode(ta) {
var obj = document.forms[ta].code;
if ( (navigator.appName=="Microsoft Internet Explorer") && (parseInt(navigator.appVersion)>=4) ) {
copythecode(obj);
}
else {
highlightthecode(obj);
}
}

function highlightthecode(obj) {
obj.select();
obj.focus();
}

function copythecode(obj) {
highlightthecode(obj);
textRange = obj.createTextRange();
textRange.execCommand("RemoveFormat");
textRange.execCommand("Copy");
alert("Code segment has been copied to your clipboard.");
}

The following code (from www.searchengineforums.com) allows you to click a link to select all the code in a textarea box. You can then Ctrl+C it to copy it. If you're using Internet Explorer, it's copied to the clipboard for you.

As I mentioned above, this piece of Javascript comes from www.searchengineforums.com. This site contains a stack of interesting forums and is well worth checking out.

To display the CSS class name of objects on the page as you move the mouse over them, add the following JavaScript in the head section of the page (or in the link .js file):

document.onmouseover=Function("window.status=event.srcElement.className");

The class name is displayed in the status bar.

You can do the same thing for element names (change className to tagName) or IDs (change className to id).

OK, so I've given in. But at least now I can get on and finish off the page, which has been languishing, three-quarters-done, for about a week now. ITauthor.com will then, finally, have a proper home page.


NOTE

In case you're wondering how I styled the code above (in other words, for my own benefit when I want to do the same thing in a few weeks time and can't remember what I did). I just typed in an inline style in the normal MovableType input box.

For more details about inline CSS, take a look at:
http://www.alabamatechnologies.com/resources/css-09.asp