Error Console: Difference between revisions

From MozillaZine Knowledge Base
Jump to navigationJump to search
(Components.reportError -> Components.utils.reportError; 1.1a -> 1.5)
Line 3: Line 3:
==What is JavaScript Console==
==What is JavaScript Console==
JavaScript Console is a tool available in most Mozilla-based applications that is used for reporting errors in the application chrome and in web pages user opens. Despite its name it reports not only [[JavaScript]]-related errors and warnings, but also [[CSS]] errors and arbitrary messages from chrome code.
JavaScript Console is a tool available in most Mozilla-based applications that is used for reporting errors in the application chrome and in web pages user opens. Despite its name it reports not only [[JavaScript]]-related errors and warnings, but also [[CSS]] errors and arbitrary messages from chrome code.
[http://forums.mozillazine.org/viewtopic.php?t=318102 Console<sup>2</sup>] provides a replacement for JavaScript Console, fixing many of its bugs and implementing long-wanted enhancement requests.


==Manipulating data displayed in JavaScript Console==
==Manipulating data displayed in JavaScript Console==

Revision as of 23:25, 18 December 2005

This page is part of the extension development documentation project.

Ask your questions in MozillaZine Forums. Also try browsing example code.

Note: development documentation is in process of being moved to Mozilla Development Center (MDC).

What is JavaScript Console

JavaScript Console is a tool available in most Mozilla-based applications that is used for reporting errors in the application chrome and in web pages user opens. Despite its name it reports not only JavaScript-related errors and warnings, but also CSS errors and arbitrary messages from chrome code.

Console2 provides a replacement for JavaScript Console, fixing many of its bugs and implementing long-wanted enhancement requests.

Manipulating data displayed in JavaScript Console

Information displayed in JavaScript Console can be accessed and manipulated through nsIConsoleService interface. To get it use the code similar to the following (you can read more about creating XPCOM components and interfaces here):

var consoleService = Components.classes['@mozilla.org/consoleservice;1']
                               .getService(Components.interfaces.nsIConsoleService);

Logging custom messages in JavaScript Console

There are two functions in nsIConsoleService that may be used to log messages from your code: logMessage() and logStringMessage(). The former is more flexible, while the latter is easier to use. How to use each of them is explained below.

The easy way

To print simple string messages to JavaScript Console, use the following code:

consoleService.logStringMessage("Hello world!");

You may want to create a helper function like this:

function myDump(aMessage) {
  var consoleService = Components.classes["@mozilla.org/consoleservice;1"]
                                 .getService(Components.interfaces.nsIConsoleService);
  consoleService.logStringMessage("My extension: " + aMessage);
}

You can also use the dump() function for that. For more details see Viewing dump() output.

The advanced way

The more tricky way is to pass an nsIScriptError instance to nsIConsoleService.logMessage() method:

function myLogToConsole(aMessage, aSourceName, aSourceLine, aLineNumber, 
                        aColumnNumber, aFlags, aCategory)
{
  var consoleService = Components.classes["@mozilla.org/consoleservice;1"]
                                 .getService(Components.interfaces.nsIConsoleService);
  var scriptError = Components.classes["@mozilla.org/scripterror;1"]
                              .createInstance(Components.interfaces.nsIScriptError);
  scriptError.init(aMessage, aSourceName, aSourceLine, aLineNumber, 
                   aColumnNumber, aFlags, aCategory);
  consoleService.logMessage(scriptError);
}

The above function logs a message like this to JavaScript Console:

Warning: function goQuitApplication does not always return a value
Source File: chrome://global/content/globalOverlay.js     Line: 68
  return true;
--------------^

Now to the meaning of function's parameters:

  • aMessage — the string to be logged. You must provide this.
  • aSourceName — the URL of file with error. This will be a hyperlink in the JavaScript Console, so you'd better use real URL. You may pass null if it's not applicable.
  • aSourceLine — the line #aLineNumber from aSourceName file. You are responsible for providing that line. You may pass null if you are lazy; that will prevent showing the source line in JavaScript Console.
  • aLineNumber and aColumnNumber — specify the exact location of error. aColumnNumber is used to draw the arrow pointing to the problem character.
  • aFlags — one of flags declared in nsIScriptError. At the time of writing, possible values are: nsIScriptError.errorFlag = 0, nsIScriptError.warningFlag = 1, nsIScriptError.exceptionFlag = 2 and nsIScriptError.strictFlag = 4.
  • aCategory — a string indicating what kind of code caused the message. There are quite a few category strings and they don't seem to be listed in a single place. Hopefully, they will all be listed in nsIScriptError.idl eventually.

An example call, that generates the above warning:

myLogToConsole("function goQuitApplication does not always return a value", 
  "chrome://global/content/globalOverlay.js", "  return true;", 68, 13, 
  Components.interfaces.nsIScriptError.warningFlag, "XUL javascript");

Using Components.utils.reportError

In Firefox 1.5 and later (and other products) there's a new method, Components.utils.reportError(). It is intended to be used in a catch block to report caught errors in the JS Console, but you can also use it to log arbitrary messages. Note, that unlike nsIConsoleService.log[String]Message(), Components.utils.reportError() reports the message with severity "error".

Example 1. This is how Components.utils.reportError() is intended to be used.

try {
  ...
} catch(e) {
  // handle the exception
  Components.utils.reportError(e); // still report it to the console
}

Example 2. This is a very easy way to print a string to the JS Console, which you can use for debugging, if you can't be bothered to obtain a reference to console service (as described above).

Components.utils.reportError("hi!")

Again, this only works on Firefox/Thunderbird 1.5 or later.

Note: during the 1.5 development cycle, this function was initially introduced as Components.reportError(). The access by older name is supported, but deprecated. It may be removed in the future versions.

Using console listeners

This section is a stub. You can help MozillaZine knowledge base by writing it.
  • What are console listeners. When they are used (in JS Console implementation, for example).
  • An example of console listener, registered with nsIConsoleService.registerListener().

Accessing available messages

This section is a stub. You can help MozillaZine knowledge base by writing it.
  • An example using nsIConsoleService.getMessageArray().
  • Possible performance problems.

Miscellaneous

toJavaScriptConsole()

If your code is executed in a browser or mail overlay, the toJavaScriptConsole() helper function is available. It opens the JavaScript Console, useful when debugging an extension.

Resources