CSS Content State Selectors Module Level 1

Editor's Draft 4 February 2012

This version:
Latest version:
www-style@w3.org with subject line “[css-content-state] … message topic …
François REMY, Université Libre de Bruxelles


CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, in speech, etc. This module contains the features of CSS level 3 related to elements that depends on external resources to display their content or interact with the document.

Such elements may require or trigger particular formatting based on their current state. For example, a designer may want to provide a fallback image in case the external images fails to be retreived, or may want to display a message while content requierd for the application to run is still loading.

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. Its publication here does not imply endorsement of its contents by W3C. Don't cite this document other than as work in progress.

The (archived) public mailing list www-style@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “css-content-state” in the subject, preferably like this: “[css-content-state] …summary of comment…

The following features are at risk:

All features marked as 'at risk' may be removed from this specification if no concensus is made about them.

Table of contents

1. Introduction

This section is not normative.

While most of the documents used on the web today relies a way or another on external content (ie: any piece of data used in a document but defined outside of the document structure itself), untill now, the only way to control their load state and react to errors is to use a scripting language.

This specification provides a way for CSS agents to target an element based on the load state of its content. The goal is to provide in-between or on-error fallbacks in the most common situations, even if the user agent does not support scripting.

This also makes it easier for WYSIWYG editors to show a placeholder for elements which cannot be rendered due to a content error, to incomplete load or to content restrictions.

The exact mechanism used to load the resource itself (also called the download process) is not defined in this specification. Usually, resources defined using an URI are fetched over the network using a communication protocol like HTTP or loaded locally using the computer filesystem or directly by unpacking the URI at the UA level (like in the 'data:' protocol).

1.1. Module interactions

This module extends the dynamic pseudo-classes defined in [CSS3-SELECTORS] section 6.6.1 by adding additionnal entries.

1.2. Values

This specification follows the CSS property definition conventions from [CSS21]. Value types not defined in this specification are defined in CSS Level 2 Revision 1 [CSS21]. Other CSS modules may expand the definitions of these value types: for example [CSS3COLOR], when combined with this module, expands the definition of the <color> value type as used in this specification.

In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the inherit keyword as their property value. For readability it has not been repeated explicitly.

2. Definitions

By ‘external resource’, this specification means any piece of data represented by a Unique Resource Identifier (URI) and which impact the behavior, layout or rendering of an element.

The nodes contained in a SGML element are not considered as an external resource until they are used somewhere by referencing them using a Unique Resource Identifier. Any custom content identifier like CSS Regions Named Flows are not considered external content.

By ‘download’ of a resource, this specification means the set of operations that are requierd to convert the Unique Resource Identifier (URI) that defines the resource into an actually usable piece of data that can be interpreted. However, this does not cover the actual process of interpretation, which is dependant of the element itself and the use he's intended to make of the resource.

The term ‘load’ of a resource is sometimes used in this specification and has the same meaning as the term ‘download’ of a resource

Should content state pseudo-classes take in consideration the cases where the 'content' property has been set by a CSS rule to an URI in addition to the cases where the resource is loaded by an intrinsic element behavior? I would argue that they should not since a CSS rule may change the displayed content based on an interaction with the content state pseudo-classes and it would create circular references. For exemple, if img:error is used to provide a fallback content, that content may be defined using a URI which does not trigger an error, clearing the :error flag and invalidating itself.

A solution would be to say that they apply on all content declarations except the ones set in interactions with content state pseudo-classes, but it can be rather complex to implement.

Another solution to avoid circular references would be to state that the content state pseudo-class applies to the element who contains the URI reference used for the download. This would mean that the download of a resource used in a stylesheet defined in a LINK element would trigger the :loading pseudo-class to apply to the LINK element and not the element which actually uses the resource (eg, by having the content property set). However, if the content property is set using the style attribute of the element, it would trigger the :loading pseudo-class to apply directly to the element itself.

By ‘intrinsic content’ of an element, this specification means the content used to control the element layout, behavior or render that is defined and interpreted by the element itself. This does not include any content needed to cover the layout, behavior or render of the element that is controlled or defined outside the element itself, like in a stylesheet.

The intrinsic content of an element can include zero or more external resources.

3. New pseudo-classes

The following pseudo-classes are meant to match any element which alters its layout, rendering or behavior based on an external resource.

In case of HTML, this includes (but isn't limited to) the following tags: IMG, VIDEO, AUDIO, LINK, SCRIPT and OBJECT.

Should those pseudo-classes be named :content-uninitialized, :content-loading, :content-interactive, :content-loaded and :content-error instead?

This would make clear they only apply to external resources loaded by an element to be used as an intrinsic content.

This is, however, somewhat longer to type.

3.1. The ‘:uninitialized’ pseudo-class

The :uninitialized pseudo-class applies to any element which should load at least one external resource to use in its intrinsic content but which doesn't have any instruction defining which external resource(s) should be loaded.

The following example should render a 16px*16px square. This could be useful in a WYSIWYG editor, for example.

img:uninitialized { 
	content: ''; 
	width: 16px; 
	height: 16px; 
	background: currentColor; 

HTML Code :

<img />

3.2. The ‘:loading’ pseudo-class

The :loading pseudo-class applies to any element which is currently in the process of downloading an external resource to use in its intrinsic content.

It doesn't matter if the element already has downloaded one or more resource completely in the past.

While 'some-big-picture.jpg' is loading, '[...]' should be displayed instead of the image itself (or, in this case, its ALT description).

img:loading { content: '[...]'; }

HTML Code :

	alt="A very big description that you don't want 
	     to show while the picutre is loading." 

3.3. The ‘:interactive’ pseudo-class

The :interactive pseudo-class applies to any element which can load one or more external resources to use in its intrinsic content and which have retreived enough data to work approximately as if the full resource has been downloaded. This usually means that the user has the same level of interaction as if the download was complete, but that some information may be less accurate or unavailable to him.

The level of approximation accepted is at the discretion of the element's own specification. If the specification doesn't define such an interactive mode, the :interactive pseudo-class should be a synonym for :loaded:not(:error).

That pseudo-class is however different from :loaded:not(:error) in some important cases. This is for example true in the case of an Interlaced Progressive JPEG image which has been downloaded to a point where a first approximation of the final image can be rendered by the user agent.

This is also the case of a streamed video which has enough data to render its first frame.

The following example should render a 16px*16px square until the UA has something else to display. This could be useful in a WYSIWYG editor, for example.

img:not(:interactive) {	content: ''; 
	width: 16px; 
	height: 16px; 
	background: currentColor; 

HTML Code :

	alt="A very big description that you don't want 
	     to show while the picutre is loading." 

3.4. The ‘:loaded’ pseudo-class

The :loaded pseudo-class applies to any element which can load an external resource to use in its intrinsic content and which have retreived all data from the resource. This doesn't take in consideration the fact that the data are in a format understood by the element itself.

An element matching :loaded should usually also match either :interactive or :error, to be coherent. This may however not be the case if the received data need some long processing before that the element enters in the interactive mode.

3.5. The ‘:error’ pseudo-class

The :error pseudo-class applies to any element which can load one or more external resources to use in its intrinsic content and (1) which have retreived enough data from the resources to determine that it can't use its content in the intended way, for example because it doesn't understand the format OR (2) which has failled to download the requested resources.

An element which has fallback content for a given resource should not match the :error pseudo-class if the fallback content can be correctly interpreted. The :error pseudo-class only match elements which has downloaded and rejected all fallback content associated to a specified resource.

The mechanism used to specify fallback content for a resource is not defined in this specification. This includes fallback content defined on the element itself or in the downloaded resource. This does not, however, take in consideration fallback content defined outside the scope of the element, as in a stylesheet.

This specification doesn't the behavior of an element matching the :error pseudo-class. Some elements may continue to work almost correctly even if they match that pseudo-class. In such case, they should continue to match the :interactive pseudo-class.

The following example replace all video's the UA can't show by an error message.

video:error { 
	content: 'Sorry, an error occured. There should have been a video here.'; 
	diplay: block; 
	color: yellow; 
	background: red; 
	margin: 3px; 
	padding: 5px; 

Please notice that an unrecognized format generally leads to :loaded:error while a download faillure leads to :not(:loaded):error. This is however not enforced in any way by this specification and some other error causes may have the same symptoms.

4. Conformance

4.1. Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

4.2. Conformance classes

Conformance to CSS CONTENT STATE Module is defined for three conformance classes:

style sheet
A CSS style sheet.
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

A style sheet is conformant to CSS CONTENT STATE Module if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to CSS CONTENT STATE Module if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by CSS CONTENT STATE Module by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to CSS CONTENT STATE Module if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

4.3. Partial implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

4.4. Experimental implementations

To avoid clashes with future CSS features, the CSS2.1 specification reserves a prefixed syntax for proprietary and experimental extensions to CSS.

Prior to a specification reaching the Candidate Recommendation stage in the W3C process, all implementations of a CSS feature are considered experimental. The CSS Working Group recommends that implementations use a vendor-prefixed syntax for such features, including those in W3C Working Drafts. This avoids incompatibilities with future changes in the draft.

4.5. Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group's website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

4.6. CR exit criteria

For this specification to be advanced to Proposed Recommendation, there must be at least two independent, interoperable implementations of each feature. Each feature may be implemented by a different set of products, there is no requirement that all features be implemented by a single product. For the purposes of this criterion, we define the following terms:

each implementation must be developed by a different party and cannot share, reuse, or derive from code used by another qualifying implementation. Sections of code that have no bearing on the implementation of this specification are exempt from this requirement.
passing the respective test case(s) in the official CSS test suite, or, if the implementation is not a Web browser, an equivalent test. Every relevant test in the test suite should have an equivalent test created if such a user agent (UA) is to be used to claim interoperability. In addition if such a UA is to be used to claim interoperability, then there must one or more additional UAs which can also pass those equivalent tests in the same way for the purpose of interoperability. The equivalent tests must be made publicly available for the purposes of peer review.
a user agent which:
  1. implements the specification.
  2. is available to the general public. The implementation may be a shipping product or other publicly available version (i.e., beta version, preview release, or “nightly build”). Non-shipping product releases must have implemented the feature(s) for a period of at least one month in order to demonstrate stability.
  3. is not experimental (i.e., a version specifically designed to pass the test suite and is not intended for normal usage going forward).

The specification will remain Candidate Recommendation for at least six months.




Normative references

Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. W3C Recommendation. URL: http://www.w3.org/TR/2011/REC-CSS2-20110607
Tantek Çelik; et al. CSS3 module: Selectors. 29 September 2011. W3C Recommendation. URL: http://www.w3.org/TR/css3-selectors/#dynamic-pseudos
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt

Other references

Håkon Wium Lie; Bert Bos. Cascading Style Sheets (CSS1) Level 1 Specification. 11 April 2008. W3C Recommendation. URL: http://www.w3.org/TR/2008/REC-CSS1-20080411
Tantek Çelik; Chris Lilley; L. David Baron. CSS Color Module Level 3. 7 June 2011. W3C Recommendation. URL: http://www.w3.org/TR/2011/REC-css3-color-20110607