CSSOM Values Module

Abstract

This CSSOM Values module defines APIs for accessing and manipulating CSS property values using object oriented value representations. These APIs are intended to replace the underimplemented and underutilized CSSValue and related APIs defined by [DOM2STYLE].

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is the 8 January 2014 Editor's Draft of CSSOM. Please send comments to www-style@w3.org (archived) with [cssom-values] at the start of the subject line.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Table of Contents

• 1 Introduction
• 2 Conformance
  • 2.1 Dependencies
• 3 CSS Values
  • 3.1 The CSSValue Interface
  • 3.2 The CSSStyleDeclaration Interface
  • 3.3 The CSSStyleDeclarationValue Interface
  • 3.4 The CSSPropertyValue Interface
  • 3.5 The CSSPropertyValueList Interface
  • 3.6 The CSSMapValue Interface
  • 3.7 The CSSComponentValue Interface
    • 3.7.1 The CSSColorComponentValue Interface
    • 3.7.2 The CSSIdentifierComponentValue Interface
    • 3.7.3 The CSSKeywordComponentValue Interface
    • 3.7.4 The CSSLengthComponentValue Interface
    • 3.7.5 The CSSPercentageComponentValue Interface
    • 3.7.6 The CSSStringComponentValue Interface
    • 3.7.7 The CSSURLComponentValue Interface
• References
• Acknowledgments

1 Introduction

This CSSOM Values module defines APIs for accessing and manipulating CSS property values using object oriented value representations.

2 Conformance

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", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and terminate these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

Unless otherwise stated, string comparisons are done in a case-sensitive manner.

2.1 Dependencies

This specification relies upon the following underlying specifications:

CSSOM

A conforming user agent must support the CSS Object Model. [CSSOM]

Narrow this dependency to specific features of CSSOM.

3 CSS Values

3.1 The CSSValue Interface

interface CSSValue {
  // ...
};

3.2 The CSSStyleDeclaration Interface

partial interface CSSStyleDeclaration {
  readonly attribute CSSStyleDeclarationValue values;
};

values

3.3 The CSSStyleDeclarationValue Interface

interface CSSStyleDeclarationValue {
  // CSS Properties

};

The rough idea is that this interface exposes the full list of supported properties as well that each return a CSSPropertyValue object. That object can implement other objects depending on the property involved. E.g. for 'width' the object would implement CSSLengthComponentValue and CSSPercentageComponentValue.

3.4 The CSSPropertyValue Interface

interface CSSPropertyValue {
           attribute DOMString cssText;
};

cssText

3.5 The CSSPropertyValueList Interface

[NoInterfaceObject] interface CSSPropertyValueList {
  readonly attribute CSSValue[] list;
};

list

Ideally this attribute just returns a mutable array.

3.6 The CSSMapValue Interface

[NoInterfaceObject] interface CSSMapValue {
  getter CSSValue (DOMString name);
};

This seems the simplest we can get away with.

3.7 The CSSComponentValue Interface

[NoInterfaceObject] interface CSSComponentValue {
  readonly attribute DOMString type;
           attribute any value;
};

type

value

type returns "string", "keyword", "identifier", "color", "em", "ex", "px", "url".

3.7.1 The CSSColorComponentValue Interface

[NoInterfaceObject] interface CSSColorComponentValue {
           attribute short red;
           attribute short green;
           attribute short blue;
           attribute float alpha;
};

red

green

blue

alpha

We can make this more complex later. This will probably move into the CSS Color Level 4.

3.7.2 The CSSIdentifierComponentValue Interface

[NoInterfaceObject] interface CSSIdentifierComponentValue {
           attribute DOMString identifier;
};

identifier

3.7.3 The CSSKeywordComponentValue Interface

[NoInterfaceObject] interface CSSKeywordComponentValue {
           attribute DOMString keyword;
};

keyword

3.7.4 The CSSLengthComponentValue Interface

[NoInterfaceObject] interface CSSLengthComponentValue {
           attribute float em;
           attribute float ex;
           attribute float px;
           // figure out what to do with absolute lengths
};

em

ex

px

3.7.5 The CSSPercentageComponentValue Interface

[NoInterfaceObject] interface CSSPercentageComponentValue {
           attribute float percent;
};

percent

3.7.6 The CSSStringComponentValue Interface

[NoInterfaceObject] interface CSSStringComponentValue {
           attribute DOMString string;
};

string

3.7.7 The CSSURLComponentValue Interface

[NoInterfaceObject] interface CSSURLComponentValue {
           attribute DOMString? url;
};

url

References

Acknowledgments

The editors would like to thank Alexey Feldgendler, Björn Höhrmann, Brian Kardell, Christian Krebs, Daniel Glazman, David Baron, fantasai, Hallvord R. M. Steen, Ian Hickson, John Daggett, Lachlan Hunt, Morten Stenshorne, Philip Taylor, Robert O'Callahan, Sjoerd Visscher, Sylvain Galineau, Tarquin Wilton-Jones, and Zack Weinberg for contributing to this specification.

Special thanks to Anne van Kesteren who authored the material upon which this work is based.