Details

Download
Version 1.1.0
Last updated 6th November 2005
Demo View demo page
Links

About

This is a simple utility created to assist with debugging JavaScript development cross-browser.

The usual method for debugging JavaScript is to pepper the code with alert() calls to give you feedback on how the script is executing, this is especially useful in browsers that supply vague and un-helpful information about errors (or even their exact location), but can soon become counter productive - confirming multiple alert boxes breaks the code, test, code flow. This script creates a console to send messages to, where you would have traditionally used alert().

For more details see the jsDebug demo & test page.

Since I initially created this there have been a few others released, however none of these meet my personal needs:

  • Information on object & method of message origin.
  • Un-obtrusive in both implementation and end result.
  • Minimizable / closable without losing ability to continue to send messages.

Features

  • Un-obtrusive
  • Minimizable
  • Closable
  • Highlight when a message is add (useful for when minimized)
  • Styling handled via CSS for easy customization
  • Can be removed leaving debugging calls intact
  • Fixed positioning by default ensures console is always within view
  • Dragable *
  • Cross-browser - tested in:
    • IE 5.0[1], 5.5, 6 Win
    • Firefox 1.0.7
    • Netscape 7.1
    • Opera 8.5

Usage

Include the script:

HTML:
  1. <script type="text/javascript" src="debug.js" language="javascript"></script>

The console will be created when the first message is sent. To send a message to the console simply call it like:

JavaScript:
  1. // simple message
  2. Debug.raise('Hello world!');
  3.  
  4. // message with function/method name
  5. Debug.raise('Hello world!', 'doHelloWorld');
  6.  
  7. // message with method &amp; object name
  8. Debug.raise('Hello world!', 'doHelloWorld', 'HelloWorld');

This will result in the following output:

void::void -> Hello world!
void::doHelloWorld -> Hello world!
HelloWorld::doHelloWorld -> Hello world!

Note: As the script uses document.body.appendChild() to create the console trying to raise messages before the body element has loaded will cause errors to be thrown. This will only be an issue if you are using a scheduler to perform JavaScript tasks as soon as elements are available in the DOM without waiting for the DOM to finish loading. There are plans to rectify this with adding a buffer, but I don't need this functionality quite yet.

Initialising With Custom Options

The script will automatically initialise the Debug object with default values, however these can be over-ridden by calling the Debug.init() method before using the console. The parameters this takes are:

sMin
boolean - Whether to start the console minmized - default false.
webfiles
string - The relative web path where the debug files reside (must contain trailing /) - default ''

Removing console for final testing or release

The console can be removed whilst leaving the Debug.raise() calls intact, this is useful for the final testing stage, where if any bugs appear the console can be re-instated and all your original debug messages will still work.

There are two ways you can do this, replace the debug.css file with one that sets the display to none or replace the debug.js script with debug.void.js. The debug.void.js script creates a dummy Debug object with the init and raise methods, this will stop any errors that would occur when calling Debug.raise() and has the advantage of being very small <1kb when compressed. The debug.void.js method is the best option all round, but especially so if you wish to leave the Debug.raise() calls in the release.

Prototype Extension

The base utility does not require Prototype, however to make the console dragable and slightly more robust, an extension was created to take advantage of the Prototype framework, this checks for the existence of Prototype before extending the console.

To use the Prototype version of the console simply include the debug.prototype.js script after the debug.js script along with Prototype.

Note: This was developed with the 1.4.0_rc2 version of Prototype (which comes packaged with the latest release candidate of Scriptaculous), it has not being tested with the current stable version (1.3.1) of Prototype.

When the dragable feature is added to the console a class name of hasDrag is added to the console wrapper element (dbgWrap).

Finally the Prototype extension simulates fixed positioning in IE 5 - 6.


IE 5.0 The Prototype version of the console throws errors in IE5.0 somewhere in Prototype, however the console itself still works as intended, without the Prototype extensions.

The Console & Customizing

The console is only created when needed, on the first Debug.raise(). It is created with the following structure.

HTML:
  1. <div id="dbgWrap">
  2.     <div>
  3.         JS Debug output
  4.         <ul id="dbgMenu">
  5.             <li title="Clear Output">C</li>
  6.             <li title="Minimize">-</li>
  7.             <li title="Restore">+</li>
  8.             <li title="Close">X</li>
  9.         </ul>
  10.     </div>
  11.     <div id="dbgConsole">
  12.     </div>
  13. </div>

When the console is created the debug.css stylesheet is included by adding a <link /> element to the head of the document.

Note: As the stylesheet is included dynamically by the JavaScript some browsers like to treat this like their first born and refuse to see it grow up, so manually clearing the browser cache may be needed when making changes to it.

The messages are added to the console with the following structure:

HTML:
  1. <span class="className">className</span>::<span class="methodName">methodName</span> -> <span class="msg">msg</span><br />

When a message is added to the console a class name of notify is added to the console wrapper element (dbgWrap).

Next Steps

Download

Leave a Tip

If you find this code useful you can leave a donation towards the continued development & support.

Comments are disabled on this post.