css3-conditional/Overview.html@34b185ae3bac
css3-conditional/Overview.html
Wed, 06 Feb 2013 13:40:30 -0700
- author
- L. David Baron <dbaron@dbaron.org>
- date
- Wed, 06 Feb 2013 13:40:30 -0700
- changeset 7374
- 34b185ae3bac
- parent 7373
- ab8be4484fdb
- child 7381
- 06244e910e27
- permissions
- -rw-r--r--
[css3-conditional] Require whitespace around 'and' and 'or' and after 'not'.
Resolves last call issue 2.
As resolved in http://lists.w3.org/Archives/Public/www-style/2012Dec/0330.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
4 <html lang=en>
5 <head
6 profile="http://dublincore.org/documents/2008/08/04/dc-html/ http://www.w3.org/2006/03/hcard">
7 <meta content="text/html; charset=utf-8" http-equiv=Content-Type>
8 <title>CSS Conditional Rules Module Level 3</title>
10 <link href="http://purl.org/dc/terms/" rel=schema.dcterms>
11 <link href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright"
12 rel=dcterms.rights>
13 <meta content="CSS Conditional Rules Module Level 3" name=dcterms.title>
14 <meta content=text name=dcterms.type>
15 <meta content=2013-02-06 name=dcterms.issued>
16 <meta content="http://dev.w3.org/csswg/css3-conditional/"
17 name=dcterms.creator>
18 <meta content=W3C name=dcterms.publisher>
19 <meta content="http://www.w3.org/TR/2013/ED-css3-conditional-20130206/"
20 name=dcterms.identifier>
21 <link href="../default.css" rel=stylesheet type="text/css">
22 <link href="../csslogo.ico" rel="shortcut icon" type="image/x-icon">
23 <link href="http://www.w3.org/StyleSheets/TR/W3C-ED.css" rel=stylesheet
24 type="text/css"><!--
25 <script src="http://test.csswg.org/harness/annotate.js#CSS3-CONDITIONAL_DEV"
26 type="text/javascript" defer></script
27 -->
29 <body>
30 <div class=head> <!--begin-logo-->
31 <p><a href="http://www.w3.org/"><img alt=W3C height=48
32 src="http://www.w3.org/Icons/w3c_home" width=72></a> <!--end-logo-->
34 <h1>CSS Conditional Rules Module Level 3</h1>
36 <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 6 February
37 2013</h2>
39 <dl>
40 <dt>This version:
42 <dd><a href="http://www.w3.org/TR/2013/ED-css3-conditional-20130206/">
43 http://www.w3.org/TR/2013/ED-css3-conditional-20130206/</a>
45 <dt>Latest version:
47 <dd><a
48 href="http://www.w3.org/TR/css3-conditional/">http://www.w3.org/TR/css3-conditional/</a>
50 <dt>Editor's draft:
52 <dd><a
53 href="http://dev.w3.org/csswg/css3-conditional/">http://dev.w3.org/csswg/css3-conditional/</a>
55 <dt>Previous version:
57 <dd><a
58 href="http://www.w3.org/TR/2012/WD-css3-conditional-20120911/">http://www.w3.org/TR/2012/WD-css3-conditional-20120911/</a>
60 <dt>Editors:
62 <dd class=vcard><a class=fn href="http://dbaron.org/">L. David Baron</a>,
63 <a class=org href="http://www.mozilla.org/">Mozilla</a>
65 <dt>Issues list:
67 <dd>Maintained in document (only editor's draft is current)
69 <dt>Feedback:
71 <dd><a
72 href="http://lists.w3.org/Archives/Public/www-style/">www-style@w3.org</a>
73 with subject line “<kbd>[css3-conditional] <var>… message topic
74 …</var></kbd>”
76 <dt>Test suite:
78 <dd><a
79 href="https://test.csswg.org/shepherd/search/spec/css3-conditional/">submitted
80 tests</a>; no built test suite yet
81 </dl>
82 <!--begin-copyright-->
83 <p class=copyright><a
84 href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright"
85 rel=license>Copyright</a> © 2013 <a href="http://www.w3.org/"><abbr
86 title="World Wide Web Consortium">W3C</abbr></a><sup>®</sup> (<a
87 href="http://www.csail.mit.edu/"><abbr
88 title="Massachusetts Institute of Technology">MIT</abbr></a>, <a
89 href="http://www.ercim.eu/"><abbr
90 title="European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>,
91 <a href="http://www.keio.ac.jp/">Keio</a>, <a
92 href="http://ev.buaa.edu.cn/">Beihang</a>), All Rights Reserved. W3C <a
93 href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
94 <a
95 href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a>
96 and <a
97 href="http://www.w3.org/Consortium/Legal/copyright-documents">document
98 use</a> rules apply.</p>
99 <!--end-copyright-->
100 <hr title="Separator for header">
101 </div>
103 <h2 class="no-num no-toc" id=abstract>Abstract</h2>
105 <p>CSS is a language for describing the rendering of structured documents
106 (such as HTML and XML) on screen, on paper, in speech, etc. This module
107 contains the features of CSS for conditional processing of parts of style
108 sheets, conditioned on capabilities of the processor or the document the
109 style sheet is being applied to. It includes and extends the functionality
110 of CSS level 2 <a href="#CSS21"
111 rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>, which builds on CSS level 1
112 <a href="#CSS1" rel=biblioentry>[CSS1]<!--{{CSS1}}--></a>. The main
113 extensions compared to level 2 are allowing nesting of certain at-rules
114 inside ‘<code class=css>@media</code>’, and the addition of the
115 ‘<code class=css>@supports</code>’ rule for conditional processing.
117 <h2 class="no-num no-toc" id=status>Status of this document</h2>
118 <!--begin-status-->
120 <p>This is a public copy of the editors' draft. It is provided for
121 discussion only and may change at any moment. Its publication here does
122 not imply endorsement of its contents by W3C. Don't cite this document
123 other than as work in progress.
125 <p>The (<a
126 href="http://lists.w3.org/Archives/Public/www-style/">archived</a>) public
127 mailing list <a
128 href="mailto:www-style@w3.org?Subject=%5Bcss3-conditional%5D%20PUT%20SUBJECT%20HERE">
129 www-style@w3.org</a> (see <a
130 href="http://www.w3.org/Mail/Request">instructions</a>) is preferred for
131 discussion of this specification. When sending e-mail, please put the text
132 “css3-conditional” in the subject, preferably like this:
133 “[<!---->css3-conditional<!---->] <em>…summary of comment…</em>”
135 <p>This document was produced by the <a href="/Style/CSS/members">CSS
136 Working Group</a> (part of the <a href="/Style/">Style Activity</a>).
138 <p>This document was produced by a group operating under the <a
139 href="/Consortium/Patent-Policy-20040205/">5 February 2004 W3C Patent
140 Policy</a>. W3C maintains a <a href="/2004/01/pp-impl/32061/status"
141 rel=disclosure>public list of any patent disclosures</a> made in
142 connection with the deliverables of the group; that page also includes
143 instructions for disclosing a patent. An individual who has actual
144 knowledge of a patent which the individual believes contains <a
145 href="/Consortium/Patent-Policy-20040205/#def-essential">Essential
146 Claim(s)</a> must disclose the information in accordance with <a
147 href="/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the
148 W3C Patent Policy</a>.</p>
149 <!--end-status-->
151 <p>The following features are at risk:
153 <ul>
154 <li>The inclusion of ‘<code class=css>@font-face</code>’ rules and
155 ‘<code class=css>@keyframes</code>’ rules as allowed within all of
156 the @-rules in this specification is at risk, though only because of the
157 relative rates of advancement of specifications. If this specification is
158 able to advance faster than one or both of the specifications defining
159 those rules, then the inclusion of those rules will move from this
160 specification to the specification defining those rules.
162 <li>The addition of support for @-rules inside of conditional grouping
163 rules is at risk; if interoperable implementations are not found, it may
164 be removed to advance the other features in this specification to
165 Proposed Recommendation.
167 <li>The ‘<code class=css>@supports</code>’ rule is at risk; if
168 interoperable implementations are not found, it may be removed to advance
169 the other features in this specification to Proposed Recommendation.
170 </ul>
172 <p>This is a <strong>Last Call Working Draft</strong>. The deadline for
173 comments is <strong>10 January 2013</strong>. <!--
175 Things to go in level 4:
177 * Create some way to put these new conditional things on an @import.
178 * The @document rule (commented out, down below).
180 -->
182 <h2 class="no-num no-toc" id=contents>Table of contents</h2>
183 <!--begin-toc-->
185 <ul class=toc>
186 <li><a href="#introduction"><span class=secno>1. </span>Introduction</a>
187 <ul class=toc>
188 <li><a href="#context"><span class=secno>1.1. </span>Background</a>
190 <li><a href="#placement"><span class=secno>1.2. </span>Module
191 Interactions</a>
193 <li><a href="#conventions"><span class=secno>1.3. </span>Document
194 Conventions</a>
195 </ul>
197 <li><a href="#processing"><span class=secno>2. </span>Processing of
198 conditional group rules</a>
200 <li><a href="#contents-of"><span class=secno>3. </span>Contents of
201 conditional group rules</a>
203 <li><a href="#use"><span class=secno>4. </span>Placement of conditional
204 group rules</a>
206 <li><a href="#at-media"><span class=secno>5. </span>Media-specific style
207 sheets: the ‘<code class=css>@media</code>’ rule</a>
209 <li><a href="#at-supports"><span class=secno>6. </span>Feature queries:
210 the ‘<code class=css>@supports</code>’ rule</a>
211 <ul class=toc>
212 <li><a href="#support-definition"><span class=secno>6.1.
213 </span>Definition of support</a>
214 </ul>
216 <li><a href="#apis"><span class=secno>7. </span>APIs</a>
217 <ul class=toc>
218 <li><a href="#extentions-to-cssrule-interface"><span class=secno>7.1.
219 </span> Extensions to the <code>CSSRule</code> interface</a>
221 <li><a href="#the-cssgroupingrule-interface"><span class=secno>7.2.
222 </span> The <code>CSSGroupingRule</code> interface</a>
224 <li><a href="#the-cssconditionrule-interface"><span class=secno>7.3.
225 </span> The <code>CSSConditionRule</code> interface</a>
227 <li><a href="#the-cssmediarule-interface"><span class=secno>7.4. </span>
228 The <code>CSSMediaRule</code> interface</a>
230 <li><a href="#the-csssupportsrule-interface"><span class=secno>7.5.
231 </span> The <code>CSSSupportsRule</code> interface</a>
233 <li><a href="#the-css-interface"><span class=secno>7.6. </span> The
234 <code>CSS</code> interface, and the <code title="">supports()</code>
235 function</a>
236 </ul>
238 <li class=no-num><a href="#grammar">Grammar</a>
240 <li><a href="#conformance"><span class=secno>8. </span>Conformance</a>
241 <ul class=toc>
242 <li><a href="#base-modules"><span class=secno>8.1. </span>Base
243 Modules</a>
245 <li><a href="#conformance-classes"><span class=secno>8.2.
246 </span>Conformance Classes</a>
248 <li><a href="#partial"><span class=secno>8.3. </span> Partial
249 Implementations</a>
251 <li><a href="#experimental"><span class=secno>8.4. </span>Experimental
252 Implementations</a>
254 <li><a href="#cr-exit-criteria"><span class=secno>8.5. </span>CR Exit
255 Criteria</a>
256 </ul>
258 <li><a href="#changes"><span class=secno>9. </span> Changes</a>
260 <li class=no-num><a href="#acknowledgments">Acknowledgments</a>
262 <li class=no-num><a href="#references">References</a>
263 <ul class=toc>
264 <li class=no-num><a href="#normative-references">Normative
265 references</a>
267 <li class=no-num><a href="#other-references">Other references</a>
268 </ul>
270 <li class=no-num><a href="#index">Index</a>
271 </ul>
272 <!--end-toc-->
274 <h2 id=introduction><span class=secno>1. </span>Introduction</h2>
276 <h3 id=context><span class=secno>1.1. </span>Background</h3>
278 <p><em>This section is not normative.</em>
280 <p><a href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a> defines
281 one type of conditional group rule, the ‘<code
282 class=css>@media</code>’ rule, and allows only rulesets (not other
283 @-rules) inside of it. The ‘<code class=css>@media</code>’ rule
284 provides the ability to have media-specific style sheets, which is also
285 provided by style sheet linking features such as ‘<code
286 class=css>@import</code>’ and <code class=html><link></code>. The
287 restrictions on the contents of ‘<code class=css>@media</code>’ rules
288 made them less useful; they have forced authors using CSS features
289 involving @-rules in media-specific style sheets to use separate style
290 sheets for each medium.
292 <p>This specification extends the rules for the contents of conditional
293 group rules to allow other @-rules, which enables authors to combine CSS
294 features involving @-rules with media specific style sheets within a
295 single style sheet.
297 <p>This specification also defines an additional type of conditional group
298 rule, ‘<code class=css>@supports</code>’, to address author and user
299 requirements.
301 <p>The ‘<code class=css>@supports</code>’ rule allows CSS to be
302 conditioned on implementation support for CSS properties and values. This
303 rule makes it much easier for authors to use new CSS features and provide
304 good fallback for implementations that do not support those features. This
305 is particularly important for CSS features that provide new layout
306 mechanisms, and for other cases where a set of related styles needs to be
307 conditioned on property support.
309 <h3 id=placement><span class=secno>1.2. </span>Module Interactions</h3>
311 <p>This module replaces and extends the ‘<code class=css>@media</code>’
312 rule feature defined in <a href="#CSS21"
313 rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a> section <var>7.2.1</var> and
314 incorporates the modifications previously made non-normatively by <a
315 href="#MEDIAQ" rel=biblioentry>[MEDIAQ]<!--{{!MEDIAQ}}--></a> section
316 <var>1</var>.
318 <p>Its current definition depends on @-rules defined in <a
319 href="#CSS3-FONTS" rel=biblioentry>[CSS3-FONTS]<!--{{!CSS3-FONTS}}--></a>
320 and <a href="#CSS3-ANIMATIONS"
321 rel=biblioentry>[CSS3-ANIMATIONS]<!--{{!CSS3-ANIMATIONS}}--></a>, but that
322 dependency is only on the assumption that those modules will advance ahead
323 of this one. If this module advances faster, then the dependency will be
324 reversed.
326 <h3 id=conventions><span class=secno>1.3. </span>Document Conventions</h3>
328 <p>Conformance requirements are expressed with a combination of descriptive
329 assertions and RFC 2119 terminology. The key words “MUST”, “MUST
330 NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,
331 “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the
332 normative parts of this document are to be interpreted as described in RFC
333 2119. However, for readability, these words do not appear in all uppercase
334 letters in this specification.
336 <p>All of the text of this specification is normative except sections
337 explicitly marked as non-normative, examples, and notes. <a
338 href="#RFC2119" rel=biblioentry>[RFC2119]<!--{{!RFC2119}}--></a>
340 <p>Examples in this specification are introduced with the words “for
341 example” or are set apart from the normative text with <code
342 class=html>class="example"</code>, like this:
344 <div class=example>
345 <p>This is an example of an informative example.
346 </div>
348 <p>Informative notes begin with the word “Note” and are set apart from
349 the normative text with <code class=html>class="note"</code>, like this:
351 <p class=note>Note, this is an informative note.
353 <h2 id=processing><span class=secno>2. </span>Processing of conditional
354 group rules</h2>
356 <p>This specification defines some CSS @-rules, called <dfn
357 id=conditional-group-rules>conditional group rules</dfn>, that associate a
358 condition with a group of other CSS rules. These different rules allow
359 testing different types of conditions, but share common behavior for how
360 their contents are used when the condition is true and when the condition
361 is false.
363 <div class=example>
364 <p>For example, this rule:
366 <pre>@media print {
367 #navigation { display: none }
368 }</pre>
370 <p>causes a particular CSS rule (making elements with ID "navigation" be
371 display:none) apply only when the style sheet is used for a print medium.
372 </div>
374 <p>Each conditional group rule has a condition, which at any time evaluates
375 to true or false. When the condition is true, CSS processors
376 <strong>must</strong> apply the rules inside the group rule as though they
377 were at the group rule's location; when the condition is false, CSS
378 processors <strong>must not</strong> apply any of rules inside the group
379 rule. The current state of the condition does not affect the CSS object
380 model, in which the contents of the group rule always remain within the
381 group rule.
383 <p>This means that when multiple conditional group rules are nested, a rule
384 inside of both of them applies only when all of the rules' conditions are
385 true.
387 <div class=example>For example, with this set of nested rules:
388 <pre>@media print { // rule (1)
389 #navigation { display: none }
390 @media (max-width: 12cm) { // rule (2)
391 .note { float: none }
392 }
393 }</pre>
394 the condition of the rule marked (1) is true for print media, and the
395 condition of the rule marked (2) is true when the width of the display
396 area (which for print media is the page box) is less than or equal to
397 12cm. Thus the rule ‘<code class=css>#navigation { display: none
398 }</code>’ applies whenever this style sheet is applied to print media,
399 and the rule ‘<code class=css>.note { float: none }</code>’ is applied
400 only when the style sheet is applied to print media <em>and</em> the width
401 of the page box is less than or equal to 12 centimeters.</div>
403 <p>When the condition for a conditional group rule changes, CSS processors
404 <strong>must</strong> reflect that the rules now apply or no longer apply,
405 except for properties whose definitions define effects of computed values
406 that persist past the lifetime of that value (such as for some properties
407 in <a href="#CSS3-TRANSITIONS"
408 rel=biblioentry>[CSS3-TRANSITIONS]<!--{{CSS3-TRANSITIONS}}--></a> and <a
409 href="#CSS3-ANIMATIONS"
410 rel=biblioentry>[CSS3-ANIMATIONS]<!--{{!CSS3-ANIMATIONS}}--></a>).
412 <h2 id=contents-of><span class=secno>3. </span>Contents of conditional
413 group rules</h2>
415 <p>The syntax of each conditional group rule consists of some syntax
416 specific to the type of rule followed by a <dfn id=group-rule-body>group
417 rule body</dfn>, which is a block (pair of braces) containing a sequence
418 of rules.
420 <p>A group rule body is allowed to contain rulesets and any @-rules that
421 are allowed at the top level of a style sheet before and after a ruleset.
422 This means that @-rules that must occur at the beginning of the style
423 sheet (such as ‘<code class=css>@charset</code>’, ‘<code
424 class=css>@import</code>’, and ‘<code class=css>@namespace</code>’
425 rules) are not allowed inside of conditional group rules. Conditional
426 group rules can be nested.
428 <p>In terms of the grammar, this specification defines the following
429 productions for use in the grammar of conditional group rules:
431 <pre><dfn id="nested_statement">nested_statement</dfn>
432 : ruleset | <a
433 href="#media"><i>media</i></a> | page | font_face_rule | keyframes_rule |
434 <a
435 href="#supports_rule"><i>supports_rule</i></a>
436 ;
438 <dfn
439 id="group_rule_body">group_rule_body</dfn>
440 : '{' S* <a
441 href="#nested_statement"><i>nested_statement</i></a>* '}' S*
442 ;</pre>
444 <p> in which all the productions are defined in that grammar with the
445 exception of <code>font_face_rule</code> defined in <a href="#CSS3-FONTS"
446 rel=biblioentry>[CSS3-FONTS]<!--{{!CSS3-FONTS}}--></a>,
447 <code>keyframes_rule</code> defined in <a href="#CSS3-ANIMATIONS"
448 rel=biblioentry>[CSS3-ANIMATIONS]<!--{{!CSS3-ANIMATIONS}}--></a>, and <a
449 href="#media"><code>media</code></a> and <a
450 href="#supports_rule"><code>supports_rule</code></a> defined in this
451 specification.
453 <p>In general, future CSS specifications that add new @-rules that are not
454 forbidden to occur after some other types of rules should modify this <a
455 href="#nested_statement"><code>nested_statement</code></a> production to
456 keep the grammar accurate.
458 <p>Style sheets <strong>must not</strong> use rules other than the allowed
459 ones inside conditional group rules.
461 <p>CSS processors <strong>must</strong> ignore rules that are not allowed
462 within a group rule, and <strong>must</strong> handle invalid rules inside
463 of group rules as described in <a
464 href="http://www.w3.org/TR/CSS21/syndata.html#parsing-errors">section 4.2
465 (Rules for handling parsing errors)</a>, <a
466 href="http://www.w3.org/TR/CSS21/syndata.html#at-rules">section 4.1.5
467 (At-rules)</a>, and <a
468 href="http://www.w3.org/TR/CSS21/syndata.html#rule-sets">section 4.1.7
469 (Rule sets, declaration blocks, and selectors)</a> of <a href="#CSS21"
470 rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>.
472 <h2 id=use><span class=secno>4. </span>Placement of conditional group rules</h2>
474 <p>Conditional group rules are allowed at the top-level of a style sheet,
475 and inside other conditional group rules. CSS processors
476 <strong>must</strong> process such rules as <a
477 href="#processing">described above</a>.
479 <p>Any rules that are not allowed after a ruleset (e.g., ‘<code
480 class=css>@charset</code>’, ‘<code class=css>@import</code>’, or
481 ‘<code class=css>@namespace</code>’ rules) are also not allowed after
482 a conditional group rule. Therefore, style sheets <strong>must
483 not</strong> place such rules after a conditional group rules, and CSS
484 processors <strong>must</strong> ignore such rules.
486 <h2 id=at-media><span class=secno>5. </span>Media-specific style sheets:
487 the ‘<code class=css>@media</code>’ rule</h2>
489 <p>The <dfn id=atmedia-rule>‘<code class=css>@media</code>’ rule</dfn>
490 is a conditional group rule whose condition is a media query. It consists
491 of the at-keyword ‘<code class=css>@media</code>’ followed by a
492 (possibly empty) media query list (as defined in <a href="#MEDIAQ"
493 rel=biblioentry>[MEDIAQ]<!--{{!MEDIAQ}}--></a>), followed by a group rule
494 body. The condition of the rule is the result of the media query.
496 <div class=example>
497 <p>This ‘<code class=css>@media</code>’ rule:
499 <pre>@media print, (max-width: 600px) {
500 #extra_navigation { display: none }
501 }</pre>
503 <p>has the condition ‘<code class=css>print, (max-width:
504 600px)</code>’, which is true for print media and for devices whose
505 width is at most 600px. When either of these is true, the condition of
506 the rule is true, and the rule ‘<code class=css>#extra_navigation {
507 display: none }</code>’ is applied.
508 </div>
510 <p>In terms of the grammar, this specification extends the <a
511 href="#media"><code>media</code></a> production in the <a
512 href="http://www.w3.org/TR/CSS21/grammar.html">Grammar of CSS 2.1</a> (<a
513 href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>, Appendix G)
514 into:
516 <pre><dfn id=media>media</dfn>
517 : MEDIA_SYM S* media_query_list <a
518 href="#group_rule_body"><i>group_rule_body</i></a>
519 ;</pre>
521 <p>where the <a href="#group_rule_body"><code>group_rule_body</code></a>
522 production is defined in this specification, the
523 <code>media_query_list</code> production is defined in <a href="#MEDIAQ"
524 rel=biblioentry>[MEDIAQ]<!--{{!MEDIAQ}}--></a>, and the others are defined
525 in the <a href="http://www.w3.org/TR/CSS21/grammar.html">Grammar of CSS
526 2.1</a> (<a href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>,
527 Appendix G).
529 <h2 id=at-supports><span class=secno>6. </span>Feature queries: the
530 ‘<code class=css>@supports</code>’ rule</h2>
532 <p>The <dfn id=atsupports-rule>‘<code class=css>@supports</code>’
533 rule</dfn> is a conditional group rule whose condition tests whether the
534 user agent supports CSS property:value pairs. Authors can use it to write
535 style sheets that use new features when available but degrade gracefully
536 when those features are not supported. CSS has existing mechanisms for
537 graceful degradation, such as ignoring unsupported properties or values,
538 but these are not always sufficient when large groups of styles need to be
539 tied to the support for certain features, as is the case for use of new
540 layout system features.
542 <p>The syntax of the condition in the ‘<code
543 class=css>@supports</code>’ rule is slightly more complicated than for
544 the other conditional group rules (though has some similarities to media
545 queries) since:
547 <ul>
548 <li>negation is needed so that the new-feature styles and the fallback
549 styles can be separated (within the forward-compatible grammar's rules
550 for the syntax of @-rules), and not required to override each other
552 <li>conjunction (and) is needed so that multiple required features can be
553 tested
555 <li>disjunction (or) is needed when there are multiple alternative
556 features for a set of styles, particularly when some of those
557 alternatives are vendor-prefixed properties or values
558 </ul>
560 <p>Therefore, the syntax of the ‘<code class=css>@supports</code>’ rule
561 allows testing for property:value pairs, and arbitrary conjunctions (and),
562 disjunctions (or), and negations (not) of them.
564 <p>This extends the lexical scanner in the <a
565 href="http://www.w3.org/TR/CSS21/grammar.html">Grammar of CSS 2.1</a> (<a
566 href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>, Appendix G) by
567 adding:
569 <pre>
570 @{S}{U}{P}{P}{O}{R}{T}{S} {return SUPPORTS_SYM;}
571 {O}{R} {return OR;}
572 </pre>
574 <p>and the grammar by adding
576 <pre><dfn id="supports_rule">supports_rule</dfn>
577 : SUPPORTS_SYM S* <a
578 href="#supports_condition"><i>supports_condition</i></a> S* <a
579 href="#group_rule_body"><i>group_rule_body</i></a>
580 ;
582 <dfn
583 id="supports_condition">supports_condition</dfn>
584 : <a
585 href="#supports_negation"><i>supports_negation</i></a> | <a
586 href="#supports_conjunction"><i>supports_conjunction</i></a> | <a
587 href="#supports_disjunction"><i>supports_disjunction</i></a> |
588 <a
589 href="#supports_condition_in_parens"><i>supports_condition_in_parens</i></a>
590 ;
592 <dfn
593 id="supports_condition_in_parens">supports_condition_in_parens</dfn>
594 : ( '(' S* <a
595 href="#supports_condition"><i>supports_condition</i></a> S* ')' ) | <a
596 href="#supports_declaration_condition"><i>supports_declaration_condition</i></a> |
597 <a
598 href="#general_enclosed"><i>general_enclosed</i></a>
599 ;
601 <dfn
602 id="supports_negation">supports_negation</dfn>
603 : NOT S+ <a
604 href="#supports_condition_in_parens"><i>supports_condition_in_parens</i></a>
605 ;
607 <dfn
608 id="supports_conjunction">supports_conjunction</dfn>
609 : <a
610 href="#supports_condition_in_parens"><i>supports_condition_in_parens</i></a> ( S+ AND S+ <a
611 href="#supports_condition_in_parens"><i>supports_condition_in_parens</i></a> )+
612 ;
614 <dfn
615 id="supports_disjunction">supports_disjunction</dfn>
616 : <a
617 href="#supports_condition_in_parens"><i>supports_condition_in_parens</i></a> ( S+ OR S+ <a
618 href="#supports_condition_in_parens"><i>supports_condition_in_parens</i></a> )+
619 ;
621 <dfn
622 id="supports_declaration_condition">supports_declaration_condition</dfn>
623 : '(' S* declaration ')'
624 ;
626 <dfn
627 id="general_enclosed">general_enclosed</dfn>
628 : ( FUNCTION | '(' ) ( any | unused )* ')'
629 ;
630 </pre>
632 <p>in which <code>declaration</code>, <code>any</code>, and
633 <code>unused</code> are the productions in the core syntax of CSS defined
634 in <a href="http://www.w3.org/TR/CSS21/syndata.html#tokenization">section
635 4.1.1 (Tokenization)</a> of <a href="#CSS21"
636 rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>, and the <code>AND</code> and
637 <code>NOT</code> tokens are defined in the Media Queries specification <a
638 href="#MEDIAQ" rel=biblioentry>[MEDIAQ]<!--{{!MEDIAQ}}--></a>.
640 <p> Implementations <strong>must</strong> parse ‘<code
641 class=css>@supports</code>’ rules based on the above grammar, and when
642 interpreting the above grammar, <strong>must</strong> match the production
643 before an <code>|</code> operator in preference to the one after it.
645 <p> The above grammar is purposely very loose for forwards-compatibility
646 reasons, since the <a
647 href="#general_enclosed"><code>general_enclosed</code></a> production
648 allows for substantial future extensibility. Any ‘<code
649 class=css>@supports</code>’ rule that does not parse according to the
650 grammar above (that is, a rule that does not match this loose grammar
651 which includes the general_enclosed production) is invalid. Style sheets
652 <strong>must not</strong> use such a rule and processors
653 <strong>must</strong> ignore such a rule (including all of its contents).
655 <p>Each of these grammar terms is associated with a boolean result, as
656 follows:
658 <dl>
659 <dt>supports_condition
661 <dd> The result is the result of the single child term.
663 <dt>supports_condition_in_parens
665 <dd> The result is the result of the single <a
666 href="#supports_condition"><code>supports_condition</code></a> or <a
667 href="#supports_declaration_condition"><code>supports_declaration_condition</code></a>
668 child term.
670 <dt>supports_negation
672 <dd> The result is the <em>negation</em> of the result of the <a
673 href="#supports_condition_in_parens"><code>supports_condition_in_parens</code></a>
674 child term.
676 <dt>supports_conjunction
678 <dd> The result is true if the result of <em>all</em> of the <a
679 href="#supports_condition_in_parens"><code>supports_condition_in_parens</code></a>
680 child terms is true; otherwise it is false.
682 <dt>supports_disjunction
684 <dd> The result is true if the result of <em>any</em> of the <a
685 href="#supports_condition_in_parens"><code>supports_condition_in_parens</code></a>
686 child terms is true; otherwise it is false.
688 <dt>supports_declaration_condition
690 <dd> The result is whether the CSS processor <a
691 href="#support-definition">supports</a> the declaration within the
692 parentheses.
694 <dt>general_enclosed
696 <dd> The result is always false. Additionally, style sheets <strong>must
697 not</strong> write ‘<code class=css>@supports</code>’ rules that
698 match this grammar production. (In other words, this production exists
699 only for future extensibility, and is not part of the description of a
700 valid style sheet in this level of the specification.) <span
701 class=note>Note that future levels may define functions or other
702 parenthesized expressions that can evaluate to true.</span>
703 </dl>
705 <p>The condition of the ‘<code class=css>@supports</code>’ rule is the
706 result of the <a
707 href="#supports_condition"><code>supports_condition</code></a> term that
708 is a child of the <a href="#supports_rule"><code>supports_rule</code></a>
709 term.
711 <div class=example>
712 <p>For example, the following rule
714 <pre>@supports ( display: flexbox ) {
715 body, #navigation, #content { display: flexbox; }
716 #navigation { background: blue; color: white; }
717 #article { background: white; color: black; }
718 }</pre>
720 <p>applies the rules inside the ‘<code class=css>@supports</code>’
721 rule only when ‘<code class=css>display: flexbox</code>’ is
722 supported.
723 </div>
725 <div class=example>
726 <p>The following example shows an additional ‘<code
727 class=css>@supports</code>’ rule that can be used to provide an
728 alternative for when ‘<code class=css>display: flexbox</code>’ is not
729 supported:
731 <pre>@supports not ( display: flexbox ) {
732 body { width: 100%; height: 100%; background: white; color: black; }
733 #navigation { width: 25%; }
734 #article { width: 75%; }
735 }</pre>
737 <p>Note that the ‘<code class=property>width</code>’ declarations may
738 be harmful to the flexbox-based layout, so it is important that they be
739 present only in the non-flexbox styles.
740 </div>
742 <div class=example>
743 <p>The following example checks for support for the ‘<code
744 class=property>box-shadow</code>’ property, including checking for
745 support for vendor-prefixed versions of it. When the support is present,
746 it specifies both ‘<code class=property>box-shadow</code>’ (with the
747 prefixed versions) and ‘<code class=property>color</code>’ in a way
748 what would cause the text to become invisible were ‘<code
749 class=property>box-shadow</code>’ not supported.
751 <pre>@supports ( box-shadow: 2px 2px 2px black ) or
752 ( -moz-box-shadow: 2px 2px 2px black ) or
753 ( -webkit-box-shadow: 2px 2px 2px black ) or
754 ( -o-box-shadow: 2px 2px 2px black ) {
755 .outline {
756 color: white;
757 -moz-box-shadow: 2px 2px 2px black;
758 -webkit-box-shadow: 2px 2px 2px black;
759 -o-box-shadow: 2px 2px 2px black;
760 box-shadow: 2px 2px 2px black; /* unprefixed last */
761 }
762 }</pre>
763 </div>
765 <p>To avoid confusion between ‘<code class=css>and</code>’ and ‘<code
766 class=css>or</code>’, the syntax requires that both ‘<code
767 class=css>and</code>’ and ‘<code class=css>or</code>’ be specified
768 explicitly (rather than, say, using commas or spaces for one of them).
769 Likewise, to avoid confusion caused by precedence rules, the syntax does
770 not allow ‘<code class=css>and</code>’, ‘<code
771 class=css>or</code>’, and ‘<code class=css>not</code>’ operators to
772 be mixed without a layer of parentheses.
774 <div class=example>
775 <p>For example, the following rule is not valid:
777 <pre class=illegal>@supports (transition-property: color) or
778 (animation-name: foo) and
779 (transform: rotate(10deg)) {
780 // ...
781 }</pre>
783 <p>Instead, authors must write one of the following:
785 <pre>@supports ((transition-property: color) or
786 (animation-name: foo)) and
787 (transform: rotate(10deg)) {
788 // ...
789 }</pre>
791 <pre>@supports (transition-property: color) or
792 ((animation-name: foo) and
793 (transform: rotate(10deg))) {
794 // ...
795 }</pre>
796 </div>
798 <p>Furthermore, whitespace is required after a ‘<code
799 class=css>not</code>’ and on both sides of an ‘<code
800 class=css>and</code>’ or ‘<code class=css>or</code>’.
802 <p>The declaration being tested must always occur within parentheses, when
803 it is the only thing in the expression.
805 <p>
807 <div class=example>
808 <p>For example, the following rule is not valid:
810 <pre class=illegal>@supports display: flexbox {
811 // ...
812 }</pre>
814 <p>Instead, authors must write:
816 <pre>@supports (display: flexbox) {
817 // ...
818 }</pre>
819 </div>
821 <p>The syntax allows extra parentheses when they are not needed. This
822 flexibility is sometimes useful for authors (for example, when commenting
823 out parts of an expression) and may also be useful for authoring tools.
825 <div class=example>
826 <p>For example, authors may write:
828 <pre>@supports ((display: flexbox)) {
829 // ...
830 }</pre>
831 </div>
833 <p>A trailing ‘<code class=css>!important</code>’ on a declaration
834 being tested is allowed, though it won't change the validity of the
835 declaration.
837 <div class=example>
838 <p>For example, the following rule is valid:
840 <pre>@supports (display: flexbox !important) {
841 // ...
842 }</pre>
843 </div>
845 <h3 id=support-definition><span class=secno>6.1. </span>Definition of
846 support</h3>
848 <p>For forward-compatibility, <a
849 href="http://www.w3.org/TR/CSS21/syndata.html#declaration">section 4.1.8
850 (Declarations and properties)</a> of <a href="#CSS21"
851 rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a> defines rules for handling
852 invalid properties and values. CSS processors that do not implement or
853 partially implement a specification <strong>must</strong> treat any part
854 of a value that they do not implement, or do not have a usable level of
855 support for, as invalid according to this rule for handling invalid
856 properties and values, and therefore <strong>must</strong> discard the
857 declaration as a parse error.
859 <p>A CSS processor is considered to <dfn id=dfn-support>support</dfn> a
860 declaration (consisting of a property and value) if it accepts that
861 declaration (rather than discarding it as a parse error). If a processor
862 does not implement, with a usable level of support, the value given, then
863 it <strong>must not</strong> accept the declaration or claim support for
864 it.
866 <p>These rules (and the equivalence between them) allow authors to use
867 fallback (either in the <a href="#CSS1"
868 rel=biblioentry>[CSS1]<!--{{CSS1}}--></a> sense of declarations that are
869 overridden by later declarations or with the new capabilities provided by
870 the ‘<code class=css>@supports</code>’ rule in this specification)
871 that works correctly for the features implemented. This applies especially
872 to compound values; implementations must implement all parts of the value
873 in order to consider the declaration supported, either inside a ruleset or
874 in the declaration condition of an ‘<code class=css>@supports</code>’
875 rule.</p>
876 <!--
877 <h2 id="at-document">Document queries: the '@document' rule</h2>
879 <p>The <dfn>'@document' rule</dfn> is a conditional group
880 rule whose condition depends on the
881 <a href="#url-of-doc">URL of the document being styled</a>.
882 This allows style sheets, particularly user style sheets, to have styles
883 that only apply to a set of pages rather than to all pages using the
884 style sheet.</p>
886 <p class="issue">Given that this @-rule is intended primarily for user
887 style sheets, what should this specification say about its use in author
888 style sheets? Should it be forbidden? Should use instead be
889 discouraged? Or should this specification remain neutral on the
890 topic, since there are valid uses in author style sheets?</p>
892 <p id="url-of-doc">The <dfn>URL of the document being styled</dfn> is
893 the URI at which the document is located, excluding any fragment
894 identifiers. (This means, for example, that HTTP redirects have been
895 followed.) If the styles are being applied inside a complete document
896 embedded into the presentation of another (e.g., [[HTML5]]'s <code
897 class="html">iframe</code>, <code class="html">object</code>, or <code
898 class="html">img</code> elements), the relevant URI is that of the
899 frame, not of its container. However, if content from other documents
900 is mixed in via mechanisms that mix content from one document into
901 another (e.g., [[SVG11]]'s <code>use</code> element), then the
902 address of the container document is used.</p>
904 <p class="note">Note: In [[HTML5]], this is the
905 <a href="http://dev.w3.org/html5/spec/dom.html#documents">document's address</a>
906 of a document in a
907 <a href="http://dev.w3.org/html5/spec/browsers.html#browsing-context">browsing context</a>.</p>
909 <div class="issue">What form of normalization is done on URLs and domains
910 before matching? In particular, this specification needs to describe:
911 <ul>
912 <li>what form is used for the <a href="#url-of-doc">URL of the document
913 being styled</a> (and what has been normalized in that form)</li>
914 <li>what normalization (if any) happens to the argument of each of the match
915 functions before the comparison that they describe and</li>
916 <li>whether the
917 comparison algorithm used is string comparison or some other URL
918 comparison algorithm.</li></ul></div>
920 <p>The '@document' rule's condition is written as a
921 comma-separated list of <dfn>URL matching functions</dfn>, and the
922 condition evaluates to true whenever any one of those functions
923 evaluates to true. The following URL matching functions are
924 permitted:</p>
926 <dl>
927 <dt><dfn id="url-exact" title="url()|URL matching functions::exact"><url></dfn></dt>
929 <dd>
930 <p>The 'url()' function is the <dfn>exact url matching
931 function</dfn>. It evaluates to true whenever the <a
932 href="#url-of-doc">URL of the document being styled</a> is exactly
933 the URL given.</p>
935 <p class="Note">The 'url()' function, since it is a core syntax
936 element in CSS, is allowed (subject to different character
937 limitations and thus escaping requirements) to contain an unquoted
938 value (in addition to the string values that are allowed as
939 arguments for all four functions).</p>
941 <div class="example">
942 <p>For example, this rule:</p>
943 <pre>@document url("http://www.w3.org/Style/CSS/") {
944 #summary { background: yellow; color: black}
945 }</pre>
946 <p>styles the <code class="html">summary</code> element on the page
947 <code>http://www.w3.org/Style/CSS/</code>, but not on any other
948 pages.</p>
949 </div>
950 </dd>
952 <dt><dfn id="url-prefix" title="url-prefix()|URL matching functions::prefix">url-prefix(<string>)</dfn></dt>
954 <dd>
955 <p>The 'url-prefix()' function is the <dfn>url prefix
956 matching function</dfn>. It evaluates to true whenever the
957 <a href="#url-of-doc">URL of the document being styled</a>
958 has the argument to the function as an
959 initial substring (which is true when the two strings are equal).
960 When the argument is the empty string, it evaluates to true for all
961 documents.</p>
962 <div class="example">
963 <p>For example, this rule:</p>
964 <pre>@document url-prefix("http://www.w3.org/Style/CSS/") {
965 #summary { background: yellow; color: black}
966 }</pre>
967 <p>styles the <code class="html">summary</code> element on the page
968 <code>http://www.w3.org/Style/CSS/</code> and on the page
969 <code>http://www.w3.org/Style/CSS/Test</code>, but it does not
970 affect the page <code>http://www.w3.org/</code> or the page
971 <code>http://www.example.com/Style/CSS/</code>.</p>
972 </div>
973 </dd>
975 <dt><dfn id="url-domain" title="domain()|URL matching functions::domain">domain(<string>)</dfn></dt>
977 <dd>
978 <p>The 'domain()' function is the <dfn>domain
979 matching function</dfn>. It evaluates to true whenever
980 the <a href="#url-of-doc">URL of the document being styled</a>
981 has a host subcomponent (as defined in [[!URI]])
982 and that host subcomponent is exactly the argument to the
983 'domain()' function or a final substring of the host
984 component is a period (U+002E) immediately followed by the argument
985 to the 'domain()' function.</p>
986 <div class="example">
987 <p>For example, this rule:</p>
988 <pre>@document domain("w3.org") {
989 body { font-size: 16px ! important }
990 }</pre>
991 <p>changes the font size of the body element for pages such as
992 <code>http://www.w3.org/Style/CSS/</code> and
993 <code>http://w3.org/Style/CSS/</code> and
994 <code>http://lists.w3.org/Archives/Public/www-style/</code>
995 but it does not affect the page
996 <code>http://www.example.com/Style/CSS/</code>.</p>
997 </div>
998 </dd>
1000 <dt><dfn id="url-regexp" title="regexp()|URL matching functions::regular expression">regexp(<string>)</dfn></dt>
1002 <dd>
1003 <p>The contents of the <string> argument <strong>must</strong>
1004 match the JavaScript <code>Pattern</code> production
1005 ([[!ECMA-262-5.1]], section 15.10.1). However,
1006 failing to do so is not a CSS syntax error and does not trigger any
1007 error handling for CSS syntax errors.</p>
1009 <p>The ''regexp()'' function evaluates to true whenever the string
1010 argument compiled as a JavaScript regular expression with the
1011 <code>global</code>, <code>ignoreCase</code> and
1012 <code>multiline</code> flags <em>disabled</em>
1013 (see [[!ECMA-262-5.1]], sections 15.10.7.2 through 15.10.7.4)
1014 compiles successfully and the resulting regular expression matches
1015 the entirety of the
1016 <a href="#url-of-doc">URL of the document being styled</a>.</p>
1018 <p class="note">Note that regular expression must match the entire
1019 URL, not just a part of it.</p>
1021 <p class="note">Note that this definition intentionally matches the
1022 behavior of the <a
1023 href="http://dev.w3.org/html5/spec/common-input-element-attributes.html#attr-input-pattern"><code class="html">pattern</code>
1024 attribute</a> on the <code class="html">input</code> element
1025 in [[HTML5]].</p>
1027 <div class="example">
1028 <p>For example, this rule:</p>
1029 <pre>@document regexp("http://www.w3.org/TR/\\d{4}/[^/]*-CSS2-\\d{8}/") {
1030 body { font-size: 20px ! important }
1031 }</pre>
1032 <p>changes the font size of the body element for pages such as
1033 <code>http://www.w3.org/TR/2011/PR-CSS2-20110412/</code>.</p>
1034 <p class="note">Note that the backslashes in the regular
1035 expression require CSS escaping as ''\\''.</p>
1036 </div>
1037 </dd>
1039 </dl>
1041 <p>Implementations <strong>must</strong> treat any unknown URL matching
1042 functions as a syntax error, and thus ignore the '@document' rule.
1043 <span class="issue">Should we instead have more complicated error
1044 handling rules to make forward-compatibility work differently, or is
1045 this rule the best solution for such future expansion anyway?</span></p>
1047 <div class="issue">This syntax doesn't offer any ability to do negations,
1048 which has been requested in <a
1049 href="https://bugzilla.mozilla.org/show_bug.cgi?id=349813">Mozilla bug
1050 349813</a>. Use cases that people have wanted negations for
1051 include:
1052 <ul>
1053 <li>User style sheets that want a particular rule in general, but know
1054 that that rule does more harm than good on specific sites.</li>
1055 <li>Authors who have a rule that they want to apply to most of their
1056 pages, but wish to make a few exceptions for.</li>
1057 </ul>
1058 </div>
1060 <p>This extends the lexical scanner in the
1061 <a href="http://www.w3.org/TR/CSS21/grammar.html">Grammar of CSS 2.1</a>
1062 ([[!CSS21]], Appendix G) by adding:
1063 <pre>@{D}{O}{C}{U}{M}{E}{N}{T} {return DOCUMENT_SYM;}</pre>
1064 <p>and the grammar by adding</p>
1065 <pre><dfn>document_rule</dfn>
1066 : DOCUMENT_SYM S+ <i>url_match_fn</i> ( "," S* <i>url_match_fn</i> )* <i>group_rule_body</i>
1067 ;
1069 <dfn>url_match_fn</dfn>
1070 : (URI | FUNCTION S* STRING S* ')' ) S*
1071 ;</pre>
1072 -->
1074 <h2 id=apis><span class=secno>7. </span>APIs</h2>
1076 <h3 id=extentions-to-cssrule-interface><span class=secno>7.1. </span>
1077 Extensions to the <code>CSSRule</code> interface</h3>
1079 <p>The <code>CSSRule</code> interface is extended as follows:
1081 <pre class=idl>partial interface CSSRule {
1082 const unsigned short SUPPORTS_RULE = 12;
1083 <!--
1084 const unsigned short DOCUMENT_RULE = 13;
1085 -->
1086 }</pre>
1088 <h3 id=the-cssgroupingrule-interface><span class=secno>7.2. </span> The <a
1089 href="#cssgroupingrule"><code>CSSGroupingRule</code></a> interface</h3>
1091 <p>The <dfn id=cssgroupingrule><code>CSSGroupingRule</code></dfn> interface
1092 represents an at-rule that contains other rules nested inside itself.
1094 <pre class=idl>interface CSSGroupingRule : CSSRule {
1095 readonly attribute <a
1096 href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSRuleList">CSSRuleList</a> cssRules;
1097 unsigned long insertRule (DOMString rule, unsigned long index);
1098 void deleteRule (unsigned long index);
1099 }</pre>
1101 <dl class=idl-attributes>
1102 <dt><code>cssRules</code> of type <code><a
1103 href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSRuleList">CSSRuleList</a></code>,
1104 readonly
1106 <dd>The <code>cssRules</code> attribute must return a
1107 <code>CSSRuleList</code> object for the list of CSS rules nested inside
1108 the grouping rule.
1109 </dl>
1111 <dl class=idl-methods>
1112 <dt><code>insertRule(DOMString rule, unsigned long index)</code>, returns
1113 <code>unsigned long</code>
1115 <dd> The <code>insertRule</code> operation must insert a CSS rule
1116 <var>rule</var> into the CSS rule list returned by <code>cssRules</code>,
1117 such that the inserted rule will be at position <var>index</var>, and any
1118 rules previously at <var>index</var> or higher will increase their index
1119 by one. It must throw INDEX_SIZE_ERR if index is greater than
1120 <code>cssRules.length</code>. It must throw SYNTAX_ERR if the rule has a
1121 syntax error and is unparseable; this does not include syntax errors
1122 handled by error handling rules for constructs inside of the rule. It
1123 must throw HIERARCHY_REQUEST_ERR if the rule cannot be inserted at the
1124 location specified, for example, if an ‘<code
1125 class=css>@import</code>’ rule is inserted inside a group rule. <span
1126 class=issue>This needs to specify what to do if <code>rule</code> is the
1127 empty string, if it contains more than one CSS rule, or if it contains
1128 garbage after a valid rule.</span>
1130 <dt><code>deleteRule (unsigned long index)</code>, return
1131 <code>void</code>
1133 <dd> The <code>deleteRule</code> operation must remove a CSS rule from the
1134 CSS rule list returned by <code>cssRules</code> at <var>index</var>. It
1135 must throw INDEX_SIZE_ERR if index is greater than or equal to
1136 <code>cssRules.length</code>.
1137 </dl>
1139 <h3 id=the-cssconditionrule-interface><span class=secno>7.3. </span> The <a
1140 href="#cssconditionrule"><code>CSSConditionRule</code></a> interface</h3>
1142 <p>The <dfn id=cssconditionrule><code>CSSConditionRule</code></dfn>
1143 interface represents all the "conditional" at-rules, which consist of a
1144 condition and a statement block.
1146 <pre class=idl>interface CSSConditionRule : CSSGroupingRule {
1147 attribute DOMString conditionText;
1148 }</pre>
1150 <dl class=idl-attributes>
1151 <dt><code>conditionText</code> of type <code>DOMString</code>
1153 <dd>
1154 <p>The <code>conditionText</code> attribute represents the condition of
1155 the rule. Since what this condition does varies between the derived
1156 interfaces of <a
1157 href="#cssconditionrule"><code>CSSConditionRule</code></a>, those
1158 derived interfaces may specify different behavior for this attribute
1159 (see, for example, <a href="#cssmediarule"><code>CSSMediaRule</code></a>
1160 below). In the absence of such rule-specific behavior, the following
1161 rules apply:
1163 <p>The <code>conditionText</code> attribute, on getting, must return the
1164 result of serializing the associated condition.
1166 <p>On setting the <code>conditionText</code> attribute these steps must
1167 be run:
1169 <ol>
1170 <li>Trim the given value of white space.
1172 <li>If the given value matches the grammar of the appropriate condition
1173 production for the given rule, replace the associated CSS condition
1174 with the given value.
1176 <li>Otherwise, do nothing.
1177 </ol>
1178 </dl>
1180 <h3 id=the-cssmediarule-interface><span class=secno>7.4. </span> The <a
1181 href="#cssmediarule"><code>CSSMediaRule</code></a> interface</h3>
1183 <p>The <dfn id=cssmediarule><code>CSSMediaRule</code></dfn> interface
1184 represents a ‘<code class=css>@media</code>’ rule:
1186 <pre class=idl>interface CSSMediaRule : CSSConditionRule {
1187 readonly attribute <a
1188 href="http://www.w3.org/TR/DOM-Level-2-Style/stylesheets.html#StyleSheets-MediaList">MediaList</a> media;
1189 }</pre>
1191 <dl class=idl-attributes>
1192 <dt><a href="#media"><code>media</code></a> of type <code><a
1193 href="http://www.w3.org/TR/DOM-Level-2-Style/stylesheets.html#StyleSheets-MediaList">MediaList</a></code>,
1194 readonly
1196 <dd>The <a href="#media"><code>media</code></a> attribute must return a
1197 <code>MediaList</code> object for the list of media queries specified
1198 with the ‘<code class=css>@media</code>’ rule.
1200 <dt><code>conditionText</code> of type <code>DOMString</code>
1202 <dd>The <code>conditionText</code> attribute (defined on the <a
1203 href="#cssconditionrule"><code>CSSConditionRule</code></a> parent rule),
1204 on getting, must return the value of <code>media.mediaText</code> on the
1205 rule.
1206 <p>Setting the <code>conditionText</code> attribute must set the
1207 <code>media.mediaText</code> attribute on the rule.
1208 </dl>
1210 <h3 id=the-csssupportsrule-interface><span class=secno>7.5. </span> The <a
1211 href="#csssupportsrule"><code>CSSSupportsRule</code></a> interface</h3>
1213 <p>The <dfn id=csssupportsrule><code>CSSSupportsRule</code></dfn> interface
1214 represents a ‘<code class=css>@supports</code>’ rule.
1216 <pre class=idl>interface CSSSupportsRule : CSSConditionRule {
1217 }</pre>
1218 <!--
1219 <h3 id="the-cssdocumentrule-interface">
1220 The <code>CSSDocumentRule</code> interface</h3>
1222 <p>The <dfn><code>CSSDocumentRule</code></dfn> interface represents a ''@document'' rule.</p>
1224 <pre class='idl'>interface CSSDocumentRule : CSSConditionRule {
1225 }</pre>
1226 -->
1228 <h3 id=the-css-interface><span class=secno>7.6. </span> The <a
1229 href="#CSS-interface"><code>CSS</code></a> interface, and the <code
1230 title="">supports()</code> function</h3>
1232 <p>The <dfn id=CSS-interface><code>CSS</code></dfn> interface holds useful
1233 CSS-related functions that do not belong elsewhere.
1235 <pre class=idl>interface CSS {
1236 static boolean supports(DOMString property, DOMString value);
1237 static boolean supports(DOMString conditionText);
1238 }</pre>
1240 <dl class=idl-methods>
1241 <dt><code>supports(DOMString property, DOMString value)</code>, returns
1242 <code>boolean</code>
1244 <dt><code>supports(DOMString conditionText)</code>, returns
1245 <code>boolean</code>
1247 <dd> When the <code title="">supports()</code> method is invoked with two
1248 arguments <var>property</var> and <var>value</var>, it must return
1249 <code>true</code> if <var>property</var> is a literal match for the name
1250 of a CSS property that the UA supports, and <var>value</var> would be
1251 successfully parsed as a supported value for that property. Otherwise, it
1252 must return <code>false</code>.
1253 <p> When invoked with a single <var>conditionText</var> argument, it must
1254 return <code>true</code> if <var>conditionText</var>, when parsed and
1255 evaluated as a <a
1256 href="#supports_condition"><code>supports_condition</code></a>, would
1257 return true. Otherwise, it must return <code>false</code>.
1258 </dl>
1260 <h2 class=no-num id=grammar>Grammar</h2>
1262 <p>In order to allow these new @-rules in CSS style sheets, this
1263 specification modifies the <code>stylesheet</code> production in the <a
1264 href="http://www.w3.org/TR/CSS21/grammar.html">Appendix G</a> grammar of
1265 <a href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a> by replacing
1266 the <a href="#media"><code>media</code></a> production defined in <a
1267 href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a> with the <a
1268 href="#media"><code>media</code></a> production defined in this one, and
1269 additionally inserting <code>| supports_rule</code> alongside
1270 <code>ruleset | media | page</code>.
1272 <h2 id=conformance><span class=secno>8. </span>Conformance</h2>
1274 <h3 id=base-modules><span class=secno>8.1. </span>Base Modules</h3>
1276 <p>This specification defines conformance in terms of base modules, which
1277 are modules that this specification builds on top of. The base modules of
1278 this module are:
1280 <ul>
1281 <li><a href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>
1282 </ul>
1284 <p>All of the conformance requirements of all base modules are incorporated
1285 as conformance requirements of this module, except where overridden by
1286 this module.
1288 <p>Additionally, all conformance requirements related to validity of syntax
1289 in this module and all of its base modules are to be interpreted as though
1290 all syntax in all of those modules is valid.
1292 <div class=example>
1293 <p>For example, this means that grammar presented in modules other than <a
1294 href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a> must obey the
1295 requirements that <a href="#CSS21"
1296 rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a> defines for the parsing of
1297 properties, and that requirements for handling invalid syntax in <a
1298 href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a> do not treat
1299 syntax added by other modules as invalid.
1300 </div>
1302 <p>Additionally, the set of valid syntax can be increased by the
1303 conformance of a style sheet or processor to additional modules; use of
1304 such syntax does not make a style sheet nonconformant and failure to treat
1305 such syntax as invalid does not make a processor nonconformant.
1307 <h3 id=conformance-classes><span class=secno>8.2. </span>Conformance
1308 Classes</h3>
1310 <p>Conformance to the CSS Conditional Rules Module is defined for three
1311 conformance classes:
1313 <dl>
1314 <dt><dfn id=conform-style-sheet title="conformance::style sheet">style
1315 sheet</dfn>
1317 <dd>A <a href="http://www.w3.org/TR/CSS21/conform.html#style-sheet">CSS
1318 style sheet</a>.
1320 <dt><dfn id=conform-processor
1321 title="conformance::processor">processor</dfn>
1323 <dd>A tool that reads CSS style sheets: it may be a renderer or <a
1324 href="http://www.w3.org/TR/CSS21/conform.html#user-agent">user-agent</a>
1325 that interprets the semantics of a style sheet and renders documents that
1326 use style sheets, or it may be a validator that checks style sheets.
1328 <dt><dfn id=conform-authoring-tool
1329 title="conformance::authoring tool">authoring tool</dfn>
1331 <dd>A tool that writes a style sheet.
1332 </dl>
1334 <p>A style sheet is conformant to the CSS Conditional Rules Module if it
1335 meets all of the conformance requirements in the module that are described
1336 as requirements of style sheets.
1338 <p>A processor is conformant to the CSS Conditional Rules Module if it
1339 meets all applicable conformance requirements in the module that are
1340 described as requirements of processors. In general, all requirements are
1341 applicable to renderers. Requirements concerning a part of CSS not
1342 performed by a processor are not applicable, e.g., requirements related to
1343 rendering are not applicable to a validator. The inability of a processor
1344 to correctly render a document due to limitations of the device does not
1345 make it non-conformant. (For example, a renderer is not required to render
1346 color on a monochrome monitor.)
1348 <p>An authoring tool is conformant to the CSS Conditional Rules Module if
1349 it writes style sheets that conform to the module and (if it reads CSS) it
1350 is a conformant processor.
1352 <h3 id=partial><span class=secno>8.3. </span> Partial Implementations</h3>
1354 <p>So that authors can exploit the forward-compatible parsing rules to
1355 assign fallback values, CSS renderers <strong>must</strong> treat as
1356 invalid (and <a
1357 href="http://www.w3.org/TR/CSS21/conform.html#ignore">ignore as
1358 appropriate</a>) any at-rules, properties, property values, keywords, and
1359 other syntactic constructs for which they have no usable level of support.
1360 In particular, user agents <strong>must not</strong> selectively ignore
1361 unsupported component values and honor supported values in a single
1362 multi-value property declaration: if any value is considered invalid (as
1363 unsupported values must be), CSS requires that the entire declaration be
1364 ignored.
1366 <h3 id=experimental><span class=secno>8.4. </span>Experimental
1367 Implementations</h3>
1369 <p>To avoid clashes with future CSS features, the CSS specifications
1370 reserve a <a
1371 href="http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords">prefixed
1372 syntax</a> for proprietary property and value extensions to CSS. The CSS
1373 Working Group recommends that experimental implementations of features in
1374 CSS Working Drafts also use vendor-prefixed property or value names. This
1375 avoids any incompatibilities with future changes in the draft. Once a
1376 specification reaches the Candidate Recommendation stage, implementors
1377 should implement the non-prefixed syntax for any feature they consider to
1378 be correctly implemented according to spec.
1380 <h3 id=cr-exit-criteria><span class=secno>8.5. </span>CR Exit Criteria</h3>
1382 <p>For this specification to be advanced to Proposed Recommendation, there
1383 must be at least two independent, interoperable implementations of each
1384 feature. Each feature may be implemented by a different set of products,
1385 there is no requirement that all features be implemented by a single
1386 product. For the purposes of this criterion, we define the following
1387 terms:
1389 <dl>
1390 <dt>independent
1392 <dd>each implementation must be developed by a different party and cannot
1393 share, reuse, or derive from code used by another qualifying
1394 implementation. Sections of code that have no bearing on the
1395 implementation of this specification are exempt from this requirement.
1397 <dt>interoperable
1399 <dd>passing the respective test case(s) in the official CSS test suite,
1400 or, if the implementation is not a Web browser, an equivalent test. Every
1401 relevant test in the test suite should have an equivalent test created if
1402 such a user agent (UA) is to be used to claim interoperability. In
1403 addition if such a UA is to be used to claim interoperability, then there
1404 must one or more additional UAs which can also pass those equivalent
1405 tests in the same way for the purpose of interoperability. The equivalent
1406 tests must be made publicly available for the purposes of peer review.
1408 <dt>implementation
1410 <dd>a user agent which:
1411 <ol class=inline>
1412 <li>implements the specification.
1414 <li>is available to the general public. The implementation may be a
1415 shipping product or other publicly available version (i.e., beta
1416 version, preview release, or “nightly build”). Non-shipping product
1417 releases must have implemented the feature(s) for a period of at least
1418 one month in order to demonstrate stability.
1420 <li>is not experimental (i.e., a version specifically designed to pass
1421 the test suite and is not intended for normal usage going forward).
1422 </ol>
1423 </dl>
1425 <p>The specification will remain Candidate Recommendation for at least six
1426 months.
1428 <h2 id=changes><span class=secno>9. </span> Changes</h2>
1430 <p>The following (non-editorial) changes were made to this specification
1431 since the <a
1432 href="http://www.w3.org/TR/2012/WD-css3-conditional-20120911/">11
1433 September 2012 Working Draft</a>:
1435 <ul>
1436 <li>Removed ‘<code class=css>@document</code>’ rule; it has been
1437 deferred to Level 4.
1439 <li>Allow functional notation in ‘<code class=css>@supports</code>’
1440 queries to be valid (to allow for future extensions), but treat such
1441 notations as always being false.
1443 <li>Corrected the grammar as follows:
1444 <pre>
1445 - : SUPPORTS_SYM S+ supports_condition group_rule_body
1446 + : SUPPORTS_SYM S* supports_condition group_rule_body
1447 </pre>
1449 <pre>
1450 - : (URI | FUNCTION) S*
1451 + : (URI | FUNCTION S* STRING S* ')' ) S*
1452 </pre>
1454 <li>Switched "and", "or", and "not" keywords to use appropriate
1455 productions rather than literals.
1457 <li>Clarified definition of support used for interpreting ‘<code
1458 class=css>@support</code>’ rules and its relationship to CSS
1459 forwards-compatible parsing rules.
1460 </ul>
1462 <h2 class=no-num id=acknowledgments>Acknowledgments</h2>
1464 <p> Thanks to the ideas and feedback from Tab Atkins, <span lang=tr>Tantek
1465 Çelik</span>, Alex Danilo, Elika Etemad, Pascal Germroth, <span
1466 lang=de>Björn Höhrmann</span>, Paul Irish, <span lang=nl>Anne van
1467 Kesteren</span>, Vitor Menezes, Alex Mogilevsky, Chris Moschini, Simon
1468 Sapin, Ben Ward, Zack Weinberg, Estelle Weyl, Boris Zbarsky, and all the
1469 rest of the <a
1470 href="http://lists.w3.org/Archives/Public/www-style/">www-style</a>
1471 community.
1473 <h2 class=no-num id=references>References</h2>
1475 <h3 class=no-num id=normative-references>Normative references</h3>
1476 <!--begin-normative-->
1477 <!-- Sorted by label -->
1479 <dl class=bibliography>
1480 <dt style="display: none"><!-- keeps the doc valid if the DL is empty -->
1481 <!---->
1483 <dt id=CSS21>[CSS21]
1485 <dd>Bert Bos; et al. <a
1486 href="http://www.w3.org/TR/2011/REC-CSS2-20110607/"><cite>Cascading Style
1487 Sheets Level 2 Revision 1 (CSS 2.1) Specification.</cite></a> 7 June
1488 2011. W3C Recommendation. URL: <a
1489 href="http://www.w3.org/TR/2011/REC-CSS2-20110607/">http://www.w3.org/TR/2011/REC-CSS2-20110607/</a>
1490 </dd>
1491 <!---->
1493 <dt id=CSS3-ANIMATIONS>[CSS3-ANIMATIONS]
1495 <dd>Dean Jackson; et al. <a
1496 href="http://www.w3.org/TR/2012/WD-css3-animations-20120403/"><cite>CSS
1497 Animations.</cite></a> 3 April 2012. W3C Working Draft. (Work in
1498 progress.) URL: <a
1499 href="http://www.w3.org/TR/2012/WD-css3-animations-20120403/">http://www.w3.org/TR/2012/WD-css3-animations-20120403/</a>
1500 </dd>
1501 <!---->
1503 <dt id=CSS3-FONTS>[CSS3-FONTS]
1505 <dd>John Daggett. <a
1506 href="http://www.w3.org/TR/2012/WD-css3-fonts-20121211/"><cite>CSS Fonts
1507 Module Level 3.</cite></a> 11 December 2012. W3C Working Draft. (Work in
1508 progress.) URL: <a
1509 href="http://www.w3.org/TR/2012/WD-css3-fonts-20121211/">http://www.w3.org/TR/2012/WD-css3-fonts-20121211/</a>
1510 </dd>
1511 <!---->
1513 <dt id=MEDIAQ>[MEDIAQ]
1515 <dd>Florian Rivoal. <a
1516 href="http://www.w3.org/TR/2012/REC-css3-mediaqueries-20120619/"><cite>Media
1517 Queries.</cite></a> 19 June 2012. W3C Recommendation. URL: <a
1518 href="http://www.w3.org/TR/2012/REC-css3-mediaqueries-20120619/">http://www.w3.org/TR/2012/REC-css3-mediaqueries-20120619/</a>
1519 </dd>
1520 <!---->
1522 <dt id=RFC2119>[RFC2119]
1524 <dd>S. Bradner. <a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>Key
1525 words for use in RFCs to Indicate Requirement Levels.</cite></a> Internet
1526 RFC 2119. URL: <a
1527 href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>
1528 </dd>
1529 <!---->
1530 </dl>
1531 <!--end-normative-->
1533 <h3 class=no-num id=other-references>Other references</h3>
1534 <!--begin-informative-->
1535 <!-- Sorted by label -->
1537 <dl class=bibliography>
1538 <dt style="display: none"><!-- keeps the doc valid if the DL is empty -->
1539 <!---->
1541 <dt id=CSS1>[CSS1]
1543 <dd>Håkon Wium Lie; Bert Bos. <a
1544 href="http://www.w3.org/TR/2008/REC-CSS1-20080411"><cite>Cascading Style
1545 Sheets (CSS1) Level 1 Specification.</cite></a> 11 April 2008. W3C
1546 Recommendation. URL: <a
1547 href="http://www.w3.org/TR/2008/REC-CSS1-20080411">http://www.w3.org/TR/2008/REC-CSS1-20080411</a>
1548 </dd>
1549 <!---->
1551 <dt id=CSS3-TRANSITIONS>[CSS3-TRANSITIONS]
1553 <dd>Dean Jackson; et al. <a
1554 href="http://www.w3.org/TR/2012/WD-css3-transitions-20120403/"><cite>CSS
1555 Transitions.</cite></a> 3 April 2012. W3C Working Draft. (Work in
1556 progress.) URL: <a
1557 href="http://www.w3.org/TR/2012/WD-css3-transitions-20120403/">http://www.w3.org/TR/2012/WD-css3-transitions-20120403/</a>
1558 </dd>
1559 <!---->
1560 </dl>
1561 <!--end-informative-->
1563 <h2 class=no-num id=index>Index</h2>
1564 <!--begin-index-->
1566 <ul class=indexlist>
1567 <li>conditional group rules, <a href="#conditional-group-rules"
1568 title="section 2."><strong>2.</strong></a>
1570 <li>conformance
1571 <ul>
1572 <li>authoring tool, <a href="#conform-authoring-tool"
1573 title="section 8.2."><strong>8.2.</strong></a>
1575 <li>processor, <a href="#conform-processor"
1576 title="section 8.2."><strong>8.2.</strong></a>
1578 <li>style sheet, <a href="#conform-style-sheet"
1579 title="section 8.2."><strong>8.2.</strong></a>
1580 </ul>
1582 <li><a href="#CSS-interface"><code>CSS</code></a>, <a
1583 href="#CSS-interface" title="section 7.6."><strong>7.6.</strong></a>
1585 <li><a href="#cssconditionrule"><code>CSSConditionRule</code></a>, <a
1586 href="#cssconditionrule" title="section 7.3."><strong>7.3.</strong></a>
1588 <li><a href="#cssgroupingrule"><code>CSSGroupingRule</code></a>, <a
1589 href="#cssgroupingrule" title="section 7.2."><strong>7.2.</strong></a>
1591 <li><a href="#cssmediarule"><code>CSSMediaRule</code></a>, <a
1592 href="#cssmediarule" title="section 7.4."><strong>7.4.</strong></a>
1594 <li><a href="#csssupportsrule"><code>CSSSupportsRule</code></a>, <a
1595 href="#csssupportsrule" title="section 7.5."><strong>7.5.</strong></a>
1597 <li>general_enclosed, <a href="#general_enclosed"
1598 title="section 6."><strong>6.</strong></a>
1600 <li>group rule body, <a href="#group-rule-body"
1601 title="section 3."><strong>3.</strong></a>
1603 <li>group_rule_body, <a href="#group_rule_body"
1604 title="section 3."><strong>3.</strong></a>
1606 <li>media, <a href="#media" title="section 5."><strong>5.</strong></a>
1608 <li>‘<code class=css>@media</code>’ rule, <a href="#atmedia-rule"
1609 title="section 5."><strong>5.</strong></a>
1611 <li>nested_statement, <a href="#nested_statement"
1612 title="section 3."><strong>3.</strong></a>
1614 <li>support, <a href="#dfn-support"
1615 title="section 6.1."><strong>6.1.</strong></a>
1617 <li>supports_condition, <a href="#supports_condition"
1618 title="section 6."><strong>6.</strong></a>
1620 <li>supports_condition_in_parens, <a href="#supports_condition_in_parens"
1621 title="section 6."><strong>6.</strong></a>
1623 <li>supports_conjunction, <a href="#supports_conjunction"
1624 title="section 6."><strong>6.</strong></a>
1626 <li>supports_declaration_condition, <a
1627 href="#supports_declaration_condition"
1628 title="section 6."><strong>6.</strong></a>
1630 <li>supports_disjunction, <a href="#supports_disjunction"
1631 title="section 6."><strong>6.</strong></a>
1633 <li>supports_negation, <a href="#supports_negation"
1634 title="section 6."><strong>6.</strong></a>
1636 <li>‘<code class=css>@supports</code>’ rule, <a
1637 href="#atsupports-rule" title="section 6."><strong>6.</strong></a>
1639 <li>supports_rule, <a href="#supports_rule"
1640 title="section 6."><strong>6.</strong></a>
1641 </ul>
1642 <!--end-index-->
1643 </html>
1644 <!-- Keep this comment at the end of the file
1645 Local variables:
1646 mode: sgml
1647 sgml-declaration:"~/SGML/HTML4.decl"
1648 sgml-default-doctype-name:"html"
1649 sgml-minimize-attributes:t
1650 sgml-nofill-elements:("pre" "style" "br")
1651 sgml-live-element-indicator:t
1652 sgml-omittag:nil
1653 sgml-shorttag:nil
1654 sgml-namecase-general:t
1655 sgml-general-insert-case:lower
1656 sgml-always-quote-attributes:t
1657 sgml-indent-step:nil
1658 sgml-indent-data:t
1659 sgml-parent-document:nil
1660 sgml-exposed-tags:nil
1661 sgml-local-catalogs:nil
1662 sgml-local-ecat-files:nil
1663 End:
1664 -->
