2 Copyright (c) 2009, Yahoo! Inc. All rights reserved.
3 Code licensed under the BSD License:
4 http://developer.yahoo.net/yui/license.txt
8 YUI.add('stylesheet', function(Y) {
11 * The StyleSheet component is a module for creating and modifying CSS
17 p = d.createElement('p'), // Have to hold the node (see notes)
18 workerStyle = p.style, // worker style collection
19 isString = Y.Lang.isString,
22 floatAttr = ('cssFloat' in workerStyle) ? 'cssFloat' : 'styleFloat',
30 // Normalizes the removal of an assigned style for opacity. IE uses the filter
32 _unsetOpacity = (OPACITY in workerStyle) ?
33 function (style) { style.opacity = EMPTY; } :
34 function (style) { style.filter = EMPTY; };
36 // Normalizes the removal of an assigned style for a given property. Expands
37 // shortcut properties if necessary and handles the various names for the float
39 workerStyle.border = "1px solid red";
40 workerStyle.border = EMPTY; // IE doesn't unset child properties
41 _unsetProperty = workerStyle.borderLeft ?
42 function (style,prop) {
44 if (prop !== floatAttr && prop.toLowerCase().indexOf(FLOAT) != -1) {
47 if (isString(style[prop])) {
50 case 'filter' : _unsetOpacity(style); break;
52 style.font = style.fontStyle = style.fontVariant =
53 style.fontWeight = style.fontSize = style.lineHeight =
54 style.fontFamily = EMPTY;
58 if (p.indexOf(prop) === 0) {
65 function (style,prop) {
66 if (prop !== floatAttr && prop.toLowerCase().indexOf(FLOAT) != -1) {
69 if (isString(style[prop])) {
70 if (prop === OPACITY) {
79 * Create an instance of StyleSheet to encapsulate a css stylesheet.
80 * The constructor can be called using function or constructor syntax.
81 * <pre><code>var sheet = Y.StyleSheet(..);</pre></code>
83 * <pre><code>var sheet = new Y.StyleSheet(..);</pre></code>
85 * The first parameter passed can be any of the following things:
87 * <li>The desired string name to register a new empty sheet</li>
88 * <li>The string name of an existing StyleSheet instance</li>
89 * <li>The unique guid generated for an existing StyleSheet instance</li>
90 * <li>The id of an existing <code><link></code> or <code><style></code> node</li>
91 * <li>The node reference for an existing <code><link></code> or <code><style></code> node</li>
92 * <li>The Y.Node instance wrapping an existing <code><link></code> or <code><style></code> node</li>
93 * <li>A chunk of css text to create a new stylesheet from</li>
96 * <p>If a string is passed, StyleSheet will first look in its static name
97 * registry for an existing sheet, then in the DOM for an element with that id.
98 * If neither are found and the string contains the { character, it will be
99 * used as a the initial cssText for a new StyleSheet. Otherwise, a new empty
100 * StyleSheet is created, assigned the string value as a name, and registered
101 * statically by that name.</p>
103 * <p>The optional second parameter is a string name to register the sheet as.
104 * This param is largely useful when providing a node id/ref or chunk of css
105 * text to create a populated instance.</p>
109 * @param seed {String|HTMLElement|Node} a style or link node, its id, or a
110 * name or guid of a StyleSheet, or a string of css text
111 * @param name {String} (optional) name to register instance for future static
114 function StyleSheet(seed, name) {
124 // Factory or constructor
125 if (!(this instanceof StyleSheet)) {
126 return new StyleSheet(seed,name);
129 // Extract the DOM node from Node instances
131 if (Y.Node && seed instanceof Y.Node) {
132 node = Y.Node.getDOMNode(seed);
133 } else if (seed.nodeName) {
135 // capture the DOM node if the string is an id
136 } else if (isString(seed)) {
137 if (seed && sheets[seed]) {
140 node = d.getElementById(seed.replace(/^#/,EMPTY));
143 // Check for the StyleSheet in the static registry
144 if (node && sheets[Y.stamp(node)]) {
145 return sheets[Y.stamp(node)];
150 // Create a style node if necessary
151 if (!node || !/^(?:style|link)$/i.test(node.nodeName)) {
152 node = d.createElement('style');
153 node.type = 'text/css';
156 if (isString(seed)) {
157 // Create entire sheet from seed cssText
158 if (seed.indexOf('{') != -1) {
159 // Not a load-time fork because low run-time impact and IE fails
160 // test for s.styleSheet at page load time (oddly)
161 if (node.styleSheet) {
162 node.styleSheet.cssText = seed;
164 node.appendChild(d.createTextNode(seed));
171 // Make sure the node is attached to the appropriate head element
172 if (!node.parentNode || node.parentNode.nodeName.toLowerCase() !== 'head') {
173 head = (node.ownerDocument || d).getElementsByTagName('head')[0];
174 // styleSheet isn't available on the style node in FF2 until appended
175 // to the head element. style nodes appended to body do not affect
177 head.appendChild(node);
180 // Begin setting up private aliases to the important moving parts
181 // 1. The stylesheet object
182 // IE stores StyleSheet under the "styleSheet" property
183 // Safari doesn't populate sheet for xdomain link elements
184 sheet = node.sheet || node.styleSheet;
186 // 2. The style rules collection
187 // IE stores the rules collection under the "rules" property
188 _rules = sheet && ('cssRules' in sheet) ? 'cssRules' : 'rules';
190 // 3. The method to remove a rule from the stylesheet
191 // IE supports removeRule
192 _deleteRule = ('deleteRule' in sheet) ?
193 function (i) { sheet.deleteRule(i); } :
194 function (i) { sheet.removeRule(i); };
196 // 4. The method to add a new rule to the stylesheet
197 // IE supports addRule with different signature
198 _insertRule = ('insertRule' in sheet) ?
199 function (sel,css,i) { sheet.insertRule(sel+' {'+css+'}',i); } :
200 function (sel,css,i) { sheet.addRule(sel,css,i); };
202 // 5. Initialize the cssRules map from the node
203 // xdomain link nodes forbid access to the cssRules collection, so this
204 // will throw an error.
205 // TODO: research alternate stylesheet, @media
206 for (i = sheet[_rules].length - 1; i >= 0; --i) {
207 r = sheet[_rules][i];
208 sel = r.selectorText;
211 cssRules[sel].style.cssText += ';' + r.style.cssText;
218 // Cache the instance by the generated Id
219 StyleSheet.register(Y.stamp(node),this);
221 // Register the instance by name if provided or defaulted from seed
223 StyleSheet.register(name,this);
229 * Get the unique stamp for this StyleSheet instance
232 * @return {Number} the static id
234 getId : function () { return Y.stamp(node); },
237 * Enable all the rules in the sheet
240 * @return {StyleSheet}
243 enable : function () { sheet.disabled = false; return this; },
246 * Disable all the rules in the sheet. Rules may be changed while the
247 * StyleSheet is disabled.
250 * @return {StyleSheet}
253 disable : function () { sheet.disabled = true; return this; },
256 * Returns false if the StyleSheet is disabled. Otherwise true.
261 isEnabled : function () { return !sheet.disabled; },
264 * <p>Set style properties for a provided selector string.
265 * If the selector includes commas, it will be split into individual
266 * selectors and applied accordingly. If the selector string does not
267 * have a corresponding rule in the sheet, it will be added.</p>
269 * <p>The object properties in the second parameter must be the JavaScript
270 * names of style properties. E.g. fontSize rather than font-size.</p>
272 * <p>The float style property will be set by any of "float",
273 * "styleFloat", or "cssFloat".</p>
276 * @param sel {String} the selector string to apply the changes to
277 * @param css {Object} Object literal of style properties and new values
278 * @return {StyleSheet}
281 set : function (sel,css) {
282 var rule = cssRules[sel],
283 multi = sel.split(/\s*,\s*/),i,
286 // IE's addRule doesn't support multiple comma delimited selectors
287 if (multi.length > 1) {
288 for (i = multi.length - 1; i >= 0; --i) {
289 this.set(multi[i], css);
294 // Some selector values can cause IE to hang
295 if (!StyleSheet.isValidSelector(sel)) {
299 // Opera throws an error if there's a syntax error in assigned
300 // cssText. Avoid this using a worker style collection, then
301 // assigning the resulting cssText.
303 rule.style.cssText = StyleSheet.toCssText(css,rule.style.cssText);
305 idx = sheet[_rules].length;
306 css = StyleSheet.toCssText(css);
308 // IE throws an error when attempting to addRule(sel,'',n)
309 // which would crop up if no, or only invalid values are used
311 _insertRule(sel, css, idx);
313 // Safari replaces the rules collection, but maintains the
314 // rule instances in the new collection when rules are
316 cssRules[sel] = sheet[_rules][idx];
323 * <p>Unset style properties for a provided selector string, removing
324 * their effect from the style cascade.</p>
326 * <p>If the selector includes commas, it will be split into individual
327 * selectors and applied accordingly. If there are no properties
328 * remaining in the rule after unsetting, the rule is removed.</p>
330 * <p>The style property or properties in the second parameter must be the
331 * JavaScript style property names. E.g. fontSize rather than font-size.</p>
333 * <p>The float style property will be unset by any of "float",
334 * "styleFloat", or "cssFloat".</p>
337 * @param sel {String} the selector string to apply the changes to
338 * @param css {String|Array} style property name or Array of names
339 * @return {StyleSheet}
342 unset : function (sel,css) {
343 var rule = cssRules[sel],
344 multi = sel.split(/\s*,\s*/),
348 // IE's addRule doesn't support multiple comma delimited selectors
349 // so rules are mapped internally by atomic selectors
350 if (multi.length > 1) {
351 for (i = multi.length - 1; i >= 0; --i) {
352 this.unset(multi[i], css);
361 workerStyle.cssText = rule.style.cssText;
362 for (i = css.length - 1; i >= 0; --i) {
363 _unsetProperty(workerStyle,css[i]);
366 if (workerStyle.cssText) {
367 rule.style.cssText = workerStyle.cssText;
373 if (remove) { // remove the rule altogether
374 rules = sheet[_rules];
375 for (i = rules.length - 1; i >= 0; --i) {
376 if (rules[i] === rule) {
377 delete cssRules[sel];
388 * Get the current cssText for a rule or the entire sheet. If the
389 * selector param is supplied, only the cssText for that rule will be
390 * returned, if found. If the selector string targets multiple
391 * selectors separated by commas, the cssText of the first rule only
392 * will be returned. If no selector string, the stylesheet's full
393 * cssText will be returned.
396 * @param sel {String} Selector string
399 getCssText : function (sel) {
403 // IE's addRule doesn't support multiple comma delimited
404 // selectors so rules are mapped internally by atomic selectors
405 rule = cssRules[sel.split(/\s*,\s*/)[0]];
407 return rule ? rule.style.cssText : null;
410 for (sel in cssRules) {
411 if (cssRules.hasOwnProperty(sel)) {
412 rule = cssRules[sel];
413 css.push(rule.selectorText+" {"+rule.style.cssText+"}");
416 return css.join("\n");
423 _toCssText = function (css,base) {
424 var f = css.styleFloat || css.cssFloat || css[FLOAT],
428 workerStyle.cssText = base || EMPTY;
430 if (f && !css[floatAttr]) {
432 delete css.styleFloat; delete css.cssFloat; delete css[FLOAT];
437 if (css.hasOwnProperty(prop)) {
439 // IE throws Invalid Value errors and doesn't like whitespace
440 // in values ala ' red' or 'red '
441 workerStyle[prop] = trim(css[prop]);
447 return workerStyle.cssText;
452 * <p>Converts an object literal of style properties and values into a string
453 * of css text. This can then be assigned to el.style.cssText.</p>
455 * <p>The optional second parameter is a cssText string representing the
456 * starting state of the style prior to alterations. This is most often
457 * extracted from the eventual target's current el.style.cssText.</p>
459 * @method StyleSheet.toCssText
460 * @param css {Object} object literal of style properties and values
461 * @param cssText {String} (optional) starting cssText value
462 * @return {String} the resulting cssText string
465 toCssText : ((OPACITY in workerStyle) ? _toCssText :
466 // Wrap IE's toCssText to catch opacity. The copy/merge is to preserve
467 // the input object's integrity, but if float and opacity are set, the
468 // input will be copied twice in IE. Is there a way to avoid this
469 // without increasing the byte count?
470 function (css, cssText) {
471 if (OPACITY in css) {
473 filter: 'alpha(opacity='+(css.opacity*100)+')'
477 return _toCssText(css,cssText);
481 * Registers a StyleSheet instance in the static registry by the given name
483 * @method StyleSheet.register
484 * @param name {String} the name to assign the StyleSheet in the registry
485 * @param sheet {StyleSheet} The StyleSheet instance
486 * @return {Boolean} false if no name or sheet is not a StyleSheet
487 * instance. true otherwise.
490 register : function (name,sheet) {
491 return !!(name && sheet instanceof StyleSheet &&
492 !sheets[name] && (sheets[name] = sheet));
496 * <p>Determines if a selector string is safe to use. Used internally
497 * in set to prevent IE from locking up when attempting to add a rule for a
498 * "bad selector".</p>
500 * <p>Bad selectors are considered to be any string containing unescaped
501 * `~!@$%^&()+=|{}[];'"?< or space. Also forbidden are . or # followed by
502 * anything other than an alphanumeric. Additionally -abc or .-abc or
503 * #_abc or '# ' all fail. There are likely more failure cases, so
504 * please file a bug if you encounter one.</p>
506 * @method StyleSheet.isValidSelector
507 * @param sel {String} the selector string
511 isValidSelector : function (sel) {
514 if (sel && isString(sel)) {
516 if (!selectors.hasOwnProperty(sel)) {
517 // TEST: there should be nothing but white-space left after
518 // these destructive regexs
519 selectors[sel] = !/\S/.test(
521 sel.replace(/\s+|\s*[+~>]\s*/g,' ').
522 // attribute selectors (contents not validated)
523 replace(/([^ ])\[.*?\]/g,'$1').
524 // pseudo-class|element selectors (contents of parens
525 // such as :nth-of-type(2) or :not(...) not validated)
526 replace(/([^ ])::?[a-z][a-z\-]+[a-z](?:\(.*?\))?/ig,'$1').
528 replace(/(?:^| )[a-z0-6]+/ig,' ').
529 // escaped characters
530 replace(/\\./g,EMPTY).
531 // class and id identifiers
532 replace(/[.#]\w[\w\-]*/g,EMPTY));
535 valid = selectors[sel];
542 Y.StyleSheet = StyleSheet;
547 * Style node must be added to the head element. Safari does not honor styles
548 applied to StyleSheet objects on style nodes in the body.
549 * StyleSheet object is created on the style node when the style node is added
550 to the head element in Firefox 2 (and maybe 3?)
551 * The cssRules collection is replaced after insertRule/deleteRule calls in
552 Safari 3.1. Existing Rules are used in the new collection, so the collection
553 cannot be cached, but the rules can be.
554 * Opera requires that the index be passed with insertRule.
555 * Same-domain restrictions prevent modifying StyleSheet objects attached to
556 link elements with remote href (or "about:blank" or "javascript:false")
557 * Same-domain restrictions prevent reading StyleSheet cssRules/rules
558 collection of link elements with remote href (or "about:blank" or
560 * Same-domain restrictions result in Safari not populating node.sheet property
561 for link elements with remote href (et.al)
562 * IE names StyleSheet related properties and methods differently (see code)
563 * IE converts tag names to upper case in the Rule's selectorText
564 * IE converts empty string assignment to complex properties to value settings
565 for all child properties. E.g. style.background = '' sets non-'' values on
566 style.backgroundPosition, style.backgroundColor, etc. All else clear
567 style.background and all child properties.
568 * IE assignment style.filter = '' will result in style.cssText == 'FILTER:'
569 * All browsers support Rule.style.cssText as a read/write property, leaving
570 only opacity needing to be accounted for.
571 * Benchmarks of style.property = value vs style.cssText += 'property: value'
572 indicate cssText is slightly slower for single property assignment. For
573 multiple property assignment, cssText speed stays relatively the same where
574 style.property speed decreases linearly by the number of properties set.
575 Exception being Opera 9.27, where style.property is always faster than
577 * Opera 9.5b throws a syntax error when assigning cssText with a syntax error.
578 * Opera 9.5 doesn't honor rule.style.cssText = ''. Previous style persists.
579 You have to remove the rule altogether.
580 * Stylesheet properties set with !important will trump inline style set on an
581 element or in el.style.property.
582 * Creating a worker style collection like document.createElement('p').style;
583 will fail after a time in FF (~5secs of inactivity). Property assignments
584 will not alter the property or cssText. It may be the generated node is
585 garbage collected and the style collection becomes inert (speculation).
586 * IE locks up when attempting to add a rule with a selector including at least
587 characters {[]}~`!@%^&*()+=|? (unescaped) and leading _ or -
588 such as addRule('-foo','{ color: red }') or addRule('._abc','{...}')
589 * IE's addRule doesn't support comma separated selectors such as
590 addRule('.foo, .bar','{..}')
591 * IE throws an error on valid values with leading/trailing white space.
592 * When creating an entire sheet at once, only FF2/3 & Opera allow creating a
593 style node, setting its innerHTML and appending to head.
594 * When creating an entire sheet at once, Safari requires the style node to be
595 created with content in innerHTML of another element.
596 * When creating an entire sheet at once, IE requires the style node content to
597 be set via node.styleSheet.cssText
598 * When creating an entire sheet at once in IE, styleSheet.cssText can't be
599 written until node.type = 'text/css'; is performed.
600 * When creating an entire sheet at once in IE, load-time fork on
601 var styleNode = d.createElement('style'); _method = styleNode.styleSheet ?..
602 fails (falsey). During run-time, the test for .styleSheet works fine
603 * Setting complex properties in cssText will SOMETIMES allow child properties
605 set unset FF2 FF3 S3.1 IE6 IE7 Op9.27 Op9.5
606 ---------- ----------------- --- --- ---- --- --- ------ -----
607 border -top NO NO YES YES YES YES YES
608 -top-color NO NO YES YES YES
609 -color NO NO NO NO NO
610 background -color NO NO YES YES YES
611 -position NO NO YES YES YES
612 -position-x NO NO NO NO NO
613 font line-height YES YES NO NO NO NO YES
614 -style YES YES NO YES YES
615 -size YES YES NO YES YES
616 -size-adjust ??? ??? n/a n/a n/a ??? ???
617 padding -top NO NO YES YES YES
618 margin -top NO NO YES YES YES
619 list-style -type YES YES YES YES YES
620 -position YES YES YES YES YES
621 overflow -x NO NO YES n/a YES
623 ??? - unsetting font-size-adjust has the same effect as unsetting font-size
624 * FireFox and WebKit populate rule.cssText as "SELECTOR { CSSTEXT }", but
626 * IE6 and IE7 silently ignore the { and } if passed into addRule('.foo','{
627 color:#000}',0). IE8 does not and creates an empty rule.
628 * IE6-8 addRule('.foo','',n) throws an error. Must supply *some* cssText