You've seen the quick demonstration on the home page, and now you probably want a more comprehensive explanation of how to use jTrace. It just so happens that you've come to the right place.
Using jTrace Before you start littering your code with jTrace calls, it really is a good idea to make sure you have the jTrace.js file set up properly in your html file. How do you set it up? It's simple, just include the jTrace.js file somewhere in your html file below your jQuery script-tag.
Example script tags:
<script type="text/javascript" src="javascript/jTrace.js"></script>
I'll leave it up to you where you want to put those script-tags (personally I follow the yahoo developers and place my script tags right above the closing body tag (</body>). You can always throw it in between your <head></head> tags if you want.
Applying inline jTrace calls to your html files: You can either tie an event to jTrace (like an onclick), or you can just drop the script tag right in your html and let it do it's thing.
If you followed the above setup/usage method, then all you need to do is call jTrace on any event. To use jTrace on a click event you could do the following:
With the above code jTrace will show the message "You clicked on the link!" when your link is clicked. For a live example, just click the following link (it uses the same code). Click here to see a trace message in the jTrace Window.
You can also use jTrace inline to show the value of input, variables, etc.
<input type="text" name="onchange-test-input" id="onchange-test-input" value="0" size="2" onchange="jTrace('Value of #onchange-test-input: ' + $('#onchange-test-input').val(),'');"/>
If you look at the code you'll notice that I used jQuery to get the value of the text box, but that doesn't mean that you have to, you can always grab the value by using document.getElementById('onchange-test-input').value instead of $('#onchange-test-input').val() . Although since this is a jQuery plugin, I suppose it doesn't make much sense not to use jQuery ;)
For another example of inline code we can use the setTimeout funciton (like I used on the home page). Please note: if you are going to throw jTrace in the middle the page, make sure that you've included/imported/referenced the jTrace.js and jQuery.js file above where you are inserting the code! This will help you avoid javascript errors being thrown on page load.
<script type="text/javascript" src="javascript/jTrace.js"></script>
...
<!-- your html code -->
...
<script type="text/javascript">setTimeout("jTrace('30 second timer fired!','warning')","30000");</script>
I know, I know, how useful is an inline setTimeout function, not very right? But this is a good foundation for seeing that you can use an inline script. If you were using a templating or decorating system (like sitemesh, tiles, etc.) you could throw the jTrace.js file in your decorator/template, then just throw the <script> tag in the file you needed to trace, assign an event handler to something on your page, and BAM!, instant variable notification in your jTrace Window. Let's take a quick look at a JSP using JSTL example of how this could be useful.
<%-- setting myValue variable --%>
<c:set var="myValue" value="${category.description.name}" />
...jsp code...
<%-- Test the variable in jTrace --%>
<script type="text/javascript">
$("document").click(function(){ //I'm attaching to the document level so that a click anywhere will populate my trace log
jTrace('The Value of myValue: ' + <c:out value='${myValue}' />,'warning');
});
</script>
I'm not running a java server pages equiped server here, so I can't give you a live sample, but for those of you who do have one, this example should be enough to get you started. Note that I'm using the old JSTL version of outputting a variable (using the <c:out...), in theory you could just use ${myValue} (JSTL 2.0 spec... I think), but I haven't tested that yet, so go with it at your own risk ;)
Using jTrace in an external js file: Using jTrace in an external js file is just about the same as using it inline. Instead of only using it only to see when events are triggering, or for value checking, you can use it to really see what your functions are doing (In my opinion, this is what jTrace was really created for).
Let's write up an example. So you have a function that calls another function before it finishes, and you want to know when it enters the second function and to check what the values are while in that function. With jTrace, this is just a few lines of code.
<label for="number-test-input">Enter a number in the box and click the Go button.</label>
<input type="text" name="number-test-input" id="number-test-input" value="" size="4" />
//This is in your external js file (scripts.js, or what-have-you)
$("#number-test-input").change(function(){
jTrace('Value in #number-test-input = ' + this.value,'warning');
numeric(this.value);
jTrace('numberic function has completed','');
});
function numeric(input){
jTrace('Entered numeric function','');
if(input.match(/^\d+$/)){
jTrace('a number (' + input + ') was passed','warning');
} else {
jTrace('(' + input + ') is not a number!','error');
}
jTrace('Leaving numeric function','');
}
The above code will check the input box to see if a number was entered into the text input. I used an onchange event (although you could use just about anything you wanted) to fire off the event (so if you refreshed the page, click the input, press enter, and nothing happens, it's because you didn't change the value in the box. Anyway, I added a jTrace call into the external js when the "numeric" function was entered, then another call to show the value of what had been passed into the function, another to show that the function had run and was leaving, and finally one call to show that the original function had been completed.
I clicked "close" on the jTrace Window and now the jTrace Window is gone! Uh... yeah, that's what 'close' means. That button was put on there because as you may have noticed, every once in a while the jTrace Window sits right on top of something you want to read or see on your page. You can get the window back by refreshing the page... OR if you are using firebug in conjunction with jTrace switch to the console, then type: $("#jTrace").show(); and click 'run'. If you did it right, the jTrace Window will be back and you can continue on your way.
In the jTrace Window, what do the wide and original words do? Since you probably clicked on "close" (it's a button...ish) you're probably a little apprehensive about clicking on those other word-buttons aren't you? Well don't worry, the "wide" word (button) makes the jTrace Window expand to the width of your screen (it does not change the height). The "original" word-button just shrinks the jTrace Window back to normal size. While it may take up a bit of screen real-estate, using firebug with the jTrace window on "wide" actually looks pretty good, I mean that could just be me, but I like it.