MozillaZine

Error Console

From MozillaZine Knowledge Base

(Difference between revisions)
Revision as of 10:34, 16 January 2005
Asqueella (Talk | contribs)
(adding Example code category)
<-- Previous diff
Revision as of 16:16, 24 January 2005
Asqueella (Talk | contribs)
(add more info)
Next diff -->
Line 1: Line 1:
{{extdev}} {{extdev}}
-You can print information to JavaScript Console using the following method:+==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.
-<ol>+==Manipulating data displayed in JavaScript Console==
-<li>Declare a variable (global if you're scripting your own window or [[Dev : Javascript coding guidelines|your object's member]] if you're overlaying an existing window):+Information displayed in [[JavaScript Console]] can be accessed and manipulated through <code>nsIConsoleService</code> interface. To get it use the code similar to the following (you can read more about creating XPCOM components and interfaces [http://xulplanet.com/references/xpcomref/creatingcomps.html here]):
-<pre>var gConsoleService = Components.classes['@mozilla.org/consoleservice;1']+<pre>var consoleService = Components.classes['@mozilla.org/consoleservice;1']
.getService(Components.interfaces.nsIConsoleService);</pre> .getService(Components.interfaces.nsIConsoleService);</pre>
-(note, that you can use <tt>toJavaScriptConsole()</tt> function to open JavaScript console on startup) 
-</li> 
-<li>Define a function:+===Logging custom messages in JavaScript Console===
-<pre>function myExt_logMessage(aMessage) {+There are two functions in <code>nsIConsoleService</code> that may be used to log messages from your code: <code>logMessage()</code> and <code>logStringMessage()</code>. The former is more flexible, while the latter is easier to use. How to use each of them is explained below.
- gConsoleService.logStringMessage('My extension: ' + aMessage);+ 
 +====The easy way====
 +To print simple string messages to JavaScript Console, use the following code:
 +<pre>consoleService.logStringMessage("Hello world!");</pre>
 + 
 +You may want to create a helper function like this:
 +<pre>
 +function myDump(aMessage) {
 + var consoleService = Components.classes["@mozilla.org/consoleservice;1"]
 + .getService(Components.interfaces.nsIConsoleService);
 + consoleService.logStringMessage("My extension: " + aMessage);
}</pre> }</pre>
-</li>+You can also use the <code>dump()</code> function for that. For more details see [[Viewing dump() output]].
-<li>Use it like here:+ 
-<pre>myExt_logMessage("Initialized.");</pre>+====The advanced way====
-</li>+The more tricky way is to pass an <code>nsIScriptError</code> instance to <code>nsIConsoleService.logMessage()</code> method:
-</ol>+ 
 +<pre>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);
 +}</pre>
 + 
 +The above function logs a message like this to JavaScript Console:
 +<pre>Warning: function goQuitApplication does not always return a value
 +Source File: chrome://global/content/globalOverlay.js Line: 68
 + return true;
 +--------------^</pre>
 + 
 +Now to the meaning of function's parameters:
 +*<code>aMessage</code> &mdash; the string to be logged. You must provide this.
 +*<code>aSourceName</code> &mdash; 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 <code>null</code> if it's not applicable.
 +*<code>aSourceLine</code> &mdash; the line #<code>aLineNumber</code> from <code>aSourceName</code> file. You are responsible for providing that line. You may pass <code>null</code> if you are lazy; that will prevent showing the source line in JavaScript Console.
 +*<code>aLineNumber</code> and <code>aColumnNumber</code> &mdash; specify the exact location of error. <code>aColumnNumber</code> is used to draw the arrow pointing to the problem character.
 +*<code>aFlags</code> &mdash; one of flags declared in <code>nsIScriptError</code>. At the time of writing, possible values are: <code>nsIScriptError.errorFlag = 0</code>, <code>nsIScriptError.warningFlag = 1</code>, <code>nsIScriptError.exceptionFlag = 2</code> and <code>nsIScriptError.strictFlag = 4</code>.
 +*<code>aCategory</code> &mdash; 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 <tt>nsIScriptError.idl</tt> eventually.
 + 
 +An example call, that generates the above warning:
 +<pre>myLogToConsole("function goQuitApplication does not always return a value",
 + "chrome://global/content/globalOverlay.js", " return true;", 68, 13,
 + Components.interfaces.nsIScriptError.warningFlag, "XUL javascript");</pre>
 + 
 +===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 <code>nsIConsoleService.registerListener()</code>.
 + 
 +===Accessing available messages===
 +:''This section is a stub. You can help MozillaZine knowledge base by writing it.''
 +* An example using <code>nsIConsoleService.getMessageArray()</code>.
 +* Possible performance problems.
 + 
 +==Miscellaneous==
 + 
 +===toJavaScriptConsole()===
 +If your code is executed in a browser or mail overlay, the <code>toJavaScriptConsole()</code> helper function is available. It opens the JavaScript Console, useful when debugging an extension.
 + 
 +==Resources==
 +* [http://www.mozilla.org/projects/xpcom/using-consoleservice.html Using Console service document] at mozilla.org
 +* XulPlanet.com documents
 +** [http://xulplanet.com/references/xpcomref/ifaces/nsIConsoleService.html nsIConsoleService]
 +** [http://xulplanet.com/references/xpcomref/ifaces/nsIScriptError.html nsIScriptError]
-See also: [[Viewing dump() output]], [http://www.mozilla.org/projects/xpcom/using-consoleservice.html Using Console service]. 
-[[Category:Development]] [[Category:Example code|Printing to Javascript Console]]+[[Category:Development]] [[Category:Example code]]

Revision as of 16:16, 24 January 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).

Contents

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.

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 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