Sortie personnalisée dans la Console Web

Ce document décrit comment vous pouvez étendre et personnaliser la sortie de la Console Web et de la Console Javascript. Vous pourreez aussi apprendre comment étendre l'aperçu des objets que nous générons dans les consoles et dans l'Inspecteur d'Objet.

Modification du style de la sortie

La feuille de style pour la sortie de la console est webconsole.css. Vous devriez ajouter tous les styles à ce fichier, dans votre thème. Utilisez la Boîte d'Outils du Navigateur ou l'extension «Inspecteur DOM» pour trouver la structure du balisage de la sortie de la console, des éléments et des classes utilisées.

Dans votre extension, vous pouvez ajouter des styles et du comportement personnalisé au fichier webconsole.xul.

En apprendre plus sur la création de thèmes pour Firefox.

Ajouter des messages

Pour ajouter un message à la Console Web, vous devez premièrement quel API vous voulez utilisez et à quel onglet votre message appartient. Vous avez plusieurs options, comme indiqué ci-dessous.

Utiliser le nsIConsoleService

Créez une instance nsIScriptError et définissez le innerWindowID de votre message pour qu'il soit le même que le innerWindowID de la fenêtre de haut niveau de l'onglet où vous voulez que votre message soit affiché. Vous pouvez aussi utiliser le innerWindowID de n'importe quel iframe contenu dans l'onglet.

Tous les messages venant nsiConsoleService sont mis dans une des catégories CSS, Security ou JavaScript. Assurez-vous d'avoir les bonnes valeurs pour la catégorie et la sévérité du message d'erreur.

Si l'erreur n'a pas de innerWindowID, ou si celui-ci est incorrect, le message ne sera pas affiché dans la Console Web ou dans l'onglet que vous voulez. Vous devriez voir tous les messages dans la Console de Navigateur (introduite avec Firefox 24).

Exemple de code qui utilise nsIScriptError:

const { classes: Cc, interfaces: Ci, utils: Cu } = Components;
const WARN_FLAG = Ci.nsIScriptError.warningFlag;
const ERROR_FLAG = Ci.nsIScriptError.ERROR_FLAG;

Cu.import("resource://gre/modules/Services.jsm");

// Log a message to the Web Console using an nsIScriptError.
function logMessage({flags, message, category, url,
                     lineText, line, column, windowId}) {
  let scriptError = Cc["@mozilla.org/scripterror;1"]
                    .createInstance(Ci.nsIScriptError);
  if (windowId) {
    scriptError.initWithWindowID(message, url, lineText, line,
                                 column, flags, category, windowId);
  } else {
    scriptError.init(message, url, lineText, line, column, flags, category);
  }
  Services.console.logMessage(scriptError);
}

// Get the innerWindowID of the given window.
function getInnerWindowID(win) {
  try {
     let utils = win.QueryInterface(Ci.nsIInterfaceRequestor)
                 .getInterface(Ci.nsIDOMWindowUtils);
     return utils.currentInnerWindowID;
  } catch (ex) {  }

  return null;
}

// Log a "hello world" message for a given window |win|.
logMessage({
  flags: WARN_FLAG,
  message: "hello world",
  url: "https://example.com/script.js",
  line: 10,
  windowId: getInnerWindowID(win),
});

Vous pouvez aussi utiliser Cu.reportError() pour enregistrer les erreurs. Cette méthode est particulièrement utile avec les exceptions.

Pour enregistrer une chaîne de caractères dans la Console de Navigateur, vous pouvez utiliser nsIConsoleService.logStringMessage().

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.

In JavaScript Modules you can do the following:

const {console} = Cu.import("resource://gre/modules/devtools/Console.jsm", {});
console.log("hello world", foo);

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.

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

const {gDevTools} = Cu.import("resource:///modules/devtools/gDevTools.jsm", {});
const {devtools} = Cu.import("resource://gre/modules/devtools/Loader.jsm", {});

function getWebConsole(tab) {
  // |tab| is the XUL tab for the page you want.
  let target = devtools.TargetFactory.forTab(tab);
  let toolbox = gDevTools.getToolbox(target);
  let panel = toolbox ? toolbox.getPanel("webconsole") : null;
  return panel ? panel.hud : null;
}

Once you have the WebConsole object you can add a message like this:

// Get the Messages object which holds the main classes of Messages
// used by the Web Console.
const {Messages} = devtools.require("devtools/webconsole/console-output");

// Create the simplest message we can.
let msg = new Messages.Simple("hello world", {
  category: "js",
  severity: "error",
});

// Add it to the output.
let hud = getWebConsole(myTab);
hud.ui.output.addMessage(msg);

Output a message in the Browser Console

If you want to use the Web Console API to output a message to the Browser Console you can do this:

// Get HUDService - the Web/Browser Consoles manager.
const hudservice = devtools.require("devtools/webconsole/hudservice");

// Get the Browser Console - there can only be one.
// This method returns null if the Browser Console is not open.
let browserConsole = hudservice.getBrowserConsole();

// Add a message.
browserConsole.ui.output.addMessage(msgObject);

In the following table you see a list of message classes you can use. To create a new message you can do:

let msg = new Messages.ConstructorName();

Messages.BaseMessage

The BaseMessage object is used for all types of messages. Every kind of message should use this object as its base. No functionality is provided by this class.

Messages.Simple

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

message (string|element|function):

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.

options (optional, object):

options for this message:

category (string):

the category that this message belongs to. Defaults to no category.

severity (string):

severity of the message. Defaults to no severity.

timestamp (number):

date and time when the message was recorded. Defaults to Date.now().

link (string):

if provided, the message will be wrapped in an anchor pointing to the given URL here.

linkCallback (function):

if provided, the message will be wrapped in an anchor. The linkCallback function will be added as click event handler.

location (object):

tells the message source: url, line, column and lineText.

className (string):

additional element class names for styling purposes.

private (boolean):

mark this as a private message.

filterDuplicates (boolean):

true if you want this message to be filtered as a potential duplicate message, false otherwise.

The following table describes a part of the Messages.Simple API:

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

Examples:

const {Messages} = devtools.require("devtools/webconsole/console-output");

// Add a link.
let msg = new Messages.Simple("this is a link", {
  link: "https://example.com/page",
});
hud.output.addMessage(msg);

// Add a link with a callback function.
msg = new Messages.Simple("click me", {
  linkCallback: function() {
    msg.element.style.background = "red";
  },
});
hud.output.addMessage(msg);

Messages.Extended

The Extended message class is used whenever the Web Console needs to display object actors or messages with multiple elements inline. This class extends the Simple class. Constructor arguments:

messagePieces (array):

the message to display given as an array of elements. Each array element can be a DOM element, function, ObjectActor, LongString or a string.

options (optional, object):

same options as Messages.Simple, plus the following:

quoteStrings (boolean):

tells if you want strings to be wrapped in quotes or not.

Example use:

const {Messages} = devtools.require("devtools/webconsole/console-output");
const XHTML_NS = "https://www.w3.org/1999/xhtml";

// Create a DOM element to be added in this message.
let file = hud.output.document.createElementNS(XHTML_NS, "a");
file.textContent = "foobar.js";
file.href = "https://example.com/foobar.js";

// Use a function to display an interactive button.
// This is invoked when the message is rendered.
function button(msg) {
  let clicks = 0;
  let elem = msg.document.createElementNS(XHTML_NS, "button");
  elem.textContent = "click me " + Date.now();
  elem.onclick = function() {
    elem.textContent = "clicks " + (++clicks);
  };
  return elem;
}

// Create the message object.
let pieces = ["there was an error in ", file, button];
let msg = new Messages.Extended(pieces, {
  category: "js",
  severity: "error",
});

// Make sure a click on the file name opens the anchor in a new tab.
msg._addLinkCallback(file);

// Add the new message.
hud.output.addMessage(msg);

Add new types of messages

If you want to create complex kinds of messages in the Web Console you may want to create a reusable Message class. Simply extend any of the existing message classes:

const {Messages} = devtools.require("devtools/webconsole/console-output");
const Heritage = require("sdk/core/heritage");

Messages.RandomPrefix = function(msg) {
  this._onClick = this._onClick.bind(this);

  let prefix = this._getPrefix();
  Messages.Simple.call(this, prefix + msg, {
    linkCallback: this._onClick,
  });
};

Messages.RandomPrefix.prototype = Heritage.extend(Messages.Simple.prototype,
{
  _onClick: function() {
    let body = this.element.querySelector(".body");
    let newPrefix = this._getPrefix();
    body.textContent = body.textContent.replace(/^\[[\d.]+\]/, newPrefix);
  },

  _getPrefix: function() {
    return "[" + Math.random() + "] ";
  },
};

// Later you can use this message class.
let msg = new Messages.RandomPrefix("oh la la");
hud.output.addMessage(msg);

That's all you need for custom messages.

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

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:

valueGrip:

the value grip as defined in the remote debugger protocol.

options (object, optional):

Options for string display:

concise (boolean):

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.

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.

Here is an example stringifier used for displaying functions:

const {VariablesView} = Cu.import("resource:///modules/devtools/VariablesView.jsm", {});

VariablesView.stringifiers.byObjectClass.Function = function(grip, {concise}) {
  let name = grip.userDisplayName || grip.displayName || grip.name || "";
  name = VariablesView.getString(name, { noStringQuotes: true });

  let params = grip.parameterNames || "";
  if (!concise) {
    return "function " + name + "(" + params + ")";
  }
  return (name || "function ") + "(" + params + ")";
};

The Web Console Message objects use Widgets to display object actors, stack frames and other well-contained output elements that can be reused between different messages.

Here is an example Message class that uses the Stacktrace widget:

// Get the Widgets object - this is where we can find all of the
// console output widgets.
const {Messages, Widgets} = devtools.require("devtools/webconsole/console-output");
const Heritage = require("sdk/core/heritage");

// The stacktrace argument is expected to use the same format as that
// of the console.trace() calls provided over the remote debugging protocol.
Messages.StalkyMuch = function(stacktrace) {
  Messages.BaseMessage.call(this);
  this._stacktrace = stacktrace;
};

Messages.StalkyMuch.prototype = Heritage.extend(Messages.BaseMessage.prototype,
{
  render: function() {
    let stack = new Widgets.Stacktrace(this, this._stacktrace).render();
    let render = Messages.BaseMessage.prototype.render.bind(this);
    render().element.appendChild(stack.element);
    return this;
  },
};

// Later you can do this:
let msg = new Messages.StalkyMuch(stackFromServer);
hud.output.addMessage(msg);

Widgets API

The table below is an overview of the available widgets you can use.

The BaseWidget API:

// Create element "tag" with ID "id"
// and two class names: "class" and "names".
this.el("tag#id.class.names");

// A <span attr1=value1> element
this.el("span", { attr1: "value1"}) 

// A <p attr1=value1>text content<p> element.
this.el("p", { attr1: "value1", ... }, "text content");

// A <p>text content</p> element.
this.el("p", "text content");

As an example, here is the MessageTimestamp widget from console-output.js:

const {devtools} = Cu.import("resource://gre/modules/devtools/Loader.jsm", {});
const {Widgets} = devtools.require("devtools/webconsole/console-output");
const Heritage = require("sdk/core/heritage");
const WebConsoleUtils = require("devtools/toolkit/webconsole/utils").Utils;
const STRINGS_URI = "chrome://browser/locale/devtools/webconsole.properties";
const l10n = new WebConsoleUtils.l10n(STRINGS_URI);
const XHTML_NS = "https://www.w3.org/1999/xhtml";

Widgets.MessageTimestamp = function(message, timestamp) {
  Widgets.BaseWidget.call(this, message);
  this.timestamp = timestamp;
};

Widgets.MessageTimestamp.prototype = Heritage.extend(Widgets.BaseWidget.prototype,
{
  timestamp: 0,
  render: function() {
    if (this.element) {
      return this;
    }

    this.element = this.document.createElementNS(XHTML_NS, "span");
    this.element.className = "timestamp devtools-monospace";
    this.element.textContent = l10n.timestampString(this.timestamp) + " ";

    return this;
  },
});

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.

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.

void initialize(ownerMessage, objectActor[, options]) (optional, function):

the constructor of the renderer widget. This function is invoked with the following arguments:

• the owner message object instance,
• the object actor grip to display, and
• an options object. Read the previous section for details about this object.

void render() (required, function):

the method that displays the given object actor. This method must make the this.element property available for use, as explained in the previous section.

Any other methods and properties in the descriptor will be set on the prototype of the new Widget object that is added to Widgets.ObjectRenderers.

As an example here is the object renderer used for Date:

const {devtools} = Cu.import("resource://gre/modules/devtools/Loader.jsm", {});
const {Widgets} = devtools.require("devtools/webconsole/console-output");

Widgets.ObjectRenderers.add({
  byClass: "Date",

  render: function() {
    let {preview} = this.objectActor;
    this.element = this.el("span.class-" + this.objectActor.class);

    let anchorText = this.objectActor.class;
    let anchorClass = "cm-variable";
    if ("timestamp" in preview && typeof preview.timestamp != "number") {
      anchorText = new Date(preview.timestamp).toString(); // invalid date
      anchorClass = "";
    }

    this._anchor(anchorText, { className: anchorClass });

    if (!("timestamp" in preview) || typeof preview.timestamp != "number") {
      return;
    }

    this._text(" ");

    let elem = this.el("span.cm-string-2", new Date(preview.timestamp).toISOString());
    this.element.appendChild(elem);
  },
});

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.
• the rawObj argument is subject to XPConnect wrapping.
• 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.
• you will most-likely want to look at script.js.

Examples from the codebase:

// Import the DebuggerServer.
const {DebuggerServer} = Cu.import("resource://gre/modules/devtools/dbg-server.jsm", {});
const {DevToolsUtils} = Cu.import("resource://gre/modules/devtools/DevToolsUtils.jsm", {});

// Add the previewer for CSSStyleRules in the generic Object class.
// Use unshift() to add elements in front of other previewers.
DebuggerServer.ObjectActorPreviewers.Object
  .unshift(function CSSStyleRule({obj, threadActor}, aGrip, aRawObj) {
    // Check if this is the type of object we can provide previews for.
    if (!aRawObj || !(aRawObj instanceof Ci.nsIDOMCSSStyleRule)) {
      return false;
    }
    aGrip.preview = {
      kind: "ObjectWithText",
      text: threadActor.createValueGrip(aRawObj.selectorText),
    };
    return true;
  },

  // The previewer we use for Errors.
  function Error({obj, threadActor}, aGrip) {
    switch (obj.class) {
      case "Error":
      case "EvalError":
      case "RangeError":
      case "ReferenceError":
      case "SyntaxError":
      case "TypeError":
      case "URIError":
        let name = DevToolsUtils.getProperty(obj, "name");
        let msg = DevToolsUtils.getProperty(obj, "message");
        let stack = DevToolsUtils.getProperty(obj, "stack");
        let fileName = DevToolsUtils.getProperty(obj, "fileName");
        let lineNumber = DevToolsUtils.getProperty(obj, "lineNumber");
        let columnNumber = DevToolsUtils.getProperty(obj, "columnNumber");
        aGrip.preview = {
          kind: "Error",
          name: threadActor.createValueGrip(name),
          message: threadActor.createValueGrip(msg),
          stack: threadActor.createValueGrip(stack),
          fileName: threadActor.createValueGrip(fileName),
          lineNumber: threadActor.createValueGrip(lineNumber),
          columnNumber: threadActor.createValueGrip(columnNumber),
        };
        return true;
      default:
        return false;
    }
  });

This is all! Thank you for reading and extending our developer tools! Do you have questions? Contact the developer tools team.