Reading HTML and Javascript – for Tech Writers

Posted by admin on March 8th, 2014 filed in Technical Writing

A colleague wanted to use Google Analytics event tracking code in a ZIP download link on one of our product pages. Our plan was to use Google Analytics event tracking to count how often customers download the documentation, compared to reading the HTML version online.

(We were testing the theory that mainframe users download and print documentation more often, whereas users of cloud and distributed software will bookmark and read the HTML pages. Mainframe users are typically offline in a highly secured environment, maybe even using a dumb terminal; users of cloud and distributed software are typically online, maybe even using mobile devices. I might write here about the results one day when we have them.)

Even if our doc had contained a standard download link (by that I mean <A HREF="http://example.com/file.zip">Download ABC...</A>), the Google Analytics instructions were difficult to understand for beginners. Additionally, our ZIP download link turned out to be horribly generated by a JavaScript, and was unrecognizable for any HTML/Javascript beginner. So my colleague and I looked at it together, and I gave him some examples of what a tech writer should be expecting when reading HTML:

A plain link is the simplest case:
<A HREF=”http://example.com”>Visit the Example homepage.</A>
The “Visit…!” part is the link text – that’s the blue underlined text that is visible to the reader.
You read “A HREF” out loud as Anchor Hypertext Reference or short Aitchreff. When your readers click this “Anchor” (i.e. link), the browser takes them to the Example homepage.

What you need to know about Anchor HREF: This is your everyday link. Click it to go to a web page.

When you see an Anchor HREF element that contains a hash symbol like so…
<A HREF=”http://example.com#news”>Read Example.com news</A>
… then you know that this Anchor Hyptertext Reference must be paired up with an Anchor Name somewhere on the said page. The Anchor Name looks as follows in the source code…
<A NAME=”news”>This is what's new here.</A>
… but it will be invisible to your readers. If a reader clicks the above “Read Example.com news”, the link does not only go to a web page, but the page additionally scrolls right down to a named anchor. In this case, the browser jumps down to the “news” section.

What you need to know about Anchor Name: Before the hash you define where an HREF links jumps horizontally, i.e. to which web page. After the hash you define where it jumps vertically, i.e. where it scrolls within the target page.

What does it mean when you see an empty Anchor HREF, with only a hash and its Anchor Name?
<A HREF=”#news”>News</A>
You see that no horizontal jump has been defined here. This it means, clicking this link doesn’t actually go to another webpage! The reader stays on this page, and merely jumps down to the news section on this very page. This is handy for a table of contents that lets you jump down to page sections.

What you need to know about empty HREF links with hash signs: Empty links do no jump horizontally to other pages. You use them to stay on a page and do another action, such as scroll down to a #named section.

Along the same lines, clicking a completely empty Anchor HREF…
<A HREF=”#”>I got nuthin!</A>
… does nothing. The reader just stays where he is on this page. In recent years, web developers repurposed the empty HTML Anchor to trigger side-effects. This way, a click on a “link” can start off a JavaScript action, while staying on the page.

What you need to know about empty HREF links: In modern HTML, clicking Anchor HREFs does not necessarily jump to a page or scroll. HREFs can be like buttons that execute scripts. Today, jumping is an optional feature of a link.

Because with the invention of JavaScript…

<A HREF=”#” onClick=”doStuff('blah',12345); return false;”>recalibrate the universe</A>

… clicking an empty link can execute spectacular programmer-like JavaScript stuff on the web page. :-) Catch is, if the user has JavaScript disabled, the onClick() action cannot execute.

To be prepared for this case, you also want to provide an old-fashioned HREF link, as a backup plan.

<A HREF=”lame_excuse_for_failure.html” 
    onClick=”doStuff('blah',12345); return false;”>recalibrate the universe.</A>

The backup plan is to jump to another page (here: lame_excuse_for_failure.html). This page either says “sorry, please activate JavaScript”, or it’s a page where you offer an alternative for the same action.

What you need to know about HTML and JavaScript: Web developers really like to mix the two…

While we are at it, here are some other common, optional HTML4 attributes that a good tech writer should recognize in HTML code:

<A HREF=”http://example.com” target=”_blank”>Visit the Example homepage!</A>

After frames where invented, the Anchor Target attribute let you specify in which frame this link opens. “Target blank” means the link opens in a new blank browser tab or window. Other options include to open the link in the current tab, or even inside a frame on the same tab.

<A HREF=”http://example.com” class=”custom_styled_link”>Visit the Example homepage!</A>

The Class attribute is the typical way to specify the text style for an HTML element. You define what text style exactly “custom_styled_link” stands for in the web page’s CSS stylesheet. The class controls font, font size, font color, etc (e.g. “green Verdana 11”).

The take-away message is: Be prepared that CSS, HTML, and JavaScript code can be mixed, even within one line. The order of arguments is flexible, so be prepared to encounter <A CLASS=”x” HREF=””> instead of <A HREF=””>.

In our case of a docs and support page, the HREF action (JavaScript disabled) is to download the ZIP file directly, and to not track this one download; the onClick action (JavaScript enabled) is to download the ZIP, and then run some code that tracks this download in Google Analytics. Here is our, admittedly not very readable, download link:

<script language="javascript" type="text/javascript">
var str = location.href;
if ((str.slice(0,6).toLowerCase() === "https:")||(str.slice(0,5).toLowerCase() === "http:")) {
  str = str.slice(0, str.lastIndexOf("/"));
  document.write(' <a class="z--jumptourl" title="" href="' + str + '.zip" 
      target="_blank">Download ABC...</a>');  
}
</script>

Now the Google Analytics event tracking doc tells us (among other things) to integrate the event tracker into an existing HTML link like this:

<a href="#" 
    onClick="_gaq.push(['_trackEvent', 'ZIP', 'Download', 'doc name']);">Download ABC</a>

Our JavaScript-enhanced link however is more complex. How do we merge everything we learned here? Like this:

<script language="javascript" type="text/javascript">
var str = location.href;
if ((str.slice(0,6).toLowerCase() === "https:")||(str.slice(0,5).toLowerCase() === "http:")) {
  str = str.slice(0, str.lastIndexOf("/"));
  document.write(' <a class="z--jumptourl" title="" href="' + str + '.zip" 
      onClick="_gaq.push([\'_trackEvent\', \'BookshelfDownloads\', \'Download\', \'' + str + '.zip\']);"
      target="_blank">Download ABC...</a>');  
}
</script>

Be careful with single and double quotation marks: The <A HREF> uses double quotes. Each item in JavaScript’s .push(['item']) method must be surrounded by single quotes. But the expression itself is a string inside a document.write() method, and is therefor already wrapped in single-quotes… This means you must escape all extra single-quotes as \'. — In case of doubt, paste your code snippet into an IDE and enjoy the benefits of live syntax checking. :)

Comments are closed.