css3-conditional/Overview.src.html

Wed, 05 Sep 2012 09:35:55 -0700

author
Tab Atkins Jr. <jackalmage@gmail.com>
date
Wed, 05 Sep 2012 09:35:55 -0700
changeset 6655
8c75e6e6f34d
parent 6625
66482bcc960b
child 6696
b3ba1ce728f8
permissions
-rwxr-xr-x

[css3-conditional] Split CSSConditionRule into a CSSGroupingRule superclass.

dbaron@2974 1 <!DOCTYPE html public '-//W3C//DTD HTML 4.01//EN'
dbaron@2974 2 'http://www.w3.org/TR/html4/strict.dtd'>
dbaron@2974 3 <html lang="en">
dbaron@2974 4 <head profile="http://www.w3.org/2006/03/hcard">
dbaron@2974 5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
dbaron@2974 6 <title>CSS Conditional Rules Module Level 3</title>
dbaron@2974 7 <link rel="stylesheet" type="text/css" href="../default.css">
dbaron@2974 8 <link rel="stylesheet" type="text/css"
dbaron@2974 9 href="http://www.w3.org/StyleSheets/TR/W3C-[STATUS].css">
dbaron@2974 10 </head>
dbaron@2974 11
dbaron@2974 12 <div class="head">
dbaron@2974 13 <!--logo-->
dbaron@2974 14
dbaron@2974 15 <h1>CSS Conditional Rules Module Level 3</h1>
dbaron@2974 16
dbaron@2974 17 <h2 class="no-num no-toc">[LONGSTATUS] [DATE]</h2>
dbaron@2974 18 <dl>
dbaron@2974 19 <dt>This version:
dbaron@2974 20 <dd><a href="[VERSION]">
dbaron@3415 21 http://www.w3.org/TR/[YEAR]/ED-css3-conditional-[CDATE]/</a>
dbaron@2974 22
dbaron@2974 23 <dt>Latest version:
dbaron@3241 24 <dd><a href="http://www.w3.org/TR/[SHORTNAME]/">http://www.w3.org/TR/[SHORTNAME]/</a>
dbaron@2974 25
dbaron@3245 26 <dt>Editor's draft:
bert@3404 27 <dd><a href="http://dev.w3.org/csswg/[SHORTNAME]/">http://dev.w3.org/csswg/[SHORTNAME]/</a>
dbaron@3245 28
dbaron@2974 29 <dt>Previous version:
dbaron@3421 30 <dd><a href="http://www.w3.org/TR/2011/WD-css3-conditional-20110901/">http://www.w3.org/TR/2011/WD-css3-conditional-20110901/</a></dd>
dbaron@2974 31
dbaron@2974 32 <dt>Editors:
dbaron@2974 33 <dd class=vcard><a class=fn href="http://dbaron.org/">L. David Baron</a>,
dbaron@6308 34 <a class=org href="http://www.mozilla.org/">Mozilla</a>
dbaron@3744 35
dbaron@3744 36 <dt>Issues list:
dbaron@3744 37 <dd>Maintained in document (only editor's draft is current)
dbaron@3744 38
dbaron@3744 39 <dt>Send feedback to:
dbaron@3744 40 <dd>public mailing list <a href="www-style@w3.org">www-style@w3.org</a> (<a href="http://lists.w3.org/Archives/Public/www-style/">archive</a>, <a href="http://www.w3.org/Mail/Request">instructions</a>) with [[SHORTNAME]] at start of the subject
dbaron@3744 41
dbaron@3744 42 <dt>Test suite:
dbaron@6115 43 <dd><a href="https://test.csswg.org/shepherd/search/spec/css3-conditional/">submitted tests</a>; no built test suite yet
dbaron@3744 44
dbaron@2974 45 </dl>
dbaron@2974 46
dbaron@2974 47 <!--copyright-->
dbaron@2974 48
dbaron@2974 49 <hr title="Separator for header">
dbaron@2974 50 </div>
dbaron@2974 51
jackalmage@6617 52 <h2 class="no-num no-toc" id="abstract">Abstract</h2>
dbaron@2974 53
dbaron@2974 54 <p>CSS is a language for describing the rendering of structured documents
dbaron@2974 55 (such as HTML and XML) on screen, on paper, in speech, etc. This module
dbaron@2974 56 contains the features of CSS for conditional processing of parts of
dbaron@2974 57 style sheets, conditioned on capabilities of the processor or the
dbaron@2974 58 document the style sheet is being applied to.
dbaron@2974 59 It includes and extends the functionality of CSS level&nbsp;2 [[!CSS21]],
dbaron@2974 60 which builds on CSS level&nbsp;1 [[CSS1]].
dbaron@2974 61 The main extensions compared to level&nbsp;2 are
dbaron@2983 62 allowing nesting of certain at-rules inside '@media',
dbaron@2983 63 the addition of the '@supports' and '@document'
dbaron@2974 64 rules for conditional processing.
dbaron@2974 65
jackalmage@6617 66 <h2 class="no-num no-toc" id="status">Status of this document</h2>
dbaron@2974 67
dbaron@2974 68 <!--status-->
dbaron@2974 69
dbaron@2974 70 <p>The following features are at risk:
dbaron@2974 71 <ul>
dbaron@2983 72 <li>The inclusion of '@font-face' rules and
dbaron@2983 73 '@keyframes' rules as allowed within all of the @-rules in
dbaron@2974 74 this specification is at risk, though only because of the relative
dbaron@2974 75 rates of advancement of specifications. If this specification is able
dbaron@2974 76 to advance faster than one or both of the specifications defining
dbaron@2974 77 those rules, then the inclusion of those rules will move from this
dbaron@2974 78 specification to the specification defining those rules.</li>
dbaron@2974 79
dbaron@2974 80 <li>The addition of support for @-rules inside of conditional grouping
dbaron@2974 81 rules is at risk; if interoperable implementations are not found, it
dbaron@2974 82 may be removed to advance the other features in this specification to
dbaron@2974 83 Proposed Recommendation.</li>
dbaron@2974 84
dbaron@2983 85 <li>The '@supports' rule is at risk; if interoperable
dbaron@2974 86 implementations are not found, it may be removed to advance the other
dbaron@2974 87 features in this specification to Proposed Recommendation.</li>
dbaron@2974 88
dbaron@2983 89 <li>The '@document' rule is at risk; if interoperable
dbaron@2974 90 implementations are not found, it may be removed to advance the other
dbaron@2974 91 features in this specification to Proposed Recommendation.</li>
dbaron@2974 92
dbaron@2974 93 </ul>
dbaron@2974 94
jackalmage@6617 95 <h2 class="no-num no-toc" id="contents">Table of contents</h2>
dbaron@2974 96
dbaron@2974 97 <!--toc-->
dbaron@2974 98
jackalmage@6617 99 <h2 id="introduction">Introduction</h2>
dbaron@2974 100
jackalmage@6617 101 <h3 id="context">Background</h3>
dbaron@2974 102
dbaron@2974 103 <p><em>This section is not normative.</em>
dbaron@2974 104
dbaron@2974 105 <p>[[!CSS21]] defines one type of conditional group rule, the
dbaron@2983 106 '@media' rule, and allows only rulesets (not other @-rules)
dbaron@2983 107 inside of it. The '@media' rule provides the ability to
dbaron@2974 108 have media-specific style sheets, which is also provided by style
dbaron@2983 109 sheet linking features such as '@import' and
dbaron@2983 110 <code class="html">&lt;link&gt;</code>. The restrictions on the contents of
dbaron@2983 111 '@media' rules made them less useful; they have forced authors
dbaron@2974 112 using CSS features involving @-rules in media-specific style sheets to
dbaron@2974 113 use separate style sheets for each medium.</p>
dbaron@2974 114
dbaron@2974 115 <p>This specification extends the rules for the contents of
dbaron@2974 116 conditional group rules to allow other @-rules, which enables authors
dbaron@2974 117 to combine CSS features involving @-rules with media specific style
dbaron@2974 118 sheets within a single style sheet.</p>
dbaron@2974 119
dbaron@2974 120 <p>This specification also defines additional types of conditional
dbaron@2983 121 group rules, '@supports' and '@document', to
dbaron@2974 122 address author and user requirements.</p>
dbaron@2974 123
dbaron@2983 124 <p>The '@supports' rule allows CSS to be conditioned on
dbaron@2974 125 implementation support for CSS properties and values. This rule makes
dbaron@2974 126 it much easier for authors to use new CSS features and provide good
dbaron@2974 127 fallback for implementations that do not support those features. This
dbaron@2974 128 is particularly important for CSS features that provide new layout
dbaron@2974 129 mechanisms, and for other cases where a set of related styles needs to
dbaron@2974 130 be conditioned on property support.</p>
dbaron@2974 131
dbaron@2983 132 <p>The '@document' rule allows CSS to be conditioned on the
dbaron@2974 133 page to which the style sheet is being applied. This allows users to
dbaron@2974 134 apply styles to a particular page or group of pages, which greatly
dbaron@2974 135 increases the power of user style sheets.</p>
dbaron@2974 136
jackalmage@6617 137 <h3 id="placement">Module Interactions</h3>
dbaron@2974 138
dbaron@2983 139 <p>This module replaces and extends the '@media' rule
dbaron@2974 140 feature defined in [[!CSS21]] section <var>7.2.1</var> and
dbaron@2974 141 incorporates the modifications previously made non-normatively by
dbaron@2974 142 [[!MEDIAQ]] section <var>1</var>.</p>
dbaron@2974 143
dbaron@3462 144 <p>Its current definition depends on @-rules defined in [[!CSS3-FONTS]]
dbaron@2974 145 and [[!CSS3-ANIMATIONS]], but that dependency is only on the
dbaron@2974 146 assumption that those modules will advance ahead of this one. If this
dbaron@2974 147 module advances faster, then the dependency will be reversed.</p>
dbaron@2974 148
jackalmage@6617 149 <h3 id="conventions">Document Conventions</h3>
dbaron@2974 150
dbaron@2974 151 <p>Conformance requirements are expressed with a combination of
dbaron@2974 152 descriptive assertions and RFC 2119 terminology. The key words “MUST”,
dbaron@2974 153 “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”,
dbaron@2974 154 “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this
dbaron@2974 155 document are to be interpreted as described in RFC 2119.
dbaron@2979 156 However, for readability, these words do not appear in all uppercase
dbaron@2979 157 letters in this specification.
dbaron@2974 158
dbaron@2974 159 <p>All of the text of this specification is normative except sections
dbaron@2974 160 explicitly marked as non-normative, examples, and notes. [[!RFC2119]]</p>
dbaron@2974 161
dbaron@2974 162 <p>Examples in this specification are introduced with the words “for example”
dbaron@2983 163 or are set apart from the normative text with
dbaron@2983 164 <code class="html">class="example"</code>, like this:
dbaron@2974 165
dbaron@2974 166 <div class="example">
dbaron@2974 167 <p>This is an example of an informative example.</p>
dbaron@2974 168 </div>
dbaron@2974 169
dbaron@2974 170 <p>Informative notes begin with the word “Note” and are set apart from the
dbaron@2983 171 normative text with <code class="html">class="note"</code>, like this:
dbaron@2974 172
dbaron@2974 173 <p class="note">Note, this is an informative note.</p>
dbaron@2974 174
jackalmage@6617 175 <h2 id="processing">Processing of conditional group rules</h2>
dbaron@2974 176
dbaron@2974 177 <p>This specification defines some CSS @-rules, called <dfn>conditional
dbaron@2974 178 group rules</dfn>, that associate a condition with a group of other
dbaron@2974 179 CSS rules. These different rules allow testing different types of
dbaron@2974 180 conditions, but share common behavior for how their contents are used
dbaron@2974 181 when the condition is true and when the condition is false.</p>
dbaron@2974 182
dbaron@2974 183 <div class="example">
dbaron@2974 184 <p>For example, this rule:</p>
dbaron@2974 185 <pre>@media print {
dbaron@2974 186 #navigation { display: none }
dbaron@2974 187 }</pre>
dbaron@2974 188 <p>causes a particular CSS rule (making elements with ID "navigation" be
dbaron@2974 189 display:none) apply only when the style sheet is used for a print
dbaron@2974 190 medium. Likewise, this CSS rule:</p>
dbaron@2974 191 <pre>@document url("http://www.example.com/") {
dbaron@2974 192 #example1 { display: none }
dbaron@2974 193 }</pre>
dbaron@2974 194 <p>does the same type of conditional application, but using a different
dbaron@2974 195 condition: whether the style sheet is being applied to the page
dbaron@2974 196 <code>http://www.example.com/</code>.</p>
dbaron@2974 197 </div>
dbaron@2974 198
dbaron@2974 199 <p>Each conditional group rule has a condition, which at any time
dbaron@2974 200 evaluates to true or false. When the condition is true, CSS processors
dbaron@2979 201 <strong>must</strong> apply the rules inside the group rule as though
dbaron@2979 202 they were at the group rule's location; when the condition is false, CSS
dbaron@3948 203 processors <strong>must not</strong> apply any of rules inside the group
dbaron@2979 204 rule. The current state of the condition does not affect the CSS object
dbaron@2979 205 model, in which the contents of the group rule always remain within the
dbaron@2979 206 group rule.</p>
dbaron@2974 207
dbaron@2974 208 <p>This means that when multiple conditional group rules are nested,
dbaron@2974 209 a rule inside of both of them applies only when all of the rules'
dbaron@2974 210 conditions are true.</p>
dbaron@2974 211
dbaron@2974 212 <div class="example">For example, with this set of nested rules:
dbaron@2974 213 <pre>@media print { // rule (1)
dbaron@2974 214 #navigation { display: none }
dbaron@2974 215 @media (max-width: 12cm) { // rule (2)
dbaron@2974 216 .note { float: none }
dbaron@2974 217 }
dbaron@2974 218 }</pre>
dbaron@2974 219 the condition of the rule marked (1) is true for print media, and the
dbaron@2974 220 condition of the rule marked (2) is true when the width of the display
dbaron@2974 221 area (which for print media is the page box) is less than or equal to
dbaron@2983 222 12cm. Thus the rule ''#navigation { display: none }'' applies
dbaron@2974 223 whenever this style sheet is applied to print media, and the rule
dbaron@2983 224 ''.note { float: none }'' is applied only when the style sheet
dbaron@2974 225 is applied to print media <em>and</em> the width of the page box is less
dbaron@2974 226 than or equal to 12 centimeters.</div>
dbaron@2974 227
dbaron@2979 228 <p>When the condition for a conditional group rule changes, CSS
dbaron@2979 229 processors <strong>must</strong> reflect that the rules now apply or no
dbaron@2979 230 longer apply, except for properties whose definitions define effects of
dbaron@2979 231 computed values that persist past the lifetime of that value (such as
dbaron@2979 232 for some properties in [[CSS3-TRANSITIONS]] and
dbaron@2979 233 [[!CSS3-ANIMATIONS]]).</p>
dbaron@2974 234
jackalmage@6617 235 <h2 id="contents-of">Contents of conditional group rules</h2>
dbaron@2974 236
dbaron@2975 237 <p class="issue">There is also likely demand for using these
dbaron@2983 238 conditions with '@import'. We should see if we can
dbaron@2975 239 come up with sensible syntax for that, perhaps functional notation
dbaron@2983 240 at the end of the '@import' rule.</p>
dbaron@2975 241
dbaron@2974 242 <p>The syntax of each conditional group rule consists of some syntax
dbaron@2974 243 specific to the type of rule followed by a <dfn>group rule body</dfn>,
dbaron@2974 244 which is a block (pair of braces) containing a sequence of rules.</p>
dbaron@2974 245
dbaron@2974 246 <p>A group rule body is allowed to contain rulesets and any @-rules that
dbaron@2974 247 are allowed at the top level of a style sheet before and after a
dbaron@2974 248 ruleset. This means that @-rules that must occur at the beginning of
dbaron@3020 249 the style sheet (such as '@charset', '@import',
dbaron@3020 250 and '@namespace' rules) are not allowed inside of conditional group
dbaron@2974 251 rules. Conditional group rules can be nested.</p>
dbaron@2974 252
dbaron@2974 253 <p>In terms of the grammar, this specification defines the following
dbaron@2974 254 productions for use in the grammar of conditional group rules:</p>
dbaron@2974 255
dbaron@2974 256 <pre>nested_statement
dbaron@5294 257 : ruleset | media | page | font_face_rule | keyframes_rule |
dbaron@2974 258 supports_rule | document_rule
dbaron@2974 259 ;
dbaron@2974 260
dbaron@2974 261 group_rule_body
dbaron@2974 262 : '{' S* nested_statement* '}' S*
dbaron@2974 263 ;</pre>
bert@3404 264 <p>
dbaron@2974 265 in which all the productions are defined in that grammar with the
dbaron@2974 266 exception of <code>font_face_rule</code> <span class="issue">not</span>
dbaron@5294 267 defined in [[!CSS3-FONTS]], <code>keyframes_rule</code> defined in
dbaron@2974 268 [[!CSS3-ANIMATIONS]], and <code>media</code>, <code>supports_rule</code>
dbaron@2974 269 and <code>document_rule</code> defined in this specification.</p>
dbaron@2974 270
dbaron@2974 271 <p>In general, future CSS specifications that add new @-rules that are
dbaron@2974 272 not forbidden to occur after some other types of rules should modify
dbaron@2974 273 this <code>nested_statement</code> production to keep the grammar
dbaron@2974 274 accurate.</p>
dbaron@2974 275
dbaron@2979 276 <p>Style sheets <strong>must not</strong> use rules other than the allowed ones inside
dbaron@2974 277 conditional group rules.</p>
dbaron@2974 278
dbaron@3019 279 <p>CSS processors <strong>must</strong> ignore rules that are not
dbaron@3019 280 allowed within a group rule, and <strong>must</strong> handle invalid
dbaron@3019 281 rules inside of group rules as described in <a
dbaron@3019 282 href="http://www.w3.org/TR/CSS21/syndata.html#parsing-errors">section
dbaron@3019 283 4.2 (Rules for handling parsing errors)</a>, <a
dbaron@3019 284 href="http://www.w3.org/TR/CSS21/syndata.html#at-rules">section 4.1.5
dbaron@3019 285 (At-rules)</a>, and <a
dbaron@3019 286 href="http://www.w3.org/TR/CSS21/syndata.html#rule-sets">section 4.1.7
dbaron@3019 287 (Rule sets, declaration blocks, and selectors)</a> of [[!CSS21]].</p>
dbaron@2974 288
jackalmage@6617 289 <h2 id="use">Placement of conditional group rules</h2>
dbaron@2974 290
dbaron@3019 291 <p>Conditional group rules are allowed at the top-level of a style
dbaron@3019 292 sheet, and inside other conditional group rules. CSS processors
dbaron@3019 293 <strong>must</strong> process such rules as <a
dbaron@3019 294 href="#processing">described above</a>.</p>
dbaron@3019 295
dbaron@3020 296 <p>Any rules that are not allowed after a ruleset (e.g., ''@charset'',
dbaron@3020 297 ''@import'', or ''@namespace'' rules) are also not allowed after a
dbaron@3020 298 conditional group rule. Therefore, style sheets <strong>must
dbaron@3019 299 not</strong> place such rules after a conditional group rules, and CSS
dbaron@3019 300 processors <strong>must</strong> ignore such rules.</p>
dbaron@2974 301
jackalmage@6617 302 <h2 id="at-media">Media-specific style sheets: the '@media' rule</h2>
dbaron@2974 303
dbaron@2983 304 <p>The <dfn>'@media' rule</dfn> is a conditional group rule whose
dbaron@2974 305 condition is a media query. It consists of the at-keyword
dbaron@2983 306 '@media' followed by a (possibly empty) media query (as
dbaron@2974 307 defined in [[!MEDIAQ]]), followed by a group rule body. The condition
dbaron@2974 308 of the rule is the result of the media query.</p>
dbaron@2974 309
dbaron@2974 310 <div class="example">
dbaron@2983 311 <p>This '@media' rule:</p>
dbaron@2974 312 <pre>@media print, (max-width: 600px) {
dbaron@2974 313 #extra_navigation { display: none }
dbaron@2974 314 }</pre>
dbaron@2983 315 <p>has the condition ''print, (max-width: 600px)'', which is
dbaron@2974 316 true for print media and for devices whose width is at most 600px. When
dbaron@2979 317 either of these is true, the condition of the rule is true, and the rule
dbaron@2983 318 ''#extra_navigation { display: none }'' is applied.
dbaron@2974 319 </div>
dbaron@2974 320
dbaron@2974 321 <p>In terms of the grammar, this specification extends the
dbaron@2974 322 <code>media</code> production in the
dbaron@2974 323 <a href="http://www.w3.org/TR/CSS21/grammar.html">Grammar of CSS 2.1</a>
dbaron@2974 324 ([[!CSS21]], Appendix G) into:
dbaron@2974 325 <pre>media
dbaron@6114 326 : MEDIA_SYM S* media_query_list group_rule_body
dbaron@2974 327 ;</pre>
dbaron@2974 328 <p>where the <code>group_rule_body</code> production is defined in this
dbaron@2974 329 specification, the <code>media_query_list</code> production is defined
dbaron@2974 330 in [[!MEDIAQ]], and the others are defined in the <a
dbaron@2974 331 href="http://www.w3.org/TR/CSS21/grammar.html">Grammar of CSS 2.1</a>
dbaron@2974 332 ([[!CSS21]], Appendix G).
dbaron@2974 333
jackalmage@6617 334 <h2 id="at-supports">Feature queries: the '@supports' rule</h2>
dbaron@2974 335
dbaron@2983 336 <p>The <dfn>'@supports' rule</dfn> is a conditional group
dbaron@2974 337 rule whose condition tests whether the user agent supports CSS
dbaron@2974 338 property:value pairs. Authors can use it to write style sheets that use
dbaron@2974 339 new features when available but degrade gracefully when those features
dbaron@2974 340 are not supported. CSS has existing mechanisms for graceful
dbaron@2974 341 degradation, such as ignoring unsupported properties or values, but
dbaron@2974 342 these are not always sufficient when large groups of styles need to be
dbaron@2974 343 tied to the support for certain features, as is the case for use of new
dbaron@2974 344 layout system features.</p>
dbaron@2974 345
dbaron@2983 346 <p>The syntax of the condition in the '@supports' rule is
dbaron@2974 347 slightly more complicated than for the other conditional group rules
dbaron@2974 348 (though has some similarities to media queries) since:</p>
dbaron@2974 349 <ul>
dbaron@2974 350 <li>negation is needed so that the new-feature styles and the fallback
dbaron@2974 351 styles can be separated (within the forward-compatible grammar's rules
dbaron@2974 352 for the syntax of @-rules), and not required to override each other</li>
dbaron@2974 353 <li>conjunction (and) is needed so that multiple required features can
dbaron@2974 354 be tested</li>
dbaron@2974 355 <li>disjunction (or) is needed when there are multiple alternative
dbaron@2974 356 features for a set of styles, particularly when some of those
dbaron@2974 357 alternatives are vendor-prefixed properties or values</li>
dbaron@2974 358 </ul>
dbaron@2974 359
dbaron@2983 360 <p>Therefore, the syntax of the '@supports' rule allows
dbaron@2974 361 testing for property:value pairs, and arbitrary conjunctions (and),
dbaron@2974 362 disjunctions (or), and negations (not) of them.</p>
dbaron@2974 363
dbaron@2974 364 <p>This extends the lexical scanner in the
dbaron@2974 365 <a href="http://www.w3.org/TR/CSS21/grammar.html">Grammar of CSS 2.1</a>
dbaron@2974 366 ([[!CSS21]], Appendix G) by adding:
dbaron@2974 367 <pre>@{S}{U}{P}{P}{O}{R}{T}{S} {return SUPPORTS_SYM;}</pre>
dbaron@2974 368 <p>and the grammar by adding</p>
jackalmage@6315 369 <pre><dfn>supports_rule</dfn>
dbaron@2974 370 : SUPPORTS_SYM S+ supports_condition group_rule_body
dbaron@2974 371 ;
dbaron@2974 372
jackalmage@6315 373 <dfn>supports_condition</dfn>
dbaron@2974 374 : supports_negation | supports_conjunction | supports_disjunction |
dbaron@3957 375 supports_condition_in_parens
dbaron@3957 376 ;
dbaron@3957 377
jackalmage@6315 378 <dfn>supports_condition_in_parens</dfn>
dbaron@3958 379 : ( '(' S* supports_condition ')' S* ) | supports_declaration_condition
dbaron@2974 380 ;
dbaron@2974 381
jackalmage@6315 382 <dfn>supports_negation</dfn>
dbaron@2974 383 : 'not' S* supports_condition_in_parens
dbaron@2974 384 ;
dbaron@2974 385
jackalmage@6315 386 <dfn>supports_conjunction</dfn>
dbaron@2974 387 : supports_condition_in_parens ( 'and' S* supports_condition_in_parens )+
dbaron@2974 388 ;
dbaron@2974 389
jackalmage@6315 390 <dfn>supports_disjunction</dfn>
dbaron@2974 391 : supports_condition_in_parens ( 'or' S* supports_condition_in_parens )+
dbaron@2974 392 ;
dbaron@2974 393
jackalmage@6315 394 <dfn>supports_declaration_condition</dfn>
dbaron@3024 395 : '(' S* core_declaration ')' S*
dbaron@2974 396 ;</pre>
dbaron@3024 397 <p>in which <code>core_declaration</code> is the production
dbaron@3024 398 <code>declaration</code> in the core syntax of CSS defined in <a
dbaron@3024 399 href="http://www.w3.org/TR/CSS21/syndata.html#tokenization">section
dbaron@3024 400 4.1.1 (Tokenization)</a> of [[!CSS21]].</p>
dbaron@3024 401
dbaron@3024 402 <p>Any ''@supports'' rule that does not parse according to the grammar
dbaron@3024 403 above is invalid. Style sheets <strong>must not</strong> use such a
dbaron@3024 404 rule and processors <strong>must</strong> ignore such a rule.</p>
dbaron@3024 405
dbaron@3024 406 <p class="note">Note that this means that declarations that meet the
dbaron@3024 407 forward-compatible syntax for declarations are permitted (and support
dbaron@3024 408 for them is then tested by the ''@supports'' rule), but declarations
dbaron@3024 409 that do not meet the forward-compatible syntax for declarations cause
dbaron@3024 410 the entire ''@supports'' rule to be ignored.</p>
dbaron@3024 411
dbaron@3024 412 <p class="issue">Is any further allowance for forward-compatible parsing
dbaron@3024 413 needed, for example, to allow additional features (such as, say,
dbaron@3024 414 selector tests) to be added to the ''@supports'' rule? Or are these
dbaron@3024 415 forward-compatible parsing rules the best solution for such future
dbaron@3024 416 expansion anyway?</p>
dbaron@2974 417
dbaron@3021 418 <p>Each of these grammar terms is associated with a boolean result, as
dbaron@3021 419 follows:</p>
dbaron@2974 420 <dl>
dbaron@2974 421 <dt>supports_condition</dt>
dbaron@2974 422 <dd>
dbaron@3021 423 The result is the result of the single child term.
dbaron@2974 424 </dd>
dbaron@2974 425
dbaron@3957 426 <dt>supports_condition_in_parens</dt>
dbaron@3957 427 <dd>
dbaron@3957 428 The result is the result of the single <code>supports_condition</code>
dbaron@3957 429 or <code>supports_declaration_condition</code> child term.
dbaron@3957 430 </dd>
dbaron@3957 431
dbaron@2974 432 <dt>supports_negation</dt>
dbaron@2974 433 <dd>
dbaron@3021 434 The result is the <em>negation</em> of the result of the
dbaron@3021 435 <code>supports_condition_in_parens</code> child term.
dbaron@2974 436 </dd>
dbaron@2974 437
dbaron@2974 438 <dt>supports_conjunction</dt>
dbaron@2974 439 <dd>
dbaron@3021 440 The result is true if the result of <em>all</em> of the
dbaron@3021 441 <code>supports_condition_in_parens</code> child terms is true;
dbaron@3021 442 otherwise it is false.
dbaron@2974 443 </dd>
dbaron@2974 444
dbaron@2974 445 <dt>supports_disjunction</dt>
dbaron@2974 446 <dd>
dbaron@3021 447 The result is true if the result of <em>any</em> of the
dbaron@3021 448 <code>supports_condition_in_parens</code> child terms is true;
dbaron@3021 449 otherwise it is false.
dbaron@2974 450 </dd>
dbaron@2974 451
dbaron@2974 452 <dt>supports_declaration_condition</dt>
dbaron@2974 453 <dd>
dbaron@3021 454 The result is whether the CSS processor <a
dbaron@3021 455 href="#support-definition">supports</a> the declaration.
dbaron@2974 456 </dd>
dbaron@2974 457 </dl>
dbaron@2974 458
dbaron@3021 459 <p>The condition of the '@supports' rule is the result of the
dbaron@3021 460 <code>supports_condition</code> term that is a child of the
dbaron@3021 461 <code>supports_rule</code> term.</p>
dbaron@2974 462
dbaron@2982 463 <div class="example">
dbaron@2982 464 <p>For example, the following rule</p>
dbaron@2982 465 <pre>@supports ( display: flexbox ) {
dbaron@2982 466 body, #navigation, #content { display: flexbox; }
dbaron@2982 467 #navigation { background: blue; color: white; }
dbaron@2982 468 #article { background: white; color: black; }
dbaron@2982 469 }</pre>
dbaron@2983 470 <p>applies the rules inside the '@supports' rule only when
dbaron@2983 471 ''display: flexbox'' is supported.</p>
dbaron@2982 472 </div>
dbaron@2974 473
dbaron@2982 474 <div class="example">
dbaron@2982 475 <p>The following example shows an additional '@supports' rule that can
dbaron@2982 476 be used to provide an alternative for when ''display: flexbox'' is not
dbaron@2982 477 supported:</p>
dbaron@2982 478 <pre>@supports not ( display: flexbox ) {
dbaron@2982 479 body { width: 100%; height: 100%; background: white; color: black; }
dbaron@2982 480 #navigation { width: 25%; }
dbaron@2982 481 #article { width: 75%; }
dbaron@2974 482 }</pre>
dbaron@2982 483 <p>Note that the 'width' declarations may be harmful to the
dbaron@2982 484 flexbox-based layout, so it is important that they be present only in
dbaron@2982 485 the non-flexbox styles.</p>
dbaron@2982 486 </div>
dbaron@2974 487
dbaron@2982 488 <div class="example">
dbaron@2982 489 <p>The following example checks for support for the 'box-shadow'
dbaron@2982 490 property, including checking for support for vendor-prefixed versions of
dbaron@2982 491 it. When the support is present, it specifies both 'box-shadow' (with
dbaron@2982 492 the prefixed versions) and 'color' in a way what would cause the text to
dbaron@2982 493 become invisible were 'box-shadow' not supported.</p>
dbaron@2982 494 <pre>@supports ( box-shadow: 2px 2px 2px black ) or
dbaron@2982 495 ( -moz-box-shadow: 2px 2px 2px black ) or
dbaron@2974 496 ( -webkit-box-shadow: 2px 2px 2px black ) or
dbaron@2974 497 ( -o-box-shadow: 2px 2px 2px black ) {
dbaron@2982 498 .outline {
dbaron@2982 499 color: white;
dbaron@2982 500 -moz-box-shadow: 2px 2px 2px black;
dbaron@2982 501 -webkit-box-shadow: 2px 2px 2px black;
dbaron@2982 502 -o-box-shadow: 2px 2px 2px black;
dbaron@3960 503 box-shadow: 2px 2px 2px black; /* unprefixed last */
dbaron@2982 504 }
dbaron@2982 505 }</pre></div>
dbaron@2974 506
dbaron@2984 507 <p>To avoid confusion between ''and'' and ''or'', the syntax requires
dbaron@2984 508 that both ''and'' and ''or'' be specified explicitly (rather than, say,
dbaron@2984 509 using commas or spaces for one of them). Likewise, to avoid confusion
dbaron@2984 510 caused by precedence rules, the syntax does not allow ''and'', ''or'',
dbaron@2984 511 and ''not'' operators to be mixed without a layer of parentheses.</p>
dbaron@2974 512
dbaron@2984 513 <div class="example">
dbaron@2984 514 <p>For example, the following rule is not valid:
dbaron@3959 515 <pre class="illegal">@supports (transition-property: color) or
dbaron@2984 516 (animation-name: foo) and
dbaron@2984 517 (transform: rotate(10deg)) {
dbaron@2984 518 // ...
dbaron@2984 519 }</pre>
dbaron@2984 520 <p>Instead, authors must write one of the following:</p>
dbaron@2984 521 <pre>@supports ((transition-property: color) or
dbaron@2984 522 (animation-name: foo)) and
dbaron@2984 523 (transform: rotate(10deg)) {
dbaron@2984 524 // ...
dbaron@2984 525 }</pre>
dbaron@2984 526 <pre>@supports (transition-property: color) or
dbaron@3430 527 ((animation-name: foo) and
dbaron@2984 528 (transform: rotate(10deg))) {
dbaron@2984 529 // ...
dbaron@2984 530 }</pre>
dbaron@2984 531 </div>
dbaron@2974 532
dbaron@3957 533 <p>The declaration being tested must always occur within parentheses,
dbaron@3957 534 when it is the only thing in the expression.<p>
dbaron@3957 535
dbaron@3957 536 <div class="example">
dbaron@3957 537 <p>For example, the following rule is not valid:
dbaron@3959 538 <pre class="illegal">@supports display: flexbox {
dbaron@3957 539 // ...
dbaron@3957 540 }</pre>
dbaron@3957 541 <p>Instead, authors must write:</p>
dbaron@3957 542 <pre>@supports (display: flexbox) {
dbaron@3957 543 // ...
dbaron@3957 544 }</pre>
dbaron@3957 545 </div>
dbaron@3957 546
dbaron@3957 547 <p>The syntax allows extra parentheses when they are not needed. This
dbaron@3957 548 flexibility is sometimes useful for authors (for example, when
dbaron@3957 549 commenting out parts of an expression) and may also be useful for
dbaron@3957 550 authoring tools.</p>
dbaron@3957 551
dbaron@3957 552 <div class="example">
dbaron@3957 553 <p>For example, authors may write:</p>
dbaron@3957 554 <pre>@supports ((display: flexbox)) {
dbaron@3957 555 // ...
dbaron@3957 556 }</pre>
dbaron@3957 557 </div>
dbaron@3957 558
dbaron@6306 559 <p class="issue">Add an example involving <code>!important</code>.</p>
dbaron@6306 560
jackalmage@6617 561 <h3 id="support-definition">Definition of support</h3>
dbaron@3021 562
jackalmage@6617 563 <p>A CSS processor is considered to <dfn id="dfn-support">support</dfn>
dbaron@3021 564 a declaration (consisting of a property and value) if it implements the
dbaron@3021 565 given value of the given property.</p>
dbaron@3021 566
jackalmage@6617 567 <h3 id="partial-implementations">Partial implementations</h3>
dbaron@3021 568
dbaron@3021 569 <p>For forward-compatibility, <a
dbaron@3021 570 href="http://www.w3.org/TR/CSS21/syndata.html#declaration">section 4.1.8
dbaron@3021 571 (Declarations and properties)</a> of [[!CSS21]] defines rules for
dbaron@3021 572 handling invalid properties and values. CSS processors that partially
dbaron@3021 573 implement a specification <strong>must</strong> treat any part of a
dbaron@3021 574 value that they:</p>
dbaron@3021 575 <ul>
dbaron@3021 576 <li>do not implement, or</li>
dbaron@3021 577 <li>do not have a usable level of support for,</li>
dbaron@3021 578 </ul>
dbaron@6252 579 <p>as invalid according to this rule
dbaron@6252 580 for handling invalid properties and values,
dbaron@6252 581 and <strong>must not</strong>
dbaron@3021 582 accept or support a declaration containing such a value. This allows
dbaron@3021 583 authors to use fallback (either in the [[CSS1]] sense of declarations
dbaron@3021 584 that are overridden by later declarations or with the new capabilities
dbaron@3021 585 provided by the ''@supports'' rule in this specification) that works
dbaron@3021 586 correctly for the features implemented. This applies especially to
dbaron@3021 587 compound values; implementations must implement all parts of the value
dbaron@3021 588 in order to consider the declaration supported, either inside a ruleset
dbaron@3021 589 or in the declaration condition of an ''@supports'' rule.</p>
dbaron@3021 590
jackalmage@6617 591 <h2 id="at-document">Document queries: the '@document' rule</h2>
dbaron@2974 592
dbaron@2983 593 <p>The <dfn>'@document' rule</dfn> is a conditional group
dbaron@3027 594 rule whose condition depends on the
dbaron@3027 595 <a href="#url-of-doc">URL of the document being styled</a>.
dbaron@2974 596 This allows style sheets, particularly user style sheets, to have styles
dbaron@2974 597 that only apply to a set of pages rather than to all pages using the
dbaron@2974 598 style sheet.</p>
dbaron@2974 599
dbaron@2974 600 <p class="issue">Given that this @-rule is intended primarily for user
dbaron@2974 601 style sheets, what should this specification say about its use in author
dbaron@2974 602 style sheets? Should it be forbidden? Should use instead be
dbaron@2974 603 discouraged? Or should this specification remain neutral on the
dbaron@2986 604 topic, since there are valid uses in author style sheets?</p>
dbaron@2974 605
jackalmage@6617 606 <p id="url-of-doc">The <dfn>URL of the document being styled</dfn> is
dbaron@3027 607 the URI at which the document is located, excluding any fragment
dbaron@3027 608 identifiers. (This means, for example, that HTTP redirects have been
dbaron@3027 609 followed.) If the styles are being applied inside a complete document
dbaron@3246 610 embedded into the presentation of another (e.g., [[HTML5]]&#39;s <code
dbaron@3027 611 class="html">iframe</code>, <code class="html">object</code>, or <code
dbaron@3027 612 class="html">img</code> elements), the relevant URI is that of the
dbaron@3027 613 frame, not of its container. However, if content from other documents
dbaron@3027 614 is mixed in via mechanisms that mix content from one document into
dbaron@3246 615 another (e.g., [[SVG11]]&#39;s <code>use</code> element), then the
dbaron@3027 616 address of the container document is used.</p>
dbaron@3027 617
dbaron@3027 618 <p class="note">Note: In [[HTML5]], this is the
dbaron@3027 619 <a href="http://dev.w3.org/html5/spec/dom.html#the-document-s-address">document's address</a>
dbaron@3027 620 of a document in a
dbaron@3027 621 <a href="http://dev.w3.org/html5/spec/browsers.html#browsing-context">browsing context</a>.</p>
dbaron@3027 622
dbaron@3240 623 <div class="issue">What form of normalization is done on URLs and domains
dbaron@3240 624 before matching? In particular, this specification needs to describe:
dbaron@3240 625 <ul>
dbaron@3240 626 <li>what form is used for the <a href="#url-of-doc">URL of the document
dbaron@3240 627 being styled</a> (and what has been normalized in that form)</li>
dbaron@3240 628 <li>what normalization (if any) happens to the argument of each of the match
dbaron@3240 629 functions before the comparison that they describe and</li>
dbaron@3240 630 <li>whether the
dbaron@3240 631 comparison algorithm used is string comparison or some other URL
dbaron@3240 632 comparison algorithm.</li></ul></div>
dbaron@3027 633
dbaron@2983 634 <p>The '@document' rule's condition is written as a
dbaron@2974 635 comma-separated list of <dfn>URL matching functions</dfn>, and the
dbaron@2974 636 condition evaluates to true whenever any one of those functions
dbaron@2974 637 evaluates to true. The following URL matching functions are
dbaron@2974 638 permitted:</p>
dbaron@2974 639
dbaron@2974 640 <dl>
jackalmage@6617 641 <dt><dfn id="url-exact" title="url()|URL matching functions::exact">&lt;url&gt;</dfn></dt>
dbaron@2974 642
dbaron@2974 643 <dd>
dbaron@2983 644 <p>The 'url()' function is the <dfn>exact url matching
dbaron@3027 645 function</dfn>. It evaluates to true whenever the <a
dbaron@3027 646 href="#url-of-doc">URL of the document being styled</a> is exactly
dbaron@3027 647 the URL given.</p>
dbaron@2974 648
dbaron@2983 649 <p class="Note">The 'url()' function, since it is a core syntax
dbaron@2974 650 element in CSS, is allowed (subject to different character
dbaron@2974 651 limitations and thus escaping requirements) to contain an unquoted
dbaron@2974 652 value (in addition to the string values that are allowed as
dbaron@2974 653 arguments for all four functions).</p>
dbaron@2974 654
dbaron@2974 655 <div class="example">
dbaron@2974 656 <p>For example, this rule:</p>
dbaron@2974 657 <pre>@document url("http://www.w3.org/Style/CSS/") {
dbaron@2974 658 #summary { background: yellow; color: black}
dbaron@2974 659 }</pre>
dbaron@2983 660 <p>styles the <code class="html">summary</code> element on the page
dbaron@2974 661 <code>http://www.w3.org/Style/CSS/</code>, but not on any other
dbaron@2974 662 pages.</p>
dbaron@2974 663 </div>
dbaron@2974 664 </dd>
dbaron@2974 665
jackalmage@6617 666 <dt><dfn id="url-prefix" title="url-prefix()|URL matching functions::prefix">url-prefix(&lt;string&gt;)</dfn></dt>
dbaron@2974 667
dbaron@2974 668 <dd>
dbaron@2983 669 <p>The 'url-prefix()' function is the <dfn>url prefix
dbaron@3027 670 matching function</dfn>. It evaluates to true whenever the
dbaron@3027 671 <a href="#url-of-doc">URL of the document being styled</a>
dbaron@3027 672 has the argument to the function as an
dbaron@2974 673 initial substring (which is true when the two strings are equal).
dbaron@2974 674 When the argument is the empty string, it evaluates to true for all
dbaron@2974 675 documents.</p>
dbaron@2974 676 <div class="example">
dbaron@2974 677 <p>For example, this rule:</p>
dbaron@2974 678 <pre>@document url-prefix("http://www.w3.org/Style/CSS/") {
dbaron@2974 679 #summary { background: yellow; color: black}
dbaron@2974 680 }</pre>
dbaron@2983 681 <p>styles the <code class="html">summary</code> element on the page
dbaron@2974 682 <code>http://www.w3.org/Style/CSS/</code> and on the page
dbaron@2974 683 <code>http://www.w3.org/Style/CSS/Test</code>, but it does not
dbaron@2974 684 affect the page <code>http://www.w3.org/</code> or the page
dbaron@2974 685 <code>http://www.example.com/Style/CSS/</code>.</p>
dbaron@2974 686 </div>
dbaron@2974 687 </dd>
dbaron@2974 688
jackalmage@6617 689 <dt><dfn id="url-domain" title="domain()|URL matching functions::domain">domain(&lt;string&gt;)</dfn></dt>
dbaron@2974 690
dbaron@2974 691 <dd>
dbaron@2983 692 <p>The 'domain()' function is the <dfn>domain
dbaron@2974 693 matching function</dfn>. It evaluates to true whenever
dbaron@3027 694 the <a href="#url-of-doc">URL of the document being styled</a>
dbaron@3027 695 has a host subcomponent (as defined in [[!URI]])
dbaron@2974 696 and that host subcomponent is exactly the argument to the
dbaron@2983 697 'domain()' function or a final substring of the host
dbaron@2974 698 component is a period (U+002E) immediately followed by the argument
dbaron@2983 699 to the 'domain()' function.</p>
dbaron@2974 700 <div class="example">
dbaron@2974 701 <p>For example, this rule:</p>
dbaron@2974 702 <pre>@document domain("w3.org") {
dbaron@2974 703 body { font-size: 16px ! important }
dbaron@2974 704 }</pre>
dbaron@2974 705 <p>changes the font size of the body element for pages such as
dbaron@2974 706 <code>http://www.w3.org/Style/CSS/</code> and
dbaron@2974 707 <code>http://w3.org/Style/CSS/</code> and
dbaron@2974 708 <code>http://lists.w3.org/Archives/Public/www-style/</code>
dbaron@2974 709 but it does not affect the page
dbaron@2974 710 <code>http://www.example.com/Style/CSS/</code>.</p>
dbaron@2974 711 </div>
dbaron@2974 712 </dd>
dbaron@2974 713
jackalmage@6617 714 <dt><dfn id="url-regexp" title="regexp()|URL matching functions::regular expression">regexp(&lt;string&gt;)</dfn></dt>
dbaron@2974 715
dbaron@2974 716 <dd>
dbaron@2986 717 <p>The contents of the &lt;string&gt; argument <strong>must</strong>
dbaron@3068 718 match the JavaScript <code>Pattern</code> production
dbaron@3068 719 ([[!ECMA-262-5.1]], section 15.10.1). However,
dbaron@2986 720 failing to do so is not a CSS syntax error and does not trigger any
dbaron@2986 721 error handling for CSS syntax errors.</p>
dbaron@2986 722
dbaron@2986 723 <p>The ''regexp()'' function evaluates to true whenever the string
dbaron@2986 724 argument compiled as a JavaScript regular expression with the
dbaron@2986 725 <code>global</code>, <code>ignoreCase</code> and
dbaron@2986 726 <code>multiline</code> flags <em>disabled</em>
dbaron@3068 727 (see [[!ECMA-262-5.1]], sections 15.10.7.2 through 15.10.7.4)
dbaron@2986 728 compiles successfully and the resulting regular expression matches
dbaron@3027 729 the entirety of the
dbaron@3027 730 <a href="#url-of-doc">URL of the document being styled</a>.</p>
dbaron@2986 731
dbaron@2986 732 <p class="note">Note that regular expression must match the entire
dbaron@2986 733 URL, not just a part of it.</p>
dbaron@2974 734
dbaron@3018 735 <p class="note">Note that this definition intentionally matches the
dbaron@3018 736 behavior of the <a
dbaron@2983 737 href="http://dev.w3.org/html5/spec/common-input-element-attributes.html#attr-input-pattern"><code class="html">pattern</code>
dbaron@2983 738 attribute</a> on the <code class="html">input</code> element
dbaron@2983 739 in [[HTML5]].</p>
dbaron@2986 740
dbaron@2986 741 <div class="example">
dbaron@2986 742 <p>For example, this rule:</p>
dbaron@2986 743 <pre>@document regexp("http://www.w3.org/TR/\\d{4}/[^/]*-CSS2-\\d{8}/") {
dbaron@2986 744 body { font-size: 20px ! important }
dbaron@2986 745 }</pre>
dbaron@2986 746 <p>changes the font size of the body element for pages such as
dbaron@2986 747 <code>http://www.w3.org/TR/2011/PR-CSS2-20110412/</code>.</p>
dbaron@2986 748 <p class="note">Note that the backslashes in the regular
dbaron@2986 749 expression require CSS escaping as ''\\''.</p>
dbaron@2986 750 </div>
dbaron@2974 751 </dd>
dbaron@2974 752
dbaron@2974 753 </dl>
dbaron@2974 754
dbaron@2979 755 <p>Implementations <strong>must</strong> treat any unknown URL matching
dbaron@3045 756 functions as a syntax error, and thus ignore the '@document' rule.
dbaron@3045 757 <span class="issue">Should we instead have more complicated error
dbaron@3045 758 handling rules to make forward-compatibility work differently, or is
dbaron@3045 759 this rule the best solution for such future expansion anyway?</span></p>
dbaron@2974 760
dbaron@5293 761 <div class="issue">This syntax doesn't offer any ability to do negations,
dbaron@5293 762 which has been requested in <a
jackalmage@6617 763 href="https://bugzilla.mozilla.org/show_bug.cgi?id=349813">Mozilla bug
dbaron@5293 764 349813</a>. Use cases that people have wanted negations for
dbaron@5293 765 include:
dbaron@5293 766 <ul>
dbaron@5293 767 <li>User style sheets that want a particular rule in general, but know
dbaron@5293 768 that that rule does more harm than good on specific sites.</li>
dbaron@5293 769 <li>Authors who have a rule that they want to apply to most of their
dbaron@5293 770 pages, but wish to make a few exceptions for.</li>
dbaron@5293 771 </ul>
dbaron@5293 772 </div>
dbaron@5293 773
dbaron@2974 774 <p>This extends the lexical scanner in the
dbaron@2974 775 <a href="http://www.w3.org/TR/CSS21/grammar.html">Grammar of CSS 2.1</a>
dbaron@2974 776 ([[!CSS21]], Appendix G) by adding:
dbaron@2974 777 <pre>@{D}{O}{C}{U}{M}{E}{N}{T} {return DOCUMENT_SYM;}</pre>
dbaron@2974 778 <p>and the grammar by adding</p>
dbaron@2974 779 <pre>document_rule
dbaron@2974 780 : DOCUMENT_SYM S+ url_match_fn ( "," S* url_match_fn )* group_rule_body
dbaron@2974 781 ;
dbaron@2974 782
dbaron@2974 783 url_match_fn
dbaron@3028 784 : (URI | FUNCTION) S*
dbaron@2974 785 ;</pre>
dbaron@2974 786
jackalmage@6617 787 <h2 id="apis">APIs</h2>
dbaron@3416 788
jackalmage@6617 789 <h3 id='extentions-to-cssrule-interface'>
jackalmage@6315 790 Extensions to the <code>CSSRule</code> interface</h3>
dbaron@3416 791
jackalmage@6315 792 <p>The <code>CSSRule</code> interface is extended as follows:
jackalmage@6315 793
jackalmage@6315 794 <pre class='idl'>partial interface CSSRule {
jackalmage@6315 795 const unsigned short SUPPORTS_RULE = 12;
jackalmage@6315 796 const unsigned short DOCUMENT_RULE = 13;
jackalmage@6315 797 }</pre>
jackalmage@6315 798
jackalmage@6315 799
jackalmage@6655 800 <h3 id='the-cssgroupingrule-interface'>
jackalmage@6655 801 The <code>CSSGroupingRule</code> interface</h3>
jackalmage@6655 802
jackalmage@6655 803 <p>The <dfn><code>CSSGroupingRule</code></dfn> interface represents an at-rule that contains other rules nested inside itself.
jackalmage@6655 804
jackalmage@6655 805 <pre class='idl'>interface CSSGroupingRule : CSSRule {
jackalmage@6655 806 readonly attribute CSSRuleList cssRules;
jackalmage@6655 807 unsigned long insertRule (DOMString rule, unsigned long index);
jackalmage@6655 808 void deleteRule (unsigned long index);
jackalmage@6655 809 }</pre>
jackalmage@6655 810
jackalmage@6655 811 <dl class='idl-attributes'>
jackalmage@6655 812 <dt><code>cssRules</code> of type <code>CSSRuleList</code>, readonly
jackalmage@6655 813 <dd>The <code>cssRules</code> attribute must return a <code>CSSRuleList</code>
jackalmage@6655 814 object for the list of CSS rules nested inside the grouping rule.
jackalmage@6655 815 </dl>
jackalmage@6655 816
jackalmage@6655 817 <dl class='idl-methods'>
jackalmage@6655 818 <dt><code>insertRule(DOMString rule, unsigned long index)</code>, returns
jackalmage@6655 819 <code>unsigned long</code>
jackalmage@6655 820 <dd>The <code>insertRule</code> operation must insert a CSS rule <var>rule</var>
jackalmage@6655 821 into the CSS rule list returned by <code>cssRules</code> at <var>index</var>.
jackalmage@6655 822
jackalmage@6655 823 <dt><code>deleteRule (unsigned long index)</code>, return <code>void</code>
jackalmage@6655 824 <dd>The <code>deleteRule</code> operation must remove a CSS rule from the
jackalmage@6655 825 CSS rule list returned by <code>cssRules</code> at <var>index</var>.
jackalmage@6655 826 </dl>
jackalmage@6655 827
jackalmage@6655 828
jackalmage@6618 829 <h3 id="the-cssconditionrule-interface">
jackalmage@6618 830 The <code>CSSConditionRule</code> interface</h3>
jackalmage@6315 831
jackalmage@6620 832 <p>The <dfn><code>CSSConditionRule</code></dfn> interface represents all the "conditional" at-rules,
jackalmage@6620 833 which consist of a condition and a statement block.
dbaron@6323 834
jackalmage@6655 835 <pre class='idl'>interface CSSConditionRule : CSSGroupingRule {
dbaron@6324 836 attribute DOMString conditionText;
jackalmage@6315 837 }</pre>
jackalmage@6315 838
jackalmage@6315 839 <dl class='idl-attributes'>
jackalmage@6619 840 <dt><code>conditionText</code> of type <code>DOMString</code>
dbaron@6325 841 <dd>The <code>conditionText</code> attribute, on getting, must return
jackalmage@6618 842 the result of serializing the associated condition.
jackalmage@6315 843
dbaron@6324 844 <p>On setting the <code>conditionText</code> attribute these steps
jackalmage@6315 845 must be run:
jackalmage@6315 846
jackalmage@6315 847 <ol>
jackalmage@6315 848 <li>Trim the given value of white space.
jackalmage@6315 849 <li>If the given value matches the grammar of the
jackalmage@6618 850 appropriate condition production for the given rule,
jackalmage@6618 851 replace the associated CSS condition with the given value.
jackalmage@6315 852 <li>Otherwise, do nothing.
jackalmage@6315 853 </ol>
jackalmage@6315 854 </dl>
jackalmage@6315 855
jackalmage@6618 856
jackalmage@6618 857 <h3 id="the-cssmediarule-interface">
jackalmage@6618 858 The <code>CSSMediaRule</code> interface</h3>
jackalmage@6618 859
jackalmage@6618 860 <p>The <dfn><code>CSSMediaRule</code></dfn> interface represents a ''@media'' rule:
jackalmage@6618 861
jackalmage@6618 862 <pre class='idl'>interface CSSMediaRule : CSSConditionRule {
jackalmage@6618 863 readonly attribute MediaList media;
jackalmage@6618 864 }</pre>
jackalmage@6618 865
jackalmage@6618 866 <dl class='idl-attributes'>
jackalmage@6618 867 <dt><code>media</code> of type <code>MediaList</code>, readonly
jackalmage@6618 868 <dd>The <code>media</code> attribute must return a <code>MediaList</code> object
jackalmage@6618 869 for the list of media queries specified with the ''@media'' rule.
jackalmage@6618 870
jackalmage@6619 871 <dt><code>conditionText</code> of type <code>DOMString</code>
jackalmage@6618 872 <dd>The <code>conditionText</code> attribute (defined on the <code>CSSConditionRule</code> parent rule),
jackalmage@6618 873 on getting, must return the value of <code>media.mediaText</code> on the rule.
jackalmage@6618 874
jackalmage@6621 875 <p>Setting the <code>conditionText</code> attribute
jackalmage@6621 876 must set the <code>media.mediaText</code> attribute on the rule.
jackalmage@6621 877 </dl>
jackalmage@6618 878
jackalmage@6618 879
jackalmage@6618 880 <h3 id="the-csssupportsrule-interface">
jackalmage@6618 881 The <code>CSSSupportsRule</code> interface</h3>
jackalmage@6618 882
jackalmage@6618 883 <p>The <dfn><code>CSSSupportsRule</code></dfn> interface represents a ''@supports'' rule.</p>
jackalmage@6618 884
jackalmage@6621 885 <pre class='idl'>interface CSSSupportsRule : CSSConditionRule {
jackalmage@6618 886 }</pre>
jackalmage@6618 887
jackalmage@6618 888
jackalmage@6618 889 <h3 id="the-cssdocumentrule-interface">
jackalmage@6618 890 The <code>CSSDocumentRule</code> interface</h3>
jackalmage@6618 891
jackalmage@6618 892 <p>The <dfn><code>CSSDocumentRule</code></dfn> interface represents a ''@document'' rule.</p>
jackalmage@6618 893
jackalmage@6621 894 <pre class='idl'>interface CSSDocumentRule : CSSConditionRule {
jackalmage@6618 895 }</pre>
jackalmage@6315 896
jackalmage@6315 897
jackalmage@6620 898 <h3 id='the-css-interface'>
jackalmage@6620 899 The <code>CSS</code> interface, and the <code title=''>supports()</code> function</h3>
jackalmage@6315 900
jackalmage@6620 901 <p>The <dfn id='CSS-interface'><code>CSS</code></dfn> interface holds useful CSS-related functions that do not belong elsewhere.
jackalmage@6315 902
jackalmage@6620 903 <pre class='idl'>interface CSS {
jackalmage@6620 904 boolean supports(DOMString property, DOMString value);
jackalmage@6620 905 boolean supports(DOMString declaration);
jackalmage@6620 906 }</pre>
jackalmage@6620 907
jackalmage@6620 908 <dl class='idl-methods'>
jackalmage@6620 909 <dt><code>supports(DOMString property, DOMString value)</code>,
jackalmage@6620 910 returns <code>boolean</code>
jackalmage@6625 911 <dt><code>supports(DOMString conditionText)</code>,
jackalmage@6620 912 returns <code>boolean</code>
jackalmage@6620 913 <dd>
jackalmage@6620 914 When the <code title=''>supports()</code> method is invoked with two arguments <var>property</var> and <var>value</var>,
jackalmage@6620 915 it must return <code>true</code> if <var>property</var> is a literal match for the name of a CSS property that the UA supports,
jackalmage@6620 916 and <var>value</var> would be successfully parsed as a supported value for that property.
jackalmage@6620 917 Otherwise, it must return <code>false</code>.
jackalmage@6620 918
jackalmage@6620 919 <p>
jackalmage@6625 920 When invoked with a single <var>conditionText</var> argument,
jackalmage@6625 921 it must return <code>true</code> if <var>conditionText</var>,
jackalmage@6625 922 when parsed and evaluated as a <code>supports_condition</code>,
jackalmage@6625 923 would return true.
jackalmage@6620 924 Otherwise, it must return <code>false</code>.
jackalmage@6620 925 </dl>
jackalmage@6620 926
dbaron@3417 927
jackalmage@6617 928 <h2 id="conformance">Conformance</h2>
dbaron@2974 929
jackalmage@6617 930 <h3 id="base-modules">Base Modules</h3>
dbaron@3022 931
dbaron@3022 932 <p>This specification defines conformance in terms of base modules,
dbaron@3022 933 which are modules that this specification builds on top of. The base
dbaron@3022 934 modules of this module are:</p>
dbaron@3022 935
dbaron@3022 936 <ul>
dbaron@3022 937 <li>[[!CSS21]]</li>
dbaron@3022 938 </ul>
dbaron@3022 939
dbaron@3022 940 <p>All of the conformance requirements of all base modules are
dbaron@3022 941 incorporated as conformance requirements of this module, except where
dbaron@3022 942 overridden by this module.</p>
dbaron@3022 943
dbaron@3022 944 <p>Additionally, all conformance requirements related to validity of
dbaron@3022 945 syntax in this module and all of its base modules are to be interpreted
dbaron@3022 946 as though all syntax in all of those modules is valid.</p>
dbaron@3022 947
dbaron@3022 948 <div class="example"><p>For example, this means that grammar presented
dbaron@3022 949 in modules other than [[!CSS21]] must obey the requirements that
dbaron@3022 950 [[!CSS21]] defines for the parsing of properties, and that requirements
dbaron@3022 951 for handling invalid syntax in [[!CSS21]] do not treat syntax added by
dbaron@3022 952 other modules as invalid.</p></div>
dbaron@3022 953
dbaron@3022 954 <p>Additionally, the set of valid syntax can be increased by the
dbaron@3022 955 conformance of a style sheet or processor to additional modules; use of
dbaron@3022 956 such syntax does not make a style sheet nonconformant and failure to
dbaron@3022 957 treat such syntax as invalid does not make a processor
dbaron@3022 958 nonconformant.</p>
dbaron@3022 959
jackalmage@6617 960 <h3 id="conformance-classes">Conformance Classes</h3>
dbaron@2974 961
dbaron@2974 962 <p>Conformance to the CSS Conditional Rules Module is defined for three
dbaron@2974 963 conformance classes:
dbaron@2974 964 <dl>
jackalmage@6617 965 <dt><dfn title="conformance::style sheet" id="conform-style-sheet">style sheet</dfn>
dbaron@2974 966 <dd>A <a href="http://www.w3.org/TR/CSS21/conform.html#style-sheet">CSS
dbaron@3022 967 style sheet</a>.</dd>
jackalmage@6617 968 <dt><dfn title="conformance::processor" id="conform-processor">processor</dfn></dt>
dbaron@3022 969 <dd>A tool that reads CSS style sheets: it may be a renderer or
dbaron@3022 970 <a
dbaron@3022 971 href="http://www.w3.org/TR/CSS21/conform.html#user-agent">user-agent</a>
dbaron@2974 972 that interprets the semantics of a style sheet and renders
dbaron@3022 973 documents that use style sheets, or it may be a validator that
dbaron@3022 974 checks style sheets.</dd>
jackalmage@6617 975 <dt><dfn title="conformance::authoring tool" id="conform-authoring-tool">authoring tool</dfn></dt>
dbaron@3022 976 <dd>A tool that writes a style sheet.</dd>
dbaron@2974 977 </dl>
dbaron@3022 978
dbaron@3022 979 <p>A style sheet is conformant to the CSS Conditional Rules Module
dbaron@3022 980 if it meets all of the conformance requirements in the module that are
dbaron@3022 981 described as requirements of style sheets.</p>
dbaron@3022 982
dbaron@3022 983 <p>A processor is conformant to the CSS Conditional Rules Module if it
dbaron@3022 984 meets all applicable conformance requirements in the module that are
dbaron@3022 985 described as requirements of processors. In general, all requirements
dbaron@3022 986 are applicable to renderers. Requirements concerning a part of CSS
dbaron@3022 987 not performed by a processor are not applicable, e.g., requirements
dbaron@3022 988 related to rendering are not applicable to a validator. The inability
dbaron@3022 989 of a processor to correctly render a document due to limitations of
dbaron@3022 990 the device does not make it non-conformant. (For example, a renderer
dbaron@3022 991 is not required to render color on a monochrome monitor.)</p>
dbaron@3022 992
dbaron@3022 993 <p>An authoring tool is conformant to the CSS Conditional Rules Module
dbaron@3022 994 if it writes style sheets that conform to the module and (if it reads
dbaron@3022 995 CSS) it is a conformant processor.</p>
dbaron@2974 996
jackalmage@6617 997 <h3 id="partial">
dbaron@2974 998 Partial Implementations</h3>
dbaron@2974 999
dbaron@2974 1000 <p>So that authors can exploit the forward-compatible parsing rules to
dbaron@2974 1001 assign fallback values, CSS renderers <strong>must</strong>
dbaron@2974 1002 treat as invalid (and <a href="http://www.w3.org/TR/CSS21/conform.html#ignore">ignore
dbaron@2974 1003 as appropriate</a>) any at-rules, properties, property values, keywords,
dbaron@2974 1004 and other syntactic constructs for which they have no usable level of
dbaron@2974 1005 support. In particular, user agents <strong>must not</strong> selectively
dbaron@2974 1006 ignore unsupported component values and honor supported values in a single
dbaron@2974 1007 multi-value property declaration: if any value is considered invalid
dbaron@2974 1008 (as unsupported values must be), CSS requires that the entire declaration
dbaron@2974 1009 be ignored.</p>
dbaron@2974 1010
jackalmage@6617 1011 <h3 id="experimental">Experimental Implementations</h3>
dbaron@2974 1012
dbaron@2974 1013 <p>To avoid clashes with future CSS features, the CSS specifications
dbaron@2974 1014 reserve a <a href="http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords">prefixed
dbaron@2974 1015 syntax</a> for proprietary property and value extensions to CSS. The CSS
dbaron@2974 1016 Working Group recommends that experimental implementations of features in
dbaron@2974 1017 CSS Working Drafts also use vendor-prefixed property or value names. This
dbaron@2974 1018 avoids any incompatibilities with future changes in the draft. Once a
dbaron@2974 1019 specification reaches the Candidate Recommendation stage, implementors
dbaron@2974 1020 should implement the non-prefixed syntax for any feature they consider to
dbaron@2974 1021 be correctly implemented according to spec.</p>
dbaron@2974 1022
jackalmage@6617 1023 <h3 id="cr-exit-criteria">CR Exit Criteria</h3>
dbaron@2974 1024
dbaron@3244 1025 <p>For this specification to be advanced to Proposed Recommendation,
dbaron@2974 1026 there must be at least two independent, interoperable implementations
dbaron@2974 1027 of each feature. Each feature may be implemented by a different set of
dbaron@2974 1028 products, there is no requirement that all features be implemented by
dbaron@2974 1029 a single product. For the purposes of this criterion, we define the
dbaron@2974 1030 following terms:
dbaron@2974 1031
dbaron@2974 1032 <dl>
dbaron@2974 1033 <dt>independent <dd>each implementation must be developed by a
dbaron@2974 1034 different party and cannot share, reuse, or derive from code
dbaron@2974 1035 used by another qualifying implementation. Sections of code that
dbaron@2974 1036 have no bearing on the implementation of this specification are
dbaron@2974 1037 exempt from this requirement.
dbaron@2974 1038
dbaron@2974 1039 <dt>interoperable <dd>passing the respective test case(s) in the
dbaron@2974 1040 official CSS test suite, or, if the implementation is not a Web
dbaron@2974 1041 browser, an equivalent test. Every relevant test in the test
dbaron@2974 1042 suite should have an equivalent test created if such a user
dbaron@2974 1043 agent (UA) is to be used to claim interoperability. In addition
dbaron@2974 1044 if such a UA is to be used to claim interoperability, then there
dbaron@2974 1045 must one or more additional UAs which can also pass those
dbaron@2974 1046 equivalent tests in the same way for the purpose of
dbaron@2974 1047 interoperability. The equivalent tests must be made publicly
dbaron@2974 1048 available for the purposes of peer review.
dbaron@2974 1049
dbaron@2974 1050 <dt>implementation <dd>a user agent which:
dbaron@2974 1051
dbaron@2974 1052 <ol class=inline>
dbaron@2974 1053 <li>implements the specification.
dbaron@2974 1054
dbaron@2974 1055 <li>is available to the general public. The implementation may
dbaron@2974 1056 be a shipping product or other publicly available version
dbaron@2974 1057 (i.e., beta version, preview release, or “nightly build”).
dbaron@2974 1058 Non-shipping product releases must have implemented the
dbaron@2974 1059 feature(s) for a period of at least one month in order to
dbaron@2974 1060 demonstrate stability.
dbaron@2974 1061
dbaron@2974 1062 <li>is not experimental (i.e., a version specifically designed
dbaron@2974 1063 to pass the test suite and is not intended for normal usage
dbaron@2974 1064 going forward).
dbaron@2974 1065 </ol>
dbaron@2974 1066 </dl>
dbaron@2974 1067
dbaron@2974 1068 <p>The specification will remain Candidate Recommendation for at least
dbaron@2974 1069 six months.
dbaron@2974 1070
jackalmage@6617 1071 <h2 class=no-num id="grammar">Grammar</h2>
dbaron@2974 1072
dbaron@2974 1073 <p>In order to allow these new @-rules in CSS style sheets, this
dbaron@2974 1074 specification modifies the <code>stylesheet</code> production in the <a
dbaron@2974 1075 href="http://www.w3.org/TR/CSS21/grammar.html">Appendix G</a> grammar of
dbaron@2974 1076 [[!CSS21]] by replacing the <code>media</code> production defined in
dbaron@2974 1077 [[!CSS21]] with the <code>media</code> production defined in this one,
dbaron@2974 1078 and additionally inserting <code>| supports_rule | document_rule</code>
dbaron@2974 1079 alongside <code>ruleset | media | page</code>.</p>
dbaron@2974 1080
jackalmage@6617 1081 <h2 class=no-num id="acknowledgments">Acknowledgments</h2>
dbaron@2974 1082
dbaron@2974 1083 <p>
dbaron@2974 1084 Thanks to the ideas and feedback from
dbaron@3418 1085 Tab Atkins,
dbaron@2974 1086 <span lang="tr">Tantek Çelik</span>,
dbaron@3418 1087 Alex Danilo,
dbaron@2974 1088 Elika Etemad,
dbaron@2974 1089 Pascal Germroth,
dbaron@2974 1090 <span lang="de">Björn Höhrmann</span>,
dbaron@3417 1091 Paul Irish,
dbaron@3418 1092 Vitor Menezes,
dbaron@2977 1093 Alex Mogilevsky,
dbaron@2974 1094 Chris Moschini,
dbaron@2974 1095 Ben Ward,
dbaron@2974 1096 Zack Weinberg,
dbaron@3430 1097 Estelle Weyl,
dbaron@2974 1098 Boris Zbarsky,
dbaron@2974 1099 and all the rest of the <a href="http://lists.w3.org/Archives/Public/www-style/">www-style</a> community.
dbaron@2974 1100
dbaron@2974 1101 </p>
dbaron@2974 1102
jackalmage@6617 1103 <h2 class=no-num id="references">References</h2>
dbaron@2974 1104
dbaron@2974 1105
jackalmage@6617 1106 <h3 class="no-num" id="normative-references">Normative references</h3>
dbaron@2974 1107 <!--normative-->
dbaron@2974 1108
jackalmage@6617 1109 <h3 class="no-num" id="other-references">Other references</h3>
dbaron@2974 1110 <!--informative-->
dbaron@2974 1111
jackalmage@6617 1112 <h2 class="no-num" id="index">Index</h2>
dbaron@2974 1113 <!--index-->
dbaron@2974 1114
dbaron@2974 1115 </body>
dbaron@2974 1116 </html>
dbaron@2974 1117 <!-- Keep this comment at the end of the file
dbaron@2974 1118 Local variables:
dbaron@2974 1119 mode: sgml
dbaron@2974 1120 sgml-declaration:"~/SGML/HTML4.decl"
dbaron@2974 1121 sgml-default-doctype-name:"html"
dbaron@2974 1122 sgml-minimize-attributes:t
dbaron@2974 1123 sgml-nofill-elements:("pre" "style" "br")
dbaron@2974 1124 sgml-live-element-indicator:t
dbaron@2974 1125 sgml-omittag:nil
dbaron@2974 1126 sgml-shorttag:nil
dbaron@2974 1127 sgml-namecase-general:t
dbaron@2974 1128 sgml-general-insert-case:lower
dbaron@2974 1129 sgml-always-quote-attributes:t
dbaron@2974 1130 sgml-indent-step:nil
dbaron@2974 1131 sgml-indent-data:t
dbaron@2974 1132 sgml-parent-document:nil
dbaron@2974 1133 sgml-exposed-tags:nil
dbaron@2974 1134 sgml-local-catalogs:nil
dbaron@2974 1135 sgml-local-ecat-files:nil
dbaron@2974 1136 End:
dbaron@2974 1137 -->
dbaron@2974 1138

mercurial