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