Cascading Style Sheets Object Model (CSSOM)

Abstract

The Cascading Style Sheets Object Model defines enables developers to find style sheets associated with a Document and to query and modify rules within a CSS style sheet (through an object model).

Status of this Document

This document is in its very early stages. The intention is that this specification will in due course supersede DOM Level 2 Style.

Table of Contents

Introduction

...

History

Several interfaces from DOM Level 2 Style have been obsoleted because they where thought to be too awkward for frequent use. This specification no longer contains those features. DOMImplementationCSS and CSSCharsetRule have been removed as well as they were not deemed necessary.

Conformance Requirements

Everything in this specification is normative except for diagrams, examples, notes and sections marked non-normative.

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 [RFC2119].

The following conformance classes are defined (and considered) by this specification:

conforming implementation

A user agent that implements all interfaces described in this specification and follows all must-, required- and shall-level of criteria in this specification.

conforming document

A document that follows all must-, required- and shall-level of criteria in this specification that apply to document authors.

conforming authoring tool

One that produces conforming documents.

Terminology

A color component integer is a base-ten integer in the range 0-255 using digits 0-9, U+0030 to U+0039, in the shortest form possible.

A color component separator is a literal U+002C COMMA followed by a U+0020 SPACE.

When this specification talks about object A where A is actually an interface, it generally means an object implementing interface A.

The terms whitespace and style sheet are used as defined in the CSS 2.1 Specification [CSS21].

A CSS style sheet is a style sheet that conforms to the CSS syntax rules.

Style Sheets and the DOM

Style Sheet

Each document has a collection of zero or more associated style sheets. A style sheet is represented by an object that implements the StyleSheet interface (as described below) and has a number of properties that need to be set when a style sheet is created. These properties can be modified over time.

style sheet type

A string that is the MIME type of the style sheet. [RFC2046].

style sheet location

A string that is the URI of the style sheet's location or the null value if the style sheet was embedded within a document.

style sheet media

A string with the media queries applicable to the style sheet. When the style sheet is created the mediaText attribute returned by the media attribute on the style sheet must be set to this string.

style sheet title

A string that is the title of the style sheet. A style sheet is said to have a title if this string is not the empty string.

The following CSS style sheets have a style sheet title that is the empty string:

<style title=""> body { background:lime } </style>

<style> body { background:lime } </style>

style sheet alternate flag

...

The following style sheets have their style sheet alternate flag set to true:

<?xml-stylesheet alternate="yes" title="x" href="data:text/css,…"?>

<link rel="alternate stylesheet" title="x" href="data:text/css,…">

style sheet disabled flag

...

This flag is independent of whether the style sheet is actually applied. That depends on the style sheet media as well, for instance.

Specifications must not allow the creation of style sheets with the style sheet alternate flag set to true and the style sheet title set to the empty string. In addition they must not allow the creation of style sheets for which the user agent does not support the style sheet language.

The StyleSheet Interface

interface StyleSheet {
  readonly attribute DOMString type;
           attribute boolean disabled;
  readonly attribute Node ownerNode;
  readonly attribute StyleSheet parentStyleSheet;
  readonly attribute DOMString href;
  readonly attribute DOMString title;
  [PutForwards=mediaText] readonly attribute MediaList media;
};

CSS style sheets objects implement the CSSStyleSheet interface which inherits from the StyleSheet interface.

The type attribute, on getting, must return the style sheet type.

The disabled attribute, on getting, must return true when the style sheet disabled flag is true and false if that flag is false. On setting, it must set the style sheet disabled flag to true if set to true, and set the flag to false if set to false.

The ownerNode attribute, on getting, must return the Node that associates the style sheet with the document or it must return null if there is no such Node.

The aformentioned Node has implemented the LinkStyle interface.

The parentStyleSheet attribute, on getting, must return the StyleSheet object that caused the inclusion of the current style sheet or null if there is no such object.

The href attribute, on getting, must return the style sheet location.

The title attribute, on getting, must return the style sheet title.

The media attribute, on getting, must return an object implementing the MediaList interface that represents the style sheet media.

The StyleSheetList Interface

The object implementing this interface represents an ordered collection of objects implementing the StyleSheet interface. Items in this collection are accessible through an integral index, starting from zero.

interface StyleSheetList {
  readonly attribute unsigned long length;
  [IndexGetter] StyleSheet item(in unsigned long index);
};

The length attribute, on getting, must return the number of objects currently in the list.

The item(index) method, when invoked, must return the StyleSheet object in the list given by index, or null, if index is greater than or equal to the number of items in the list.

Media Queries

creating a MediaList object?

The rules for parsing a media query for a given string s are to follow the rules for parsing a list of media queries and return the first media query those rules return, or null if null is returned.

The rules for parsing a list of media queries ...

The rules for serializing a media query are as follows:

1. Let s be the empty string.

2. If the media query is negated append the literal string "not", followed by a U+0020 character, to s.

3. If the media query does not contain media features append the canonical form of the media type (as specified in the syntax) to s, then return s and terminate this algorithm.

4. If the media type is not all append the canonical form of the media type, followed by a U+0020 character, followed by the literal string "and", followed by a U+0020 character, to s.

5. Remove all duplicate media features.

6. Convert each media feature name and media feature value to its canonical form (as specified in the syntax).

7. Sort the media features in lexicographical order.

8. Then, for each media feature:

   1. Append a U+0028 (() character, followed by the media feature name, to s.

   2. If a value is given append a U+003A (:) character, followed by a U+0020 character, followed by the media feature value, to s.

   3. Append a U+0029 ()) character to s.

   4. If this is not the last media feature append a U+0020 character, followed by the literal string "and", followed by a U+0020 character, to s.

9. Return s.

The rules for serializing a list of media queries are as follows:

1. Let s be the empty string.

2. If the list is empty return s and terminate this algorithm.

3. For each media query in the list:

   1. Append the result of serializing the media query to s.

   2. If this is not the last media query append a U+002C (,) character, followed by a U+0020 character to s.

4. Return s.

The rules for comparing media queries m1 and m2 are to serialize them both and if they are equal return true and false otherwise.

The MediaList Interface

Objects implementing the MediaList interface represent an ordered collection of media queries. Items in this collection are accessible through an integral index, starting from zero.

interface MediaList {
           attribute DOMString mediaText;
  readonly attribute unsigned long length;
  [IndexGetter] DOMString item(in unsigned long index);
  void appendMedium(in DOMString medium)
  void deleteMedium(in DOMString medium)
};

In bindings that allow it, such as ECMAScript, MediaList objects must stringify to their mediaText attribute's value.

The mediaText attribute, on getting, must return a serialization of the media qeuries. On setting, setting must be ignored if the return value of parsing the setted string is null. Otherwise the return values of parsing must be used as the new media queries.

The length attribute, on getting, must return the number of items in the collection.

The item(index) method, when invoked, must return the item in the list given by index, or null, if index is greater than or equal to the number of items in the list.

The appendMedium(medium) method, when invoked, ....

The deleteMedium(medium) method, when invoked, must raise a NOT_FOUND_ERR exception when medium is not in the collection. Otherwise, medium must be removed from the collection.

Style Sheet Types

A persistent style sheet is a style sheet whose style sheet title is the empty string.

A style sheet set is a collection of one or more style sheets which have an identical style sheet title that is not the empty string.

An alternative style sheet set is a style sheet set of which the style sheet alternate flag is true.

preferred style sheet set

Accessing Style Sheets

The LinkStyle Interface

The LinkStyle interface provides a bridge between the node that takes care of the embedding or inclusion of a style sheet and the StyleSheet object representing the style sheet.

The style content attribute found in various markup languages does not embed, or represent, a style sheet.

interface LinkStyle {
  readonly attribute StyleSheet sheet;
};

The sheet attribute, on getting, must return the associated StyleSheet object, or null, if there is no associated StyleSheet object.

<style type=text/css> body { background:lime } </style>
<style type=text/example-sheets> $(body).background := lime </style>

Whether or not the node refers to a style sheet is defined by the specification that defines the semantics of said node.

Requirements on specifications

Specifications introducing new ways of associating style sheets through the DOM should define which Nodes implement the LinkStyle interface. These specifications should also define how the various properties of a style sheet are set when sheet is not null.

This specification defines it for SVG, <?xml-stylesheet?>, and the HTTP Link header for the time being.

Requirements User Agents Implementing SVG

This section applies to user agents implementing SVG.

SVG user agents must implement the LinkStyle interfaces on objects implementing the SVGStyleElement interface.

...

Requirements on User Agents Implementing <?xml-stylesheet?>

This section applies to user agents implementing <?xml-stylesheet?>.

User agents supporting supporting <?xml-stylesheet?> must implement the LinkStyle on objects implementing ProcessingInstruction.

If the target DOM attribute of the ProcessingInstruction is not xml-stylesheet then the sheet attribute of the node's LinkStyle interface must return null.

Else, if the target DOM attribute is xml-stylesheet but the specified resource has not completed downloading, or is not a supported style sheet language the sheet attribute of the node's LinkStyle interface must return null.

Otherwise, a new style sheet must be created with style sheet type set to the canonical type, style sheet location to the location of the style sheet, style sheet title to the value of the title pseudo-attribute, style sheet media to the value of the media pseudo-attribute, the style sheet alternate flag to true if the alternate pseudo-attribute is "yes" and false otherwise, and the style sheet disabled flag to false.

Requirements on User Agents Implementing the HTTP Link Header

...

The DocumentStyle Interface

Any object implementing the Document interface must also implement the DocumentStyle interface.

interface DocumentStyle {
  readonly attribute StyleSheetList styleSheets;
           attribute DOMString selectedStyleSheetSet;
  readonly attribute DOMString lastStyleSheetSet;
  readonly attribute DOMString preferredStyleSheetSet;
  readonly attribute DOMStringList styleSheetSets;
  void enableStylesheetsForSet(in DOMString name);
};

For this interface, the DOMString values null and "the empty string" are distinct and must not be considered equivalent.

styleSheets of type StyleSheetList

This attribute must be a StyleSheetList object containing a collection of all StyleSheet objects in document order (those returned by sheet attribute on objects implementing the LinkStyle interface) preceded by style sheets introduced through the HTTP Link header.

selectedStyleSheetSet of type DOMString

This attribute indicates which style sheet set is in use. This attribute is live; changing the disabled attribute on style sheets directly will change the value of this attribute.

If all the sheets that are enabled and have a title have the same title (by case-sensitive comparisons) then the value of this attribute must be exactly equal to the title of the first enabled style sheet with a title in the styleSheets list. Otherwise, if style sheets from different sets are enabled, then the return value must be null (there is no way to determine what the currently selected style sheet set is in those conditions). Otherwise, either all style sheets that have a title are disabled, or there are no alternative style sheets, and selectedStyleSheetSet must return the empty string.

Setting this attribute to the null value must have no effect.

Setting this attribute to a non-null value must call enableStylesheetsForSet() with that value as the method's argument, and set lastStyleSheetSet to that value.

From the DOM's perspective, all views have the same selectedStyleSheetSet. If a user agent supports multiple views with different selected alternative style sheets, then this attribute (and the StyleSheet interface's disabled attribute) must return and set the value for the default view.

lastStyleSheetSet of type DOMString, readonly

This attribute must initially have the value null. Its value changes when the selectedStyleSheetSet attribute is set.

preferredStyleSheetSet of type DOMString, readonly

This attribute must be the preferred style sheet set as set by the author. It is determined from the order of style sheet declarations and the Default-Style HTTP headers. If there is no preferred style sheet set, this attribute must be the empty string. The case of this attribute must exactly match the case given by the author where the preferred style sheet is specified or implied. This attribute must never be null.

styleSheetSets of type DOMStringList, readonly

This must be a live list of the currently available style sheet sets. This list is constructed by enumerating all the style sheets for this document available to the implementation, in the order they are listed in the styleSheets attribute, adding the title of each style sheet with a title to the list, avoiding duplicates by dropping titles that match (case-sensitively) titles that have already been added to the list.

enableStylesheetsForSet(name), method

Invoking this method must change the disabled attribute on each StyleSheet object with a title in the styleSheets attribute, so that all those whose title matches the name argument are enabled, and all others are disabled. Title matches must be case-sensitive.

Invoking this method with the empty string value must disable all alternative and preferred style sheets (but does not change the state of persistent style sheets).

Invoking this method with the null value must have no effect.

Style sheets that do not have a title are never affected by this method. This method does not change the values of the lastStyleSheetSet or preferredStyleSheetSet attributes.

Dynamically adding new style sheets

If new style sheets with titles are added to the document, the user agent must decide whether or not the style sheets should be initially enabled or not. How this happens depends on the exact state of the document at the time the style sheet is added, as follows.

Adding style sheets

First, if the style sheet is a preferred style sheet (it has a title, but is not marked as alternative), and there is no current preferred style sheet (the preferredStyleSheetSet attribute is equal to the empty string) then the preferredStyleSheetSet attribute is set to the exact value of this style sheet's title. (This changes the preferred style sheet set, which causes further changes — see below.)

Then, for all sheets, if any of the following is true, then the style sheet must be enabled:

• The style sheet has an empty title.
• The lastStyleSheetSet is null, and the style sheet's title matches (by case-sensitive match) the value of the preferredStyleSheetSet attribute.
• The style sheet's title matches (by case-sensitive match) the value of the lastStyleSheetSet attribute.

Otherwise, the style sheet must be disabled.

Changing the preferred style sheet set

The first time the preferred style sheet set is set, which is either before any alternative style sheets are seen (e.g. using a Default-Style HTTP header), or is the first time a titled, non-alternative style sheet is seen (in the absence of information to the contrary, the first titled non-alternative sheet sets the name of the preferred set), the preferredStyleSheetSet attribute's value must be set to the name of that preferred style sheet set. This does not change the lastStyleSheetSet attribute.

If the user agent has the preferred style sheet set changed, for example if it receives a Default-Style HTTP header after it receives HTTP Link headers implying another preferred style sheet, then the preferredStyleSheetSet attribute's value must be changed appropriately, and, if the lastStyleSheetSet is null, the enableStylesheetsForSet() method must be called with the new preferredStyleSheetSet value. (The lastStyleSheetSet attribute is, again, not changed.)

Examples

<link rel="alternate stylesheet" title="foo" href="a">
<link rel="alternate stylesheet" title="bar" href="b">
<script>

  document.selectedStyleSheetSet = 'foo';
  document.styleSheets[1].disabled = false;
</script>
<link rel="alternate stylesheet" title="foo" href="c">
<link rel="alternate stylesheet" title="bar" href="d">

<link rel="alternate stylesheet" title="foo" href="a">
<link rel="alternate stylesheet" title="bar" href="b">
<script>
  var before = document.preferredStyleSheetSet;
  document.styleSheets[1].disabled = false;
</script>
<link rel="stylesheet" title="foo" href="c">

<link rel="alternate stylesheet" title="bar" href="d">
<script>
  var after = document.preferredStyleSheetSet;
</script>

Interaction with the User Interface

The user interface of Web browsers that support style sheets should list the style sheet titles given in the styleSheetSets list, showing the selectedStyleSheetSet as the selected style sheet set, leaving none selected if it is null or the empty string, and selecting an extra option "Basic Page Style" (or similar) if it is the empty string and the preferredStyleSheetSet is the empty string as well.

Selecting a style sheet from this list should set the selectedStyleSheetSet attribute. This (by definition) affects the lastStyleSheetSet attribute.

Persisting the selected style sheet set

If UAs persist the selected style sheet set, they should use the value of the selectedStyleSheetSet attribute, or if that is null, the lastStyleSheetSet attribute, when leaving the page (or at some other time) to determine the set name to store. If that is null then the style sheet set should not be persisted.

When re-setting the style sheet set to the persisted value (which can happen at any time, typically at the first time the style sheets are needed for styling the document, after the <head> of the document has been parsed, after any scripts that are not dependent on computed style have executed), the style sheet set should be set by setting the selectedStyleSheetSet attribute as if the user had selected the set manually.

This specification does not give any suggestions on how UAs should decide to persist the style sheet set or whether or how to persist the selected set across pages.

Forward compatibility

Future versions of CSS may introduce ways of having alternative style sheets declared at levels lower than the top level, i.e. embedded within other style sheets. Implementations of this specification that also support this proposed declaration of alternative style sheets are expected to perform depth-first traversals of the styleSheets list, not simply enumerations of the styleSheets list that only contains the top level.

Would that actually work?!

Cascading Style Sheets APIs

This section (and its subsections) are only applicable to user agents implementing CSS.

The previous section provided a way of getting access to style sheets in a generic way. This section provides a way for getting access to the individual style rules within a Cascading Style Sheet as defined by the CSS specifications. [CSS]

Parsing and Serializing CSS Constructs

This section (and its subsections) define rules for parsing and serialization of CSS constructs.

CSS Value Rules

The rules for parsing a CSS value for a given property are as given in the following algorithm. The result is either a CSS value or "null" if the operation failed.

1. Parse the value using the S* expr production in combination with the allowed values for the given property. If this fails return "null". Otherwise return the parsed value.

The aforementioned production is defined in the CSS 2.1 specification. [CSS]

The rules for serializing a CSS value are as given in the following algorithm:

1. Relative lengths (em, ex, px, all the font-size keywords and %) do not have their units changed. However, absolute lengths must be given in millimeters. For example, the canonical version of +012.0pt is 4.2333mm (give or take a few significant figures). Computed values may well be in different units than the specified value. User agents are to use px as their final units for computed length values.

2. When a <length> of zero is given, then any specified units must be removed.

3. A <color> value is canonicalized as follows:

   It is a system color

   See below (you use the representation given in the specification that defines the keyword).

   Alpha component is equal to 1.0

   The color is an uppercase six-digit hexadecimal value, prefixed with a # character (U+0023 NUMBER SIGN), with the first two digits representing the red component, the next two digits representing the green component, and the last two digits representing the blue component, the digits being in the range 0-9 A-F (U+0030 to U+0039 and U+0041 to U+0046).

   Alpha component is less than 1.0

   The color is in the CSS rgba() functional-notation format: the literal string rgba (U+0072 U+0067 U+0062 U+0061) followed by a U+0028 LEFT PARENTHESIS, a color component integer representing the red component, a color component separator, a color component integer for the green component, a color component separator, a color component integer for the blue component, another color component separator a U+0030 DIGIT ZERO, a U+002E FULL STOP (representing the decimal point), one or more digits in the range 0-9 (U+0030 to U+0039) representing the fractional part of the alpha value, and finally a U+0029 RIGHT PARENTHESIS.

   The keyword transparent is used

   The color is rgba(0, 0, 0, 0).

4. Angles are canonicalized to deg and normalized to the range of their property. For example, azimuth: 700grad would be canonicalized to azimuth: 270deg. This also applies to angle keywords as used in the elevation and azimuth properties, they are canonicalized to their value in degrees.

5. Times are canonicalized to seconds (s).

6. Frequencies are canonicalized to Hertz (Hz).

7. For all integers and real numbers, including those with units, these canonicalization steps must be followed: If the number is 0, the canonical result is the literal string 0 plus any units (for lengths, the unit identifier will have been removed before this step). Otherwise, leading zeros must be omitted, any leading + must be omitted, the decimal point in a real number must be omitted unless there is a fractional part, and if the number is in the range -1 < x < 1, then one leading 0 must be inserted before the decimal point. The number of given significant figures is completely user agent dependent.

8. Where multiple values may appear in any order without changing the meaning of the value (typically represented by a double bar || in the value syntax), user agents are to use the canonical order as given in the syntax (e.g. <border-width> <border-style> <color> for the border short-hand property).

9. When repeated values may be omitted without changing the meaning of the value (e.g. as in the margin and padding properties), then the fewest number of values should be given.

10. If whitespace may be removed without changing the meaning of the value it is to be removed.

11. <specific-voice> and <family-name values are to be quoted.

12. Double quotes (rather than single quotes) shall be used for string quotation. (When changing from single quotes to double quotes, double quotes already in the string are escaped.)

13. The quotes in the <uri> form should be removed. (Parenthesises that were in the string, along with any other characters not legal when the string is not quoted (such as commas), must be escaped.)

14. Unnecessary escapes should be removed. (For example, \z should be represented as z. This extends to unescaping UNICODE escapes, except, of course, if the encoding cannot contain those characters!)

15. Where components of the value may be dropped without changing the meaning of the value (for example, initial values in shorthand properties), then they should be removed. If this would remove all the values, then the first allowed value must be given (For example, for background that would be rgba(0, 0, 0, 0) since background-color is the first component of the value; for border it would be 0 since the first component of that value is border-width).

16. A single space should be added after each comma that is not part of a string, except where that would change the meaning of the value. For example:

    foo,bar,baz

    should become:

    foo, bar, baz

17. Whenever case is insensitive, for example in property or counter names, the text should be changed to the canonical case as given in the syntax definition. For example, the canonical value of:

    COUNTER( PAR-NUM,UPPER-ROMAN ) DISC

    is:

    counter(par-num, upper-roman) disc

    but the color WINDOWTEXT becomes WindowText.

Examples of the CSS Value Serializing Algorithm

The steps above should guarantee that there is no data loss, from a CSS point of view. Here are some examples of before and after results on specified values. The before column could be what the author wrote in a stylesheet, while the after column shows what querying the DOM would return.

Selectors Rules

The rules for parsing a group of selectors are as given in the following algorithm. The return value is either a group of selectors or "null" (if parsing failed).

1. Parse the value using the selectors_group production. If this fails return "null". Otherwise return the parsed value.

The aforementioned production is defined in the Selectors specification. [Selectors]

The rules for serializing a group of selectors are as given in the following algorithm. The input is a a non-normalized group of selectors and the output is a normalized group of selectors.

1. Replace one or more consecutive whitespace characters with a single U+0020 character.

2. Remove leading and trailing whitespace.

3. Make sure combinators other than the descendant combinator are preceded and followed by a single U+0020 character (and not more).

4. Make sure each U+002C (,) character is followed by a single U+0020 character (and not more).

5. Convert pseudo-classes and pseudo-elements to their canonical form as given in the specification. :HOver becomes :hover and :befoRe becomes ::before for example.

6. Hmm, what about pseudo-classes taking arguments? Attribute selectors? Namespace prefixes?

CSS Page Selectors Rules

Need to define the rules for parsing a CSS page selector and serializing a CSS page selector.

Processing CSS Statements

Need to split this up in parsing and common algorithms.

The rules for inserting a statement are as given in the following algorithm. The variables rule, rule list and index are to be considered equivalent to the identically named variables used when invoking this algorithm. If an exception is raised the algorithm is to be aborted. The steps must be followed in order, as follows:

1. If index is negative or greater than the length of the rule list an INDEX_SIZE_ERR exception must be raised.

2. Parse rule as a CSS statement. If the rule is ignored by the CSS parser abort this algorithm (don't raise an exception). Otherwise, create an object that implements one of the inherited interfaces of CSSStyle appropriate for the parsed rule. Let object be the newly created object.

3. If object can't be inserted within the rule list at the given index because that's not allowed per the CSS specification a HIERARCHY_REQUEST_ERR exception must be raised.

4. Insert object at the given index within the rule list.

The rules for removing a statement are as given in the following algorithm. The variables index and rule list are to be considered equivalent to the identically named variables used when invoking this algorithm. If an exception is raised this algorithm is to be aborted. The steps must be followed in order, as follows:

1. If index is negative or greater than the length of the rule list an INDEX_SIZE_ERR exception must be raised.

2. Remove the object at index from rule list.

The rules for replacing a statement are as given in the following algorithm. The variable rule and old object are to be considered equivalent to the identically named variables used when invoking this algorithm. If an exception is raised this algorithm is to be aborted. The steps must be followed in order, as follows:

1. Parse rule as a CSS statement. If the rule is ignored by the CSS parser abort this algorithm (don't raise an exception). Otherwise, create an object that implements one of the inherited interfaces of CSSStyle appropriate for the parsed rule. Let object be the newly created object.

2. If the type of object does not match the type of old object it will replace user agents must raise an INVALID_MODIFICATION_ERR exception.

3. Replace old object with object.

The CSSStyleSheet Interface

The CSSStyleSheet interface represents a CSS style sheet.

interface CSSStyleSheet : StyleSheet {
  readonly attribute CSSRule ownerRule;
  readonly attribute CSSRuleList cssRules;
  unsigned long insertRule(in DOMString rule, in unsigned long index);
  void deleteRule(in unsigned long index);
};

The ownerRule attribute, on getting, must return the CSSImportRule that caused this style sheet to be imported (if any). Otherwise, if no CSSImportRule caused it to be imported the attribute must return null.

The cssRules attribute, on getting, must return a CSSRuleList object consisting of a list of statements in order they were found in the CSS style sheet.

Statements that were dropped during parsing can not be found using these APIs.

The insertRule(rule, index) method, when invoked, must insert a statement where rule is rule, index is index and rule list is cssRules.

The deleteRule(index) method, when invoked, must remove a statement where index is index and rule list is cssRules.

The CSSRuleList Interface

The CSSRuleList object represents an ordered collection of CSS statements. Items in this collection are accessible through an integral index, starting from zero.

interface CSSRuleList {
  readonly attribute unsigned long length;
  CSSRule item(in unsigned long index);
};

The length attribute, on getting, must return the number of items associated with the object.

The item(index) method, when invoked, must return the CSSRule object in the list given by index, or null, if index is greater than or equal to the number of items in the list.

Interfaces for CSS Statements

This section defines several specific interfaces for different types of CSS statements and one generic from which the more specific inherit.

The CSSRule Interface

The CSSRule interface a base interface. Each specific CSS statement has an interface which inherits from this one.

interface CSSRule {
  // CSS statement type
  const unsigned short STYLE_RULE = 1;
  const unsigned short IMPORT_RULE = 3;
  const unsigned short MEDIA_RULE = 4;
  const unsigned short FONT_FACE_RULE = 5;
  const unsigned short PAGE_RULE = 6;
  const unsigned short NAMESPACE_RULE = 7;
  readonly attribute unsigned short type;

  // Textual representation
           attribute DOMString cssText;
  
  // Context information
  readonly attribute CSSRule parentRule;
  readonly attribute CSSStyleSheet parentStyleSheet;
};

The type attribute, on getting, must return the CSS statement type as detailed for each specific type.

The cssText attribute, on setting, must replace a statement where rule is the value being set and old object is the object of which this attribute is set.

On getting the cssText attribute, ....

The parentRule attribute must return the nearest enclosing rule of the current rule or null, if there is no enclosing rule. For example, an @media block enclosing the current rule.

The parentStyleSheet attribute must return the CSSStyleSheet object that contains the the current rule.

Extensibility

The constant values 0-1000 are reserved for future use by the CSS WG.

Vendors are encouraged to use reasonably unique values outside this range so that they do not clash with extensions from other vendors. For example, the first value for Mozilla could be 0x08EC0001 and 0x09E8A001 could be the first for Opera.

Vendors are encouraged to prefix the new interface names with a vendor specific prefix. For example, "Example company" could have an interface called "ExampleCSSTestRule".

In general, vendors are encouraged to discuss extensions on a public forum, such as www-style@w3.org.

The CSSStyleRule Interface

The CSSStyleRule object represents a ruleset specified (if any) in a CSS style sheet. It provides access to a declaration block as well as to the associated group of selectors.

Objects implementing the CSSStyleRule interface can be identified by the STYLE_RULE constant. On these objects the type attribute must return the value of that constant.

interface CSSStyleRule : CSSRule {
           attribute DOMString selectorText;
  readonly attribute CSSStyleDeclaration style;
};

The selectorText attribute, on getting, must return the result of serializing a group of selectors. On setting, the setted value must be used as input for parsing a group of selectors and if that returns a non-"null" value that is to be used as a selector for the CSS statement. If it returns "null" setting must not have an effect.

The style attribute must return a live CSSStyleDeclaration object for the ruleset.

The CSSImportRule Interface

Objects implementing the CSSImportRule interface can be identified by the IMPORT_RULE constant. On these objects the type attribute must return the value of that constant.

The CSSImportRule object represents an @import rule specified (if any) in a CSS style sheet.

interface CSSImportRule : CSSRule {
  readonly attribute DOMString href;
  [PutForwards=mediaText] readonly attribute MediaList media;
  readonly attribute CSSStyleSheet styleSheet;
};

The href attribute, on getting, must return the specified URI of the style sheet referenced by the @import rule.

The media attribute, on getting, must return a live MediaList object containing a list of media queries applicable to the imported style sheet as specified by the @import rule.

The styleSheet attribute, on getting, must return the CSSStyleSheet object that represents the referenced (parsed) style sheet from the @import rule.

If loading of the style sheet fails its cssRules list is simply empty.

The CSSMediaRule Interface

Objects implementing the CSSMediaRule interface can be identified by the MEDIA_RULE constant. On these objects the type attribute must return the value of that constant.

The CSSMediaRule object represents an @media rule specified (if any) in a CSS style sheet. It is a single statement that contains zero or more rulesets which are contrained by one or more media queries (unless one happens to be all).

interface CSSMediaRule : CSSRule {
  [PutForwards=mediaText] readonly attribute MediaList media;
  readonly attribute CSSRuleList cssRules;
  unsigned long insertRule(in DOMString rule, in unsigned long index);
  void deleteRule(in unsigned long index);
};

The media attribute, on getting, must return a MediaList object containing a list of media queries specified with the @media rule.

The cssRules attribute, on getting, must return a CSSRuleList object containing a list of all the rulesets specified within the @media rule.

The insertRule(rule, index) method, when invoked, must insert a statement where rule is rule, index is index and rule list is cssRules.

The deleteRule(index) method, when invoked, must remove a statement where index is index and rule list is cssRules.

The CSSFontFaceRule Interface

Objects implementing the CSSFontFaceRule interface can be identified by the FONT_FACE_RULE constant. On these objects the type attribute must return the value of that constant.

The CSSFontFaceRule object represents an @font-face rule specified (if any) in a CSS style sheet.

interface CSSFontFaceRule : CSSRule {
  readonly attribute CSSStyleDeclaration style;
};

The style attribute must return a CSSStyleDeclaration block that contains the property declarations specified within the @font-face rule.

The CSSPageRule Interface

Objects implementing the CSSPageRule interface can be identified by the PAGE_RULE constant. On these objects the type attribute must return the value of that constant.

The CSSPageRule object represents an @page rule specified (if any) in a CSS style sheet.

interface CSSPageRule : CSSRule {
           attribute DOMString selectorText;
  readonly attribute CSSStyleDeclaration style;
};

The selectorText attribute, on getting, must return the result of serializing CSS page selectors. On setting, the setted value must be used as input for parsing CSS page selectors and if that returns a non-"null" value that is to be used as a selector for the @page rule. If it returns "null" setting must not have an effect.

The style attribute, on getting, must return a CSSStyleDeclaration that contains the specified property declarations within the @page rule.

The CSSNamespaceRule Interface

Objects implementing the CSSNamespaceRule interface can be identified by the NAMESPACE_RULE constant. On these objects the type attribute must return the value of that constant.

The CSSNamespaceRule object represents an @namespace rule specified (if any) in a CSS style sheet that consists of a prefix and namespace.

interface CSSNamespaceRule : CSSRule {
  readonly attribute DOMString namespaceURI;
  readonly attribute DOMString prefix;
};

The namespaceURI attribute, on getting, must return specified namespace IRI from the @namespace rule.

The prefix attribute, on getting, must return the specified prefix from the @namespace rule or the empty string if there is no prefix.

Accessing declaration blocks

The ElementCSSInlineStyle Interface

interface ElementCSSInlineStyle {
  readonly attribute CSSStyleDeclaration style;
  readonly attribute CSSStyleDeclaration currentStyle;
  readonly attribute CSSStyleDeclaration runtimeStyle;
};

...

The currentStyle attribute, on getting, must return a readonly CSSStyleDeclaration object which represents the computed style for the element on which it was called.

Serialization of the style attribute is not guaranteed to work.

The ViewCSS Interface

Objects implementing the Window interface must also implement the ViewCSS interface.

interface ViewCSS {
  CSSStyleDeclaration getComputedStyle(in Element elt);
  CSSStyleDeclaration getComputedStyle(in Element elt, in DOMString pseudoElt);
};

The getComputedStyle method must return a live CSSStyleDeclaration object that contains the computed style declaration block for elt, when the pseudoElt argument is null, the empty string or omitted. Otherwise, for the pseudo-element pseudoElt of elt. [CSS]

CSS Declaration Blocks

The interfaces described in this section provide generic and convenient attributes for manipulating CSS declaration blocks.

The CSSStyleDeclaration Interface

The CSSStyleDeclaration interface gives access to read and manipulate CSS properties and their values within a declaration block.

If an attribute or method returns an object implementing the CSSStyleDeclaration interface (and related interfaces) and says the object is readonly user agents must raise a NO_MODIFICATION_ALLOWED_ERR exception on an attempt to modify the object.

Invoking removeProperty or setting cssText would be examples of that.

CSSStyleDeclaration can represent computed values and used values. (This also goes for interfaces implemented on top of CSSStyleDeclaration objects obviously.)

This object stringifies to its cssText attribute. Or not?

interface CSSStyleDeclaration {
           attribute DOMString cssText;
  DOMString getPropertyValue(in DOMString property);
  DOMString getPropertyPriority(in DOMString property);
  DOMString removeProperty(in DOMString property);
  void setProperty(in DOMString property, in DOMString value);
  void setProperty(in DOMString property, in DOMString value, in DOMString priority);
  readonly attribute unsigned long length;
  DOMString item(in unsigned long index);
  readonly attribute CSSRule parentRule;
};

The cssText attribute, on getting, ....

On setting the cssText attribute, user agents must remove all properties currently set on the object and then parse the given string as the contents of a declaration block and set each property / value pair that is not ignored on the CSSStyleDeclaration block. [CSS]

The getPropertyValue(property) method, when invoked, ....

The getPropertyPriority(property) method, when invoked, if property case-insensitively matches a specified property that has a priority user agents must return the canonical priority of that property as given in the syntax definition. Otherwise, the empty string must be returned.

For background-color:lime !IMPORTANT the return value would be important.

The removeProperty(property) method, when invoked, if property case-insensitively matches a specified property user agents must remove that property declaration.

The setProperty(property, value, priority) method gives a way to set a declaration. When invoked, user agents must run the following steps:

1. If property does not case-insensitively match a supported property abort this algorithm.

2. If value is null or the empty string invoke removeProperty with property as argument and abort this algorithm.

3. If the priority argument has been omitted let priority be null.

4. If priority is neither a valid priority nor null or the empty string abort this algorithm.

5. If parsing the value returns "null" abort this algorithm.

   value can not include !important.

6. Finally, set property to value with priority priority when priority is not null or the empty string. Otherwise set property to value.

The length attribute must be the number of setted properties.

The item(index) method, when invoked, ....

The parentRule attribute, on getting, must return the CSSrule object the CSSStyleDeclaration is object is associated with or null if it is not associated with a CSSrule object.

The CSS2Properties Interface

...

References

This section will be done when going to Last Call. Before that state please ask the author whenever a reference is unclear.

Acknowledgements

The editor would like to thank Alexey Feldgendler, Björn Höhrmann, David Baron, Hallvord R. M. Steen, Ian Hickson, Lachlan Hunt, Morten Stenshorne, Robert O'Callahan, Sjoerd Visscher, Simon Pieters, and Tarquin Wilton-Jones for contributing to this specification.

Even more thanks to Ian Hickson for writing up the the initial version of the alternative style sheets API and canonicalization rules for CSS values.