Console API

From FirebugWiki

(Difference between revisions)
Jump to: navigation, search
(Fixed broken markup)
(Described %.xf)
(17 intermediate revisions not shown)
Line 1: Line 1:
-
{{stub}}
+
Firebug adds a global variable named "console" to all web pages loaded in Firefox.  This object contains many methods that allow you to write to the Firebug console to expose information that is flowing through your scripts.
-
<p>Firebug adds a global variable named "console" to all web pages loaded in Firefox.  This object contains many methods that allow you to write to the Firebug console to expose information that is flowing through your scripts.</p>
+
== Commands ==
-
            <h3>console.log(object[, object, ...])</h3>
+
=== console.log(object[, object, ...]) ===
-
            <p>Writes a message to the console. You may pass as many arguments as you'd like, and they will be joined together in a space-delimited line.</p>
+
Writes a message to the console. You may pass as many arguments as you'd like, and they will be joined together in a space-delimited line.
-
            <p>The first argument to <code>log</code> may be a string containing printf-like string substitution patterns.  For example:</p>
+
-
            <pre class="code">console.log("The %s jumped over %d tall buildings", animal, count);</pre>
+
-
            <p>The example above can be re-written without string substitution to achieve the same result:</p>
+
-
            <pre class="code">console.log("The", animal, "jumped over", count, "tall buildings");</pre>
+
The first argument to <code>log</code> may be a string containing printf-like string substitution patterns. For example:
-
            <p>These two techniques can be combined.  If you use string substitution but provide more arguments than there are substitution patterns, the remaining arguments will be appended in a space-delimited line, like so:</p>
+
-
            <pre class="code">console.log("I am %s and I have:", myName, thing1, thing2, thing3);</pre>
+
-
            <p>If objects are logged, they will be written not as static text, but as interactive hyperlinks that can be clicked to inspect the object in Firebug's HTML, CSS, Script, or DOM tabs.  You may also use the %o pattern to substitute a hyperlink in a string.</p>
+
-
            <p>Here is the complete set of patterns that you may use for string substitution:</p>
+
<source lang="javascript">
-
            <table width="600">
+
console.log("The %s jumped over %d tall buildings", animal, count);
 +
</source>
-
                <tr><td class="keyHead" colspan="2">String Substitution Patterns</td></tr>
+
The example above can be re-written without string substitution to achieve the same result:
-
                <tr><td class="keyType">%s</td><td class="keyCode">String</td></tr>
+
-
                <tr><td class="keyType">%d, %i</td><td class="keyCode">Integer (numeric formatting is not yet supported)</td></tr>
+
-
                <tr><td class="keyType">%f</td><td class="keyCode">Floating point number (numeric formatting is not yet supported)</td></tr>
+
-
                <tr><td class="keyType">%o</td><td class="keyCode">Object hyperlink</td></tr>
+
-
            </table>
+
<source lang="javascript">
 +
console.log("The", animal, "jumped over", count, "tall buildings");
 +
</source>
-
            <h3>console.debug(object[, object, ...])</h3>
+
These two techniques can be combined. If you use string substitution but provide more arguments than there are substitution patterns, the remaining arguments will be appended in a space-delimited line, like so:
-
            <p>Writes a message to the console, including a hyperlink to the line where it was called.</p>
+
-
            <h3>console.info(object[, object, ...])</h3>
+
<source lang="javascript">
-
            <p>Writes a message to the console with the visual "info" icon and color coding and a hyperlink to the line where it was called.</p>
+
console.log("I am %s and I have:", myName, thing1, thing2, thing3);
 +
</source>
-
            <h3>console.warn(object[, object, ...])</h3>
+
If objects are logged, they will be written not as static text, but as interactive hyperlinks that can be clicked to inspect the object in Firebug's HTML, CSS, Script, or DOM tabs. You may also use the <code>%o</code> pattern to substitute a hyperlink in a string.
-
            <p>Writes a message to the console with the visual "warning" icon and color coding and a hyperlink to the line where it was called.</p>
+
-
            <h3>console.error(object[, object, ...])</h3>
+
You may also use the <code>%c</code> pattern to use the second argument as a style formatting parameter. For example:
-
            <p>Writes a message to the console with the visual "error" icon and color coding and a hyperlink to the line where it was called.</p>
+
-
            <h3>console.assert(expression[, object, ...])</h3>
+
<source lang="javascript">
 +
console.log("%cThis is green text on a yellow background.", "color:green; background-color:yellow");
 +
</source>
-
            <p>Tests that an expression is true.  If not, it will write a message to the console and throw an exception.</p>
+
You can even use several <code>%c</code> patterns within the string to use different formattings. For each <code>%c</code> there needs to be one argument:
-
            <h3>console.dir(object)</h3>
+
<source lang="javascript">
-
            <p>Prints an interactive listing of all properties of the object.  This looks identical to the view that you would see in the DOM tab.</p>
+
console.log("%cRed text, %cgreen text, %cblue text", "color:red", "color:green", "color:blue");
 +
</source>
-
            <h3>console.dirxml(node)</h3>
+
Here is the complete set of patterns that you may use for string substitution:
-
            <p>Prints the XML source tree of an HTML or XML element.  This looks identical to the view that you would see in the HTML tab.  You can click on any node to inspect it in the HTML tab.</p>
+
-
            <h3>console.trace()</h3>
+
{| class="wikitable"
-
            <p>Prints an interactive stack trace of JavaScript execution at the point where it is called.</p>
+
|-
-
            <p>The stack trace details the functions on the stack, as well as the values that were passed as arguments to each function.  You can click each function to take you to its source in the Script tab, and click each argument value to inspect it in the DOM or HTML tabs.</p>
+
! Pattern !! Type
 +
|-
 +
| <code>%s</code> || String
 +
|-
 +
| <code>%d</code>, <code>%i</code> || Integer (numeric formatting is not yet supported)
 +
|-
 +
| <code>%f</code>/<code>%.''x''f</code> || Floating point number; ''x'' denotes the number of decimal places the number should be rounded to (if ommitted, the number won't be rounded)
 +
|-
 +
| <code>%o</code> || Object hyperlink
 +
|-
 +
| <code>%c</code> || Style formatting
 +
|}
-
            <h3>console.group(object[, object, ...])</h3>
+
=== console.debug(object[, object, ...]) ===
-
            <p>Writes a message to the console and opens a nested block to indent all future messages sent to the console.  Call <code>console.groupEnd()</code> to close the block.</p>
+
Writes a message to the console, including a hyperlink to the line where it was called.
-
            <h3>console.groupCollapsed(object[, object, ...])</h3>
+
=== console.info(object[, object, ...]) ===
-
            <p>Like <code>console.group()</code>, but the block is initially collapsed.</p>
+
Writes a message to the console with the visual "info" icon and color coding and a hyperlink to the line where it was called.
-
            <h3>console.groupEnd()</h3>
+
=== console.warn(object[, object, ...]) ===
-
            <p>Closes the most recently opened block created by a call to <code>console.group()</code> or <code>console.groupEnd()</code></p>
+
Writes a message to the console with the visual "warning" icon and color coding and a hyperlink to the line where it was called.
-
            <h3>console.time(name)</h3>
+
=== console.error(object[, object, ...]) ===
-
            <p>Creates a new timer under the given name.  Call <code>console.timeEnd(name)</code> with the same name to stop the timer and print the time elapsed..</p>
+
Writes a message to the console with the visual "error" icon and color coding and a hyperlink to the line where it was called.
-
            <h3>console.timeEnd(name)</h3>
+
=== console.assert(expression[, object, ...]) ===
-
            <p>Stops a timer created by a call to <code>console.time(name)</code> and writes the time elapsed.</p>
+
Tests that an expression is true.  If not, it will write a message to the console and throw an exception.
-
            <h3>console.profile([title])</h3>
+
=== console.clear() ===
-
            <p>Turns on the JavaScript profiler.  The optional argument <code>title</code> would contain the text to be printed in the header of the profile report.</p>
+
Clears the console.
-
            <h3>console.profileEnd()</h3>
+
=== console.dir(object) ===
-
            <p>Turns off the JavaScript profiler and prints its report.</p>
+
Prints an interactive listing of all properties of the object.  This looks identical to the view that you would see in the DOM tab.
-
            <h3>console.count([title])</h3>
+
=== console.dirxml(node) ===
-
            <p>Writes the number of times that the line of code where <code>count</code> was called was executedThe optional argument <code>title</code> will print a message in addition to the number of the count.</p>
+
Prints the XML source tree of an HTML or XML element.  This looks identical to the view that you would see in the HTML tabYou can click on any node to inspect it in the HTML tab.
-
           
+
=== console.trace() ===
-
            <h2>Implementation Notes</h2>
+
Prints an interactive stack trace of JavaScript execution at the point where it is called.
-
            <p>The <code>console</code> is an object attached to the <code>window</code> object in the web page.
+
The stack trace details the functions on the stack, as well as the values that were passed as arguments to each function. You can click each function to take you to its source in the Script tab, and click each argument value to inspect it in the DOM or HTML tabs.
-
            In Firebug for Firefox the object is attached only if the Console panel is enabled. In Firebug lite,
+
-
            the console is attached if Lite is installed in the page.</p>
+
-
            <h3>Firebug 1.4</h3>
+
-
            <p>The console is implemented by adding a <code>div</code> element and a <code>script</code> tag to the web page just
+
-
            before the first Javascript script tag is run. So the first script tag is compiled, then the console is injected, then
+
-
            the outer function code of the script tag is executed.</p>
+
-
            <h3>Firebug 1.3</h3>
+
=== console.group(object[, object, ...]) ===
-
            <p>As in Firebug 1.4</p>
+
Writes a message to the console and opens a nested block to indent all future messages sent to the console.  Call <code>console.groupEnd()</code> to close the block.
-
            <h3>Firebug 1.2</h3>
+
 
-
            <p>The code and tags are added on document load event.</p>
+
=== console.groupCollapsed(object[, object, ...]) ===
-
            <h3>Firebug 1.1 and earlier</h3>
+
Like <code>console.group()</code>, but the block is initially collapsed.
-
            <p>The console is implemented with an insecure technique</p>
+
 
 +
=== console.groupEnd() ===
 +
Closes the most recently opened block created by a call to <code>console.group()</code> or <code>console.groupCollapsed()</code>
 +
 
 +
=== console.time(name) ===
 +
Creates a new timer under the given name.  Call <code>console.timeEnd(name)</code> with the same name to stop the timer and print the time elapsed..
 +
 
 +
=== console.timeEnd(name) ===
 +
Stops a timer created by a call to <code>console.time(name)</code> and writes the time elapsed.
 +
 
 +
=== console.timeStamp(name) ===
 +
Creates a time stamp, which can be used together with [[Net Panel#Request Timeline|HTTP traffic timing]] to measure when a certain piece of code was executed.
 +
 
 +
=== console.profile([title]) ===
 +
Turns on the JavaScript profiler.  The optional argument <code>title</code> would contain the text to be printed in the header of the profile report.
 +
 
 +
=== console.profileEnd() ===
 +
Turns off the JavaScript profiler and prints its report.
 +
 
 +
=== console.count([title]) ===
 +
Writes the number of times that the line of code where <code>count</code> was called was executed.  The optional argument <code>title</code> will print a message in addition to the number of the count.
 +
 
 +
=== console.exception(error-object[, object, ...]) ===
 +
Prints an error message together with an interactive stack trace of JavaScript execution at the point where the exception occurred.
 +
 
 +
=== console.table(data[, columns]) ===
 +
Allows to log provided data using tabular layout. The method takes one required parameter that represents table-like data (array of arrays or list of objects). The optional <code>columns</code> parameter can be used to specify columns and/or properties to be logged (see more at [http://www.softwareishard.com/blog/firebug/tabular-logs-in-firebug/ softwareishard.com]).
 +
 
 +
== Implementation Notes ==
 +
* The <code>console</code> is an object attached to the <code>window</code> object in the web page.
 +
* If the page already contains a <code>console</code> variable, it is '''not''' overwritten by Firebug's Console API.
 +
* In Firebug for Firefox the object is attached only if the [[Console Panel]] is enabled, and it is injected just before the first JavaScript script tag is run. So the first script tag is compiled, then the console is injected, then the outer function code of the script tag is executed. As a consequence, Firebug might not always catch logs done by e.g. Greasemonkey scripts. [http://code.google.com/p/fbug/issues/detail?id=4978 This might be fixed in a future version.]
 +
* In [http://getfirebug.com/firebuglite Firebug Lite], the console is attached as soon as Lite is installed into the page.
 +
 
 +
== Note ==
 +
The console API formerly implemented a <code>console.firebug</code> property. This property was removed from the API in Firebug 1.9.0 in order to prevent sites from detecting whether a user has Firebug installed.
 +
 
 +
== See also ==
 +
* [[Console]]
 +
* [[Command Line API]]

Revision as of 21:34, 21 August 2013

Firebug adds a global variable named "console" to all web pages loaded in Firefox. This object contains many methods that allow you to write to the Firebug console to expose information that is flowing through your scripts.

Contents

Commands

console.log(object[, object, ...])

Writes a message to the console. You may pass as many arguments as you'd like, and they will be joined together in a space-delimited line.

The first argument to log may be a string containing printf-like string substitution patterns. For example:

console.log("The %s jumped over %d tall buildings", animal, count);

The example above can be re-written without string substitution to achieve the same result:

console.log("The", animal, "jumped over", count, "tall buildings");

These two techniques can be combined. If you use string substitution but provide more arguments than there are substitution patterns, the remaining arguments will be appended in a space-delimited line, like so:

console.log("I am %s and I have:", myName, thing1, thing2, thing3);

If objects are logged, they will be written not as static text, but as interactive hyperlinks that can be clicked to inspect the object in Firebug's HTML, CSS, Script, or DOM tabs. You may also use the %o pattern to substitute a hyperlink in a string.

You may also use the %c pattern to use the second argument as a style formatting parameter. For example:

console.log("%cThis is green text on a yellow background.", "color:green; background-color:yellow");

You can even use several %c patterns within the string to use different formattings. For each %c there needs to be one argument:

console.log("%cRed text, %cgreen text, %cblue text", "color:red", "color:green", "color:blue");

Here is the complete set of patterns that you may use for string substitution:

Pattern Type
%s String
%d, %i Integer (numeric formatting is not yet supported)
%f/%.xf Floating point number; x denotes the number of decimal places the number should be rounded to (if ommitted, the number won't be rounded)
%o Object hyperlink
%c Style formatting

console.debug(object[, object, ...])

Writes a message to the console, including a hyperlink to the line where it was called.

console.info(object[, object, ...])

Writes a message to the console with the visual "info" icon and color coding and a hyperlink to the line where it was called.

console.warn(object[, object, ...])

Writes a message to the console with the visual "warning" icon and color coding and a hyperlink to the line where it was called.

console.error(object[, object, ...])

Writes a message to the console with the visual "error" icon and color coding and a hyperlink to the line where it was called.

console.assert(expression[, object, ...])

Tests that an expression is true. If not, it will write a message to the console and throw an exception.

console.clear()

Clears the console.

console.dir(object)

Prints an interactive listing of all properties of the object. This looks identical to the view that you would see in the DOM tab.

console.dirxml(node)

Prints the XML source tree of an HTML or XML element. This looks identical to the view that you would see in the HTML tab. You can click on any node to inspect it in the HTML tab.

console.trace()

Prints an interactive stack trace of JavaScript execution at the point where it is called.

The stack trace details the functions on the stack, as well as the values that were passed as arguments to each function. You can click each function to take you to its source in the Script tab, and click each argument value to inspect it in the DOM or HTML tabs.

console.group(object[, object, ...])

Writes a message to the console and opens a nested block to indent all future messages sent to the console. Call console.groupEnd() to close the block.

console.groupCollapsed(object[, object, ...])

Like console.group(), but the block is initially collapsed.

console.groupEnd()

Closes the most recently opened block created by a call to console.group() or console.groupCollapsed()

console.time(name)

Creates a new timer under the given name. Call console.timeEnd(name) with the same name to stop the timer and print the time elapsed..

console.timeEnd(name)

Stops a timer created by a call to console.time(name) and writes the time elapsed.

console.timeStamp(name)

Creates a time stamp, which can be used together with HTTP traffic timing to measure when a certain piece of code was executed.

console.profile([title])

Turns on the JavaScript profiler. The optional argument title would contain the text to be printed in the header of the profile report.

console.profileEnd()

Turns off the JavaScript profiler and prints its report.

console.count([title])

Writes the number of times that the line of code where count was called was executed. The optional argument title will print a message in addition to the number of the count.

console.exception(error-object[, object, ...])

Prints an error message together with an interactive stack trace of JavaScript execution at the point where the exception occurred.

console.table(data[, columns])

Allows to log provided data using tabular layout. The method takes one required parameter that represents table-like data (array of arrays or list of objects). The optional columns parameter can be used to specify columns and/or properties to be logged (see more at softwareishard.com).

Implementation Notes

  • The console is an object attached to the window object in the web page.
  • If the page already contains a console variable, it is not overwritten by Firebug's Console API.
  • In Firebug for Firefox the object is attached only if the Console Panel is enabled, and it is injected just before the first JavaScript script tag is run. So the first script tag is compiled, then the console is injected, then the outer function code of the script tag is executed. As a consequence, Firebug might not always catch logs done by e.g. Greasemonkey scripts. This might be fixed in a future version.
  • In Firebug Lite, the console is attached as soon as Lite is installed into the page.

Note

The console API formerly implemented a console.firebug property. This property was removed from the API in Firebug 1.9.0 in order to prevent sites from detecting whether a user has Firebug installed.

See also

Personal tools