You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: css-variables/Overview.src.html
+33-15Lines changed: 33 additions & 15 deletions
Original file line number
Diff line number
Diff line change
@@ -80,9 +80,9 @@ <h3 id="values">
80
80
definition of the <color> value type as used in this specification.</p>
81
81
82
82
<h2id="defining-variables">
83
-
Defining Variables</h2>
83
+
Defining Variables With Data Properties</h2>
84
84
85
-
<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>
85
+
<p>This specification defines an open-ended set of properties called <i>data properties</i>, which are used to define <i>variables</i>.</p>
86
86
87
87
<tableclass='propdef'>
88
88
<tr>
@@ -93,7 +93,7 @@ <h2 id="defining-variables">
93
93
<td><divclass='issue'>Figure this out - restricted or wide-open</div>
94
94
<tr>
95
95
<th>Initial:
96
-
<td><divclass='issue'>???</div>
96
+
<td>invalid (a keyword, but see prose)
97
97
<tr>
98
98
<th>Applies To:
99
99
<td>all elements
@@ -108,6 +108,10 @@ <h2 id="defining-variables">
108
108
<td>all
109
109
</table>
110
110
111
+
<p><em>Any</em> property name starting with the prefix "data-" is a <i>data property</i>. <spanclass='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 <ahref="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>
112
+
113
+
<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>
<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:
123
+
<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:
<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>
127
+
<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>
124
128
</div>
125
129
126
-
<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>
130
+
<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>
127
131
128
132
<divclass='example'>
129
-
<p>If a variable is declared multiple times, the standard cascade rules help resolve it:</p>
133
+
<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>
130
134
131
135
<pre>
132
136
:root { data-color: blue; }
133
137
div { data-color: green; }
134
138
#alert { data-color: red; }
135
139
* { color: data(color); }
136
140
137
-
<p>I'm blue!</p>
138
-
<div>I'm green!</div>
141
+
<p>I inherited blue from the root element!</p>
142
+
<div>I got green set directly on me!</div>
139
143
<div id='alert'>
140
-
And I'm red!
141
-
<p>So am I, because of inheritance!</p>
144
+
While I got red set directly on me!
145
+
<p>I'm red too, because of inheritance!</p>
142
146
</div></pre>
143
147
</div>
144
148
145
-
<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>
149
+
<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>
146
150
147
151
<divclass='example'>
148
-
<p>This example shows a variable safely depending on another:</p>
152
+
<p>This example shows a data property safely using a variable:</p>
149
153
150
154
<pre>
151
155
:root {
@@ -180,9 +184,23 @@ <h2 id="defining-variables">
180
184
<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>
181
185
</div>
182
186
183
-
<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>
187
+
<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>
188
+
189
+
<divclass='example'>
190
+
<pre>
191
+
<div>
192
+
<p>Sample text</p>
193
+
</div>
194
+
<style>
195
+
p { data-foo: invalid; }
196
+
div,p { font-family: data(foo); }
197
+
</style></pre>
198
+
199
+
<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>
200
+
201
+
<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>
202
+
</div>
184
203
185
-
<p>Before they are defined by a <i>data property</i>, all variables are <i>invalid variables</i>.</p>
0 commit comments