jsDebug

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:

Features

Usage

Include the script:

<script type="text/javascript" src="debug.js" language="javascript"></script>
```html

  The <a href="/code/jsdebug/#console">console will be created</a> when the first message is sent. To send a message to the console simply call it like:
```js
// simple message
Debug.raise('Hello world!');

// message with function/method name
Debug.raise('Hello world!', 'doHelloWorld');

// message with method &amp; object name
Debug.raise('Hello world!', 'doHelloWorld', 'HelloWorld');
```js

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](http://prototype.conio.net/ "Prototype JavaScript Framework"), 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](http://script.aculo.us/)), 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
<div id="dbgWrap">
  <div>
    JS Debug output
    <ul id="dbgMenu">
      <li title="Clear Output">C</li>
      <li title="Minimize">-</li>
      <li title="Restore">+</li>
      <li title="Close">X</li>
    </ul>
  </div>
  <div id="dbgConsole">
  </div>
</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:

<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).