Re: Proposal for :context Selector

[Lachlan Hunt]

Lachlan Hunt wrote:

The attached file is a draft proposal for a new contextual selector.

Revision 3 is attached.

--
Lachlan Hunt - Opera Software
http://lachy.id.au/
http://www.opera.com/

Title: The Contextual Selector

The Contextual Selector

Working Draft 14 July 2008

This version:

http://lists.w3.org/Archives/Public/www-archive/2008Jul/att-0025/Overview.html

Previous Versions:

http://lists.w3.org/Archives/Public/www-archive/2008Jul/att-0023/Overview.html

http://lists.w3.org/Archives/Public/www-archive/2008Jul/att-0019/Overview.html

Editors:

Lachlan Hunt (Opera Software ASA) <[EMAIL PROTECTED]>

---

Abstract

This specification introduces a special contextual pseudo-class that matches a specified reference element, depending on the context in which its used.

Status of this document

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.

Table of contents

• 1. Introduction
• 2. Requirements and Use Cases
• 3. Conformance Requirements
  • 3.1 Terminology and Conventions
• 4. The :scope Pseudo-Class
• 5. Examples
• References
  • Normative references
  • Other references
• Acknowledgments

1. Introduction

This section is non-normative.

This specification introduces a special contextual pseudo-class that matches a specified reference element, depending on the context in which its used. 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].

2. Requirements and Use Cases

This section is non-normative.

This selector is required to address the following use cases.

• Match the scope element of a query performed using the methods defined in Selectors API. This should allow for the following cases, when the API is executed on either an Element node, and should at least behave sanely when executed on a Document node:
  1. Finding descendants of another element that is also a descendant of the scope element.
  2. Finding a child of the scope element.
  3. Finding a child of an element that is itself a descendant of the scope element.
• Allow for styles to be applied to the contextual root element and its child nodes (in conjunction with the child combinator) of a scoped stylesheet in HTML5.
• In XBL, when used in the context of a binding, it should match the bound element. It is already matched by :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.

3. Conformance Requirements

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:

conforming user agent

A user agent that implements the :scope pseudo-class described in this specification and conforms to all must-level criteria that apply to implementations.

3.1 Terminology and Conventions

Scope Element

The scope element is a specified reference Element node within the context in which a selector is being evaluated.

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.

4. The :scope Pseudo-Class

The :scope pseudo-class must match the scope element.

By default, when a given element is being evaluated against a given selector, the scope element is, unless otherwise specified in another specification, the root element of the document to which the element belongs. If there is no specified scope element, and the element does not belong to a document, there is no scope element.

Specifications intending for this pseudo-class to match a specific element other than the document's root element must define which element is the scope element.

For example, in Selectors API [SELECTORS-API], when the querySelector method is invoked on an element, the scope element is defined to be the element itself.

5. Examples

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 scope element 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.

This will require HTML5 to specify that the scope element is the parent element of a scoped stylesheet.

<section>
  <style scoped>
  :scope { background: #FFC; margin: 1em; padding: 1em; }
  :scope>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 scope element 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 :scope pseudo-class to restrict the scope.

var div = container.querySelector(":scope div div");

That one will match the innermost div in the example.

The :scope pseudo-class can also be used in conjunction with the child combinator to ensure that only child elements of the scope element are selected.

var columns = container.querySelector(":scope>div");

References

Normative references

[DOM-LEVEL-3-CORE]

Arnaud Le Hors; et al. Document Object Model (DOM) Level 3 Core Specification. 7 April 2004. W3C Recommendation. URL: http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407

[RFC2119]

S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt

[SELECT]

Daniel Glazman; Tantek Çelik; Ian Hickson. Selectors. 15 December 2005. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2005/WD-css3-selectors-20051215

Other references

[HTML5]

Ian Hickson; David Hyatt. HTML 5. 22 January 2008. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2008/WD-html5-20080122

[SELECTORS-API]

Anne van Kesteren; Lachlan Hunt. Selectors API. 21 December 2007. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2007/WD-selectors-api-20071221

Acknowledgments

The editors would like to thank to the following people who have contributed to this specification (ordered on first name):

• Björn Höhrmann
• Ian Hickson
• Maciej Stachowiak