615590 - Add Panorama API module to Add-on SDK

Status: RESOLVED INVALID

(Add-on SDK Graveyard :: General, enhancement, P2)

Description

[Michael Yoshitaka Erlewine [:mitcho]]

Attachment: API v1: exposes TabItems but not GroupItems; creates some event handler bindings

Features which we would like to expose (ideally):

- add event handlers to tabs and groups, for example when they're added, removed, etc.
- modify the DOM element for GroupItem's and TabItem's in the Panorama representation
- get information on TabItem's and GroupItem's, like their titles, parent-age, etc. Perhaps also edit titles, or move tabs between tabs.
- open Panorama, close Panorama, view particular groups (though that can simply be done by switching to one of the member tabs using the tabs api).

Comment 1

[Michael Yoshitaka Erlewine [:mitcho]]

Attachment: For reference: Sample addon main code which uses the module

More metadata and an xpi for this addon package can be found at https://github.com/mitcho/badges .

Comment 2

[Ian Gilman [:iangilman]]

Comment on attachment 494025 [details] [diff] [review]
API v1: exposes TabItems but not GroupItems; creates some event handler bindings

I love it! Comments: 

* I agree it would be nice to have the events coming from within Panorama, rather than having to shadow them. 
* For TabItem.dom(), do we really want to return the iQ object? Do Jetpack authors typically have something like jQuery available to them?

Comment 3

[Dietrich Ayala (:dietrich)]

By Jetpack 1.0, most Jetpack code will need to be able to run out outside the main browser process. This means that APIs in modules like this should 1) be asynchronous if they touch the browser DOM and 2) not return any DOM elements.

I've started on a guide here: http://etherpad.mozilla.com:9000/JetpackE10s

Comment 4

[Myk Melez [:myk] [@mykmelez]]

Comment on attachment 494025 [details] [diff] [review]
API v1: exposes TabItems but not GroupItems; creates some event handler bindings

I drafted some docs in the process of reading through this code to help me understand the API it is presenting:

--------------------------------------------------------------------------------
The Panorama API gives you access to Firefox's "Panorama" feature for organizing
tabs into groups.  The interface to the feature is called the tab view.

To be notified when the tab view is initialized for a browser window,
add a listener for the "init" event.  To be notified when the view is shown
and hidden, add listeners for the "show" and "hide" events respectively.

Event listeners are passed one argument, `panorama`, which is a Panorama object
representing the tab view for a given window.

Panorama objects have two properties, `TabItems` and `iQ`.

The TabItems property is an object representing the set of TabItem objects
in the window.  TabItem objects represent individual tabs that are open
in the window and being organized by the tab view.

The iQ property is ???

TabItem objects have two properties, `dom` and `parent`.
The `dom` property is a ???.  The `parent` property is a `???`.
--------------------------------------------------------------------------------

Nevertheless, I still don't quite understand what is being exposed here.  The `dom` property suggests DOM elements; are they the representations of those tabs in the tab view?  And what is the `iQ` object?

As Dietrich noted, in the near future SDK-based addons will run in separate "addon processes" from the "content processes" in which web pages are loaded, which imposes constraints on the designs of the APIs we expose to addons.

In particular, access to page content needs to be proxied through an interface that loads a "content script" in the content process that has access to the page content and can pass messages to the addon code running in the addon process.

So presuming the `dom` property is providing access to some kind of DOM object, this API will need to expose a content script-style interface for accessing it rather than exposing it directly, just as the Page Mods API provides access to the DOM of web pages by loading content scripts for them.

(Alternately, and perhaps preferably, the API could expose higher-level properties and methods for manipulating those objects in the ways you expect addon developers to want to manipulate them.)

Also, it won't be possible to merely expose an object in the browser like the `iQ` object to addon code.  Rather, the API will need to have its own properties and methods that provide access to the properties and methods of that object, and we'll have to evaluate each of those individual attributes to determine how best to expose them given the process boundary considerations.

More information about the goals of the interface would be very helpful for me to understand this API better and be able to make suggestions for how it could fit into the SDK.  In particular, it'd be great to have descriptions of the primary use cases that the API is concerned with satisfying.  And it'd be especially helpful for them to be accompanied by code examples showing how the prospective API would be used to satisfy those use cases.

Perhaps you can provide or point me to additional documentation?

I'm not quite sure how to mark the flag here.  "feedback+" sounds like "this is the right API", which seems likely not to be the case, given the various considerations mentioned above (although further info is really needed to make a definitely judgement there).

But "feedback-" sounds like "we should not do this," whereas I very much do want a Panorama API, it's just a question of how to provide one that fits into the SDK architecture.

Marking this feedback- for now, but please do keep working on this, and let's work together to figure out how to provide the right API to Panorama for SDK developers!

Comment 5

[Michael Yoshitaka Erlewine [:mitcho]]

This surely is something we would like to get in the API in the near future, as Panorama has shipped with fx4. Unfortunately I am moving on from Panorama right now, so I leave this bug open for someone else to pick up.

Comment 6

[Wes Kocher (:KWierso) (Not reading bugmail; email directly if needed)]

Marking anything that potentially looks like a feature request as "enhancement", sorry for the bugspam. :)

Comment 7

[Wes Kocher (:KWierso) (Not reading bugmail; email directly if needed)]

We'll investigate in a Feature Page if this would be worth having. For now, it'd probably be better for this to live as a third party library.