This specification defines a pseudo-class designed for the purpose of matching the context node of a query, where the the scope of elements that match a given Selector is constrained to be within a subtree rooted by a particular node.
This is a public copy of the editors' draft. It is provided for discussion only and may change at any moment. It probably contains errors. Its publication here does not imply endorsement of its contents by W3C.
:context Pseudo-Class
This section is non-normative.
This specification introduces a special contextual pseudo-class that matches the root element of a subtree that constrains the scope of a given selector to itself and its descendants. This is designed for use with applications of Selectors with features that provide a scoping mechanism, such as Selectors API [SELECTORS-API] and scoped stylesheets within HTML 5 [HTML5].
This section is non-normative.
This selector is required to address the following use cases.
:bound-element, but
it is not the same as it because they will differ when used outside of a
binding. There doesn’t appear to be any way to avoid the redundancy in
this case.
All diagrams, examples and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.
The key words must, should, and may in the normative parts of this document are to be interpreted as described in RFC 2119 [RFC2119].
The following conformance classes are defined (and considered) by this specification:
:context described in
this specification and conforms to all must-level
criteria that apply to implementations.
The context node itself might not necessarily be considered in scope, depending on the context in which the selector is used.
By default, unless otherwise specified in another specification, the context node is the Document node of the
document to which all elements that are in scope
belong. This specification does not define how to determine which elements
are considered to be in scope.
For example, in Selectors API [SELECTORS-API], only descendants of the context node are considered to be in scope, but for scoped stylesheets in HTML 5 [HTML5], the context node and its descendants are in scope. For regular stylesheets that apply to the entire document, all elements are in scope.
In addition to the terms defined in this specification, the terms defined in Selectors [SELECT] and DOM Level 3 Core [DOM-LEVEL-3-CORE] are also used.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent.
:context Pseudo-ClassIf the context node is an Element
node, then the :context pseudo-class must
match that element.
If the context node is a Document
node, then the :context pseudo-class must
match the documentElement of the given document.
If the context node is a
DocumentFragment node, then the user agent must behave as if the node itself were an element that is
matched by the :context pseudo-class for the purpose of
evaluating a selector. However, this node must not be
evaluated as the subject of a selector.
If the context node is any other node type, the
:context pseudo-class must not match
anything.
This section is non-normative
This pseudo-class can be used within a scoped stylesheet in HTML 5 [HTML5] to select the
style element’s parent node. The following example
demonstrates how to apply styles to the context node and to one of it’s
child nodes, without inadvertently selecting and styling other
descendants. The outer article element will be styled with
the border, padding and margin, but the inner article element
containing the reader’s comment will not be.
<section>
<style scoped>
:context { background: #FFC; margin: 1em; padding: 1em; }
:context>article { border-left: 2px solid silver; padding: .5em; margin: 1em 0; }
</style>
<article>
<h1>An Example</h1>
<p>This is an example article.
<h2>Comments</h2>
<article>
<p>First Post!</p>
<footer><em>Comment by A. Troll</em></footer>
</article>
</article>
</section>
The pseudo-class can also be used within queries performed using the methods defined in Selectors API [SELECTORS-API]. The following examples will make use of this sample document fragment.
<div>
<section id="container">
<div>
<p>This is a <em>sample</em> document fragment and this is column 1.
<div>
<p>It contains a couple of paragraphs and a few levels of nested divs.
</div>
</div>
<div>
<p>This is column 2.
</div>
</section>
</div>
Ordinarily, a selector in a query is evaluated against an element in the context of the entire document. This means that if you wish to select descendant elements using the descendant combinator, ancestor elements of the context node will be considered during selector evaulation.
var container = document.getElementById("container");
var div = container.querySelector("div div");
That query will return the first child div element within the container div. This is because the container’s ancestor is also a div, which is matched during selector evaluation. To ensure that only descendant elements are considered, you can use the :context pseudo-class to restrict the scope.
var div = container.querySelector(":context div div");
That one will match the innermost div in the example.
The :context pseudo-class can also be used in conjunction
with the child combinator to ensure that only child elements of the
context node are selected.
var columns = container.querySelector(":context>div");