AspectJS - Supplementary: Trace-Debugging Library Tutorial - A Guide to using the JavaScript-Library for Displaying Debugging Information

Demonstration
Usage
Shorthand Syntax
Applications

Demonstration

The steps for viewing the demo are as follows:

Ensure that both JavaScript and pop-up windows are enabled on your browser
Pass the mouse cursor over the three elements in the box on the right
Click on the 'Show Window' button. A tracing window will appear and a set of messages reflecting those mouse movements will be displayed
Now move the mouse cursor again over the three elements in the box. The window will display a message for each mouse-over and mouse-out event
Click on the button on the right again
Repeat steps 2 - 5 as many times as you wish
Click the button again to hide the window

Usage

The essential syntax for creating and using a tracing object is shown in the Example One, and while no other calls are necessary for the majority of applications, the library also provides methods for turning tracing on and off, for closing a tracing window, and for closing all tracing windows.

Given this, all that the code for the demonstration does is tie event-handler functions to the HTML for each element, and all that the event handlers do is make a Tracer.MsgOut () call to display the relevant message.

Note that if the window is closed explicitly (i.e. by clicking on its 'close' button) then the demo button's legend does not change from 'Hide Window' back to 'Show Window' automatically (unless you pass the mouse over the test elements again). Unfortunately, this amounts to a bug in the library, in that the window does not communicate the fact that it is closing to the execution context for the host page (this page, in this case). Note also that this same (rather frustrating) technicality also precludes placing a 'Suspend/Resume' button at the top of the tracer window.

A solution to these problems is quite possible, but only in non-Microsoft browsers, and providing one that degrades gracefully in IE would clutter-up the design of what is supposed to be a very simple utility. Happily, this glitch is completely harmless, as the tracer object detects the missing window upon the next call to Tracer.MsgOut (upon which it resumes buffering).


 <!-- Example 1 -->

 <html>
    <head>
       <script type = "text/javascript" src="TracerLib.js"></script>
       <script type = "text/javascript">

       var Tracer = TracerManager.CreateTracer ();

       Tracer.OpenWin ();

       // Application code

       Tracer.MsgOut (" ... ");

       // More application code

       </script>
    </head>

    <body> ... </body>

 </html>

Shorthand Syntax

Note that, as of V1.2 of the library, the Tracer.OpenWin method returns a reference to the Tracer object for which the window has been opened. This means that it is possible to create a tracer and open its window in one rather than two statements, and this makes the presence of debug-code a little less obtrusive within the application.

This is illustrated in Example Two.


 // Example 2

 var Tracer = TracerManager.CreateTracer ().OpenWin ();

 Tracer.MsgOut ("Works as before");

Applications

Obviously, a tracer window can be used for more than displaying simple static character-strings, and an example is enumerating the properties of a JavaScript object. This is accomplished by means of a for ... in loop that outputs the name and value of each member of an object, and is illustrated in Example Three.

Note that the exception handling is necessary because the eval call can fail on certain object-members when running this code in IE.


 // Example 3

 var Tracer = TracerManager.CreateTracer ().OpenWin ();

 EnumerateProperties (window, Tracer);

 function EnumerateProperties (Obj, Tracer)
   {
   Tracer.MsgOut ("--- Enumerating ---");

   for (var Property in Obj)
      {
      try { Tracer.MsgOut (Obj[Property]); }
      catch (e)
         {
         Tracer.MsgOut ("Error evaluating object member. "
                      + e.name
                      + " : "
                      + e.message);

         continue;

         }

      }

   Tracer.MsgOut ("--- Done ---");

   }