A few devtools extension questions

[Hallvord R. M. Steen]

Hi,
playing around with making a devtools extension. I've used this to start
https://developer.mozilla.org/en-US/docs/Tools/Adding_a_panel_to_the_toolbox
So I have a reference to the panel's window and one to the debugging
target (I think, although to get things like event listeners done I
seem to have to use target._target).

>From here, I wonder..

* Is there a nice way to set the User-Agent override for the debugging
target? (Especially keeping in mind that the target might be a remote
debug target - setting a UA override pref for the engine one is running
in won't do).

* Is there a nice way to inject JS into the debugging target page?

* What about taking a screenshot?

Thanks for any answers. I might suggest changes and added examples to
the developer.mozilla.org pages if I get some good advice :)
-Hallvord

[Brian Grinstead]

This doesn’t answer your questions, but we are ultimately planning to implement web extension support for devtools[0] and I’m curious if those APIs [1] would provide the functionality you need. I know that there’s an easy way to inject scripts into a page with that API, but am not aware of UA override or screenshot functionality.

For today, if you just need to flip a pref for the UA override there is a preference actor that can be accessed through getPreferenceFront (see _toggleAutohide in toolbox.js for an example). I’m not sure about the others off hand.

Brian

[0]: https://bugzilla.mozilla.org/show_bug.cgi?id=1211859
[1]: https://developer.chrome.com/extensions/devtools

> _______________________________________________
> dev-developer-tools mailing list
> dev-devel...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-developer-tools

[J. Ryan Stinnett]

On Tue, Jul 26, 2016 at 8:02 AM, Hallvord R. M. Steen <
geck...@hallvord.com> wrote:

> * Is there a nice way to set the User-Agent override for the debugging
> target? (Especially keeping in mind that the target might be a remote
> debug target - setting a UA override pref for the engine one is running
> in won't do).
>

You can use the "reconfigure" method on the tab client for this. See
responsive design[1]. This goes over the RDP to the remote target and uses
a docshell attribute instead of a pref so it will only affect the current
tab instead of all tabs.

If you _want_ to affect all tabs, then the preference actor approach
:bgrins mentions seems best.

[1]:
https://dxr.mozilla.org/mozilla-central/source/devtools/client/responsivedesign/responsivedesign.jsm#986

- Ryan

[J. Ryan Stinnett]

On Tue, Jul 26, 2016 at 8:02 AM, Hallvord R. M. Steen <
geck...@hallvord.com> wrote:

> * What about taking a screenshot?

One option is the device actor[1], though that takes a full chrome window
screenshot, not just content.

There is also the GCLI screenshot command. However, we don't currently
expose GCLI for remote devices in the UI, so I am unsure of the current
status. Worth investigating at least.

[1]:
https://dxr.mozilla.org/mozilla-central/source/devtools/server/actors/device.js#42

- Ryan

[Hallvord R. M. Steen]

On 27.07.2016 00:48, J. Ryan Stinnett wrote:
> On Tue, Jul 26, 2016 at 8:02 AM, Hallvord R. M. Steen <
> geck...@hallvord.com> wrote:
>

>> * Is there a nice way to set the User-Agent override for the debugging
>> target?

> You can use the "reconfigure" method on the tab client for this. See
> responsive design[1]. This goes over the RDP to the remote target and uses
> a docshell attribute instead of a pref so it will only affect the current
> tab instead of all tabs.

That sounds perfect! But the follow up question (since I'm still rather
clueless about this API) is: when I have a debugging *target*, how do I
get from there to a *tab client*? Do I have to create a DebuggingClient
and use attachTab like this code does:
https://dxr.mozilla.org/mozilla-central/source/devtools/client/responsivedesign/responsivedesign.jsm#273

(I'm defining a tooldef object with a build() function that receives
"window" and "target" arguments. Now I don't remember exactly what I
based this code on and many of the examples I see are slightly
different, defining the panel as a class extending Panel and having a
setup() method where you get to options.debuggee. Should I rewrite to
use this approach instead?)
-Hallvord R

[Hallvord R. M. Steen]

On 27.07.2016 00:51, J. Ryan Stinnett wrote:
>
> On Tue, Jul 26, 2016 at 8:02 AM, Hallvord R. M. Steen

> <geck...@hallvord.com <mailto:geck...@hallvord.com>> wrote:
>
> * What about taking a screenshot?
>
>
> One option is the device actor[1], though that takes a full chrome
> window screenshot, not just content.

Well, I'm after a content screenshot - I can always draw the document
onto a canvas and get the image data like I believe the GCLI command
does under the hood. However, when I have a reference to a debug
"target" (passed to the tool definition's build method), how do I get
from there a reference to the related DOM document or window?

It would also be interesting to know (just to understand how things are
glued together) how I could invoke the device actor screenshot code. I
have to load or require the resource://devtools/server/actors/device.js
file in my extension code? But it isn't written like a module and
doesn't export anything? Or can I create the device actor with some
constructor I can reach by including something else?

> There is also the GCLI screenshot command. However, we don't currently
> expose GCLI for remote devices in the UI, so I am unsure of the
> current status. Worth investigating at least.

It seems promising as long as you can make it deal with the right document..
-Hallvord R

[J. Ryan Stinnett]

On Wed, Jul 27, 2016 at 12:30 AM, Hallvord R. M. Steen <
geck...@hallvord.com> wrote:

> On 27.07.2016 00:48, J. Ryan Stinnett wrote:
> > On Tue, Jul 26, 2016 at 8:02 AM, Hallvord R. M. Steen <

> > geck...@hallvord.com> wrote:
> >
> >> * Is there a nice way to set the User-Agent override for the debugging
> >> target?
> > You can use the "reconfigure" method on the tab client for this. See
> > responsive design[1]. This goes over the RDP to the remote target and
> uses
> > a docshell attribute instead of a pref so it will only affect the current
> > tab instead of all tabs.
>
> That sounds perfect! But the follow up question (since I'm still rather
> clueless about this API) is: when I have a debugging *target*, how do I
> get from there to a *tab client*? Do I have to create a DebuggingClient
> and use attachTab like this code does:
>
> https://dxr.mozilla.org/mozilla-central/source/devtools/client/responsivedesign/responsivedesign.jsm#273

The target object calls `attachTab` itself[1] and saves the tab client as
the `activeTab` property, so you should be able to use that since you are
being passed a target.

[1]:
https://dxr.mozilla.org/mozilla-central/rev/fef429fba4c64c5b9c0c823a6ab713edbbcd4220/devtools/client/framework/target.js#396

- Ryan

[Hallvord R. M. Steen]

On 27.07.2016 00:39, Brian Grinstead wrote:
> This doesn’t answer your questions, but we are ultimately planning to implement web extension support for devtools[0]

Perhaps I should write the Chrome devtools addon first and wait for you
to catch up? :)

> and I’m curious if those APIs [1] would provide the functionality you need. I know that there’s an easy way to inject scripts into a page with that API, but am not aware of UA override or screenshot functionality.

Not in the devtools extension API itself, but there's useful stuff
elsewhere in the Chrome extension APIs:

https://developer.chrome.com/extensions/desktopCapture
http://stackoverflow.com/questions/15618923/in-google-chrome-what-is-the-extension-api-for-changing-the-useragent-and-devic

-Hallvord R

[J. Ryan Stinnett]

On Wed, Jul 27, 2016 at 7:04 PM, Hallvord R. M. Steen <
geck...@hallvord.com> wrote:

> On 27.07.2016 00:51, J. Ryan Stinnett wrote:
>
>
> On Tue, Jul 26, 2016 at 8:02 AM, Hallvord R. M. Steen <
> geck...@hallvord.com> wrote:
>

>> * What about taking a screenshot?
>
>
> One option is the device actor[1], though that takes a full chrome window
> screenshot, not just content.
>
>
> Well, I'm after a content screenshot - I can always draw the document onto
> a canvas and get the image data like I believe the GCLI command does under
> the hood. However, when I have a reference to a debug "target" (passed to
> the tool definition's build method), how do I get from there a reference to
> the related DOM document or window?
>

Your add-on runs on the client side of the connection and the target also
represents the client side. There is no "direct" reference to the document
or window, since it could be on a completely different device.

If you need to run totally custom code on the remote target, you may want
to add a custom "actor", which is a module that runs on server / targeted
thing. The Firebug examples repo[1] should help here, particularly the
"CustomActor" example. Essentially, we have a way install new actors over
the connection to add your custom feature, and then you can call it over
the protocol after it's installed.

It would also be interesting to know (just to understand how things are
> glued together) how I could invoke the device actor screenshot code. I have
> to load or require the resource://devtools/server/actors/device.js file
> in my extension code? But it isn't written like a module and doesn't export
> anything? Or can I create the device actor with some constructor I can
> reach by including something else?

You use a "front" which is a client side module that knows how to talk to
server side actor module via the protocol. You can use `getDeviceFront`[2]
to get the front for this actor. I believe `getDeviceFront(target.client,
target.root)` would work.

[1]: https://github.com/firebug/devtools-extension-examples
[2]:
https://hg.mozilla.org/mozilla-central/annotate/fef429fba4c64c5b9c0c823a6ab713edbbcd4220/devtools/shared/fronts/device.js

- Ryan

[Hallvord R. M. Steen]

>> a canvas and get the image data like I believe the GCLI command does under
>> the hood. However, when I have a reference to a debug "target" (passed to
>> the tool definition's build method), how do I get from there a reference to
>> the related DOM document or window?
> Your add-on runs on the client side of the connection and the target also
> represents the client side. There is no "direct" reference to the document
> or window, since it could be on a completely different device.

Got it.

> If you need to run totally custom code on the remote target, you may want
> to add a custom "actor", which is a module that runs on server / targeted
> thing.

Fine, I now have a sort of working custom actor - however, I'm still
struggling to find the correct and/or best method to find the actual DOM
content window from that actor's code..
Is this documented anywhere?
-HR

[J. Ryan Stinnett]

On Fri, Jul 29, 2016 at 10:12 AM, Hallvord R. M. Steen <
geck...@hallvord.com> wrote:

> Fine, I now have a sort of working custom actor - however, I'm still
> struggling to find the correct and/or best method to find the actual DOM
> content window from that actor's code..
>

If you look at the CustomActor example, it receives a "parent" as the
second argument to initialize. This is the TabActor[1] that represents the
page being targeted. It has many properties, such as "window".


> Is this documented anywhere?
>

I don't believe so. There are a few assorted docs in /devtools/docs and
/devtools/server/docs, but I am not sure they cover these questions
specifically.

[1]:
https://dxr.mozilla.org/mozilla-central/rev/ddeb0295df692695b36295177d6790e5393e1f9a/devtools/server/actors/webbrowser.js#845

- Ryan

[Hallvord R. M. Steen]

On 27.07.2016 00:48, J. Ryan Stinnett wrote:
>> * Is there a nice way to set the User-Agent override for the debugging
>> target?
> You can use the "reconfigure" method on the tab client for this.

This is great - on the other hand, there's a relatively limited number
of preferences you can set here:
https://dxr.mozilla.org/mozilla-central/source/devtools/server/actors/webbrowser.js#1646

Is it easy (and is there any interest in) adding more?
For example, I might want to be able to configure tracking protection
state from a devtools addon.
-Hallvord R

[Hallvord R. M. Steen]

> If you look at the CustomActor example, it receives a "parent" as the
> second argument to initialize. This is the TabActor[1] that represents the
> page being targeted. It has many properties, such as "window".
>
>
>> Is this documented anywhere?
>>
> I don't believe so.

Based on your help and what I could gather from the source I suggest
adding this comment to the example code:
https://github.com/firebug/devtools-extension-examples/pull/10

Might not be a splendid place to put it but better than nothing..might
have helped me understand this faster. Review welcome. Also if you think
it should go elsewhere in some docs file it would be great to get
suggestions.
-Hallvord R