openlayers/lib/OpenLayers/Console.js

   1 /* Copyright (c) 2006-2008 MetaCarta, Inc., published under the Clear BSD
   2  * license.  See http://svn.openlayers.org/trunk/openlayers/license.txt for the
   3  * full text of the license. */
   4
   5 /**
   6  * Namespace: OpenLayers.Console
   7  * The OpenLayers.Console namespace is used for debugging and error logging.
   8  * If the Firebug Lite (../Firebug/firebug.js) is included before this script,
   9  * calls to OpenLayers.Console methods will get redirected to window.console.
  10  * This makes use of the Firebug extension where available and allows for
  11  * cross-browser debugging Firebug style.
  12  *
  13  * Note:
  14  * Note that behavior will differ with the Firebug extention and Firebug Lite.
  15  * Most notably, the Firebug Lite console does not currently allow for
  16  * hyperlinks to code or for clicking on object to explore their properties.
  17  *
  18  */
  19 OpenLayers.Console = {
  20     /**
  21      * Create empty functions for all console methods.  The real value of these
  22      * properties will be set if Firebug Lite (../Firebug/firebug.js script) is
  23      * included.  We explicitly require the Firebug Lite script to trigger
  24      * functionality of the OpenLayers.Console methods.
  25      */
  26
  27     /**
  28      * APIFunction: log
  29      * Log an object in the console.  The Firebug Lite console logs string
  30      * representation of objects.  Given multiple arguments, they will
  31      * be cast to strings and logged with a space delimiter.  If the first
  32      * argument is a string with printf-like formatting, subsequent arguments
  33      * will be used in string substitution.  Any additional arguments (beyond
  34      * the number substituted in a format string) will be appended in a space-
  35      * delimited line.
  36      *
  37      * Parameters:
  38      * object - {Object}
  39      */
  40     log: function() {},
  41
  42     /**
  43      * APIFunction: debug
  44      * Writes a message to the console, including a hyperlink to the line
  45      * where it was called.
  46      *
  47      * May be called with multiple arguments as with OpenLayers.Console.log().
  48      *
  49      * Parameters:
  50      * object - {Object}
  51      */
  52     debug: function() {},
  53
  54     /**
  55      * APIFunction: info
  56      * Writes a message to the console with the visual "info" icon and color
  57      * coding and a hyperlink to the line where it was called.
  58      *
  59      * May be called with multiple arguments as with OpenLayers.Console.log().
  60      *
  61      * Parameters:
  62      * object - {Object}
  63      */
  64     info: function() {},
  65
  66     /**
  67      * APIFunction: warn
  68      * Writes a message to the console with the visual "warning" icon and
  69      * color coding and a hyperlink to the line where it was called.
  70      *
  71      * May be called with multiple arguments as with OpenLayers.Console.log().
  72      *
  73      * Parameters:
  74      * object - {Object}
  75      */
  76     warn: function() {},
  77
  78     /**
  79      * APIFunction: error
  80      * Writes a message to the console with the visual "error" icon and color
  81      * coding and a hyperlink to the line where it was called.
  82      *
  83      * May be called with multiple arguments as with OpenLayers.Console.log().
  84      *
  85      * Parameters:
  86      * object - {Object}
  87      */
  88     error: function() {},
  89
  90     /**
  91      * APIFunction: userError
  92      * A single interface for showing error messages to the user. The default
  93      * behavior is a Javascript alert, though this can be overridden by
  94      * reassigning OpenLayers.Console.userError to a different function.
  95      *
  96      * Expects a single error message
  97      *
  98      * Parameters:
  99      * object - {Object}
 100      */
 101     userError: function(error) {
 102         alert(error);
 103     },
 104
 105     /**
 106      * APIFunction: assert
 107      * Tests that an expression is true. If not, it will write a message to
 108      * the console and throw an exception.
 109      *
 110      * May be called with multiple arguments as with OpenLayers.Console.log().
 111      *
 112      * Parameters:
 113      * object - {Object}
 114      */
 115     assert: function() {},
 116
 117     /**
 118      * APIFunction: dir
 119      * Prints an interactive listing of all properties of the object. This
 120      * looks identical to the view that you would see in the DOM tab.
 121      *
 122      * Parameters:
 123      * object - {Object}
 124      */
 125     dir: function() {},
 126
 127     /**
 128      * APIFunction: dirxml
 129      * Prints the XML source tree of an HTML or XML element. This looks
 130      * identical to the view that you would see in the HTML tab. You can click
 131      * on any node to inspect it in the HTML tab.
 132      *
 133      * Parameters:
 134      * object - {Object}
 135      */
 136     dirxml: function() {},
 137
 138     /**
 139      * APIFunction: trace
 140      * Prints an interactive stack trace of JavaScript execution at the point
 141      * where it is called.  The stack trace details the functions on the stack,
 142      * as well as the values that were passed as arguments to each function.
 143      * You can click each function to take you to its source in the Script tab,
 144      * and click each argument value to inspect it in the DOM or HTML tabs.
 145      *
 146      */
 147     trace: function() {},
 148
 149     /**
 150      * APIFunction: group
 151      * Writes a message to the console and opens a nested block to indent all
 152      * future messages sent to the console. Call OpenLayers.Console.groupEnd()
 153      * to close the block.
 154      *
 155      * May be called with multiple arguments as with OpenLayers.Console.log().
 156      *
 157      * Parameters:
 158      * object - {Object}
 159      */
 160     group: function() {},
 161
 162     /**
 163      * APIFunction: groupEnd
 164      * Closes the most recently opened block created by a call to
 165      * OpenLayers.Console.group
 166      */
 167     groupEnd: function() {},
 168
 169     /**
 170      * APIFunction: time
 171      * Creates a new timer under the given name. Call
 172      * OpenLayers.Console.timeEnd(name)
 173      * with the same name to stop the timer and print the time elapsed.
 174      *
 175      * Parameters:
 176      * name - {String}
 177      */
 178     time: function() {},
 179
 180     /**
 181      * APIFunction: timeEnd
 182      * Stops a timer created by a call to OpenLayers.Console.time(name) and
 183      * writes the time elapsed.
 184      *
 185      * Parameters:
 186      * name - {String}
 187      */
 188     timeEnd: function() {},
 189
 190     /**
 191      * APIFunction: profile
 192      * Turns on the JavaScript profiler. The optional argument title would
 193      * contain the text to be printed in the header of the profile report.
 194      *
 195      * This function is not currently implemented in Firebug Lite.
 196      *
 197      * Parameters:
 198      * title - {String} Optional title for the profiler
 199      */
 200     profile: function() {},
 201
 202     /**
 203      * APIFunction: profileEnd
 204      * Turns off the JavaScript profiler and prints its report.
 205      *
 206      * This function is not currently implemented in Firebug Lite.
 207      */
 208     profileEnd: function() {},
 209
 210     /**
 211      * APIFunction: count
 212      * Writes the number of times that the line of code where count was called
 213      * was executed. The optional argument title will print a message in
 214      * addition to the number of the count.
 215      *
 216      * This function is not currently implemented in Firebug Lite.
 217      *
 218      * Parameters:
 219      * title - {String} Optional title to be printed with count
 220      */
 221     count: function() {},
 222
 223     CLASS_NAME: "OpenLayers.Console"
 224 };
 225
 226 /**
 227  * Execute an anonymous function to extend the OpenLayers.Console namespace
 228  * if the firebug.js script is included.  This closure is used so that the
 229  * "scripts" and "i" variables don't pollute the global namespace.
 230  */
 231 (function() {
 232     /**
 233      * If Firebug Lite is included (before this script), re-route all
 234      * OpenLayers.Console calls to the console object.
 235      */
 236     var scripts = document.getElementsByTagName("script");
 237     for(var i=0, len=scripts.length; i<len; ++i) {
 238         if(scripts[i].src.indexOf("firebug.js") != -1) {
 239             if(console) {
 240                 OpenLayers.Util.extend(OpenLayers.Console, console);
 241                 break;
 242             }
 243         }
 244     }
 245 })();