Bug 63580 – Web Inspector: General Purpose Tree API in Extension API

• Status: RESOLVED
• Resolution: INVALID
• Component: Web Inspector (Deprecated)

[Yehuda Katz]

Currently, the extension API makes it possible to do three things in sidebars:

* setObject: display an object
* setExpression: watch an expression and display the result
* setPage: insert an iframe (which has access to the devtools API)

However, it is not possible to insert any arbitrary tree in a sidebar, which would make it possible to do a lot more without resorting to a full-on custom page in an iframe. I'd like to propose an API for a tree structure representation that could be inserted into the sidebar (using something like setTree) and other areas that know how to render trees.

Straw Man:

    var tree = new devtools.Tree({ title: "Root" });
    var node1 = new devtools.Tree.Node({ title: "Child" });
    var node2 = new devtools.Tree.Node({ key: "name", value: "result" });
    var node3 = new devtools.Tree.Node({ key: "<span>name</span>", value: "<span style='color: green'>{{hello}}</span>", markup: true });
    tree.appendChild(node1);
    node1.appendChild(node2);
    sidebar.setTree(tree);
    // can insert new nodes and modify titles, keys, and values here

By default, the value in a key/value node is a span wrapping the text. If the developer flags the node as markup, he will be expected to provide a wrapping span, and can use any desired markup for styling. It would also be nice (but not strictly necessary) if an enumerated list of classes for these spans would be considered public APIs.

[Pavel Feldman]

I have a number of concerns on this one:
- Exposing a simple tree would increase the API surface (high maintenance cost)
- Universal tree won't be useful enough unless it exposes entire treeoutline API
- In the inspector itself, tree is just a bunch of <ol> and <li> elements. Sections, sidebars, expandable objects: everything is a tree with custom styling. So if the goal is consistent look and feel, we would need to pick the style we expose and that would kill the flexibility.

There is a couple of alternatives as I see it:

1) Let users hack / reuse existing JavaScript trees and make them look consistent
Pros:
    Zero maintenance cost for inspector, infinite flexibility for the user
Cons:
    Harder jump start for extension authors
Mitigation:
    We render simple JSON objects as trees if one likes to start fast. We can make that rendering a bit more configurable.

2) Use Library approach instead of API approach. Brush up treeoutline.js and suggest that users include it into their extension code. We can extract outline-disclosure.css that works with it and either inject it or suggest including as well (or we could do both).
Pros:
    Zero maintenance cost for inspector, infinite flexibility for the user
Cons:
    ?
Todo:
    Remove outgoing dependencies from treeoutline.js. The ones that are there are there by accident / historical reasons. Should be trivial to sanitize it.

[Yehuda Katz]

(In reply to comment #1)
> I have a number of concerns on this one:
> - Exposing a simple tree would increase the API surface (high maintenance cost)
> - Universal tree won't be useful enough unless it exposes entire treeoutline API
> - In the inspector itself, tree is just a bunch of <ol> and <li> elements. Sections, sidebars, expandable objects: everything is a tree with custom styling. So if the goal is consistent look and feel, we would need to pick the style we expose and that would kill the flexibility.
> 
> There is a couple of alternatives as I see it:
>  

One general problem is that currently, doing anything with the extension API other than setObject and setExpression requires an iframe, which requires more contortions to work with the inspected page. One of my goals with this proposal was to make it possible to populate a sidebar outside of the very isolated environment of a setPage iframe.

> 1) Let users hack / reuse existing JavaScript trees and make them look consistent
> Pros:
>     Zero maintenance cost for inspector, infinite flexibility for the user
> Cons:
>     Harder jump start for extension authors

Another con: you can only do this inside an iframe.

> Mitigation:
>     We render simple JSON objects as trees if one likes to start fast. We can make that rendering a bit more configurable.

I can open another ticket with some proposals I have for making Object rendering more flexible, but I agree that this is a major pain point for using JSON literals to print general-purpose trees. The two biggest issues are the inability to turn off the __proto__ property and the inability to change the String representation of constructors (the current implementation calls directly into in the host language, which is extracted from the AST, and therefore not runtime configurable in v8).

It would also be nice to be able to have a representation that printed prototype properties alongside the normal properties (with the option to turn off __proto__), but in grey or some other visually distinct way.

> 
> 2) Use Library approach instead of API approach. Brush up treeoutline.js and suggest that users include it into their extension code. We can extract outline-disclosure.css that works with it and either inject it or suggest including as well (or we could do both).

I think this would be a good idea regardless, as it would open up the library for more open source contribution and make it more widely useful.

> Pros:
>     Zero maintenance cost for inspector, infinite flexibility for the user
> Cons:
>     ?

This approach also requires the extension author to use an iframe (setPage) for their tree. Additionally, treeoutline.js is pretty low-level, and higher-level APIs in the inspector manually inject various kinds of spans to achieve certain look-and-feel. It would be helpful if at least some of the common kinds of tree nodes were made into a higher-level API.

I'd be willing to do the work to extract treeoutline.js into a separate library. Do you know if there are any tests for treeoutline.js in particular?

> Todo:
>     Remove outgoing dependencies from treeoutline.js. The ones that are there are there by accident / historical reasons. Should be trivial to sanitize it.

Agreed.