- From: Tab Atkins Jr.. via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 27 Oct 2011 17:32:47 +0000
- To: public-css-commits@w3.org
Update of /sources/public/csswg/css-variables
In directory hutz:/tmp/cvs-serv12364
Modified Files:
Overview.html Overview.src.html
Log Message:
Rewrite the 'defining vars' section to be more consistent in using 'data property' and 'variable'. Also improve examples.
Index: Overview.html
===================================================================
RCS file: /sources/public/csswg/css-variables/Overview.html,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -d -r1.16 -r1.17
--- Overview.html 27 Oct 2011 01:18:26 -0000 1.16
+++ Overview.html 27 Oct 2011 17:32:45 -0000 1.17
@@ -128,7 +128,7 @@
</ul>
<li><a href="#defining-variables"><span class=secno>2. </span> Defining
- Variables</a>
+ Variables With Data Properties</a>
<li><a href="#using-variables"><span class=secno>3. </span> Using
Variables</a>
@@ -219,8 +219,8 @@
<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"><i>variable</i></a>, which is accepted by all properties.
+ <p>This module defines a new type of primitive value, the <i>variable</i>,
+ which is accepted by all properties.
<h3 id=values><span class=secno>1.2. </span> Values</h3>
@@ -235,15 +235,12 @@
when combined with this module, expands the definition of the
<color> value type as used in this specification.
- <h2 id=defining-variables><span class=secno>2. </span> Defining Variables</h2>
+ <h2 id=defining-variables><span class=secno>2. </span> Defining Variables
+ With Data Properties</h2>
- <p>A <dfn id=variable>variable</dfn> is defined by assigning a value to a
- property whose name starts with the prefix "data-" (this class of
- properties will be referred to <a href="#data-property"><i>data
- properties</i></a>). <em>Any</em> property with the "data-" prefix is
- defined to be valid but meaningless, and will never be given a specific
- meaning or effect by a CSS specification or user agent; this is similar to
- the <code>data-*</code> family of custom attributes in HTML.
+ <p>This specification defines an open-ended set of properties called <a
+ href="#data-property"><i>data properties</i></a>, which are used to define
+ <i>variables</i>.
<table class=propdef>
<tbody>
@@ -262,8 +259,7 @@
<tr>
<th>Initial:
- <td>
- <div class=issue>???</div>
+ <td>invalid (a keyword, but see prose)
<tr>
<th>Applies To:
@@ -286,6 +282,22 @@
<td>all
</table>
+ <p><em>Any</em> property name starting with the prefix "data-" is a <a
+ href="#data-property"><i>data property</i></a>. <span class=issue>Spec
+ what values a data property can have.</span> Data properties are defined
+ to be valid but meaningless as they are meant solely for allowing authors
+ to pass custom data around their page, similar to the <a
+ href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#embedding-custom-non-visible-data-with-the-data-*-attributes">custom
+ data attributes</a> in HTML. Other specifications and user agents must not
+ assign a particular meaning to data properties or attach a specific effect
+ to them beyond the bare minimum that comes from them being valid
+ properties.
+
+ <p>For each <a href="#data-property"><i>data property</i></a>, there is an
+ associated variable with the same name save for the "data-" prefix. For
+ example, a data property named "data-foo" is associated with the variable
+ named "foo". See the next chapter for details on how to use variables.
+
<div class=example>
<p>This style rule:</p>
@@ -297,8 +309,8 @@
<p>declares a <a href="#data-property"><i>data property</i></a> named
"data-header-color" on the root element, and assigns to it the value
"#06c". This property is then inherited to the elements in the rest of
- the document, and its value can then be used in any place where it would
- be valid, such as:
+ the document. Its value can be referenced via the "header-color"
+ variable:
<pre>h1 { background-color: data(header-color); }</pre>
@@ -307,21 +319,21 @@
name makes the origin of the color clearer, and if ‘<code
class=css>data(header-color)</code>’ is used elsewhere in the
stylesheet, all of the uses can be updated at once by changing the
- variable declaration.</p>
+ ‘<code class=property>data-header-color</code>’ property on
+ the root element.</p>
</div>
- <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
+ <p>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..
<div class=example>
- <p>If a variable is declared multiple times, the standard cascade rules
- help resolve it:</p>
+ <p>If a <a href="#data-property"><i>data property</i></a> is declared
+ multiple times, the standard cascade rules help resolve it. Variables
+ always draw from the computed value of the associated data property on
+ the same element:</p>
<pre>
:root { data-color: blue; }
@@ -329,23 +341,25 @@
#alert { data-color: red; }
* { color: data(color); }
-<p>I'm blue!</p>
-<div>I'm green!</div>
+<p>I inherited blue from the root element!</p>
+<div>I got green set directly on me!</div>
<div id='alert'>
- And I'm red!
- <p>So am I, because of inheritance!</p>
+ While I got red set directly on me!
+ <p>I'm red too, because of inheritance!</p>
</div></pre>
</div>
<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
+ dependencies where two or more <a href="#data-property"><i>data
+ properties</i></a> each attempt to use the variable that the other
+ defines; doing so makes all the <a href="#data-property"><i>data
+ properties</i></a> 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>This example shows a variable safely depending on another:</p>
+ <p>This example shows a data property safely using a variable:</p>
<pre>
:root {
@@ -396,13 +410,36 @@
class=css>30px</code>’. Right?</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>.
+ <p>The initial value of a <a href="#data-property"><i>data property</i></a>
+ is a special invalid value which makes the associated variable an <a
+ href="#invalid-variable"><i>invalid variable</i></a>. This is represented
+ by the keyword ‘<code class=css>invalid</code>’, but that
+ keyword has no special meaning in itself, and is valid if set explicitly
+ in a data property.
- <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>.
+ <div class=example>
+ <pre>
+<div>
+ <p>Sample text</p>
+</div>
+<style>
+p { data-foo: invalid; }
+div,p { font-family: data(foo); }
+</style></pre>
+
+ <p>In this example, the "foo" variable is an <a
+ href="#invalid-variable"><i>invalid variable</i></a> at the time the DIV
+ element references it, because the ‘<code
+ class=property>data-foo</code>’ property still has its initial
+ value. This causes the DIV's ‘<code
+ class=property>font-family</code>’ property to compute to the
+ initial value for ‘<code class=property>font-family</code>’.</p>
+
+ <p>On the other hand, the P element defines an explicit value for the
+ ‘<code class=property>data-foo</code>’ property. Its
+ ‘<code class=property>font-family</code>’ property thus
+ references a font named "invalid".</p>
+ </div>
<h2 id=using-variables><span class=secno>3. </span> Using Variables</h2>
@@ -967,8 +1004,6 @@
title="style sheet, as conformance class"><strong>6.2.</strong></a>
</ul>
- <li>variable, <a href="#variable" title=variable><strong>2.</strong></a>
-
<li><a href="#variablerule"><code>VARIABLE_RULE</code></a>, <a
href="#variablerule" title="VARIABLE_RULE"><strong>4.2.1.</strong></a>
</ul>
@@ -1000,7 +1035,7 @@
<td>Figure this out - restricted or wide-open
- <td>???
+ <td>invalid (a keyword, but see prose)
<td>all elements
Index: Overview.src.html
===================================================================
RCS file: /sources/public/csswg/css-variables/Overview.src.html,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -d -r1.16 -r1.17
--- Overview.src.html 27 Oct 2011 01:18:26 -0000 1.16
+++ Overview.src.html 27 Oct 2011 17:32:45 -0000 1.17
@@ -80,9 +80,9 @@
definition of the <color> value type as used in this specification.</p>
<h2 id="defining-variables">
-Defining Variables</h2>
+Defining Variables With Data Properties</h2>
- <p>A <dfn>variable</dfn> is defined by assigning a value to a property whose name starts with the prefix "data-" (this class of properties will be referred to <i>data properties</i>). <em>Any</em> property with the "data-" prefix is defined to be valid but meaningless, and will never be given a specific meaning or effect by a CSS specification or user agent; this is similar to the <code>data-*</code> family of custom attributes in HTML.</p>
+ <p>This specification defines an open-ended set of properties called <i>data properties</i>, which are used to define <i>variables</i>.</p>
<table class='propdef'>
<tr>
@@ -93,7 +93,7 @@
<td><div class='issue'>Figure this out - restricted or wide-open</div>
<tr>
<th>Initial:
- <td><div class='issue'>???</div>
+ <td>invalid (a keyword, but see prose)
<tr>
<th>Applies To:
<td>all elements
@@ -108,6 +108,10 @@
<td>all
</table>
+ <p><em>Any</em> property name starting with the prefix "data-" is a <i>data property</i>. <span class='issue'>Spec what values a data property can have.</span> Data properties are defined to be valid but meaningless as they are meant solely for allowing authors to pass custom data around their page, similar to the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#embedding-custom-non-visible-data-with-the-data-*-attributes">custom data attributes</a> in HTML. Other specifications and user agents must not assign a particular meaning to data properties or attach a specific effect to them beyond the bare minimum that comes from them being valid properties.</p>
+
+ <p>For each <i>data property</i>, there is an associated variable with the same name save for the "data-" prefix. For example, a data property named "data-foo" is associated with the variable named "foo". See the next chapter for details on how to use variables.</p>
+
<div class=example>
<p>This style rule:</p>
@@ -116,17 +120,17 @@
data-header-color: #06c;
}</pre>
- <p>declares a <i>data property</i> named "data-header-color" on the root element, and assigns to it the value "#06c". This property is then inherited to the elements in the rest of the document, and its value can then be used in any place where it would be valid, such as:
+ <p>declares a <i>data property</i> named "data-header-color" on the root element, and assigns to it the value "#06c". This property is then inherited to the elements in the rest of the document. Its value can be referenced via the "header-color" variable:
<pre>h1 { background-color: data(header-color); }</pre>
- <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>
+ <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 'data-header-color' property on the root element.</p>
</div>
- <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>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>
<div class='example'>
- <p>If a variable is declared multiple times, the standard cascade rules help resolve it:</p>
+ <p>If a <i>data property</i> is declared multiple times, the standard cascade rules help resolve it. Variables always draw from the computed value of the associated data property on the same element:</p>
<pre>
:root { data-color: blue; }
@@ -134,18 +138,18 @@
#alert { data-color: red; }
* { color: data(color); }
-<p>I'm blue!</p>
-<div>I'm green!</div>
+<p>I inherited blue from the root element!</p>
+<div>I got green set directly on me!</div>
<div id='alert'>
- And I'm red!
- <p>So am I, because of inheritance!</p>
+ While I got red set directly on me!
+ <p>I'm red too, because of inheritance!</p>
</div></pre>
</div>
- <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>
+ <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 <i>data properties</i> each attempt to use the variable that the other defines; doing so makes all the <i>data properties</i> involved in the cycle define <i>invalid variables</i> instead of the values they had intended to define.</p>
<div class='example'>
- <p>This example shows a variable safely depending on another:</p>
+ <p>This example shows a data property safely using a variable:</p>
<pre>
:root {
@@ -180,9 +184,23 @@
<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>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>The initial value of a <i>data property</i> is a special invalid value which makes the associated variable an <i>invalid variable</i>. This is represented by the keyword ''invalid'', but that keyword has no special meaning in itself, and is valid if set explicitly in a data property.</p>
+
+ <div class='example'>
+ <pre>
+<div>
+ <p>Sample text</p>
+</div>
+<style>
+p { data-foo: invalid; }
+div,p { font-family: data(foo); }
+</style></pre>
+
+ <p>In this example, the "foo" variable is an <i>invalid variable</i> at the time the DIV element references it, because the 'data-foo' property still has its initial value. This causes the DIV's 'font-family' property to compute to the initial value for 'font-family'.</p>
+
+ <p>On the other hand, the P element defines an explicit value for the 'data-foo' property. Its 'font-family' property thus references a font named "invalid".</p>
+ </div>
- <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 17:32:51 UTC