2

When reading the specs for various JavaScript APIs, you might come across the requirement that the document be "fully active" before you can use them. Here's a definition of what that means from the specs: https://html.spec.whatwg.org/multipage/browsers.html#fully-active

What remains unclear is how to know if the document is fully active or not. As an example, the WakeLock API requires the document to be fully active. If the document is not fully active, then calling "WakeLock.request()" will reject the returned promise with a "NotAllowedError" error object. However, there are other reasons it might return a "NotAllowedError" and does not specify which reason in a given case.

So, how can I proactively determine if a document is fully active before attempting to use APIs that require it?

pongstylin
  • 95
  • 1
  • 5

1 Answers1

2

There is a section from the page: https://html.spec.whatwg.org/multipage/browsers.html#active-document

A Document d is said to be fully active when d's browsing context is non-null, d's browsing context's active document is d, and either d's browsing context is a top-level browsing context, or d's browsing context's container document is fully active.

Looking to your question:

So, how can I proactively determine if a document is fully active before attempting to use APIs that require it

let's expand the rules:

  • d's browsing context is non-null
  • d's browsing context's active document is d
  • either d's browsing context is a top-level browsing context, or d's browsing context's container document is fully active

I think that can be translated to that javascript code, but I'm not 100% sure about that:

function isFullyActive(s /* self */) {
    return s.window !== null
    && s.document === s.window.document
    && (s.window.top === s.window || isFullyActive(s.window.parent));
}

// you can use in this way on a top level javascript:
isFullyActive(self)

I didn't found any API/spec saying about an event or method to check if a document is fully active.

References:

Leo
  • 1,990
  • 1
  • 13
  • 20
  • 1
    I'm studying your code. The use of 'this' is confusing and can mean different things in different contexts (as you are probably aware). Perhaps "self" is a better term. Also "self === this" in the top level JavaScript execution context. – pongstylin Aug 24 '21 at 17:11
  • Another point of confusion. The spec says "d" is a document, but your code doesn't work if "d" is a document. (documents do not have a window property) – pongstylin Aug 24 '21 at 17:15
  • According to my research, it appears there aren't any cases where "d.window" will be null. Even in a worker (windowless) context, it would be undefined. – pongstylin Aug 24 '21 at 17:28
  • I think I fixed your code. At least the defaultView property can be null. I'm just not sure when it will be null: function isFullyActive(d) { return d.defaultView !== null && d.defaultView.document === d && (d.defaultView.top === d.defaultView || isFullyActive(d.defaultView.parent.document)); } isFullyActive(document) – pongstylin Aug 24 '21 at 17:54
  • The only question that remains, I guess, if if the function will always return true for the global document object or under what circumstances might it be false. – pongstylin Aug 24 '21 at 18:08
  • Sorry, I mixed the concept of d is a document and the self.. I changed to self for now, because the function need access to both window and document – Leo Aug 24 '21 at 18:09
  • Another thing that I found is "no document, no javascript", on this question: https://stackoverflow.com/a/12119264/1724128 this make me think if is necessary to use a function like that and "when" there is a scenario where some javascript is running, trying to use WaveLock and there is no document – Leo Aug 24 '21 at 18:11
  • One point that you should consider is to test inside a iframe, here you can have window !== window.top (and don't forget of CORS, my function will throw a eception trying to read top browsing context properties) – Leo Aug 24 '21 at 18:21
  • Also, this can fail inside a service worker because it haven't access to document and window – Leo Aug 24 '21 at 18:31