Use the console API

For any window object you can use the console API to add messages to the Web Console. Do note that these messages are only associated to the "page logging" category and this should be avoided whenever possible. Users will be confused if they see messages that do not come from their scripts.

Chrome windows will have their messages shown in the Browser Console. This is useful for addons.

Then any console API call will show in your terminal (string-only, if dump() is enabled) and in the Browser Console. Soon you will not need to import Console.jsm - once all patches from bug 965860 land.

Use the Web Console output API

(Firefox 29.0 / Thunderbird 29.0 / SeaMonkey 2.26)

First you need to get the WebConsole object instance for the tab you want. For this you need to use the DevTools API.

Displays a console API method call as described by a consoleAPICall packet received from the server through the remote debugging protocol. This message class is only used for the log(), info(), warn(), error(), exception(), debug(), count() and assert() methods.

Non-unique ID for this message object used for tracking duplicate messages. Different message kinds can identify themselves based their own criteria.

object render()

Render the message. After this method is invoked the message.element property will point to the DOM element of this message.

Return value: the message instance itself.

void _addLinkCallback(element[, callback])

Add a click callback to the given DOM element. If the callback is not given, a generic anchor click handler is used for opening anchor links in new tabs. Note that the callback is invoked only for single left clicks, not for additional click events (no invocation for right/middle/double clicks). The default event handler is prevented before the callback is invoked.

void destroy()

Invoked when the message is removed.

Messages.Simple

The Simple message is used to show any basic message in the Web Console. This class extends BaseMessage. Constructor arguments:

the message to display. If a DOM element is given the element will be inserted into the message body. If a function is given, then the function is invoked with one argument, the message object, and the result is expected to be a DOM element which is then inserted into the message body.

The Simple message class should cover most common needs for message output. Extensions can override the _render*() methods to change the styling or behavior of these types of messages, based on any criteria (category, severity, location, etc).

Render a grip that represents a value received from the server. This method picks the appropriate widget to render the value with. A grip can represent primitive values like strings and booleans, but it can also represent objects. In that case the grip is an ObjectActor grip.

Arguments:

grip:

the value grip received from the server.

options (optional, object):

options for displaying the value:

noStringQuotes (boolean):

tells the renderer to not use quotes around strings.

concise (boolean):

tells the renderer to compactly display the grip. This is typically set to true when the object needs to be displayed in an array preview, or as a property value in object previews, etc.

This method is invoked by:

_renderBodyPiece() if the given piece is not a DOM element nor a function.

any other message method or widget method that needs to display inline a value grip. For example, previewers for arrays and objects invoke this method to show array elements or object property values.

Customize previews for objects

The Web Console does not have direct access to the JavaScript objects from the content page. The console only receives a JSON packet that describes the JS object from the server - these are provided by the Object Actor. You can customize the output for such objects in console client code, and you can also extend the server to add anything you need to the JSON packet.

For the purpose of this document we describe here the following object actor properties:

type (string):

the result of typeof for the object.

class (string):

The ECMAScript Class of the object to which the instance refers, as a string. This can be anything from RegExp, Number, Date, Array, Set, Map, Object to Window, HTMLDocument, HTMLBodyElement, etc.

displayString (optional, string):

the server can include a suggested string for displaying the object.

preview (optional, object):

the server can include an object with additional presentational information. For example, for arrays the preview object includes the first 10 elements and the array length. For each object type the preview object can be different.

kind (optional, string):

most commonly preview objects include the kind property to indicate the kind of object preview is expected. Different object classes and types can share the same preview kind. For example arrays, typed arrays, sets, DOMTokenList and other object classes share the ArrayLike preview format.

You should set devtools.debugger.log to true in about:config to see the raw JSON packets sent and received by the debugger server.

String-only output

(Firefox 29.0 / Thunderbird 29.0 / SeaMonkey 2.26)

String-only output is used by the object inspector in the Web Console and in the JS Debugger. The web console uses this approach when rich output renderers are not available for any given object.

String-only previews are generated by VariablesView.getString() - see VariablesView.jsm. You can add stringifiers, functions that are given the value grip from the server.

Stringifiers are grouped as follows:

List of VariablesView stringifier categories

Object

Description

VariablesView.stringifiers.byType

Here you can add a stringifier for the object type you want. For example VariablesView.stringifiers.byType.string is used for displaying strings. In this object you can also find stringifiers for longString and object.

VariablesView.stringifiers.byObjectClass

Stringifiers for native object classes. For example, here you can find functions for displaying Number. Date, RegExp and more.

VariablesView.stringifiers.byObjectKind

Stringifiers for object previewer "kinds". Here you can see the stringifiers used for ArrayLike, MapLike, DOMNode and more.

Each of the objects in the table above holds a map of types, object classes or object kinds to functions. The function is invoked with the following arguments:

tells if a concisely formatted string should be generated. This is used when the object preview is part of the preview of a parent object. For example, concise is set to true when previews for array elements are generated.

noStringQuotes (boolean):

tells to not quote strings.

noEllipsis (boolean):

tells to not add an ellipsis after the initial text of a longString.

The stringifiers take the same arguments as VariablesView.getString(). This is the description of the getString() arguments.

Return value: each stringifier is expected to return the string to be displayed. If the stringifier returns null, then a more generic stringifier is used. You can use this return value to explicitly notify you cannot provide a preview for the given value grip.

Object renderers API

For rich output of objects we use widgets and we keep them grouped in the Widgets.ObjectRenderers object. Most often Widgets.JSObject is the base class of all these object renderers, but that is not a requirement - it's just for convenience.

List of ObjectRenderer categories

Object

Description

Widgets.ObjectRenderers.byClass

Widgets for specific object classes. Here you can find the widgets used to display objects like Date and Function.

Widgets.ObjectRenderers.byKind

Widgets for specific preview kinds. Here you can find the widgets used to display ArrayLike, MapLike, DOMEvent, DOMNode objects and more.

Each widget constructor from ObjectRenderers is invoked with the same arguments as the _renderObjectActor(objectActor[, options]) method from Messages.Extended:

objectActor (object):

the ObjectActor grip received from the server.

options (optional, object):

options for displaying the value:

noStringQuotes (boolean):

tells the renderer to not use quotes around strings.

concise (boolean):

tells the renderer to compactly display the grip. This is typically set to true when the object needs to be displayed in an array preview, or as a property value in object previews, etc.

The ObjectRenderer widgets can also have a static method named canRender(objectActor). This is invoked, if available, before the widget is constructed. This method is given only the ObjectActor grip. If true is returned, the widget is used to display the object, otherwise a more generic renderer is used.

Add an object renderer

We have a helper function for adding object renderers, this is Widgets.ObjectRenders.add(descriptor). Properties:

byClass (optional, string):

this renderer will be used for the given object class.

byKind (optional, string):

this renderer will be used for the given object kind. One of the byClass or byKind properties must be provided.

extends (optional, object):

the renderer object extends the given object. Default: Widgets.JSObject.

boolean canRender(objectActor) (optional, function):

this method is invoked when a candidate object needs to be displayed. The function is invoked as a static method, as such, none of the properties of the renderer object will be available. One argument is passed to the function: the object actor grip received from the server. If the method returns true, then this renderer is used for displaying the object, otherwise not.

Add object previewers to the server

(Firefox 29.0 / Thunderbird 29.0 / SeaMonkey 2.26)

The debugger server sends Object Actor grips to the client. The JSON packets are generated in script.js. To add more details to object actors you need to add your function to the DebuggerServer.ObjectActorPreviewers object. This object maps native object class names to arrays of functions, see the class property of Debugger.Object.

When the debugger server is asked for an object actor with class k it goes through each function of DebuggerServer.ObjectActorPreviewers[k]. If the function returns true the search for an object previewer stops. If none of the functions return true then the search starts again in the generic "Object" class, the DebuggerServer.ObjectActorPreviewers.Object array. Here you can add functions that add preview details based on different criteria than the object class.

Your function is invoked with the following arguments:

objectActor (object):

the ObjectActor instance for which an object preview is needed.

grip (object):

the actor grip, the object which will be sent to the client through the remote debugging protocol.

rawObject (optional, object):

this is the raw JavaScript object from the content page without any content script changes. For example, given a DOM element you will not find properties added by the content scripts. This argument is optional because we cannot always provide an unmodified JS object.

The previewer function needs to modify the grip object to add any additional properties needed in the client. The convention is to use a grip.preview object where you add anything you see fit. Do note that these previewers are invoked often - please exercise care and pay attention to performance.

Things to note:

the objectActor argument holds the obj property which is a Debugger.Object which wraps the JS object we work with.

you will need to use the aforementioned Debugger.Object API to read properties from obj and/or execute functions in the content page.

before you can send an object to the client you need to: (1) make it a Debuggee value, using the makeDebuggeeValue() method of Debugger.Object (if it is not already a debugger object), then (2) call the createValueGrip() method of the ThreadActor - it is available through objectActor.threadActor.

rule of thumb: never trust that the object you work with has the expected properties. This is why you should always use the Debugger API to work with such objects.