css3-conditional/Overview.html@06244e910e27
css3-conditional/Overview.html
Wed, 06 Feb 2013 23:47:11 -0800
- author
- L. David Baron <dbaron@dbaron.org>
- date
- Wed, 06 Feb 2013 23:47:11 -0800
- changeset 7381
- 06244e910e27
- parent 7374
- 34b185ae3bac
- child 7382
- 6e5d9a1539bd
- permissions
- -rw-r--r--
[css3-conditional] Make examples represent slighty better practices.
Addresses issue raised in
http://lists.w3.org/Archives/Public/www-style/2012Dec/0224.html
which is issue 1 in the LCWD disposition of comments.
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-07 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-20130207/"
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 7 February
37 2013</h2>
39 <dl>
40 <dt>This version:
42 <dd><a href="http://www.w3.org/TR/2013/ED-css3-conditional-20130207/">
43 http://www.w3.org/TR/2013/ED-css3-conditional-20130207/</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 /* hide navigation controls when printing */
368 #navigation { display: none }
369 }</pre>
371 <p>causes a particular CSS rule (making elements with ID "navigation" be
372 display:none) apply only when the style sheet is used for a print medium.
373 </div>
375 <p>Each conditional group rule has a condition, which at any time evaluates
376 to true or false. When the condition is true, CSS processors
377 <strong>must</strong> apply the rules inside the group rule as though they
378 were at the group rule's location; when the condition is false, CSS
379 processors <strong>must not</strong> apply any of rules inside the group
380 rule. The current state of the condition does not affect the CSS object
381 model, in which the contents of the group rule always remain within the
382 group rule.
384 <p>This means that when multiple conditional group rules are nested, a rule
385 inside of both of them applies only when all of the rules' conditions are
386 true.
388 <div class=example>For example, with this set of nested rules:
389 <pre>@media print { // rule (1)
390 /* hide navigation controls when printing */
391 #navigation { display: none }
392 @media (max-width: 12cm) { // rule (2)
393 /* keep notes in flow when printing to narrow pages */
394 .note { float: none }
395 }
396 }</pre>
397 the condition of the rule marked (1) is true for print media, and the
398 condition of the rule marked (2) is true when the width of the display
399 area (which for print media is the page box) is less than or equal to
400 12cm. Thus the rule ‘<code class=css>#navigation { display: none
401 }</code>’ applies whenever this style sheet is applied to print media,
402 and the rule ‘<code class=css>.note { float: none }</code>’ is applied
403 only when the style sheet is applied to print media <em>and</em> the width
404 of the page box is less than or equal to 12 centimeters.</div>
406 <p>When the condition for a conditional group rule changes, CSS processors
407 <strong>must</strong> reflect that the rules now apply or no longer apply,
408 except for properties whose definitions define effects of computed values
409 that persist past the lifetime of that value (such as for some properties
410 in <a href="#CSS3-TRANSITIONS"
411 rel=biblioentry>[CSS3-TRANSITIONS]<!--{{CSS3-TRANSITIONS}}--></a> and <a
412 href="#CSS3-ANIMATIONS"
413 rel=biblioentry>[CSS3-ANIMATIONS]<!--{{!CSS3-ANIMATIONS}}--></a>).
415 <h2 id=contents-of><span class=secno>3. </span>Contents of conditional
416 group rules</h2>
418 <p>The syntax of each conditional group rule consists of some syntax
419 specific to the type of rule followed by a <dfn id=group-rule-body>group
420 rule body</dfn>, which is a block (pair of braces) containing a sequence
421 of rules.
423 <p>A group rule body is allowed to contain rulesets and any @-rules that
424 are allowed at the top level of a style sheet before and after a ruleset.
425 This means that @-rules that must occur at the beginning of the style
426 sheet (such as ‘<code class=css>@charset</code>’, ‘<code
427 class=css>@import</code>’, and ‘<code class=css>@namespace</code>’
428 rules) are not allowed inside of conditional group rules. Conditional
429 group rules can be nested.
431 <p>In terms of the grammar, this specification defines the following
432 productions for use in the grammar of conditional group rules:
434 <pre><dfn id="nested_statement">nested_statement</dfn>
435 : ruleset | <a
436 href="#media"><i>media</i></a> | page | font_face_rule | keyframes_rule |
437 <a
438 href="#supports_rule"><i>supports_rule</i></a>
439 ;
441 <dfn
442 id="group_rule_body">group_rule_body</dfn>
443 : '{' S* <a
444 href="#nested_statement"><i>nested_statement</i></a>* '}' S*
445 ;</pre>
447 <p> in which all the productions are defined in that grammar with the
448 exception of <code>font_face_rule</code> defined in <a href="#CSS3-FONTS"
449 rel=biblioentry>[CSS3-FONTS]<!--{{!CSS3-FONTS}}--></a>,
450 <code>keyframes_rule</code> defined in <a href="#CSS3-ANIMATIONS"
451 rel=biblioentry>[CSS3-ANIMATIONS]<!--{{!CSS3-ANIMATIONS}}--></a>, and <a
452 href="#media"><code>media</code></a> and <a
453 href="#supports_rule"><code>supports_rule</code></a> defined in this
454 specification.
456 <p>In general, future CSS specifications that add new @-rules that are not
457 forbidden to occur after some other types of rules should modify this <a
458 href="#nested_statement"><code>nested_statement</code></a> production to
459 keep the grammar accurate.
461 <p>Style sheets <strong>must not</strong> use rules other than the allowed
462 ones inside conditional group rules.
464 <p>CSS processors <strong>must</strong> ignore rules that are not allowed
465 within a group rule, and <strong>must</strong> handle invalid rules inside
466 of group rules as described in <a
467 href="http://www.w3.org/TR/CSS21/syndata.html#parsing-errors">section 4.2
468 (Rules for handling parsing errors)</a>, <a
469 href="http://www.w3.org/TR/CSS21/syndata.html#at-rules">section 4.1.5
470 (At-rules)</a>, and <a
471 href="http://www.w3.org/TR/CSS21/syndata.html#rule-sets">section 4.1.7
472 (Rule sets, declaration blocks, and selectors)</a> of <a href="#CSS21"
473 rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>.
475 <h2 id=use><span class=secno>4. </span>Placement of conditional group rules</h2>
477 <p>Conditional group rules are allowed at the top-level of a style sheet,
478 and inside other conditional group rules. CSS processors
479 <strong>must</strong> process such rules as <a
480 href="#processing">described above</a>.
482 <p>Any rules that are not allowed after a ruleset (e.g., ‘<code
483 class=css>@charset</code>’, ‘<code class=css>@import</code>’, or
484 ‘<code class=css>@namespace</code>’ rules) are also not allowed after
485 a conditional group rule. Therefore, style sheets <strong>must
486 not</strong> place such rules after a conditional group rules, and CSS
487 processors <strong>must</strong> ignore such rules.
489 <h2 id=at-media><span class=secno>5. </span>Media-specific style sheets:
490 the ‘<code class=css>@media</code>’ rule</h2>
492 <p>The <dfn id=atmedia-rule>‘<code class=css>@media</code>’ rule</dfn>
493 is a conditional group rule whose condition is a media query. It consists
494 of the at-keyword ‘<code class=css>@media</code>’ followed by a
495 (possibly empty) media query list (as defined in <a href="#MEDIAQ"
496 rel=biblioentry>[MEDIAQ]<!--{{!MEDIAQ}}--></a>), followed by a group rule
497 body. The condition of the rule is the result of the media query.
499 <div class=example>
500 <p>This ‘<code class=css>@media</code>’ rule:
502 <pre>@media screen and (min-width: 35em),
503 print and (min-width: 40em) {
504 #section_navigation { float: left; width: 10em; }
505 }</pre>
507 <p>has the condition ‘<code class=css>screen and (min-width: 35em),
508 print and (min-width: 40em)</code>’, which is true for screen displays
509 whose viewport is at least 35 times the initial font size and for print
510 displays whose viewport is at least 40 times the initial font size. When
511 either of these is true, the condition of the rule is true, and the rule
512 ‘<code class=css>#section_navigation { float: left; width: 10em;
513 }</code>’ is applied.
514 </div>
516 <p>In terms of the grammar, this specification extends the <a
517 href="#media"><code>media</code></a> production in the <a
518 href="http://www.w3.org/TR/CSS21/grammar.html">Grammar of CSS 2.1</a> (<a
519 href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>, Appendix G)
520 into:
522 <pre><dfn id=media>media</dfn>
523 : MEDIA_SYM S* media_query_list <a
524 href="#group_rule_body"><i>group_rule_body</i></a>
525 ;</pre>
527 <p>where the <a href="#group_rule_body"><code>group_rule_body</code></a>
528 production is defined in this specification, the
529 <code>media_query_list</code> production is defined in <a href="#MEDIAQ"
530 rel=biblioentry>[MEDIAQ]<!--{{!MEDIAQ}}--></a>, and the others are defined
531 in the <a href="http://www.w3.org/TR/CSS21/grammar.html">Grammar of CSS
532 2.1</a> (<a href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>,
533 Appendix G).
535 <h2 id=at-supports><span class=secno>6. </span>Feature queries: the
536 ‘<code class=css>@supports</code>’ rule</h2>
538 <p>The <dfn id=atsupports-rule>‘<code class=css>@supports</code>’
539 rule</dfn> is a conditional group rule whose condition tests whether the
540 user agent supports CSS property:value pairs. Authors can use it to write
541 style sheets that use new features when available but degrade gracefully
542 when those features are not supported. CSS has existing mechanisms for
543 graceful degradation, such as ignoring unsupported properties or values,
544 but these are not always sufficient when large groups of styles need to be
545 tied to the support for certain features, as is the case for use of new
546 layout system features.
548 <p>The syntax of the condition in the ‘<code
549 class=css>@supports</code>’ rule is slightly more complicated than for
550 the other conditional group rules (though has some similarities to media
551 queries) since:
553 <ul>
554 <li>negation is needed so that the new-feature styles and the fallback
555 styles can be separated (within the forward-compatible grammar's rules
556 for the syntax of @-rules), and not required to override each other
558 <li>conjunction (and) is needed so that multiple required features can be
559 tested
561 <li>disjunction (or) is needed when there are multiple alternative
562 features for a set of styles, particularly when some of those
563 alternatives are vendor-prefixed properties or values
564 </ul>
566 <p>Therefore, the syntax of the ‘<code class=css>@supports</code>’ rule
567 allows testing for property:value pairs, and arbitrary conjunctions (and),
568 disjunctions (or), and negations (not) of them.
570 <p>This extends the lexical scanner in the <a
571 href="http://www.w3.org/TR/CSS21/grammar.html">Grammar of CSS 2.1</a> (<a
572 href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>, Appendix G) by
573 adding:
575 <pre>
576 @{S}{U}{P}{P}{O}{R}{T}{S} {return SUPPORTS_SYM;}
577 {O}{R} {return OR;}
578 </pre>
580 <p>and the grammar by adding
582 <pre><dfn id="supports_rule">supports_rule</dfn>
583 : SUPPORTS_SYM S* <a
584 href="#supports_condition"><i>supports_condition</i></a> S* <a
585 href="#group_rule_body"><i>group_rule_body</i></a>
586 ;
588 <dfn
589 id="supports_condition">supports_condition</dfn>
590 : <a
591 href="#supports_negation"><i>supports_negation</i></a> | <a
592 href="#supports_conjunction"><i>supports_conjunction</i></a> | <a
593 href="#supports_disjunction"><i>supports_disjunction</i></a> |
594 <a
595 href="#supports_condition_in_parens"><i>supports_condition_in_parens</i></a>
596 ;
598 <dfn
599 id="supports_condition_in_parens">supports_condition_in_parens</dfn>
600 : ( '(' S* <a
601 href="#supports_condition"><i>supports_condition</i></a> S* ')' ) | <a
602 href="#supports_declaration_condition"><i>supports_declaration_condition</i></a> |
603 <a
604 href="#general_enclosed"><i>general_enclosed</i></a>
605 ;
607 <dfn
608 id="supports_negation">supports_negation</dfn>
609 : NOT S+ <a
610 href="#supports_condition_in_parens"><i>supports_condition_in_parens</i></a>
611 ;
613 <dfn
614 id="supports_conjunction">supports_conjunction</dfn>
615 : <a
616 href="#supports_condition_in_parens"><i>supports_condition_in_parens</i></a> ( S+ AND S+ <a
617 href="#supports_condition_in_parens"><i>supports_condition_in_parens</i></a> )+
618 ;
620 <dfn
621 id="supports_disjunction">supports_disjunction</dfn>
622 : <a
623 href="#supports_condition_in_parens"><i>supports_condition_in_parens</i></a> ( S+ OR S+ <a
624 href="#supports_condition_in_parens"><i>supports_condition_in_parens</i></a> )+
625 ;
627 <dfn
628 id="supports_declaration_condition">supports_declaration_condition</dfn>
629 : '(' S* declaration ')'
630 ;
632 <dfn
633 id="general_enclosed">general_enclosed</dfn>
634 : ( FUNCTION | '(' ) ( any | unused )* ')'
635 ;
636 </pre>
638 <p>in which <code>declaration</code>, <code>any</code>, and
639 <code>unused</code> are the productions in the core syntax of CSS defined
640 in <a href="http://www.w3.org/TR/CSS21/syndata.html#tokenization">section
641 4.1.1 (Tokenization)</a> of <a href="#CSS21"
642 rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>, and the <code>AND</code> and
643 <code>NOT</code> tokens are defined in the Media Queries specification <a
644 href="#MEDIAQ" rel=biblioentry>[MEDIAQ]<!--{{!MEDIAQ}}--></a>.
646 <p> Implementations <strong>must</strong> parse ‘<code
647 class=css>@supports</code>’ rules based on the above grammar, and when
648 interpreting the above grammar, <strong>must</strong> match the production
649 before an <code>|</code> operator in preference to the one after it.
651 <p> The above grammar is purposely very loose for forwards-compatibility
652 reasons, since the <a
653 href="#general_enclosed"><code>general_enclosed</code></a> production
654 allows for substantial future extensibility. Any ‘<code
655 class=css>@supports</code>’ rule that does not parse according to the
656 grammar above (that is, a rule that does not match this loose grammar
657 which includes the general_enclosed production) is invalid. Style sheets
658 <strong>must not</strong> use such a rule and processors
659 <strong>must</strong> ignore such a rule (including all of its contents).
661 <p>Each of these grammar terms is associated with a boolean result, as
662 follows:
664 <dl>
665 <dt>supports_condition
667 <dd> The result is the result of the single child term.
669 <dt>supports_condition_in_parens
671 <dd> The result is the result of the single <a
672 href="#supports_condition"><code>supports_condition</code></a> or <a
673 href="#supports_declaration_condition"><code>supports_declaration_condition</code></a>
674 child term.
676 <dt>supports_negation
678 <dd> The result is the <em>negation</em> of the result of the <a
679 href="#supports_condition_in_parens"><code>supports_condition_in_parens</code></a>
680 child term.
682 <dt>supports_conjunction
684 <dd> The result is true if the result of <em>all</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_disjunction
690 <dd> The result is true if the result of <em>any</em> of the <a
691 href="#supports_condition_in_parens"><code>supports_condition_in_parens</code></a>
692 child terms is true; otherwise it is false.
694 <dt>supports_declaration_condition
696 <dd> The result is whether the CSS processor <a
697 href="#support-definition">supports</a> the declaration within the
698 parentheses.
700 <dt>general_enclosed
702 <dd> The result is always false. Additionally, style sheets <strong>must
703 not</strong> write ‘<code class=css>@supports</code>’ rules that
704 match this grammar production. (In other words, this production exists
705 only for future extensibility, and is not part of the description of a
706 valid style sheet in this level of the specification.) <span
707 class=note>Note that future levels may define functions or other
708 parenthesized expressions that can evaluate to true.</span>
709 </dl>
711 <p>The condition of the ‘<code class=css>@supports</code>’ rule is the
712 result of the <a
713 href="#supports_condition"><code>supports_condition</code></a> term that
714 is a child of the <a href="#supports_rule"><code>supports_rule</code></a>
715 term.
717 <div class=example>
718 <p>For example, the following rule
720 <pre>@supports ( display: flexbox ) {
721 body, #navigation, #content { display: flexbox; }
722 #navigation { background: blue; color: white; }
723 #article { background: white; color: black; }
724 }</pre>
726 <p>applies the rules inside the ‘<code class=css>@supports</code>’
727 rule only when ‘<code class=css>display: flexbox</code>’ is
728 supported.
729 </div>
731 <div class=example>
732 <p>The following example shows an additional ‘<code
733 class=css>@supports</code>’ rule that can be used to provide an
734 alternative for when ‘<code class=css>display: flexbox</code>’ is not
735 supported:
737 <pre>@supports not ( display: flexbox ) {
738 body { width: 100%; height: 100%; background: white; color: black; }
739 #navigation { width: 25%; }
740 #article { width: 75%; }
741 }</pre>
743 <p>Note that the ‘<code class=property>width</code>’ declarations may
744 be harmful to the flexbox-based layout, so it is important that they be
745 present only in the non-flexbox styles.
746 </div>
748 <div class=example>
749 <p>The following example checks for support for the ‘<code
750 class=property>box-shadow</code>’ property, including checking for
751 support for vendor-prefixed versions of it. When the support is present,
752 it specifies both ‘<code class=property>box-shadow</code>’ (with the
753 prefixed versions) and ‘<code class=property>color</code>’ in a way
754 what would cause the text to become invisible were ‘<code
755 class=property>box-shadow</code>’ not supported.
757 <pre>@supports ( box-shadow: 2px 2px 2px black ) or
758 ( -moz-box-shadow: 2px 2px 2px black ) or
759 ( -webkit-box-shadow: 2px 2px 2px black ) or
760 ( -o-box-shadow: 2px 2px 2px black ) {
761 .outline {
762 color: white;
763 -moz-box-shadow: 2px 2px 2px black;
764 -webkit-box-shadow: 2px 2px 2px black;
765 -o-box-shadow: 2px 2px 2px black;
766 box-shadow: 2px 2px 2px black; /* unprefixed last */
767 }
768 }</pre>
769 </div>
771 <p>To avoid confusion between ‘<code class=css>and</code>’ and ‘<code
772 class=css>or</code>’, the syntax requires that both ‘<code
773 class=css>and</code>’ and ‘<code class=css>or</code>’ be specified
774 explicitly (rather than, say, using commas or spaces for one of them).
775 Likewise, to avoid confusion caused by precedence rules, the syntax does
776 not allow ‘<code class=css>and</code>’, ‘<code
777 class=css>or</code>’, and ‘<code class=css>not</code>’ operators to
778 be mixed without a layer of parentheses.
780 <div class=example>
781 <p>For example, the following rule is not valid:
783 <pre class=illegal>@supports (transition-property: color) or
784 (animation-name: foo) and
785 (transform: rotate(10deg)) {
786 // ...
787 }</pre>
789 <p>Instead, authors must write one of the following:
791 <pre>@supports ((transition-property: color) or
792 (animation-name: foo)) and
793 (transform: rotate(10deg)) {
794 // ...
795 }</pre>
797 <pre>@supports (transition-property: color) or
798 ((animation-name: foo) and
799 (transform: rotate(10deg))) {
800 // ...
801 }</pre>
802 </div>
804 <p>Furthermore, whitespace is required after a ‘<code
805 class=css>not</code>’ and on both sides of an ‘<code
806 class=css>and</code>’ or ‘<code class=css>or</code>’.
808 <p>The declaration being tested must always occur within parentheses, when
809 it is the only thing in the expression.
811 <p>
813 <div class=example>
814 <p>For example, the following rule is not valid:
816 <pre class=illegal>@supports display: flexbox {
817 // ...
818 }</pre>
820 <p>Instead, authors must write:
822 <pre>@supports (display: flexbox) {
823 // ...
824 }</pre>
825 </div>
827 <p>The syntax allows extra parentheses when they are not needed. This
828 flexibility is sometimes useful for authors (for example, when commenting
829 out parts of an expression) and may also be useful for authoring tools.
831 <div class=example>
832 <p>For example, authors may write:
834 <pre>@supports ((display: flexbox)) {
835 // ...
836 }</pre>
837 </div>
839 <p>A trailing ‘<code class=css>!important</code>’ on a declaration
840 being tested is allowed, though it won't change the validity of the
841 declaration.
843 <div class=example>
844 <p>For example, the following rule is valid:
846 <pre>@supports (display: flexbox !important) {
847 // ...
848 }</pre>
849 </div>
851 <h3 id=support-definition><span class=secno>6.1. </span>Definition of
852 support</h3>
854 <p>For forward-compatibility, <a
855 href="http://www.w3.org/TR/CSS21/syndata.html#declaration">section 4.1.8
856 (Declarations and properties)</a> of <a href="#CSS21"
857 rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a> defines rules for handling
858 invalid properties and values. CSS processors that do not implement or
859 partially implement a specification <strong>must</strong> treat any part
860 of a value that they do not implement, or do not have a usable level of
861 support for, as invalid according to this rule for handling invalid
862 properties and values, and therefore <strong>must</strong> discard the
863 declaration as a parse error.
865 <p>A CSS processor is considered to <dfn id=dfn-support>support</dfn> a
866 declaration (consisting of a property and value) if it accepts that
867 declaration (rather than discarding it as a parse error). If a processor
868 does not implement, with a usable level of support, the value given, then
869 it <strong>must not</strong> accept the declaration or claim support for
870 it.
872 <p>These rules (and the equivalence between them) allow authors to use
873 fallback (either in the <a href="#CSS1"
874 rel=biblioentry>[CSS1]<!--{{CSS1}}--></a> sense of declarations that are
875 overridden by later declarations or with the new capabilities provided by
876 the ‘<code class=css>@supports</code>’ rule in this specification)
877 that works correctly for the features implemented. This applies especially
878 to compound values; implementations must implement all parts of the value
879 in order to consider the declaration supported, either inside a ruleset or
880 in the declaration condition of an ‘<code class=css>@supports</code>’
881 rule.</p>
882 <!--
883 <h2 id="at-document">Document queries: the '@document' rule</h2>
885 <p>The <dfn>'@document' rule</dfn> is a conditional group
886 rule whose condition depends on the
887 <a href="#url-of-doc">URL of the document being styled</a>.
888 This allows style sheets, particularly user style sheets, to have styles
889 that only apply to a set of pages rather than to all pages using the
890 style sheet.</p>
892 <p class="issue">Given that this @-rule is intended primarily for user
893 style sheets, what should this specification say about its use in author
894 style sheets? Should it be forbidden? Should use instead be
895 discouraged? Or should this specification remain neutral on the
896 topic, since there are valid uses in author style sheets?</p>
898 <p id="url-of-doc">The <dfn>URL of the document being styled</dfn> is
899 the URI at which the document is located, excluding any fragment
900 identifiers. (This means, for example, that HTTP redirects have been
901 followed.) If the styles are being applied inside a complete document
902 embedded into the presentation of another (e.g., [[HTML5]]'s <code
903 class="html">iframe</code>, <code class="html">object</code>, or <code
904 class="html">img</code> elements), the relevant URI is that of the
905 frame, not of its container. However, if content from other documents
906 is mixed in via mechanisms that mix content from one document into
907 another (e.g., [[SVG11]]'s <code>use</code> element), then the
908 address of the container document is used.</p>
910 <p class="note">Note: In [[HTML5]], this is the
911 <a href="http://dev.w3.org/html5/spec/dom.html#documents">document's address</a>
912 of a document in a
913 <a href="http://dev.w3.org/html5/spec/browsers.html#browsing-context">browsing context</a>.</p>
915 <div class="issue">What form of normalization is done on URLs and domains
916 before matching? In particular, this specification needs to describe:
917 <ul>
918 <li>what form is used for the <a href="#url-of-doc">URL of the document
919 being styled</a> (and what has been normalized in that form)</li>
920 <li>what normalization (if any) happens to the argument of each of the match
921 functions before the comparison that they describe and</li>
922 <li>whether the
923 comparison algorithm used is string comparison or some other URL
924 comparison algorithm.</li></ul></div>
926 <p>The '@document' rule's condition is written as a
927 comma-separated list of <dfn>URL matching functions</dfn>, and the
928 condition evaluates to true whenever any one of those functions
929 evaluates to true. The following URL matching functions are
930 permitted:</p>
932 <dl>
933 <dt><dfn id="url-exact" title="url()|URL matching functions::exact"><url></dfn></dt>
935 <dd>
936 <p>The 'url()' function is the <dfn>exact url matching
937 function</dfn>. It evaluates to true whenever the <a
938 href="#url-of-doc">URL of the document being styled</a> is exactly
939 the URL given.</p>
941 <p class="Note">The 'url()' function, since it is a core syntax
942 element in CSS, is allowed (subject to different character
943 limitations and thus escaping requirements) to contain an unquoted
944 value (in addition to the string values that are allowed as
945 arguments for all four functions).</p>
947 <div class="example">
948 <p>For example, this rule:</p>
949 <pre>@document url("http://www.w3.org/Style/CSS/") {
950 #summary { background: yellow; color: black}
951 }</pre>
952 <p>styles the <code class="html">summary</code> element on the page
953 <code>http://www.w3.org/Style/CSS/</code>, but not on any other
954 pages.</p>
955 </div>
956 </dd>
958 <dt><dfn id="url-prefix" title="url-prefix()|URL matching functions::prefix">url-prefix(<string>)</dfn></dt>
960 <dd>
961 <p>The 'url-prefix()' function is the <dfn>url prefix
962 matching function</dfn>. It evaluates to true whenever the
963 <a href="#url-of-doc">URL of the document being styled</a>
964 has the argument to the function as an
965 initial substring (which is true when the two strings are equal).
966 When the argument is the empty string, it evaluates to true for all
967 documents.</p>
968 <div class="example">
969 <p>For example, this rule:</p>
970 <pre>@document url-prefix("http://www.w3.org/Style/CSS/") {
971 #summary { background: yellow; color: black}
972 }</pre>
973 <p>styles the <code class="html">summary</code> element on the page
974 <code>http://www.w3.org/Style/CSS/</code> and on the page
975 <code>http://www.w3.org/Style/CSS/Test</code>, but it does not
976 affect the page <code>http://www.w3.org/</code> or the page
977 <code>http://www.example.com/Style/CSS/</code>.</p>
978 </div>
979 </dd>
981 <dt><dfn id="url-domain" title="domain()|URL matching functions::domain">domain(<string>)</dfn></dt>
983 <dd>
984 <p>The 'domain()' function is the <dfn>domain
985 matching function</dfn>. It evaluates to true whenever
986 the <a href="#url-of-doc">URL of the document being styled</a>
987 has a host subcomponent (as defined in [[!URI]])
988 and that host subcomponent is exactly the argument to the
989 'domain()' function or a final substring of the host
990 component is a period (U+002E) immediately followed by the argument
991 to the 'domain()' function.</p>
992 <div class="example">
993 <p>For example, this rule:</p>
994 <pre>@document domain("w3.org") {
995 body { font-size: 16px ! important }
996 }</pre>
997 <p>changes the font size of the body element for pages such as
998 <code>http://www.w3.org/Style/CSS/</code> and
999 <code>http://w3.org/Style/CSS/</code> and
1000 <code>http://lists.w3.org/Archives/Public/www-style/</code>
1001 but it does not affect the page
1002 <code>http://www.example.com/Style/CSS/</code>.</p>
1003 </div>
1004 </dd>
1006 <dt><dfn id="url-regexp" title="regexp()|URL matching functions::regular expression">regexp(<string>)</dfn></dt>
1008 <dd>
1009 <p>The contents of the <string> argument <strong>must</strong>
1010 match the JavaScript <code>Pattern</code> production
1011 ([[!ECMA-262-5.1]], section 15.10.1). However,
1012 failing to do so is not a CSS syntax error and does not trigger any
1013 error handling for CSS syntax errors.</p>
1015 <p>The ''regexp()'' function evaluates to true whenever the string
1016 argument compiled as a JavaScript regular expression with the
1017 <code>global</code>, <code>ignoreCase</code> and
1018 <code>multiline</code> flags <em>disabled</em>
1019 (see [[!ECMA-262-5.1]], sections 15.10.7.2 through 15.10.7.4)
1020 compiles successfully and the resulting regular expression matches
1021 the entirety of the
1022 <a href="#url-of-doc">URL of the document being styled</a>.</p>
1024 <p class="note">Note that regular expression must match the entire
1025 URL, not just a part of it.</p>
1027 <p class="note">Note that this definition intentionally matches the
1028 behavior of the <a
1029 href="http://dev.w3.org/html5/spec/common-input-element-attributes.html#attr-input-pattern"><code class="html">pattern</code>
1030 attribute</a> on the <code class="html">input</code> element
1031 in [[HTML5]].</p>
1033 <div class="example">
1034 <p>For example, this rule:</p>
1035 <pre>@document regexp("http://www.w3.org/TR/\\d{4}/[^/]*-CSS2-\\d{8}/") {
1036 body { font-size: 20px ! important }
1037 }</pre>
1038 <p>changes the font size of the body element for pages such as
1039 <code>http://www.w3.org/TR/2011/PR-CSS2-20110412/</code>.</p>
1040 <p class="note">Note that the backslashes in the regular
1041 expression require CSS escaping as ''\\''.</p>
1042 </div>
1043 </dd>
1045 </dl>
1047 <p>Implementations <strong>must</strong> treat any unknown URL matching
1048 functions as a syntax error, and thus ignore the '@document' rule.
1049 <span class="issue">Should we instead have more complicated error
1050 handling rules to make forward-compatibility work differently, or is
1051 this rule the best solution for such future expansion anyway?</span></p>
1053 <div class="issue">This syntax doesn't offer any ability to do negations,
1054 which has been requested in <a
1055 href="https://bugzilla.mozilla.org/show_bug.cgi?id=349813">Mozilla bug
1056 349813</a>. Use cases that people have wanted negations for
1057 include:
1058 <ul>
1059 <li>User style sheets that want a particular rule in general, but know
1060 that that rule does more harm than good on specific sites.</li>
1061 <li>Authors who have a rule that they want to apply to most of their
1062 pages, but wish to make a few exceptions for.</li>
1063 </ul>
1064 </div>
1066 <p>This extends the lexical scanner in the
1067 <a href="http://www.w3.org/TR/CSS21/grammar.html">Grammar of CSS 2.1</a>
1068 ([[!CSS21]], Appendix G) by adding:
1069 <pre>@{D}{O}{C}{U}{M}{E}{N}{T} {return DOCUMENT_SYM;}</pre>
1070 <p>and the grammar by adding</p>
1071 <pre><dfn>document_rule</dfn>
1072 : DOCUMENT_SYM S+ <i>url_match_fn</i> ( "," S* <i>url_match_fn</i> )* <i>group_rule_body</i>
1073 ;
1075 <dfn>url_match_fn</dfn>
1076 : (URI | FUNCTION S* STRING S* ')' ) S*
1077 ;</pre>
1078 -->
1080 <h2 id=apis><span class=secno>7. </span>APIs</h2>
1082 <h3 id=extentions-to-cssrule-interface><span class=secno>7.1. </span>
1083 Extensions to the <code>CSSRule</code> interface</h3>
1085 <p>The <code>CSSRule</code> interface is extended as follows:
1087 <pre class=idl>partial interface CSSRule {
1088 const unsigned short SUPPORTS_RULE = 12;
1089 <!--
1090 const unsigned short DOCUMENT_RULE = 13;
1091 -->
1092 }</pre>
1094 <h3 id=the-cssgroupingrule-interface><span class=secno>7.2. </span> The <a
1095 href="#cssgroupingrule"><code>CSSGroupingRule</code></a> interface</h3>
1097 <p>The <dfn id=cssgroupingrule><code>CSSGroupingRule</code></dfn> interface
1098 represents an at-rule that contains other rules nested inside itself.
1100 <pre class=idl>interface CSSGroupingRule : CSSRule {
1101 readonly attribute <a
1102 href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSRuleList">CSSRuleList</a> cssRules;
1103 unsigned long insertRule (DOMString rule, unsigned long index);
1104 void deleteRule (unsigned long index);
1105 }</pre>
1107 <dl class=idl-attributes>
1108 <dt><code>cssRules</code> of type <code><a
1109 href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSRuleList">CSSRuleList</a></code>,
1110 readonly
1112 <dd>The <code>cssRules</code> attribute must return a
1113 <code>CSSRuleList</code> object for the list of CSS rules nested inside
1114 the grouping rule.
1115 </dl>
1117 <dl class=idl-methods>
1118 <dt><code>insertRule(DOMString rule, unsigned long index)</code>, returns
1119 <code>unsigned long</code>
1121 <dd> The <code>insertRule</code> operation must insert a CSS rule
1122 <var>rule</var> into the CSS rule list returned by <code>cssRules</code>,
1123 such that the inserted rule will be at position <var>index</var>, and any
1124 rules previously at <var>index</var> or higher will increase their index
1125 by one. It must throw INDEX_SIZE_ERR if index is greater than
1126 <code>cssRules.length</code>. It must throw SYNTAX_ERR if the rule has a
1127 syntax error and is unparseable; this does not include syntax errors
1128 handled by error handling rules for constructs inside of the rule. It
1129 must throw HIERARCHY_REQUEST_ERR if the rule cannot be inserted at the
1130 location specified, for example, if an ‘<code
1131 class=css>@import</code>’ rule is inserted inside a group rule. <span
1132 class=issue>This needs to specify what to do if <code>rule</code> is the
1133 empty string, if it contains more than one CSS rule, or if it contains
1134 garbage after a valid rule.</span>
1136 <dt><code>deleteRule (unsigned long index)</code>, return
1137 <code>void</code>
1139 <dd> The <code>deleteRule</code> operation must remove a CSS rule from the
1140 CSS rule list returned by <code>cssRules</code> at <var>index</var>. It
1141 must throw INDEX_SIZE_ERR if index is greater than or equal to
1142 <code>cssRules.length</code>.
1143 </dl>
1145 <h3 id=the-cssconditionrule-interface><span class=secno>7.3. </span> The <a
1146 href="#cssconditionrule"><code>CSSConditionRule</code></a> interface</h3>
1148 <p>The <dfn id=cssconditionrule><code>CSSConditionRule</code></dfn>
1149 interface represents all the "conditional" at-rules, which consist of a
1150 condition and a statement block.
1152 <pre class=idl>interface CSSConditionRule : CSSGroupingRule {
1153 attribute DOMString conditionText;
1154 }</pre>
1156 <dl class=idl-attributes>
1157 <dt><code>conditionText</code> of type <code>DOMString</code>
1159 <dd>
1160 <p>The <code>conditionText</code> attribute represents the condition of
1161 the rule. Since what this condition does varies between the derived
1162 interfaces of <a
1163 href="#cssconditionrule"><code>CSSConditionRule</code></a>, those
1164 derived interfaces may specify different behavior for this attribute
1165 (see, for example, <a href="#cssmediarule"><code>CSSMediaRule</code></a>
1166 below). In the absence of such rule-specific behavior, the following
1167 rules apply:
1169 <p>The <code>conditionText</code> attribute, on getting, must return the
1170 result of serializing the associated condition.
1172 <p>On setting the <code>conditionText</code> attribute these steps must
1173 be run:
1175 <ol>
1176 <li>Trim the given value of white space.
1178 <li>If the given value matches the grammar of the appropriate condition
1179 production for the given rule, replace the associated CSS condition
1180 with the given value.
1182 <li>Otherwise, do nothing.
1183 </ol>
1184 </dl>
1186 <h3 id=the-cssmediarule-interface><span class=secno>7.4. </span> The <a
1187 href="#cssmediarule"><code>CSSMediaRule</code></a> interface</h3>
1189 <p>The <dfn id=cssmediarule><code>CSSMediaRule</code></dfn> interface
1190 represents a ‘<code class=css>@media</code>’ rule:
1192 <pre class=idl>interface CSSMediaRule : CSSConditionRule {
1193 readonly attribute <a
1194 href="http://www.w3.org/TR/DOM-Level-2-Style/stylesheets.html#StyleSheets-MediaList">MediaList</a> media;
1195 }</pre>
1197 <dl class=idl-attributes>
1198 <dt><a href="#media"><code>media</code></a> of type <code><a
1199 href="http://www.w3.org/TR/DOM-Level-2-Style/stylesheets.html#StyleSheets-MediaList">MediaList</a></code>,
1200 readonly
1202 <dd>The <a href="#media"><code>media</code></a> attribute must return a
1203 <code>MediaList</code> object for the list of media queries specified
1204 with the ‘<code class=css>@media</code>’ rule.
1206 <dt><code>conditionText</code> of type <code>DOMString</code>
1208 <dd>The <code>conditionText</code> attribute (defined on the <a
1209 href="#cssconditionrule"><code>CSSConditionRule</code></a> parent rule),
1210 on getting, must return the value of <code>media.mediaText</code> on the
1211 rule.
1212 <p>Setting the <code>conditionText</code> attribute must set the
1213 <code>media.mediaText</code> attribute on the rule.
1214 </dl>
1216 <h3 id=the-csssupportsrule-interface><span class=secno>7.5. </span> The <a
1217 href="#csssupportsrule"><code>CSSSupportsRule</code></a> interface</h3>
1219 <p>The <dfn id=csssupportsrule><code>CSSSupportsRule</code></dfn> interface
1220 represents a ‘<code class=css>@supports</code>’ rule.
1222 <pre class=idl>interface CSSSupportsRule : CSSConditionRule {
1223 }</pre>
1224 <!--
1225 <h3 id="the-cssdocumentrule-interface">
1226 The <code>CSSDocumentRule</code> interface</h3>
1228 <p>The <dfn><code>CSSDocumentRule</code></dfn> interface represents a ''@document'' rule.</p>
1230 <pre class='idl'>interface CSSDocumentRule : CSSConditionRule {
1231 }</pre>
1232 -->
1234 <h3 id=the-css-interface><span class=secno>7.6. </span> The <a
1235 href="#CSS-interface"><code>CSS</code></a> interface, and the <code
1236 title="">supports()</code> function</h3>
1238 <p>The <dfn id=CSS-interface><code>CSS</code></dfn> interface holds useful
1239 CSS-related functions that do not belong elsewhere.
1241 <pre class=idl>interface CSS {
1242 static boolean supports(DOMString property, DOMString value);
1243 static boolean supports(DOMString conditionText);
1244 }</pre>
1246 <dl class=idl-methods>
1247 <dt><code>supports(DOMString property, DOMString value)</code>, returns
1248 <code>boolean</code>
1250 <dt><code>supports(DOMString conditionText)</code>, returns
1251 <code>boolean</code>
1253 <dd> When the <code title="">supports()</code> method is invoked with two
1254 arguments <var>property</var> and <var>value</var>, it must return
1255 <code>true</code> if <var>property</var> is a literal match for the name
1256 of a CSS property that the UA supports, and <var>value</var> would be
1257 successfully parsed as a supported value for that property. Otherwise, it
1258 must return <code>false</code>.
1259 <p> When invoked with a single <var>conditionText</var> argument, it must
1260 return <code>true</code> if <var>conditionText</var>, when parsed and
1261 evaluated as a <a
1262 href="#supports_condition"><code>supports_condition</code></a>, would
1263 return true. Otherwise, it must return <code>false</code>.
1264 </dl>
1266 <h2 class=no-num id=grammar>Grammar</h2>
1268 <p>In order to allow these new @-rules in CSS style sheets, this
1269 specification modifies the <code>stylesheet</code> production in the <a
1270 href="http://www.w3.org/TR/CSS21/grammar.html">Appendix G</a> grammar of
1271 <a href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a> by replacing
1272 the <a href="#media"><code>media</code></a> production defined in <a
1273 href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a> with the <a
1274 href="#media"><code>media</code></a> production defined in this one, and
1275 additionally inserting <code>| supports_rule</code> alongside
1276 <code>ruleset | media | page</code>.
1278 <h2 id=conformance><span class=secno>8. </span>Conformance</h2>
1280 <h3 id=base-modules><span class=secno>8.1. </span>Base Modules</h3>
1282 <p>This specification defines conformance in terms of base modules, which
1283 are modules that this specification builds on top of. The base modules of
1284 this module are:
1286 <ul>
1287 <li><a href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>
1288 </ul>
1290 <p>All of the conformance requirements of all base modules are incorporated
1291 as conformance requirements of this module, except where overridden by
1292 this module.
1294 <p>Additionally, all conformance requirements related to validity of syntax
1295 in this module and all of its base modules are to be interpreted as though
1296 all syntax in all of those modules is valid.
1298 <div class=example>
1299 <p>For example, this means that grammar presented in modules other than <a
1300 href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a> must obey the
1301 requirements that <a href="#CSS21"
1302 rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a> defines for the parsing of
1303 properties, and that requirements for handling invalid syntax in <a
1304 href="#CSS21" rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a> do not treat
1305 syntax added by other modules as invalid.
1306 </div>
1308 <p>Additionally, the set of valid syntax can be increased by the
1309 conformance of a style sheet or processor to additional modules; use of
1310 such syntax does not make a style sheet nonconformant and failure to treat
1311 such syntax as invalid does not make a processor nonconformant.
1313 <h3 id=conformance-classes><span class=secno>8.2. </span>Conformance
1314 Classes</h3>
1316 <p>Conformance to the CSS Conditional Rules Module is defined for three
1317 conformance classes:
1319 <dl>
1320 <dt><dfn id=conform-style-sheet title="conformance::style sheet">style
1321 sheet</dfn>
1323 <dd>A <a href="http://www.w3.org/TR/CSS21/conform.html#style-sheet">CSS
1324 style sheet</a>.
1326 <dt><dfn id=conform-processor
1327 title="conformance::processor">processor</dfn>
1329 <dd>A tool that reads CSS style sheets: it may be a renderer or <a
1330 href="http://www.w3.org/TR/CSS21/conform.html#user-agent">user-agent</a>
1331 that interprets the semantics of a style sheet and renders documents that
1332 use style sheets, or it may be a validator that checks style sheets.
1334 <dt><dfn id=conform-authoring-tool
1335 title="conformance::authoring tool">authoring tool</dfn>
1337 <dd>A tool that writes a style sheet.
1338 </dl>
1340 <p>A style sheet is conformant to the CSS Conditional Rules Module if it
1341 meets all of the conformance requirements in the module that are described
1342 as requirements of style sheets.
1344 <p>A processor is conformant to the CSS Conditional Rules Module if it
1345 meets all applicable conformance requirements in the module that are
1346 described as requirements of processors. In general, all requirements are
1347 applicable to renderers. Requirements concerning a part of CSS not
1348 performed by a processor are not applicable, e.g., requirements related to
1349 rendering are not applicable to a validator. The inability of a processor
1350 to correctly render a document due to limitations of the device does not
1351 make it non-conformant. (For example, a renderer is not required to render
1352 color on a monochrome monitor.)
1354 <p>An authoring tool is conformant to the CSS Conditional Rules Module if
1355 it writes style sheets that conform to the module and (if it reads CSS) it
1356 is a conformant processor.
1358 <h3 id=partial><span class=secno>8.3. </span> Partial Implementations</h3>
1360 <p>So that authors can exploit the forward-compatible parsing rules to
1361 assign fallback values, CSS renderers <strong>must</strong> treat as
1362 invalid (and <a
1363 href="http://www.w3.org/TR/CSS21/conform.html#ignore">ignore as
1364 appropriate</a>) any at-rules, properties, property values, keywords, and
1365 other syntactic constructs for which they have no usable level of support.
1366 In particular, user agents <strong>must not</strong> selectively ignore
1367 unsupported component values and honor supported values in a single
1368 multi-value property declaration: if any value is considered invalid (as
1369 unsupported values must be), CSS requires that the entire declaration be
1370 ignored.
1372 <h3 id=experimental><span class=secno>8.4. </span>Experimental
1373 Implementations</h3>
1375 <p>To avoid clashes with future CSS features, the CSS specifications
1376 reserve a <a
1377 href="http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords">prefixed
1378 syntax</a> for proprietary property and value extensions to CSS. The CSS
1379 Working Group recommends that experimental implementations of features in
1380 CSS Working Drafts also use vendor-prefixed property or value names. This
1381 avoids any incompatibilities with future changes in the draft. Once a
1382 specification reaches the Candidate Recommendation stage, implementors
1383 should implement the non-prefixed syntax for any feature they consider to
1384 be correctly implemented according to spec.
1386 <h3 id=cr-exit-criteria><span class=secno>8.5. </span>CR Exit Criteria</h3>
1388 <p>For this specification to be advanced to Proposed Recommendation, there
1389 must be at least two independent, interoperable implementations of each
1390 feature. Each feature may be implemented by a different set of products,
1391 there is no requirement that all features be implemented by a single
1392 product. For the purposes of this criterion, we define the following
1393 terms:
1395 <dl>
1396 <dt>independent
1398 <dd>each implementation must be developed by a different party and cannot
1399 share, reuse, or derive from code used by another qualifying
1400 implementation. Sections of code that have no bearing on the
1401 implementation of this specification are exempt from this requirement.
1403 <dt>interoperable
1405 <dd>passing the respective test case(s) in the official CSS test suite,
1406 or, if the implementation is not a Web browser, an equivalent test. Every
1407 relevant test in the test suite should have an equivalent test created if
1408 such a user agent (UA) is to be used to claim interoperability. In
1409 addition if such a UA is to be used to claim interoperability, then there
1410 must one or more additional UAs which can also pass those equivalent
1411 tests in the same way for the purpose of interoperability. The equivalent
1412 tests must be made publicly available for the purposes of peer review.
1414 <dt>implementation
1416 <dd>a user agent which:
1417 <ol class=inline>
1418 <li>implements the specification.
1420 <li>is available to the general public. The implementation may be a
1421 shipping product or other publicly available version (i.e., beta
1422 version, preview release, or “nightly build”). Non-shipping product
1423 releases must have implemented the feature(s) for a period of at least
1424 one month in order to demonstrate stability.
1426 <li>is not experimental (i.e., a version specifically designed to pass
1427 the test suite and is not intended for normal usage going forward).
1428 </ol>
1429 </dl>
1431 <p>The specification will remain Candidate Recommendation for at least six
1432 months.
1434 <h2 id=changes><span class=secno>9. </span> Changes</h2>
1436 <p>The following (non-editorial) changes were made to this specification
1437 since the <a
1438 href="http://www.w3.org/TR/2012/WD-css3-conditional-20120911/">11
1439 September 2012 Working Draft</a>:
1441 <ul>
1442 <li>Removed ‘<code class=css>@document</code>’ rule; it has been
1443 deferred to Level 4.
1445 <li>Allow functional notation in ‘<code class=css>@supports</code>’
1446 queries to be valid (to allow for future extensions), but treat such
1447 notations as always being false.
1449 <li>Corrected the grammar as follows:
1450 <pre>
1451 - : SUPPORTS_SYM S+ supports_condition group_rule_body
1452 + : SUPPORTS_SYM S* supports_condition group_rule_body
1453 </pre>
1455 <pre>
1456 - : (URI | FUNCTION) S*
1457 + : (URI | FUNCTION S* STRING S* ')' ) S*
1458 </pre>
1460 <li>Switched "and", "or", and "not" keywords to use appropriate
1461 productions rather than literals.
1463 <li>Clarified definition of support used for interpreting ‘<code
1464 class=css>@support</code>’ rules and its relationship to CSS
1465 forwards-compatible parsing rules.
1466 </ul>
1468 <h2 class=no-num id=acknowledgments>Acknowledgments</h2>
1470 <p> Thanks to the ideas and feedback from Tab Atkins, <span lang=tr>Tantek
1471 Çelik</span>, Alex Danilo, Elika Etemad, Pascal Germroth, <span
1472 lang=de>Björn Höhrmann</span>, Paul Irish, <span lang=nl>Anne van
1473 Kesteren</span>, Vitor Menezes, Alex Mogilevsky, Chris Moschini, Simon
1474 Sapin, Ben Ward, Zack Weinberg, Estelle Weyl, Boris Zbarsky, and all the
1475 rest of the <a
1476 href="http://lists.w3.org/Archives/Public/www-style/">www-style</a>
1477 community.
1479 <h2 class=no-num id=references>References</h2>
1481 <h3 class=no-num id=normative-references>Normative references</h3>
1482 <!--begin-normative-->
1483 <!-- Sorted by label -->
1485 <dl class=bibliography>
1486 <dt style="display: none"><!-- keeps the doc valid if the DL is empty -->
1487 <!---->
1489 <dt id=CSS21>[CSS21]
1491 <dd>Bert Bos; et al. <a
1492 href="http://www.w3.org/TR/2011/REC-CSS2-20110607/"><cite>Cascading Style
1493 Sheets Level 2 Revision 1 (CSS 2.1) Specification.</cite></a> 7 June
1494 2011. W3C Recommendation. URL: <a
1495 href="http://www.w3.org/TR/2011/REC-CSS2-20110607/">http://www.w3.org/TR/2011/REC-CSS2-20110607/</a>
1496 </dd>
1497 <!---->
1499 <dt id=CSS3-ANIMATIONS>[CSS3-ANIMATIONS]
1501 <dd>Dean Jackson; et al. <a
1502 href="http://www.w3.org/TR/2012/WD-css3-animations-20120403/"><cite>CSS
1503 Animations.</cite></a> 3 April 2012. W3C Working Draft. (Work in
1504 progress.) URL: <a
1505 href="http://www.w3.org/TR/2012/WD-css3-animations-20120403/">http://www.w3.org/TR/2012/WD-css3-animations-20120403/</a>
1506 </dd>
1507 <!---->
1509 <dt id=CSS3-FONTS>[CSS3-FONTS]
1511 <dd>John Daggett. <a
1512 href="http://www.w3.org/TR/2012/WD-css3-fonts-20121211/"><cite>CSS Fonts
1513 Module Level 3.</cite></a> 11 December 2012. W3C Working Draft. (Work in
1514 progress.) URL: <a
1515 href="http://www.w3.org/TR/2012/WD-css3-fonts-20121211/">http://www.w3.org/TR/2012/WD-css3-fonts-20121211/</a>
1516 </dd>
1517 <!---->
1519 <dt id=MEDIAQ>[MEDIAQ]
1521 <dd>Florian Rivoal. <a
1522 href="http://www.w3.org/TR/2012/REC-css3-mediaqueries-20120619/"><cite>Media
1523 Queries.</cite></a> 19 June 2012. W3C Recommendation. URL: <a
1524 href="http://www.w3.org/TR/2012/REC-css3-mediaqueries-20120619/">http://www.w3.org/TR/2012/REC-css3-mediaqueries-20120619/</a>
1525 </dd>
1526 <!---->
1528 <dt id=RFC2119>[RFC2119]
1530 <dd>S. Bradner. <a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>Key
1531 words for use in RFCs to Indicate Requirement Levels.</cite></a> Internet
1532 RFC 2119. URL: <a
1533 href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>
1534 </dd>
1535 <!---->
1536 </dl>
1537 <!--end-normative-->
1539 <h3 class=no-num id=other-references>Other references</h3>
1540 <!--begin-informative-->
1541 <!-- Sorted by label -->
1543 <dl class=bibliography>
1544 <dt style="display: none"><!-- keeps the doc valid if the DL is empty -->
1545 <!---->
1547 <dt id=CSS1>[CSS1]
1549 <dd>Håkon Wium Lie; Bert Bos. <a
1550 href="http://www.w3.org/TR/2008/REC-CSS1-20080411"><cite>Cascading Style
1551 Sheets (CSS1) Level 1 Specification.</cite></a> 11 April 2008. W3C
1552 Recommendation. URL: <a
1553 href="http://www.w3.org/TR/2008/REC-CSS1-20080411">http://www.w3.org/TR/2008/REC-CSS1-20080411</a>
1554 </dd>
1555 <!---->
1557 <dt id=CSS3-TRANSITIONS>[CSS3-TRANSITIONS]
1559 <dd>Dean Jackson; et al. <a
1560 href="http://www.w3.org/TR/2012/WD-css3-transitions-20120403/"><cite>CSS
1561 Transitions.</cite></a> 3 April 2012. W3C Working Draft. (Work in
1562 progress.) URL: <a
1563 href="http://www.w3.org/TR/2012/WD-css3-transitions-20120403/">http://www.w3.org/TR/2012/WD-css3-transitions-20120403/</a>
1564 </dd>
1565 <!---->
1566 </dl>
1567 <!--end-informative-->
1569 <h2 class=no-num id=index>Index</h2>
1570 <!--begin-index-->
1572 <ul class=indexlist>
1573 <li>conditional group rules, <a href="#conditional-group-rules"
1574 title="section 2."><strong>2.</strong></a>
1576 <li>conformance
1577 <ul>
1578 <li>authoring tool, <a href="#conform-authoring-tool"
1579 title="section 8.2."><strong>8.2.</strong></a>
1581 <li>processor, <a href="#conform-processor"
1582 title="section 8.2."><strong>8.2.</strong></a>
1584 <li>style sheet, <a href="#conform-style-sheet"
1585 title="section 8.2."><strong>8.2.</strong></a>
1586 </ul>
1588 <li><a href="#CSS-interface"><code>CSS</code></a>, <a
1589 href="#CSS-interface" title="section 7.6."><strong>7.6.</strong></a>
1591 <li><a href="#cssconditionrule"><code>CSSConditionRule</code></a>, <a
1592 href="#cssconditionrule" title="section 7.3."><strong>7.3.</strong></a>
1594 <li><a href="#cssgroupingrule"><code>CSSGroupingRule</code></a>, <a
1595 href="#cssgroupingrule" title="section 7.2."><strong>7.2.</strong></a>
1597 <li><a href="#cssmediarule"><code>CSSMediaRule</code></a>, <a
1598 href="#cssmediarule" title="section 7.4."><strong>7.4.</strong></a>
1600 <li><a href="#csssupportsrule"><code>CSSSupportsRule</code></a>, <a
1601 href="#csssupportsrule" title="section 7.5."><strong>7.5.</strong></a>
1603 <li>general_enclosed, <a href="#general_enclosed"
1604 title="section 6."><strong>6.</strong></a>
1606 <li>group rule body, <a href="#group-rule-body"
1607 title="section 3."><strong>3.</strong></a>
1609 <li>group_rule_body, <a href="#group_rule_body"
1610 title="section 3."><strong>3.</strong></a>
1612 <li>media, <a href="#media" title="section 5."><strong>5.</strong></a>
1614 <li>‘<code class=css>@media</code>’ rule, <a href="#atmedia-rule"
1615 title="section 5."><strong>5.</strong></a>
1617 <li>nested_statement, <a href="#nested_statement"
1618 title="section 3."><strong>3.</strong></a>
1620 <li>support, <a href="#dfn-support"
1621 title="section 6.1."><strong>6.1.</strong></a>
1623 <li>supports_condition, <a href="#supports_condition"
1624 title="section 6."><strong>6.</strong></a>
1626 <li>supports_condition_in_parens, <a href="#supports_condition_in_parens"
1627 title="section 6."><strong>6.</strong></a>
1629 <li>supports_conjunction, <a href="#supports_conjunction"
1630 title="section 6."><strong>6.</strong></a>
1632 <li>supports_declaration_condition, <a
1633 href="#supports_declaration_condition"
1634 title="section 6."><strong>6.</strong></a>
1636 <li>supports_disjunction, <a href="#supports_disjunction"
1637 title="section 6."><strong>6.</strong></a>
1639 <li>supports_negation, <a href="#supports_negation"
1640 title="section 6."><strong>6.</strong></a>
1642 <li>‘<code class=css>@supports</code>’ rule, <a
1643 href="#atsupports-rule" title="section 6."><strong>6.</strong></a>
1645 <li>supports_rule, <a href="#supports_rule"
1646 title="section 6."><strong>6.</strong></a>
1647 </ul>
1648 <!--end-index-->
1649 </html>
1650 <!-- Keep this comment at the end of the file
1651 Local variables:
1652 mode: sgml
1653 sgml-declaration:"~/SGML/HTML4.decl"
1654 sgml-default-doctype-name:"html"
1655 sgml-minimize-attributes:t
1656 sgml-nofill-elements:("pre" "style" "br")
1657 sgml-live-element-indicator:t
1658 sgml-omittag:nil
1659 sgml-shorttag:nil
1660 sgml-namecase-general:t
1661 sgml-general-insert-case:lower
1662 sgml-always-quote-attributes:t
1663 sgml-indent-step:nil
1664 sgml-indent-data:t
1665 sgml-parent-document:nil
1666 sgml-exposed-tags:nil
1667 sgml-local-catalogs:nil
1668 sgml-local-ecat-files:nil
1669 End:
1670 -->
