ITauthor

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

The Web Developer extension for Firefox is in invaluable when you are writing JavaScript that dynamically changes the HTML on a Web page. The feature I use most often is: 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/ Read the rest of this entry »

You can use the following JavaScript to test whether the current page is being displayed as a frame within a frameset, or is being displayed as a standard, standalone Web page. 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>

= 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'); } } //-->

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.

Read the rest of this entry »