Ciaran McNulty

I've been doing a bit more Javascript recently, specifically using Prototype AJAX stuff with Google Maps ,and I've come up with a few guiding principles that have helped me keep stuff neat and tidy. I thought I'd share them with you, my handful of readers.

SCRIPT tags should live inside HEAD

There are very few reasons for having SCRIPT tags inside the document body. The main one, use of document.write() nearly always leads to ugly code. It's also not actually allowed in XHTML, despite most browsers accepting it as long as the page is delivered as text/html.

Furthermore, SCRIPT in the document body is in my opinion always the result of a perceived problem that's actually the result of poor architectural choices.

Data and markup should live in HTML and styles should live in CSS

Somewhat related to the first point, sometimes it's tempting to do something like this on-page or in some server-generated JS to get information into your scripting language:

<script type="text/javascript">
lng = <?php echo $lat ?>;
lat = <?php echo $lng ?>;
drawTheMap(lat,lng);
</script>

What's a little nicer is to put the info somewhere into your HTML with a distinct ID or CLASS, and let your scripting language read it out of the DOM. That way you can avoid the sticky situations of trying to generate client-side code from your server-side code.

For example the data could be stored on the page somewhere sensible using the GEO microformat:

Location: <abbr id="location" class="geo" 
    title="<?php echo $lat ?>;<?php echo $lng ?>">
    6 Example Street
</abbr>

And then read out from the DOM using something like the following:

<script type="text/javascript">
if(locElement = document.getElementById('location')){
    if(locElement.className='geo'){
        if((loc = locElement.title.split(';')) && loc.length==2){
            lng = loc[0];
            lat = loc[1];
            drawTheMap(lat,lng);
        }
    }
}
</script>

Now, that looks slightly longer than the previous example but consider that it won't change from page to page, so can live in a client-cached JS file. The first example would need to either lie inside every HTML page, or be in a server-generated .js with nocache headers and be reloaded on every page.

As an aside, if you really don't have anywhere sensible in your visible markup to show this data, you could always put it in a HEAD element like META if you really need to - I've toyed with keeping my google API keys in there for instance.

There should only be one SCRIPT tag on the page

Perhaps the rule I'm least sure of, but one I've been trying to stick to as much as possible and I've found it helpful. Having one central JS that controls everything makes the path of execution of your code a lot cleaner. When you have multiple SCRIPTs on the page (and when you have them knocking around in the BODY) you can get into situations where different scripts are trying to set window.onload, executing out of order and so forth.

To continue the Mapping example above, a lot of my pages used to have:

<script language="text/javascript" src="myscript.js"></script>

<?php if(thereMightBeAMapOnThisPage()){ ?>
<script language="text/javascript" src="http://maps.google.com...">
</script>
<?php } ?>

This relies on the script generating the head knowing whether the mapping API is needed. Neater in my opinion is to eliminate this and detect inside my own Javascript, whether the API is needed:

<script language="text/javascript">

if(locElement = document.getElementById('location')){
  var script = document.createElement("script");
  script.src = "http://www.google.com/jsapi?key=asd[...]asd3&
  script.type = "text/javascript";
  document.getElementsByTagName("head")[0].appendChild(script);
}
</script>

What this is doing essentially is inserting the SCRIPT into the HEAD via the DOM! It may well look messy at first glance, but it's worked in all the browsers I've tried it on and is the way Google recommend pulling in their external scripts.

Use the Google AJAX Libraries API

OK so this isn't so much a rule as something I think is fairly handy, and I'm sorry if I keep going on about Google!

Google are hosting lots of the common Javascript libraries, including Prototype which I use. Loading your Javascript library via the AJAX loader doesn't make much difference, but it does offer a few advantages:

• You get to use the google.load() functionality from within your script, which is quite tidy and helps with my previous point.
• It's served from the Google servers so you don't pay for the bandwidth, and it can download faster in parallel with content from your domain (most browsers won't open more than 2 simultaneous connections to a single server).
• Because it's sitting at one central location, if everyone starts doing this then most clients will have the JS already cached when they hit your site, rather than them redundantly loading it for each server they encounter.
• If you do decide in future that Google are too evil to download code from, switching back to a local copy of your library is fairly trivial.