Iraq Body Count Scrolling Web Counters: Installation Instructions

These are the detailed installation instructions for the Iraq Body Count Scrolling Web Counters. If you're an experienced webmaster, you might be able to get by with the condensed instructions provided directly on the download page

Return to the Iraq Body Count website.

Contents

Preliminaries

 Before you begin installing the counter, please read the sections below to make sure that your website fulfills the technical requirements, and that you are willing to abide by our conditions of use.

Technical Requirements

This document explains how to display an Iraq Body Count scrolling web counter on your website. First, you need a website, obviously.

Second, your website must allow you to upload and serve image files and JavaScript scripts. Free websites like myspace and free blogging accounts often do not allow you to do this. You can put a counter up, but you won't be able to get the scrolling headline feature. Read the really simple cut-and-paste instructions here.

In the instructions that follow, I assume that you have and know how to use a utility for unpacking Zip files, and that you know how to upload files to your website using an ftp client or some other program.

Conditions of Use

If you display one of our counters, you must link it to our site http://www.iraqbodycount.net. You may not deface our counters or display them in a disrespectful way.

Counter Installation in Six Steps

 If your website meets the requirements above, and if you agree to the conditions of use, then you're ready to start installing the Iraq Body Count scrolling counter. If you prefer to work with hardcopy, then this would be a good time to print out these instructions, if you haven't already.

Step 1: Pick your counter size and color

Visit the scrolling counter download page at http://www.djf.net/IBC/ (this link opens in a new window) and take a look at the counter sizes and color combinations available there. Pick the one or ones that would work best on your website. (You can use as many different counters as you like throughout your website, but note that for technical reasons, you can only have one scrolling counter per webpage: the scrolling doesn't work right if you try to display more than one.)

For the rest of these directions, I'll assume that you've picked a single counter. But you can repeat these steps if you want more than one.

Step 2: Download the counter zip file

Click on the thumbnail image of the counter you have chosen. This will take you to a new page that contains a working demo of the counter at full size, and a "Download" link. Click on the "Download" link. This should start downloading a zip file that contains everything you need for the counter. If your browser doesn't automatically ask you where you want to save the zip file, then you probably need to shift-click on the link, or right-click and select a "save link as" option from the menu. (The exact procedure varies from browser to browser.)

Different counters come in zip files with different names. For the rest of this document, I'll assume that you picked the 468x60 banner with black text on a blue background. That counter is stored in a file named ibc468.zip. Save it with that name on your desktop or somewhere else handy on your local hard-drive.

Step 3: Unpack the zip file

Now that you've downloaded the zip file, you'll need to unpack it (unless your web browser already offered to unpack it for you and you accepted). You'll need a Zip utility for your computer, such as WinZIP for Windows platforms. (I'm assuming that you know how to do this). Your counter will unzip itself into a directory or folder named IBC/. When you look in that folder, you'll see files with names like the following (the number and names of the actual files vary depending on which counter you picked): 
ibc468.js
ibc468_1.gif
ibc468_2.gif
ibc468_3.gif
ibc468_4.gif
ibc468_5.gif

If you have chosen more than one counter for your website, you can safely unpack them all into the same folder. Some counters use duplicate image files that overwrite one another, but any files that differ will have different filenames.

Before we proceed on to the next installation step, I'll pause here to explain what all these files are for.

FAQ: Why so many .gif files?

Our scrolling web-counters have moving parts: headlines that scroll and numbers that get updated. This means that they can't be composed of just a single image like an advertising banner might be. Instead, they require several images to be stitched together. (But don't worry: you won't have to do that stitching yourself.) The reason we've put the images in the zip file for you instead of hosting them on our website is that we want to get these counters out there far and wide, and our website simply does not have the bandwidth available to supply all the images to all of your visitors. The only image we supply is the one that has the actual bodycount numbers in it.

FAQ: What is the .js file for?

The file with the .js extension is a file of JavaScript code that is responsible for stitching the image together in an HTML table on your website and (more importantly) for making the headlines scroll in the counter. Because everything is in this one JavaScript file, it takes only a single line of HTML to install the counter on a webpage (we'll get to that below). Some of the visitors to your website may have disabled JavaScript in their browsers. If so, then they won't see the counter. But not many people do this, so I don't think this will be a big problem.

Step 4: Upload the files to your website

The files that are now in the IBC/ folder on your hard drive must be uploaded to your website. You must put them in a directory named IBC/ in the root directory of your website. If your website is www.example.com, then you must install these files so that they can be accessed via a URL like this: 
http://www.example.com/IBC/ibc468_1.gif
I assume here that you know how to use FTP or a similar tool to upload files to your website, and that you also know how to create new directories in your website.
If you don't have your own domain name, but have a website with a URL like http://www.example.com/people/~username, then you'll have to take additional steps. The .js JavaScript file assumes that the image files it needs are stored in the directory /IBC/ If you instead are forced to store them at /people/~username/IBC/, then you'll have to edit the .js file before you upload it to your website.

Open the .js file in a plain-text editor, and search and replace /IBC/ with /people/~username/IBC/. Do this carefully, being sure not to change anything else. For most counters, there will be four or five occurrences of /IBC/ to change. Don't let your editor word-wrap any lines and be sure that the editor saves the file as plain text without adding any formatting. Also, be sure that it saves it with the extension .js, not .js.txt.

You can also use this technique if for some other reason you do not want to install the counters in /IBC/.

Step 5: Place a counter on a webpage

Now that you've uploaded the files to your website, it is quite easy to make the counter appear on a webpage. Just add the following line of HTML to any page on your site, at whatever position you want it to appear: 
<script src="/IBC/ibc468.js"></script>
Substitute the name of your .js file for ibc468.js. And if you installed the counter somewhere other than /IBC/, then change that part too.

You can put your counter wherever you want on a page, If you want to center the counter, for example, just put it in a <center> tag: 

<center>
<script src="/IBC/ibc468.js"></script>
</center>
The counters should also work correctly when placed within tables. Remember that you can only have one scrolling counter on each page: if you try to put more than one on a page none of them will work right.

Are the scrolling headlines scrolling all the way up the page? See the Known Bugs section at the end of these instructions to learn how to fix that problem.

Step 6: Tell us about it

Once you've placed a counter on your webpage, please let us know about it by filling in this form and clicking the "Tell Us!" button.
Your Name:
Your e-mail:
URL of your website:
May we link to your website? Yes No
Comments:
 

Advanced Topics

 This section covers some advanced topics about the scrolling web counters. If you're satisfied with the counters as-is, you don't have to read this section.

Using multiple counters

As noted above, the JavaScript code in the scrolling web counter is designed with the assumption that there will only be one scrolling counter per webpage. Don't try to put more than one on a page.

This does not mean that you can't install more than one counter on your website. You can, and you can use different counters on different pages within your site. It is safe to unpack the zip archives of different counters into the same IBC/ directory.

Customizing the scrolling behavior

By default, the IBC scrolling counters wait for four seconds before they begin displaying headlines. They pause for four seconds on each headline. They loop through the complete set of headlines three three times, with another four second delay between loops, and then stop displaying the headlines.

If you want to alter this default behavior, you can do so by editing the .js file for your counter. Each .js file begins with the following 8 lines: 

var ibc = {
  // These are parameters that can be adjusted
  initialDelay: 4000, // Milliseconds to wait before starting animation
  restartDelay: 4000, // Milliseconds pause between repetitions
  numLoops: 3,        // How many times to loop through the headlines
  frameLength: 50,    // Milliseconds per frame
  pixelsPerFrame: 2,  // How much to scroll up each frame.
  pauseLength: 4000,  // Milliseconds to pause between individual headlines

To alter scrolling behavior, just change the numbers that appear in these lines. Note that the times are specified in milliseconds, so the pauseLength line specifies a 4000 millisecond (4 second) pause for each headline. If you want a 3 second pause, just change the number on this line to 3000. If you want the counter to scroll through the headlines just once, edit the numLoops line, changing 3 to 1. If you want it to display headlines indefinitely, then change the 3 to a very large number like 30000. (See below for a way to turn off scrolling altogether.)

The frameLength and pixelsPerFrame lines specify the speed and smoothness of the scroll. The default values specify that every 50 milliseconds, the current headline should move up by 2 pixels. Feel free to experiment with these values, but note that some browser and operating system combinations can't handle a frameLength shorter than 50 milliseconds.

When editing this file, be sure to use an editor that won't wrap the lines, that won't insert any formatting into the file (it must be a plain text file) and that won't append a .txt extension after the .js extension.

Disabling the scroll

If you have chosen to use a scrolling IBC counter for its easy of installation on your web pages, but don't actually like the scrolling feature, it is very easy to disable. Read the section above "Customizing the scrolling behavior" for background information. Then, in your JavaScript .js file, simply edit the line that begins with numLoops and set the number to zero. When you do this, the counter won't scroll the headlines at all, and, in fact, it won't even bother to load the headlines across the network either.

What happens in old or non-JavaScript browsers

Some webmasters are nervous using JavaScript in their webpages because they are concerned about compatibility with browsers that do not support JavaScript. I've tried to minimize compatibility problems for these scripts.

If a browser does not support JavaScript, or if the user has disabled JavaScript support in their browser (both are quite uncommon), then the scrolling counter will simply not appear. This is because you include it in your web pages with a <script> tag and browsers that don't have JavaScript support will simply ignore the tag. If the graphic design of your page depends strongly on the presence of the counter, and you belive that many of your viewers have JavaScript disabled, then this may be problematic for you.

If a user is using a browser that does support JavaScript, but that does not have the capabilities to do scrolling text, they will see a static counter with no scrolling headlines. This is because the JavaScript code first checks that the browser supports the capabilities it requires. If the necessary capabilities are not supported, the code does not attempt to do any scrolling. Browsers that cannot display the scrolling headlines include Microsoft Internet Explorer 4 and earlier, and Netscape Navigator 4 and earlier. These browsers currently account for about 5% of internet usage, so something like 95% of visitors to your site should see the scrolling headlines.

Known Bugs

The following sub-sections describe the bugs we know about in these counters.

Headlines take up full screen in IE6

If a scrolling counter is displayed on a page that includes a DOCTYPE declaration, then IE6 may display it incorrectly and you will see headlines scrolling through the entire page instead of confining themselves to the boundaries of the counter.

Explanation: Modern web browsers render HTML slightly differently when it includes a DOCTYPE declaration that specifies that the HTML is written to conform to modern web standards like HTML 4 and XHTML. IE6 appears to interpret these standards differently than Netscape 7 and Opera 7 because when IE6 displays the counter in its "Standards Mode", it causes the bug described here.

Fix: No fix available, but see workaround below. If you find a fix, please let me know!

Workaround: The easiest workaround is to remove the DOCTYPE declaration from your page. I've had a report (but have not confirmed personally) that IE6 displays the counter correctly when you use an HTML Transitional DOCTYPE like this one: 

<!DOCTYPE HTML PUBLIC "-//W3C/DTD HTML 4.01 Transitional//EN">

If you really want to include a DOCTYPE tag in your document (to declare it as XHTML, for example), and the one above does not work for you, then, consider placing the counter in a separate document and including it in your page via an <iframe> tag.

Technical Support

Please if you have trouble installing a counter, if the counter isn't working correctly on your site, if you have a suggestion for improving the counter, or if you have a suggestion for improving these instructions.

If you're having a problem with the counter, please be sure to describe the problem in detail, tell me the name of the .zip file you downloaded, and, if possible, provide a URL where I can look at how its coming out on your site.

I'll try to respond as promptly as I can, although other commitments sometimes take me away from my e-mail for two or three days at a time. If you are unable to get a response from me, try e-mailing:

Return to the Iraq Body Count website.