- From: Tab Atkins Jr.. via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 27 Oct 2011 01:18:28 +0000
- To: public-css-commits@w3.org
Update of /sources/public/csswg/css-variables
In directory hutz:/tmp/cvs-serv12283
Modified Files:
Overview.html Overview.src.html
Log Message:
Finish rewrite of 'Defining Variables' section to the new data-properties form.
Index: Overview.html
===================================================================
RCS file: /sources/public/csswg/css-variables/Overview.html,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -d -r1.15 -r1.16
--- Overview.html 26 Oct 2011 01:16:09 -0000 1.15
+++ Overview.html 27 Oct 2011 01:18:26 -0000 1.16
@@ -22,14 +22,14 @@
<h1>CSS Variables Module Level 1</h1>
- <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 26 October
+ <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 27 October
2011</h2>
<dl>
<dt>This version:
<dd><a
- href="http://www.w3.org/TR/2011/ED-css-variables-20111026/">http://dev.w3.org/csswg/css-variables/</a>
+ href="http://www.w3.org/TR/2011/ED-css-variables-20111027/">http://dev.w3.org/csswg/css-variables/</a>
<!--<dt>Latest version:
<dd><a href="http://www.w3.org/TR/css-variables/">http://www.w3.org/TR/css-variables/</a>-->
@@ -208,18 +208,19 @@
across multiple files), and may not be amenable to Find-and-Replace.
<p>This module introduces a family of custom user-defined properties known
- collectively as <b>Variables</b>, which allow an author to assign values
- to a property with an author-chosen name, and then use those values in
- other properties elsewhere in the document. This makes it easier to read
- large files, as seemingly-arbitrary values now have informative names, and
- makes editting such files much easier and less error-prone, as one only
- has to change the value once, at the variable definition site, and the
- change will propagate to all uses of that variable automatically.
+ collectively as <a href="#data-property"><i>data properties</i></a>, which
+ allow an author to assign arbitrary values to a property with an
+ author-chosen name, and then use those values in other properties
+ elsewhere in the document. This makes it easier to read large files, as
+ seemingly-arbitrary values now have informative names, and makes editting
+ such files much easier and less error-prone, as one only has to change the
+ value once, at the variable definition site, and the change will propagate
+ to all uses of that variable automatically.
<h3 id=placement><span class=secno>1.1. </span> Module Interactions</h3>
<p>This module defines a new type of primitive value, the <a
- href="#variable"><b>Variable</b></a>, which is accepted by all properties.
+ href="#variable"><i>variable</i></a>, which is accepted by all properties.
<h3 id=values><span class=secno>1.2. </span> Values</h3>
@@ -286,7 +287,7 @@
</table>
<div class=example>
- <p>This variables declaration:</p>
+ <p>This style rule:</p>
<pre>
:root {
@@ -309,89 +310,99 @@
variable declaration.</p>
</div>
- <p class=issue>Finish replacing the rest of this section.
+ <p>There is no restriction on the possible names for <a
+ href="#data-property"><i>data properties</i></a>, except that they must
+ start with "data-" and be a valid identifier like any other property name.
+ Data properties are ordinary properties, so they can be declared on any
+ element, are resolved with the normal inheritance and cascade rules, can
+ be made conditional with ‘<code class=css>@media</code>’ and
+ other conditional rules, can be used in HTML's <code>style</code>
+ attribute, can be read or set using the CSSOM, etc..
- <p>Defined variables are available to all stylesheets in the document.
- Thus, using ‘<code class=css>@import</code>’ to include a
- stylesheet also includes all variables defined in the stylesheet (and
- makes all variables declared outside available within the stylesheet, if
- applicable). ‘<code class=css>@var</code>’ rules present in
- disabled or alternate stylesheets do not define variables. Scoped
- stylesheets are an exception to this: variables defined in the global
- scope are available within a scoped stylesheet, but variables defined or
- imported within scoped stylesheets are only available within the scoped
- stylesheet and any imported stylesheets.
+ <div class=example>
+ <p>If a variable is declared multiple times, the standard cascade rules
+ help resolve it:</p>
- <p>A ‘<code class=css>@var</code>’ rule is <dfn
- id=inactive-var-rule>inactive</dfn> if it's present in a disabled or
- alternate stylesheet, a stylesheet with a media query that evaluates to
- false, or is present within a conditional rule group [[CSS3CONDITIONAL]]
- whose condition evaluates to false. <a
- href="#inactive-var-rule"><i>Inactive</i></a> ‘<code
- class=css>@var</code>’ rules do not define variables. All other
- ‘<code class=css>@var</code>’ rules are <dfn
- id=active-var-rule>active</dfn>.
+ <pre>
+:root { data-color: blue; }
+div { data-color: green; }
+#alert { data-color: red; }
+* { color: data(color); }
- <p>If new ‘<code class=css>@var</code>’ rules are added to the
- document through any means, such as direct CSSOM manipulation or new
- stylesheets being added to the document, or if an <a
- href="#inactive-var-rule"><i>inactive</i></a> ‘<code
- class=css>@var</code>’ rule becomes <a
- href="#active-var-rule"><i>active</i></a>, they define variables.
- Similarly, if ‘<code class=css>@var</code>’ rules are removed
- from the document or become <a
- href="#inactive-var-rule"><i>inactive</i></a>, they no longer define
- variables.
+<p>I'm blue!</p>
+<div>I'm green!</div>
+<div id='alert'>
+ And I'm red!
+ <p>So am I, because of inheritance!</p>
+</div></pre>
+ </div>
- <p>If multiple <a href="#active-var-rule"><i>active</i></a> ‘<code
- class=css>@var</code>’ rules attempt to define variables with the
- same name, the last one defined wins; the preceding ‘<code
- class=css>@var</code>’ rules do not define a variable. For this
- purpose, user-agent defined variable rules come before author-defined
- variable rules, which come before user-defined variable rules, which come
- before override variable rules. Within each of the preceding groups, the
- ordering is document order.
+ <p><a href="#data-property"><i>Data properties</i></a> may use variables in
+ their own values to build up composite variables. This can create cyclic
+ dependencies where two or more variables attempt to use each other's
+ value; doing so makes all the data properties involved in the cycle define
+ <a href="#invalid-variable"><i>invalid variables</i></a> instead of the
+ values they had intended to define.
<div class=example>
- <p>Earlier declarations of the same variable have no effect, even if uses
- of the variable come between the earlier and final attempts to define the
- variable:</p>
+ <p>This example shows a variable safely depending on another:</p>
<pre>
-@var $var red;
-p { color: $var; }
-@var $var blue;</pre>
+:root {
+ data-main-color: #c06;
+ data-accent-background: linear-gradient(to top, data(main-color), white);
+}</pre>
- <p>In this example, the color of <p> elements is blue, because the
- second declaration wins over the first declaration in all uses.</p>
+ <p>The ‘<code class=property>data-accent-background</code>’
+ property will automatically update when the ‘<code
+ class=property>data-main-color</code>’ property is changed.</p>
</div>
- <p>Variables can refer to other variables in their value. If a dependency
- cycle is created, all the declarations that directly contribute to the
- cycle define <a href="#invalid-variable"><i>invalid variables</i></a>.
+ <div class="example invalid-example">
+ <p>On the other hand, this example shows an invalid instance of variables
+ depending on each other:</p>
- <div class=example>
- <p>For example, the following set of variable declarations create a
- dependency cycle:</p>
+ <pre>
+:root {
+ data-one: calc(data(two) + 20px);
+ data-two: calc(data(one) - 20px);
+}</pre>
+
+ <p>Both ‘<code class=property>data-one</code>’ and
+ ‘<code class=property>data-two</code>’ now define <a
+ href="#invalid-variable"><i>invalid variables</i></a> rather than
+ lengths.</p>
+ </div>
+
+ <div class=issue>
+ <p>Is it possible to do a "cyclic" dependency safely?</p>
<pre>
-@var $foo red;
-@var $bar linear-gradient(transparent, $foo);
-@var $foo $bar;</pre>
+<one><two><three /></two></one>
+one { data-foo: 10px; }
+two { data-bar: calc(data(foo) + 10px); }
+three { data-foo: calc(data(bar) + 10px); }</pre>
- <p>The last two declarations create the cycle, and so they define
- ‘<code class=css>$bar</code>’ and ‘<code
- class=css>$foo</code>’, respectively, as <a
- href="#invalid-variable"><i>invalid variables</i></a> instead of as the
- values in the declarations. If the last rule were removed, however, there
- would be no problem - ‘<code class=css>$foo</code>’ would be
- defined as ‘<code class=css>red</code>’, while ‘<code
- class=css>$bar</code>’ would be defined as ‘<code
- class=css>linear-gradient(transparent, red)</code>’.</p>
+ <p>If I'm thinking correctly, one and two would get the value ‘<code
+ class=css>10px</code>’ for ‘<code
+ class=css>data(foo)</code>’, but three overrides ‘<code
+ class=property>data-foo</code>’ with a new definition. It gets the
+ *inherited* value of ‘<code class=property>data-bar</code>’,
+ which is ‘<code class=css>calc(10px + 10px)</code>’ (or maybe
+ just ‘<code class=css>20px</code>’ - ‘<code
+ class=css>calc()</code>’ computed values aren't well defined yet),
+ so it seems like it validly sets ‘<code
+ class=property>data-foo</code>’ to ‘<code
+ class=css>30px</code>’. Right?</p>
</div>
- <p>Before they are defined, all variables are <a
- href="#invalid-variable"><i>invalid variables</i></a>.
+ <p>Variables can refer to other variables in their value. If a dependency
+ cycle is created, all the declarations that directly contribute to the
+ cycle define <a href="#invalid-variable"><i>invalid variables</i></a>.
+
+ <p>Before they are defined by a <a href="#data-property"><i>data
+ property</i></a>, all variables are <a href="#invalid-variable"><i>invalid
+ variables</i></a>.
<h2 id=using-variables><span class=secno>3. </span> Using Variables</h2>
@@ -868,10 +879,10 @@
<dt id=CSS21>[CSS21]
<dd>Bert Bos; et al. <a
- href="http://www.w3.org/TR/2011/REC-CSS2-20110607/"><cite>Cascading Style
+ href="http://www.w3.org/TR/2011/REC-CSS2-20110607"><cite>Cascading Style
Sheets Level 2 Revision 1 (CSS 2.1) Specification.</cite></a> 7 June
2011. W3C Recommendation. URL: <a
- href="http://www.w3.org/TR/2011/REC-CSS2-20110607/">http://www.w3.org/TR/2011/REC-CSS2-20110607/</a>
+ href="http://www.w3.org/TR/2011/REC-CSS2-20110607">http://www.w3.org/TR/2011/REC-CSS2-20110607</a>
</dd>
<!---->
@@ -916,9 +927,9 @@
<dt id=CSS3COLOR>[CSS3COLOR]
<dd>Tantek Çelik; Chris Lilley; L. David Baron. <a
- href="http://www.w3.org/TR/2011/REC-css3-color-20110607/"><cite>CSS Color
+ href="http://www.w3.org/TR/2011/REC-css3-color-20110607"><cite>CSS Color
Module Level 3.</cite></a> 7 June 2011. W3C Recommendation. URL: <a
- href="http://www.w3.org/TR/2011/REC-css3-color-20110607/">http://www.w3.org/TR/2011/REC-css3-color-20110607/</a>
+ href="http://www.w3.org/TR/2011/REC-css3-color-20110607">http://www.w3.org/TR/2011/REC-css3-color-20110607</a>
</dd>
<!---->
</dl>
@@ -928,9 +939,6 @@
<!--begin-index-->
<ul class=indexlist>
- <li>active, <a href="#active-var-rule"
- title=active><strong>2.</strong></a>
-
<li>authoring tool, <a href="#authoring-tool"
title="authoring tool"><strong>6.2.</strong></a>
@@ -940,9 +948,6 @@
<li>data property, <a href="#data-property"
title="data property"><strong>2.</strong></a>
- <li>inactive, <a href="#inactive-var-rule"
- title=inactive><strong>2.</strong></a>
-
<li>invalid at computed-value time, <a
href="#invalid-at-computed-value-time"
title="invalid at computed-value time"><strong>3.1.</strong></a>
Index: Overview.src.html
===================================================================
RCS file: /sources/public/csswg/css-variables/Overview.src.html,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -d -r1.15 -r1.16
--- Overview.src.html 26 Oct 2011 01:16:09 -0000 1.15
+++ Overview.src.html 27 Oct 2011 01:18:26 -0000 1.16
@@ -61,12 +61,12 @@
<p>Large documents or applications (and even small ones) can contain quite a bit of CSS. Many of the values in the CSS file will be duplicate data; for example, a site may establish a color scheme and reuse three or four colors throughout the site. Altering this data can be difficult and error-prone, since it's scattered throughout the CSS file (and possibly across multiple files), and may not be amenable to Find-and-Replace.</p>
- <p>This module introduces a family of custom user-defined properties known collectively as <b>Variables</b>, which allow an author to assign values to a property with an author-chosen name, and then use those values in other properties elsewhere in the document. This makes it easier to read large files, as seemingly-arbitrary values now have informative names, and makes editting such files much easier and less error-prone, as one only has to change the value once, at the variable definition site, and the change will propagate to all uses of that variable automatically.</p>
+ <p>This module introduces a family of custom user-defined properties known collectively as <i>data properties</i>, which allow an author to assign arbitrary values to a property with an author-chosen name, and then use those values in other properties elsewhere in the document. This makes it easier to read large files, as seemingly-arbitrary values now have informative names, and makes editting such files much easier and less error-prone, as one only has to change the value once, at the variable definition site, and the change will propagate to all uses of that variable automatically.</p>
<h3 id="placement">
Module Interactions</h3>
- <p>This module defines a new type of primitive value, the <b>Variable</b>, which is accepted by all properties.</p>
+ <p>This module defines a new type of primitive value, the <i>variable</i>, which is accepted by all properties.</p>
<h3 id="values">
Values</h3>
@@ -109,7 +109,7 @@
</table>
<div class=example>
- <p>This variables declaration:</p>
+ <p>This style rule:</p>
<pre>
:root {
@@ -123,41 +123,66 @@
<p>The preceding rule is equivalent to writing ''background-color: #06c;'', except that the variable name makes the origin of the color clearer, and if ''data(header-color)'' is used elsewhere in the stylesheet, all of the uses can be updated at once by changing the variable declaration.</p>
</div>
- <p class='issue'>Finish replacing the rest of this section.</p>
+ <p>There is no restriction on the possible names for <i>data properties</i>, except that they must start with "data-" and be a valid identifier like any other property name. Data properties are ordinary properties, so they can be declared on any element, are resolved with the normal inheritance and cascade rules, can be made conditional with ''@media'' and other conditional rules, can be used in HTML's <code>style</code> attribute, can be read or set using the CSSOM, etc..</p>
- <p>Defined variables are available to all stylesheets in the document. Thus, using ''@import'' to include a stylesheet also includes all variables defined in the stylesheet (and makes all variables declared outside available within the stylesheet, if applicable). ''@var'' rules present in disabled or alternate stylesheets do not define variables. Scoped stylesheets are an exception to this: variables defined in the global scope are available within a scoped stylesheet, but variables defined or imported within scoped stylesheets are only available within the scoped stylesheet and any imported stylesheets.</p>
+ <div class='example'>
+ <p>If a variable is declared multiple times, the standard cascade rules help resolve it:</p>
- <p>A ''@var'' rule is <dfn id='inactive-var-rule'>inactive</dfn> if it's present in a disabled or alternate stylesheet, a stylesheet with a media query that evaluates to false, or is present within a conditional rule group [[CSS3CONDITIONAL]] whose condition evaluates to false. <i>Inactive</i> ''@var'' rules do not define variables. All other ''@var'' rules are <dfn id='active-var-rule'>active</dfn>.</p>
+ <pre>
+:root { data-color: blue; }
+div { data-color: green; }
+#alert { data-color: red; }
+* { color: data(color); }
- <p>If new ''@var'' rules are added to the document through any means, such as direct CSSOM manipulation or new stylesheets being added to the document, or if an <i>inactive</i> ''@var'' rule becomes <i>active</i>, they define variables. Similarly, if ''@var'' rules are removed from the document or become <i>inactive</i>, they no longer define variables.</p>
+<p>I'm blue!</p>
+<div>I'm green!</div>
+<div id='alert'>
+ And I'm red!
+ <p>So am I, because of inheritance!</p>
+</div></pre>
+ </div>
- <p>If multiple <i>active</i> ''@var'' rules attempt to define variables with the same name, the last one defined wins; the preceding ''@var'' rules do not define a variable. For this purpose, user-agent defined variable rules come before author-defined variable rules, which come before user-defined variable rules, which come before override variable rules. Within each of the preceding groups, the ordering is document order.</p>
+ <p><i>Data properties</i> may use variables in their own values to build up composite variables. This can create cyclic dependencies where two or more variables attempt to use each other's value; doing so makes all the data properties involved in the cycle define <i>invalid variables</i> instead of the values they had intended to define.</p>
<div class='example'>
- <p>Earlier declarations of the same variable have no effect, even if uses of the variable come between the earlier and final attempts to define the variable:</p>
+ <p>This example shows a variable safely depending on another:</p>
<pre>
-@var $var red;
-p { color: $var; }
-@var $var blue;</pre>
+:root {
+ data-main-color: #c06;
+ data-accent-background: linear-gradient(to top, data(main-color), white);
+}</pre>
- <p>In this example, the color of <p> elements is blue, because the second declaration wins over the first declaration in all uses.</p>
+ <p>The 'data-accent-background' property will automatically update when the 'data-main-color' property is changed.</p>
</div>
- <p>Variables can refer to other variables in their value. If a dependency cycle is created, all the declarations that directly contribute to the cycle define <i>invalid variables</i>.</p>
+ <div class='example invalid-example'>
+ <p>On the other hand, this example shows an invalid instance of variables depending on each other:</p>
- <div class='example'>
- <p>For example, the following set of variable declarations create a dependency cycle:</p>
+ <pre>
+:root {
+ data-one: calc(data(two) + 20px);
+ data-two: calc(data(one) - 20px);
+}</pre>
+
+ <p>Both 'data-one' and 'data-two' now define <i>invalid variables</i> rather than lengths.</p>
+ </div>
+
+ <div class='issue'>
+ <p>Is it possible to do a "cyclic" dependency safely?</p>
<pre>
-@var $foo red;
-@var $bar linear-gradient(transparent, $foo);
-@var $foo $bar;</pre>
+<one><two><three /></two></one>
+one { data-foo: 10px; }
+two { data-bar: calc(data(foo) + 10px); }
+three { data-foo: calc(data(bar) + 10px); }</pre>
- <p>The last two declarations create the cycle, and so they define ''$bar'' and ''$foo'', respectively, as <i>invalid variables</i> instead of as the values in the declarations. If the last rule were removed, however, there would be no problem - ''$foo'' would be defined as ''red'', while ''$bar'' would be defined as ''linear-gradient(transparent, red)''.</p>
+ <p>If I'm thinking correctly, one and two would get the value ''10px'' for ''data(foo)'', but three overrides 'data-foo' with a new definition. It gets the *inherited* value of 'data-bar', which is ''calc(10px + 10px)'' (or maybe just ''20px'' - ''calc()'' computed values aren't well defined yet), so it seems like it validly sets 'data-foo' to ''30px''. Right?</p>
</div>
- <p>Before they are defined, all variables are <i>invalid variables</i>.</p>
+ <p>Variables can refer to other variables in their value. If a dependency cycle is created, all the declarations that directly contribute to the cycle define <i>invalid variables</i>.</p>
+
+ <p>Before they are defined by a <i>data property</i>, all variables are <i>invalid variables</i>.</p>
<h2 id='using-variables'>
Using Variables</h2>
Received on Thursday, 27 October 2011 01:18:36 UTC