1386707 - webRequest, add a public documentation about "documentUrl"

Status: RESOLVED FIXED

(Developer Documentation Graveyard :: Add-ons, enhancement, P1)

Description

[21Naown]

Add a public documentation about "documentUrl" used by webRequest. Please be as precise as possible with a concrete example, it would be very appreciable.

Comment 1

[Shane Caraveo (:mixedpuppy)]

The basis for documenting this can be found at

http://searchfox.org/mozilla-central/source/dom/webidl/ChannelWrapper.webidl

It should note the difference between that and the originUrl, as often/usually they are the same.

Comment 2

[Will Bamberg [:wbamberg]]

Sorry to be so slow getting to this. I guess Comment 1 should now refer to https://searchfox.org/mozilla-central/source/dom/chrome-webidl/ChannelWrapper.webidl, but the comment there is not very understandable to me:

***
(documentURL)
The URL of the document loading the content for this request. This is equivalent to the LoadInfo's loadingPrincipal.

(originURL)
The URL of the principal that triggered this load. This is equivalent to the LoadInfo's triggeringPrincipal
***

Could you give me a real-world example where these two would be different, and/or when a user might want one or the other?

Comment 3

[Shane Caraveo (:mixedpuppy)]

My descriptions are simplification of the docs in nsILoadInfo, but should illustrate the basic use.

loading principal:

https://searchfox.org/mozilla-central/rev/a80651653faa78fa4dfbd238d099c2aad1cec304/netwerk/base/nsILoadInfo.idl#229

A loading principal would be the document loading something, such as an image.  So if a web page on example.com has an image in it, the loading principal for the image will be example.com

triggering principal:

https://searchfox.org/mozilla-central/rev/a80651653faa78fa4dfbd238d099c2aad1cec304/netwerk/base/nsILoadInfo.idl#269

A triggering principal may be the page that had a link to another page.  User clicks on link "triggering" a load of another page.

Comment 4

[Will Bamberg [:wbamberg]]

Thanks, that is helpful. Then does this sound good:

* documentUrl

URL of the document in which the resource will be loaded. For example, if the web page at "https://example.com" contains an image or an iframe, then the documentUrl for the image or iframe will be "https://example.com". For a top-level document, documentUrl is undefined.

* originUrl

URL of the resource which triggered the request. For example, if "https://example.com" contains a link, and the user clicks the link, then the originUrl for the resulting request is "https://example.com". The originUrl is often but not always the same as the documentUrl. For example, if a page contains an iframe, and the iframe contains a link that loads a new document into the iframe, then the documentUrl will be the iframe's parent document, but the originUrl will be the URL of the previous document in the iframe.

Comment 5

[Shane Caraveo (:mixedpuppy)]

That looks pretty good.  Thanks!

Comment 6

[Will Bamberg [:wbamberg]]

OK, thanks Shane. I've updated the webRequest.on* pages with the above.

Comment 7

[kernp25]

But documentUrl is missing from compatibility table[1]?

[1] https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/webRequest/onBeforeRequest#Browser_compatibility

Comment 8

[kernp25]

Also, should it not be "dev-doc-complete"?

Comment 10

[Will Bamberg [:wbamberg]]

Thanks for pointing that out, I just filed https://github.com/mdn/browser-compat-data/pull/2582.

> Also, should it not be "dev-doc-complete"?

No, docs bugs shouldn't set dev-doc-needed: https://groups.google.com/forum/#!topic/mozilla.dev.platform/AwM87ANMS3Y

Comment 11

[Will Bamberg [:wbamberg]]

Compat data is updated and deployed.