DHTML Console

Legal

This software is copyright © Robert Kieffer and is offered under the terms of the GNU General Public License.

Overview

The DHTML Console is a development tool that provides a consistent, cross-browser solution for analyzing and debugging DHTML applications.The functionality it provides is minimal by the standards of most IDEs, but addresses many of the needs of DHTML developers. Some of what it offers...

• Implemented using only DHTML - there's no installation required.
• Cross browser - It works on most modern browsers (IE, Firefox, Safari, Opera)
• Zero-impact integration - No changes to your existing code are required
• Rich logging support - Log messages can be any valid HTML, generated at any time during page load or page execution!
• Object dumps - Complete object hierarchy inspection is also possible.
• Expression watching - Watch and report on changes to any JavaScript expression.

Dive In!

Yeah, I'm not very patient either. So let's get a quick taste of what this console can do...

• Start by opening the console (just click here)
  This opens the console and attaches it to this window
• Let's start by checking out the DOM. Type "document" (w/out the quotes) into the command field in the console, and hit Enter↵
  The console displays all the properties of the document object.
• Next, feel free to explore the DOM by clicking the property names. For example, try clicking the "body" property. (You'll probably have to scroll back up to find it.)
  Anytime the console dumps the contents of an object, the property names can be clicked to drill down into that object.
• Now tchangesry changing something. Enter 'document.body.style.backgroundColor="#ff7"'
  to change the background color of this readme file. The command field evaluates any javascript expression and displays the result of that expression.
• Things are probably getting cluttered, so click the "Clear" button that's right below the command field.
  Ahhh... much better.
• Hey, let's keep an eye on when we scroll around over here. Enter "watch document.body.scrollTop" and then scroll around in this window.
  Any time a watched value changes, the new value is logged to the console.
• Finally, let's wrap up with some examples of how you would log information from within your application. Here are some examples you can click on to see how they work.
  • A simple log message: log('Hello world!')
  • Logging the contents of an object: log('Navigator object:', navigator)
  • Creating and logging to a custom category: log.createCategory('Sampler'); log.Sampler('Hello world!');

That's enough for now. Conceptually this is a pretty simple tool - show data, evaluate expressions, report on what's happening, and let you do it in a simple, easy-to-navigate, fashion. For more on what it's capable of, read on ...

Installation

Start by downloading the latest installation package.

Unzip the package into a directory that is accessible through your web server. For demonstration purposes, we'll assume the console directory is located at 'http://yourserver/Tools/Console'

Probably the easiest way to open the console is to use a bookmarklet like this one: DHTML Console (edited to point to the appropriate URL of course.) Then while viewing the page you want to analyze, simply click the bookmarklet.

Some web applications use windows that don't have the necessary decorations to activate a bookmark though. In those cases, I suggest you add a snippet of javascript like the following:

function openConsole() {
    var win = open('/Tools/Console/console.htm', 'dhtml_console', 'resizable=yes');
    win.opener=window;
}

... and then invoke this method in response to a suitably unlikely event. E.g. a ctrl-double-click on some small icon or image in your UI.

Note:The console must be served from the same domain as the webpage you want to analyze and debug. Also, if your web page explicitely sets the document.domain cookie, the console may not be able to properly access the opener. This can be fixed by executing the following command in the console 'local: document.domain=location.hostname'.

Executing Commands

The console UI is pretty straight-forward and revolves around what is, essentially, a command-line interface: a text field. You can enter anything you want in this field and hit Enter↵ to have it evaluated in the context of the "target" window (the window that opened the console). The command you enter, plus the results of that command are displayed in the log area of the console (that big f'in whitespace below the command bar).

Executing "local:" Commands

Sometimes it's useful to just open the console to explore the DOM, or experiment with some JavaScript to see how it behaves, without having it connected to another window. Prefixing your command with "local:" instructs the console to execute your command in the context of the Console window, as opposed to the opener window.

Builtin Commands

In addition to whatever javascript you happen to enter, the Console also provides it's own builtin commands. These are listed below the text area, and are run by either clicking them with the mouse, or typing them in and hitting Enter↵ just like you would normal javascript. Note that some commands, such as "depth" and "watch" must be typed in with additional arguments to be meaningful. For a detailed description of each command and it's usage, click the "?" in the command bar.

History

The console will remember the most recent commands that you have entered, for the duration of your browser session. You can navigate through this "history" by pressing the up ⇑ or down ⇓ arrow keys on your keyboard (but requires the focus to be on the text field!)

Note: The console history is kept in the "bc_history" cookie (on the current site). It won't be visible when the console is up, but don't be surprised if you see it in your webserver logs.

Logging

One of the most useful features of the console is it's logging capability. To use this, simply include the log.js file in your web page using an appropriate script import:

<script src="path_to_console_directory/script.log.js></script>

Then, whenever and wherever you want, you can invoke the log() method to log a message in the console... even if the console isn't running or attached. The log method has the following syntax:

log(message, extra, category)

where the arguments are as follows:

message

Any text or HTML string. This string is not HTML-escaped, so you can format your message as needed.

extra

Secondary information to display. This can be a string, but is usually an object of some sort, which the console will display the contents of.

category

A string defining the category for this object. Note: if you want to use categories, you're probably going to be interested in the createCategory method described below.

It's probably worth elaborating on how logging works when the console is displayed .vs. when it isn't. When the console isn't displayed, the arguments to log() are cached in a message queue. Once the console is opened, it looks for the message queue and displays any messages it finds. One really nice aspect of this behavior is that it lets you generate log messages during the page load sequence, so you can analyze how your web page initializes itself.

Once the console is opened, calls to log() are actually forwarded directly to the console - messages are not cached but are instead displayed immediately. In other words, you can count on the console to show messages in a timely fashion.

Categories

If you've looked at the log.js file, you probably noticed the createCategories function. This method allows you to create some alternate, perhaps simpler ways to log messages to a category.

createCategory() does two things - first, it creates and returns a cover method for the log() method, that automatically specifies the category you specify. For example...

var stderr = log.createCategory('stderr');
stderr('This is my error message', extra_object);

However, having to create and pass around a bunch of category variables can be somewhat of a hassle. So the second thing createCategory() does is to take the function it returns and set it as a property of the log object, using the category name. This means that you could write the above as follows:

log.createCategory('stderr');
log.stderr('This is my error message', extra_object);

Nice, eh? And, to recap, both of these code snippets are synonomous with the following:

log('This is my error message', extra_object, 'stderr');

Note: There is currently no support for hiding/showing messages by category. However support for this is coming "real soon now".

Customizing

The console allows you to supply your own built-in commands. This is done by defining a CONSOLE_COMMANDS array in your web page. For example, the following code defines two additional commands for the console - one to refresh the page, and one to list out the script elements in the page:

var CONSOLE_COMMANDS = [
	{
		name:'reload',
		command:'location = location.href',
		usage: 'reload',
		description: 'Refresh the page',
		style: 'color:#246'
	}
	, {
		name: 'scripts',
		command: 'document.getElementsByTagName(\'script\')'
	}
];