← Back to branch summary

~bcsaller/juju-gui/charmFind

« back to all changes in this revision

Viewing changes to lib/yui/docs/stylesheet/index.html

  • Committer: kapil.foss at gmail
  • Date: 2012-07-13 18:45:59 UTC
  • Revision ID: kapil.foss@gmail.com-20120713184559-2xl7be17egsrz0c9
reshape

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/yui/docs/stylesheet/index.html
1
 
<!DOCTYPE html>
2
 
<html lang="en">
3
 
<head>
4
 
    <meta charset="utf-8">
5
 
    <title>StyleSheet</title>
6
 
    <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Maven+Pro:400,700">
7
 
    <link rel="stylesheet" href="../../build/cssgrids/grids-min.css">
8
 
    <link rel="stylesheet" href="../assets/css/main.css">
9
 
    <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
10
 
    <script src="../../build/yui/yui-min.js"></script>
11
 
</head>
12
 
<body>
13
 
 
14
 
<div id="doc">
15
 
    <h1>StyleSheet</h1>
16
 
 
17
 
    
18
 
        <a href="#toc" class="jump">Jump to Table of Contents</a>
19
 
    
20
 
 
21
 
    <div class="yui3-g">
22
 
        <div class="yui3-u-3-4">
23
 
            <div id="main">
24
 
                <div class="content"><div class="intro component">
25
 
    <p>
26
 
        The StyleSheet module normalizes the dynamic creation and modification
27
 
        of CSS stylesheets on a page.  This makes it easy to manage the
28
 
        development, storage, and reapplication of personalized user
29
 
        stylesheets.  Because it targets styles at the CSS level, it also
30
 
        allows you to modify styles applied to a CSS pseudo-element such as
31
 
        <code>p::first-letter</code>, or pseudo-class such as
32
 
        <code>a:hover</code>.
33
 
    </p>
34
 
 
35
 
    <p>
36
 
        StyleSheet is capable of creating new stylesheets from scratch or
37
 
        modifying existing stylesheets held as properties of
38
 
        <code>&lt;link&gt;</code> or <code>&lt;style&gt;</code> elements.  It
39
 
        should be noted that not all browsers support reading or modifying
40
 
        external stylesheets from other domains.
41
 
    </p>
42
 
</div>
43
 
 
44
 
<h2 id="getting-started">Getting Started</h2>
45
 
 
46
 
<p>
47
 
To include the source files for StyleSheet and its dependencies, first load
48
 
the YUI seed file if you haven't already loaded it.
49
 
</p>
50
 
 
51
 
<pre class="code prettyprint">&lt;script src=&quot;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;3.5.1&#x2F;build&#x2F;yui&#x2F;yui-min.js&quot;&gt;&lt;&#x2F;script&gt;</pre>
52
 
 
53
 
 
54
 
<p>
55
 
Next, create a new YUI instance for your application and populate it with the
56
 
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
57
 
YUI will automatically load any dependencies required by the modules you
58
 
specify.
59
 
</p>
60
 
 
61
 
<pre class="code prettyprint">&lt;script&gt;
62
 
&#x2F;&#x2F; Create a new YUI instance and populate it with the required modules.
63
 
YUI().use(&#x27;stylesheet&#x27;, function (Y) {
64
 
    &#x2F;&#x2F; StyleSheet is available and ready for use. Add implementation
65
 
    &#x2F;&#x2F; code here.
66
 
});
67
 
&lt;&#x2F;script&gt;</pre>
68
 
 
69
 
 
70
 
<p>
71
 
For more information on creating YUI instances and on the
72
 
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
73
 
documentation for the <a href="../yui/index.html">YUI Global Object</a>.
74
 
</p>
75
 
 
76
 
 
77
 
<h2 id="using">Using the StyleSheet Utility</h2>
78
 
 
79
 
<h3 id="instantiating">Instantiating a <code>Y.StyleSheet</code></h3>
80
 
 
81
 
<p>
82
 
    The <code>Y.StyleSheet</code> constructor is written to support both
83
 
    function syntax and normal constructor syntax making the <code>new</code>
84
 
    prefix unnecessary (but harmless).
85
 
</p>
86
 
 
87
 
<p>
88
 
    The constructor has no required parameters.  Passing no arguments will
89
 
    create a new, empty StyleSheet instance.
90
 
</p>
91
 
 
92
 
<pre class="code prettyprint">&#x2F;&#x2F; These are equivalent; both create new empty StyleSheets
93
 
var myStyleSheet = new Y.StyleSheet();
94
 
 
95
 
var myOtherStyleSheet = Y.StyleSheet();</pre>
96
 
 
97
 
 
98
 
<p>
99
 
    To seed a new StyleSheet with a number of CSS rules, you can pass the
100
 
    constructor any of the following:
101
 
</p>
102
 
 
103
 
<ol>
104
 
    <li>
105
 
        a <code>&lt;style&gt;</code> or <code>&lt;link&gt;</code> node
106
 
        reference,
107
 
    </li>
108
 
    <li>
109
 
        the id of a <code>&lt;style&gt;</code> or <code>&lt;link&gt;</code>
110
 
        node, or
111
 
    </li>
112
 
    <li>a string of CSS</li>
113
 
</ol>
114
 
 
115
 
<pre class="code prettyprint">&lt;link id=&quot;local&quot; type=&quot;text&#x2F;css&quot; rel=&quot;stylesheet&quot; href=&quot;local_file.css&quot;&gt;
116
 
&lt;style id=&quot;styleblock&quot; type=&quot;text&#x2F;css&quot;&gt;
117
 
    .some select.or {
118
 
        margin-right: 2em;
119
 
    }
120
 
&lt;&#x2F;style&gt;</pre>
121
 
 
122
 
 
123
 
<pre class="code prettyprint">YUI().use(&#x27;node&#x27;,&#x27;stylesheet&#x27;, function (Y) {
124
 
 
125
 
    &#x2F;&#x2F; Node or HTMLElement reference for a style or locally sourced link element
126
 
    var sheet = Y.StyleSheet(Y.one(&quot;#styleblock&quot;));
127
 
    sheet = Y.StyleSheet(Y.DOM.byId(&#x27;local&#x27;));
128
 
 
129
 
    &#x2F;&#x2F; OR the id of a style element or locally sourced link element
130
 
    sheet = Y.StyleSheet(&#x27;#local&#x27;);
131
 
 
132
 
    &#x2F;&#x2F; OR string of css text
133
 
    var css = &quot;.moduleX .alert { background: #fcc; font-weight: bold; } &quot; +
134
 
              &quot;.moduleX .warn  { background: #eec; } &quot; +
135
 
              &quot;.hide_messages .moduleX .alert, &quot; +
136
 
              &quot;.hide_messages .moduleX .warn { display: none; }&quot;;
137
 
 
138
 
    sheet = new Y.StyleSheet(css);
139
 
 
140
 
    &#x2F;&#x2F;...
141
 
});</pre>
142
 
 
143
 
 
144
 
<p>
145
 
    Be aware that the <a
146
 
    href="http://en.wikipedia.org/wiki/Same_origin_policy">Same Origin
147
 
    policy</a> prevents access in some browsers to the style data of
148
 
    <code>&lt;link&gt;</code> elements with <code>href</code>s pointing to
149
 
    other domains.  Attempts to seed a <code>Y.StyleSheet</code> instance with
150
 
    a cross-domain <code>&lt;link&gt;</code> may result in a security
151
 
    error.
152
 
</p>
153
 
 
154
 
<pre class="code prettyprint">&lt;link id=&quot;remote&quot; type=&quot;text&#x2F;css&quot; rel=&quot;stylesheet&quot; href=&quot;http:&#x2F;&#x2F;other.domain.com&#x2F;remote_file.css&quot;&gt;</pre>
155
 
 
156
 
 
157
 
<pre class="code prettyprint">&#x2F;&#x2F; ERROR - Same Origin Policy prevents access to remote stylesheets
158
 
var styleSheet = Y.StyleSheet(&#x27;remote&#x27;);</pre>
159
 
 
160
 
 
161
 
<h3 id="registry">Getting a StyleSheet by registered name</h3>
162
 
 
163
 
<p>
164
 
    <code>Y.StyleSheet</code> supports registering instances by name allowing
165
 
    them to be recalled by that same name elsewhere in your code.  Internally,
166
 
    <code>Y.StyleSheet</code> maintains a registry of all created StyleSheet
167
 
    instances, using a unique generated id that the host node is tagged with.
168
 
    This allows future attempts to create a StyleSheet instance from the same
169
 
    node to return the previously created instance associated with that id.
170
 
</p>
171
 
 
172
 
<p>
173
 
    Register a StyleSheet instance manually using the static
174
 
    <code>register</code> method or pass the desired name as a second parameter
175
 
    to the constructor.
176
 
</p>
177
 
 
178
 
<pre class="code prettyprint">var sheetA = Y.StyleSheet(&#x27;my_stylesheet&#x27;);
179
 
 
180
 
&#x2F;&#x2F; Create a registry alias to sheetA.  We&#x27;ll call it bob.
181
 
Y.StyleSheet.register(sheetA, &#x27;bob&#x27;);
182
 
 
183
 
&#x2F;&#x2F; Create another StyleSheet passing the name as the second parameter
184
 
var css = &quot;.some .css { white-space: pre-wrap; color: pink; }&quot;;
185
 
var sheetB = Y.StyleSheet(css, &#x27;my sheet&#x27;);
186
 
 
187
 
&#x2F;&#x2F; Meanwhile, elsewhere in your code
188
 
 
189
 
&#x2F;&#x2F; sheetA is the same instance as sheet1 and sheet2
190
 
var sheet1 = Y.StyleSheet(Y.one(&#x27;#my_stylesheet&#x27;)),
191
 
    sheet2 = Y.StyleSheet(&#x27;bob&#x27;);
192
 
 
193
 
&#x2F;&#x2F; sheetB is the same instance as sheet3
194
 
var sheet3 = Y.StyleSheet(&#x27;my sheet&#x27;);</pre>
195
 
 
196
 
 
197
 
<p>
198
 
    If an unregistered name is passed as the <em>first</em> argument to the
199
 
    constructor, a new empty StyleSheet will be created and registered with
200
 
    that name.  This allows you to use the following code pattern:
201
 
</p>
202
 
 
203
 
<pre class="code prettyprint">&#x2F;&#x2F; Whichever of these executes first, an empty StyleSheet will be created
204
 
&#x2F;&#x2F; and registered as &#x27;MyApp&#x27;.
205
 
 
206
 
&#x2F;&#x2F; In one area of your app
207
 
Y.StyleSheet(&#x27;MyApp&#x27;).set(&#x27;.module .messages&#x27;, { display: &#x27;none&#x27; });
208
 
 
209
 
&#x2F;&#x2F;...
210
 
 
211
 
&#x2F;&#x2F; In another area of your app
212
 
Y.StyleSheet(&#x27;MyApp&#x27;).unset(&#x27;.module .messages&#x27;,&#x27;display&#x27;);</pre>
213
 
 
214
 
 
215
 
<h3 id="first_param">Summary of how the constructor handles the first argument</h3>
216
 
 
217
 
<p>
218
 
    When nothing is passed as the first argument, a new StyleSheet instance is
219
 
    created.
220
 
</p>
221
 
 
222
 
<p>
223
 
    When a <code>&lt;style&gt;</code> or <code>&lt;link&gt;</code> element is
224
 
    passed as the first argument, it is inspected for the id stamp that
225
 
    StyleSheet tags known host nodes with.  If it finds one, it will return the
226
 
    associated StyleSheet from the registry.  If not, it will stamp the node
227
 
    and seed the instance from the node's CSS content.
228
 
</p>
229
 
 
230
 
<p>
231
 
    When a string is passed as the first argument, StyleSheet does the
232
 
    following things in order:
233
 
</p>
234
 
 
235
 
<ol>
236
 
    <li>
237
 
        Check the registry for an instance associated to that name.  If found,
238
 
        return the instance.
239
 
    </li>
240
 
    <li>
241
 
        Check the DOM for a <code>&lt;style&gt;</code> or
242
 
        <code>&lt;link&gt;</code> node with that id.  If found, check the
243
 
        registry for an instance associated to its tagged id if present.  If
244
 
        found, return that instance.  If not, use that node to seed a new
245
 
        StyleSheet instance.
246
 
    </li>
247
 
    <li>
248
 
        Check the string for a curly brace { character.  If found, create a new
249
 
        instance seeded with the string as initial <code>cssText</code>.
250
 
    </li>
251
 
    <li>
252
 
        Create a new empty StyleSheet and register the instance by the provided
253
 
        string.
254
 
    </li>
255
 
</ol>
256
 
 
257
 
<h3 id="set">Creating and modifying CSS style rules</h3>
258
 
 
259
 
<p>
260
 
    The core method of StyleSheet instances is <code>set(selector,
261
 
    style_properties)</code>.  It will create or alter a CSS rule using the
262
 
    property:value pairs in <code>style_properties</code> targeting the
263
 
    provided <code>selector</code>.  In essence, it looks very much like
264
 
    natural CSS syntax, <em>except style properties must be in JavaScript's
265
 
    camelCase</em>.
266
 
</p>
267
 
 
268
 
<pre class="code prettyprint">Y.StyleSheet(&#x27;MyApp&#x27;).set(
269
 
    &quot;q.uoted select.or[str=ing]&quot;, {
270
 
        fontSize   : &quot;150%&quot;,         &#x2F;&#x2F; note the camel casing
271
 
        background : &quot;#030 url(&#x2F;images&#x2F;bg_image.png) scroll repeat-y top left&quot;,
272
 
        cssFloat   : &quot;left&quot;,
273
 
        opacity    : 0.5
274
 
    });</pre>
275
 
 
276
 
 
277
 
<p>
278
 
    Rather than continually add new rules that will override one another,
279
 
    StyleSheet manages one rule per selector and modifies them in place.  This
280
 
    may be relevant if you have two or more rules with selectors of the same
281
 
    specificity.
282
 
</p>
283
 
 
284
 
<p>
285
 
    As with regular CSS syntax, comma-separated selectors are supported, but
286
 
    internally StyleSheet splits them up into individual rules because browser
287
 
    support for multiple selectors is not consistent.  This means calling
288
 
    <code>set(..)</code> with such a selector string <em>will incur multiple
289
 
    repaints or reflows</em>, but limited to the number of atomic
290
 
    selectors.
291
 
</p>
292
 
 
293
 
<pre class="code prettyprint">&#x2F;&#x2F; This is valid, but will trigger 3 reflows
294
 
Y.StyleSheet(&#x27;MyApp&#x27;).set(
295
 
    &#x27;.foo, .bar, .baz&#x27;, {
296
 
        borderRight: &quot;1em solid #f00&quot;
297
 
    });</pre>
298
 
 
299
 
 
300
 
<h3 id="normalized_properties">Some style properties are normalized</h3>
301
 
 
302
 
<p>
303
 
    Two style properties have differing implementation between browsers, namely
304
 
    <code>float</code> and <code>opacity</code>.  StyleSheet instances will
305
 
    normalize these properties for you.
306
 
</p>
307
 
 
308
 
<p>
309
 
    Because &quot;float&quot; is a reserved word in JavaScript, it is supported
310
 
    by the name <code>cssFloat</code> in W3C compliant browsers and
311
 
    <code>styleFloat</code> in IE.  StyleSheet will accept any of these to set
312
 
    the <code>float</code> property.
313
 
</p>
314
 
 
315
 
<pre class="code prettyprint">&#x2F;&#x2F; Any of these will work
316
 
Y.StyleSheet(&#x27;MyApp&#x27;).set(&#x27;.foo&#x27;, {
317
 
    &quot;float&quot;    : &quot;left&quot;,   &#x2F;&#x2F; &quot;float&quot; must be quoted
318
 
    cssFloat   : &quot;right&quot;,
319
 
    styleFloat : &quot;none&quot;
320
 
});</pre>
321
 
 
322
 
 
323
 
<p>
324
 
    IE does not support the <code>opacity</code> style property, but has
325
 
    equivalent functionality offered by its proprietary <code>filter</code>
326
 
    property, though using a different value syntax.  StyleSheet will translate
327
 
    <code>opacity</code> to <code>filter</code> for IE, but it <em>will
328
 
    not</em> translate <code>filter</code> to <code>opacity</code> for
329
 
    W3C-compliant browsers.
330
 
</p>
331
 
 
332
 
<h3 id="unset">Removing and resetting CSS style rules</h3>
333
 
 
334
 
<p>
335
 
    When you want to remove a particular rule or style property from affecting
336
 
    the cascade, use <code>unset(selector,propert[y|ies])</code>.
337
 
</p>
338
 
 
339
 
<p>
340
 
    <code>unset(..)</code> can be called in any of the following ways, with the
341
 
    noted result:
342
 
</p>
343
 
 
344
 
<ul>
345
 
    <li>
346
 
        <code>unset('.foo')</code> &mdash; removes the rule associated to the
347
 
        selector entirely.
348
 
    </li>
349
 
    <li>
350
 
        <code>unset('.foo','font')</code> &mdash; unsets the <code>font</code>
351
 
        property and any child properties (e.g.
352
 
        'font-weight','font-variant','font-size','line-height', and
353
 
        'font-family').  If there are no set properties left, the rule is
354
 
        removed.
355
 
    </li>
356
 
    <li>
357
 
        <code>unset('.foo',['font','border',...])</code> &mdash; same as above,
358
 
        but the rule is modified only once with the final applicable
359
 
        <code>cssText</code>.
360
 
    </li>
361
 
</ul>
362
 
 
363
 
<p>
364
 
    It is important to note that there is a difference between setting a style
365
 
    property to its default value and unsetting it.  The former can be achieved
366
 
    by calling <code>set(selector, { property: &quot;auto&quot; })</code> (or
367
 
    the respective default value for that property).
368
 
</p>
369
 
 
370
 
<p>
371
 
    However, as the CSS is reapplied to the page, the &quot;auto&quot; value
372
 
    will override any value for that property that may have cascaded in from
373
 
    another rule.  This is different than removing the property assignment
374
 
    entirely, as this allows cascading values through.
375
 
</p>
376
 
 
377
 
<pre class="code prettyprint">Y.StyleSheet(&#x27;MyApp&#x27;).set(&#x27;.foo&#x27;, { background: &#x27;auto&#x27; });
378
 
 
379
 
&#x2F;&#x2F; is NOT the same as
380
 
 
381
 
Y.StyleSheet(&#x27;MyApp&#x27;).unset(&#x27;.foo&#x27;,&#x27;background&#x27;);</pre>
382
 
 
383
 
 
384
 
<h3 id="not_selector">A note on selector strings</h3>
385
 
 
386
 
<p>
387
 
    Though the StyleSheet Utility takes selector strings as input to its API,
388
 
    it <em>does not</em> leverage the YUI selector engine.  YUI's selector
389
 
    functionality supplements native CSS support for DOM access, but
390
 
    accomplishes this through efficient DOM traversal.  Since the StyleSheet
391
 
    Utility uses the browser's built-in stylesheet and rule objects, it can not
392
 
    handle selectors that are not supported by the browser's native CSS
393
 
    parser.
394
 
</p>
395
 
 
396
 
<pre class="code prettyprint">&#x2F;&#x2F; This will not cause a style change in IE 6, for example
397
 
Y.StyleSheet(&#x27;MyApp&#x27;).set(&#x27;input[type=checkbox]:checked&#x27;, {
398
 
    verticalAlign : &#x27;super&#x27;
399
 
});</pre>
400
 
 
401
 
 
402
 
<h3 id="disable">Disabling and enabling a StyleSheet</h3>
403
 
 
404
 
<p>
405
 
    Disabling a StyleSheet effectively turns it off; no CSS from that
406
 
    stylesheet is applied to the page.  Disabling a StyleSheet does not remove
407
 
    the host node from the page, and style can be reapplied by enabling the
408
 
    StyleSheet again.
409
 
</p>
410
 
 
411
 
<p>
412
 
    When StyleSheets are disabled, it is still possible to change their style
413
 
    rules via <code>set</code> and <code>unset</code>.
414
 
</p>
415
 
 
416
 
<pre class="code prettyprint">var sheet = Y.StyleSheet(styleNode);
417
 
 
418
 
sheet.disable();
419
 
sheet.set(&#x27;.foo&#x27;, { backgroundColor: &#x27;#900&#x27;, color: &#x27;#fff&#x27; });
420
 
sheet.set(&#x27;.bar&#x27;, { borderBottomColor: &#x27;#369&#x27; });
421
 
sheet.unset(&#x27;.baz&#x27;);
422
 
sheet.enable();</pre>
423
 
 
424
 
 
425
 
<h3 id="static">Static methods</h3>
426
 
 
427
 
<p>
428
 
    <code>Y.StyleSheet</code> exposes a few static methods.
429
 
</p>
430
 
 
431
 
<div class="apisummary">
432
 
<table>
433
 
<thead>
434
 
    <tr>
435
 
        <th>Method</th>
436
 
        <th>Use for</th>
437
 
    </tr>
438
 
</thead>
439
 
<tbody>
440
 
    <tr>
441
 
        <td>
442
 
<pre class="code prettyprint">Y.StyleSheet.register(instance, name)</pre>
443
 
 
444
 
        </td>
445
 
        <td>Use to assign a named registry entry for a StyleSheet instance.</td>
446
 
    </tr>
447
 
    <tr>
448
 
        <td>
449
 
<pre class="code prettyprint">Y.StyleSheet.toCssText(property_obj, starting_cssText)</pre>
450
 
 
451
 
        </td>
452
 
        <td>Use to translate an object of style property:value pairs to a single <code>cssText</code> string.  The optional second argument is a <code>cssText</code> string of a style's &quot;before&quot; state.</td>
453
 
    </tr>
454
 
</tbody>
455
 
</table>
456
 
</div>
457
 
 
458
 
<p>
459
 
    <code>Y.StyleSheet.toCssText</code> is used internally to assemble the
460
 
    <code>cssText</code> strings for updating the stylesheet rules.  However,
461
 
    it may also be helpful for avoiding reflow overhead when substantially
462
 
    modifying a single element's style.
463
 
</p>
464
 
 
465
 
<pre class="code prettyprint">var el           = Y.one(&#x27;some_element&#x27;),
466
 
    changes      = { color : &#x27;#684&#x27;, fontWeight: &#x27;bold&#x27;, padding: &#x27;2em&#x27; },
467
 
    currentStyle = el.getStyle(&#x27;cssText&#x27;);
468
 
 
469
 
el.setStyle(&#x27;cssText&#x27;,
470
 
    Y.StyleSheet.toCssText(changes, currentStyle));</pre>
471
 
 
472
 
 
473
 
<h2 id="mechanism">How <code>Y.StyleSheet</code> works</h2>
474
 
 
475
 
<p>
476
 
    Browsers grant access via the DOM API to stylesheets included in markup as
477
 
    <code>&lt;link&gt;</code> or <code>&lt;style&gt;</code> elements.  Despite
478
 
    differing implementations across the browser spectrum, they all support
479
 
    adding, removing, and modifying CSS rules.
480
 
</p>
481
 
 
482
 
<p>
483
 
    CSS rules are comprised of a selector and collection of style
484
 
    property:value pairs enclosed in curly braces.
485
 
</p>
486
 
 
487
 
<pre class="code prettyprint">&#x2F;* |            This is a CSS rule          |
488
 
   |    selectorText    |  style properties | *&#x2F;
489
 
   div.this-is a .rule  { font-color: #f00; }</pre>
490
 
 
491
 
 
492
 
<p>
493
 
    In JavaScript, each rule object has a <code>selectorText</code> property
494
 
    and a <code>style</code> property that operates in the same way as the
495
 
    <code>style</code> property on regular DOM elements, such as
496
 
    <code>&lt;p&gt;</code> or <code>&lt;strong&gt;</code> elements.
497
 
</p>
498
 
 
499
 
<p>
500
 
    Arguably the most valuable property of the style collection is
501
 
    <code>cssText</code> which corresponds to the serialized summary of
502
 
    property:value pairs applied by this collection (e.g. "font-size: 100%;
503
 
    color: #FF0000;").  The reason this property is important is that
504
 
    modifications to the string value will cause changes to repopulate the
505
 
    individual style properties <em>while only triggering a single repaint or
506
 
    reflow</em> by the browser.
507
 
</p>
508
 
 
509
 
<pre class="code prettyprint">var el = document.getElementById(&#x27;some_element&#x27;);
510
 
 
511
 
el.style.borderBottom = &#x27;3px solid #eee&#x27;; &#x2F;&#x2F; reflow
512
 
el.style.borderTop    = &#x27;3px solid #ccc&#x27;; &#x2F;&#x2F; another reflow
513
 
el.style.fontWeight   = &#x27;bold&#x27;;           &#x2F;&#x2F; another reflow
514
 
 
515
 
&#x2F;&#x2F; Vs. three changes in one reflow
516
 
el.style.cssText += &#x27;; border-bottom: 3px solid #eee; border-top: 3px solid #ccc; font-weight: bold&#x27;;</pre>
517
 
 
518
 
 
519
 
<p>
520
 
    <code>Y.StyleSheet</code> leverages this mechanism in addition to applying
521
 
    modifications at the CSS rule level rather than modifying each targeted DOM
522
 
    node directly.  This means changing multiple style properties on multiple
523
 
    elements (that can be identified by a single selector) will only ever incur
524
 
    one repaint or reflow.
525
 
</p>
526
 
 
527
 
<p>
528
 
    It must be noted that all reflows are not the same.  The scope of a reflow
529
 
    is greatly affected by what element triggered it.  For example, changing a
530
 
    style of an absolutely positioned element will trigger a very limited
531
 
    reflow because the browser understands that not much <em>could</em> change
532
 
    as a result.  Stylesheet modifications on the other hand are not tied to an
533
 
    element, but the page as a whole.  The CSS cascade must be recalculated and
534
 
    applied, resulting in a full page reflow.  This means it may be more
535
 
    efficient to individually update many elements than to change the
536
 
    stylesheet.
537
 
</p>
538
 
 
539
 
<h2 id="knownissues">Known Issues</h2>
540
 
 
541
 
<p>
542
 
    <strong>Unable to set style values with
543
 
    <code>!important</code></strong>.
544
 
</p>
545
 
 
546
 
<p>
547
 
    CSS syntax for declaring that a style value has <code>important</code>
548
 
    priority is to include the <code>!important</code> flag after the
549
 
    value.
550
 
</p>
551
 
 
552
 
<pre class="code prettyprint">.some-class {
553
 
    color: #000 !important;
554
 
}</pre>
555
 
 
556
 
 
557
 
<p>
558
 
    However, the DOM API for modifying stylesheets does not parse out the
559
 
    <code>!important</code> flag from the assigned value string, and thus
560
 
    considers the entire string to be an invalid value.
561
 
</p>
562
 
 
563
 
<pre class="code prettyprint">el.style.color = &quot;#000 !important&quot;; &#x2F;&#x2F; Error</pre>
564
 
 
565
 
 
566
 
<p>
567
 
    StyleSheet will support <code>!important</code> in the value string in a
568
 
    future release, but for now the only way to assign an
569
 
    <code>!important</code> style is by creating a new StyleSheet, passing a
570
 
    CSS text string to the constructor.
571
 
</p>
572
 
 
573
 
<pre class="code prettyprint">var sheet = new Y.StyleSheet();
574
 
sheet.set(&quot;.foo&quot;, { color: &quot;#000 !important&quot; }); &#x2F;&#x2F; FAIL
575
 
 
576
 
new Y.StyleSheet(&quot;.foo { color: #000 !important; }&quot;); &#x2F;&#x2F; WORKS</pre>
577
 
 
578
 
</div>
579
 
            </div>
580
 
        </div>
581
 
 
582
 
        <div class="yui3-u-1-4">
583
 
            <div class="sidebar">
584
 
                
585
 
                    <div id="toc" class="sidebox">
586
 
                        <div class="hd">
587
 
                            <h2 class="no-toc">Table of Contents</h2>
588
 
                        </div>
589
 
 
590
 
                        <div class="bd">
591
 
                            <ul class="toc">
592
 
<li>
593
 
<a href="#getting-started">Getting Started</a>
594
 
</li>
595
 
<li>
596
 
<a href="#using">Using the StyleSheet Utility</a>
597
 
<ul class="toc">
598
 
<li>
599
 
<a href="#instantiating">Instantiating a <code>Y.StyleSheet</code></a>
600
 
</li>
601
 
<li>
602
 
<a href="#registry">Getting a StyleSheet by registered name</a>
603
 
</li>
604
 
<li>
605
 
<a href="#first_param">Summary of how the constructor handles the first argument</a>
606
 
</li>
607
 
<li>
608
 
<a href="#set">Creating and modifying CSS style rules</a>
609
 
</li>
610
 
<li>
611
 
<a href="#normalized_properties">Some style properties are normalized</a>
612
 
</li>
613
 
<li>
614
 
<a href="#unset">Removing and resetting CSS style rules</a>
615
 
</li>
616
 
<li>
617
 
<a href="#not_selector">A note on selector strings</a>
618
 
</li>
619
 
<li>
620
 
<a href="#disable">Disabling and enabling a StyleSheet</a>
621
 
</li>
622
 
<li>
623
 
<a href="#static">Static methods</a>
624
 
</li>
625
 
</ul>
626
 
</li>
627
 
<li>
628
 
<a href="#mechanism">How <code>Y.StyleSheet</code> works</a>
629
 
</li>
630
 
<li>
631
 
<a href="#knownissues">Known Issues</a>
632
 
</li>
633
 
</ul>
634
 
                        </div>
635
 
                    </div>
636
 
                
637
 
 
638
 
                
639
 
                    <div class="sidebox">
640
 
                        <div class="hd">
641
 
                            <h2 class="no-toc">Examples</h2>
642
 
                        </div>
643
 
 
644
 
                        <div class="bd">
645
 
                            <ul class="examples">
646
 
                                
647
 
                                    
648
 
                                        <li data-description="Use StyleSheet to adjust the CSS rules applying a page theme from user input">
649
 
                                            <a href="stylesheet-theme.html">Adjusting a Page Theme on the Fly</a>
650
 
                                        </li>
651
 
                                    
652
 
                                
653
 
                                    
654
 
                                
655
 
                            </ul>
656
 
                        </div>
657
 
                    </div>
658
 
                
659
 
 
660
 
                
661
 
                    <div class="sidebox">
662
 
                        <div class="hd">
663
 
                            <h2 class="no-toc">Examples That Use This Component</h2>
664
 
                        </div>
665
 
 
666
 
                        <div class="bd">
667
 
                            <ul class="examples">
668
 
                                
669
 
                                    
670
 
                                
671
 
                                    
672
 
                                        <li data-description="Example Photo Browser application.">
673
 
                                            <a href="../dd/photo-browser.html">Photo Browser</a>
674
 
                                        </li>
675
 
                                    
676
 
                                
677
 
                            </ul>
678
 
                        </div>
679
 
                    </div>
680
 
                
681
 
            </div>
682
 
        </div>
683
 
    </div>
684
 
</div>
685
 
 
686
 
<script src="../assets/vendor/prettify/prettify-min.js"></script>
687
 
<script>prettyPrint();</script>
688
 
 
689
 
</body>
690
 
</html>