This is something I’ve blogged about twice before (in March 2004 and in January 2009), but going back to those topics just now neither of the solutions I gave at that time are working for me. So here’s the way to do it now.

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>';

Writing JavaScript used to be a tricky and tedious business. Now, with Dojo, script.aculo.us and particularly jQuery it’s easy - and even fun - to write JavaScript. And if, like me, you’re an occasional JavaScript coder, and your skills are rusty every time you return to do something in JavaScript, another innovation you’ll find really useful is the online scratchpad. These are Web sites where you can quickly try out some JavaScript.

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

Rewritten post: Thanks to Janet Swisher for helping me avoid misleading folks with this.

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.

After several months away from Madcap Flare, coming back to work on it again, I’m reminded that one of the reasons I like this technical authoring tool is that it uses standard XHTML. So, if you’re using Flare to produce online help, you can modify your pages just like you could any Web page. So, for example, because I don’t like Flare’s default (text-only) glossary popups, I’ve replaced those with my own variety that allow text formatting and images, and can be dragged around the screen. And because I don’t have the budget for Madcap’s Feedback Server, I’ve hooked our help system up to a MySQL database, using AJAX and PHP, to give some of the same functionality. All good stuff and it’s great to have the freedom to do that kind of customisation.

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!

Google have introduced a new beta product called Gears that allows you to write Web-based applications for offline use. Quote: "Google Gears is an open source browser extension that lets developers create web applications that can run offline."

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