--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/cm/media/js/lib/yui/yui_3.10.3/docs/stylesheet/index.html Tue Jul 16 14:29:46 2013 +0200
@@ -0,0 +1,714 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="utf-8">
+ <title>StyleSheet</title>
+ <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=PT+Sans:400,700,400italic,700italic">
+ <link rel="stylesheet" href="../../build/cssgrids/cssgrids-min.css">
+ <link rel="stylesheet" href="../assets/css/main.css">
+ <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
+ <link rel="shortcut icon" type="image/png" href="../assets/favicon.png">
+ <script src="../../build/yui/yui-min.js"></script>
+
+</head>
+<body>
+<!--
+<a href="https://github.com/yui/yui3"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"></a>
+-->
+<div id="doc">
+ <div id="hd">
+ <h1><img src="http://yuilibrary.com/img/yui-logo.png"></h1>
+ </div>
+
+ <a href="#toc" class="jump">Jump to Table of Contents</a>
+
+
+ <h1>StyleSheet</h1>
+ <div class="yui3-g">
+ <div class="yui3-u-3-4">
+ <div id="main">
+ <div class="content"><div class="intro component">
+ <p>
+ The StyleSheet module normalizes the dynamic creation and modification
+ of CSS stylesheets on a page. This makes it easy to manage the
+ development, storage, and reapplication of personalized user
+ stylesheets. Because it targets styles at the CSS level, it also
+ allows you to modify styles applied to a CSS pseudo-element such as
+ <code>p::first-letter</code>, or pseudo-class such as
+ <code>a:hover</code>.
+ </p>
+
+ <p>
+ StyleSheet is capable of creating new stylesheets from scratch or
+ modifying existing stylesheets held as properties of
+ <code><link></code> or <code><style></code> elements. It
+ should be noted that not all browsers support reading or modifying
+ external stylesheets from other domains.
+ </p>
+</div>
+
+<h2 id="getting-started">Getting Started</h2>
+
+<p>
+To include the source files for StyleSheet and its dependencies, first load
+the YUI seed file if you haven't already loaded it.
+</p>
+
+<pre class="code prettyprint"><script src="http://yui.yahooapis.com/3.10.3/build/yui/yui-min.js"></script></pre>
+
+
+<p>
+Next, create a new YUI instance for your application and populate it with the
+modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
+YUI will automatically load any dependencies required by the modules you
+specify.
+</p>
+
+<pre class="code prettyprint"><script>
+// Create a new YUI instance and populate it with the required modules.
+YUI().use('stylesheet', function (Y) {
+ // StyleSheet is available and ready for use. Add implementation
+ // code here.
+});
+</script></pre>
+
+
+<p>
+For more information on creating YUI instances and on the
+<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
+documentation for the <a href="../yui/index.html">YUI Global Object</a>.
+</p>
+
+
+<h2 id="using">Using the StyleSheet Utility</h2>
+
+<h3 id="instantiating">Instantiating a <code>Y.StyleSheet</code></h3>
+
+<p>
+ The <code>Y.StyleSheet</code> constructor is written to support both
+ function syntax and normal constructor syntax making the <code>new</code>
+ prefix unnecessary (but harmless).
+</p>
+
+<p>
+ The constructor has no required parameters. Passing no arguments will
+ create a new, empty StyleSheet instance.
+</p>
+
+<pre class="code prettyprint">// These are equivalent; both create new empty StyleSheets
+var myStyleSheet = new Y.StyleSheet();
+
+var myOtherStyleSheet = Y.StyleSheet();</pre>
+
+
+<p>
+ To seed a new StyleSheet with a number of CSS rules, you can pass the
+ constructor any of the following:
+</p>
+
+<ol>
+ <li>
+ a <code><style></code> or <code><link></code> node
+ reference,
+ </li>
+ <li>
+ the id of a <code><style></code> or <code><link></code>
+ node, or
+ </li>
+ <li>a string of CSS</li>
+</ol>
+
+<pre class="code prettyprint"><link id="local" type="text/css" rel="stylesheet" href="local_file.css">
+<style id="styleblock" type="text/css">
+ .some select.or {
+ margin-right: 2em;
+ }
+</style></pre>
+
+
+<pre class="code prettyprint">YUI().use('node','stylesheet', function (Y) {
+
+ // Node or HTMLElement reference for a style or locally sourced link element
+ var sheet = Y.StyleSheet(Y.one("#styleblock"));
+ sheet = Y.StyleSheet(Y.DOM.byId('local'));
+
+ // OR the id of a style element or locally sourced link element
+ sheet = Y.StyleSheet('#local');
+
+ // OR string of css text
+ var css = ".moduleX .alert { background: #fcc; font-weight: bold; } " +
+ ".moduleX .warn { background: #eec; } " +
+ ".hide_messages .moduleX .alert, " +
+ ".hide_messages .moduleX .warn { display: none; }";
+
+ sheet = new Y.StyleSheet(css);
+
+ //...
+});</pre>
+
+
+<p>
+ Be aware that the <a
+ href="http://en.wikipedia.org/wiki/Same_origin_policy">Same Origin
+ policy</a> prevents access in some browsers to the style data of
+ <code><link></code> elements with <code>href</code>s pointing to
+ other domains. Attempts to seed a <code>Y.StyleSheet</code> instance with
+ a cross-domain <code><link></code> may result in a security
+ error.
+</p>
+
+<pre class="code prettyprint"><link id="remote" type="text/css" rel="stylesheet" href="http://other.domain.com/remote_file.css"></pre>
+
+
+<pre class="code prettyprint">// ERROR - Same Origin Policy prevents access to remote stylesheets
+var styleSheet = Y.StyleSheet('remote');</pre>
+
+
+<h3 id="registry">Getting a StyleSheet by registered name</h3>
+
+<p>
+ <code>Y.StyleSheet</code> supports registering instances by name allowing
+ them to be recalled by that same name elsewhere in your code. Internally,
+ <code>Y.StyleSheet</code> maintains a registry of all created StyleSheet
+ instances, using a unique generated id that the host node is tagged with.
+ This allows future attempts to create a StyleSheet instance from the same
+ node to return the previously created instance associated with that id.
+</p>
+
+<p>
+ Register a StyleSheet instance manually using the static
+ <code>register</code> method or pass the desired name as a second parameter
+ to the constructor.
+</p>
+
+<pre class="code prettyprint">var sheetA = Y.StyleSheet('my_stylesheet');
+
+// Create a registry alias to sheetA. We'll call it bob.
+Y.StyleSheet.register(sheetA, 'bob');
+
+// Create another StyleSheet passing the name as the second parameter
+var css = ".some .css { white-space: pre-wrap; color: pink; }";
+var sheetB = Y.StyleSheet(css, 'my sheet');
+
+// Meanwhile, elsewhere in your code
+
+// sheetA is the same instance as sheet1 and sheet2
+var sheet1 = Y.StyleSheet(Y.one('#my_stylesheet')),
+ sheet2 = Y.StyleSheet('bob');
+
+// sheetB is the same instance as sheet3
+var sheet3 = Y.StyleSheet('my sheet');</pre>
+
+
+<p>
+ If an unregistered name is passed as the <em>first</em> argument to the
+ constructor, a new empty StyleSheet will be created and registered with
+ that name. This allows you to use the following code pattern:
+</p>
+
+<pre class="code prettyprint">// Whichever of these executes first, an empty StyleSheet will be created
+// and registered as 'MyApp'.
+
+// In one area of your app
+Y.StyleSheet('MyApp').set('.module .messages', { display: 'none' });
+
+//...
+
+// In another area of your app
+Y.StyleSheet('MyApp').unset('.module .messages','display');</pre>
+
+
+<h3 id="first_param">Summary of how the constructor handles the first argument</h3>
+
+<p>
+ When nothing is passed as the first argument, a new StyleSheet instance is
+ created.
+</p>
+
+<p>
+ When a <code><style></code> or <code><link></code> element is
+ passed as the first argument, it is inspected for the id stamp that
+ StyleSheet tags known host nodes with. If it finds one, it will return the
+ associated StyleSheet from the registry. If not, it will stamp the node
+ and seed the instance from the node's CSS content.
+</p>
+
+<p>
+ When a string is passed as the first argument, StyleSheet does the
+ following things in order:
+</p>
+
+<ol>
+ <li>
+ Check the registry for an instance associated to that name. If found,
+ return the instance.
+ </li>
+ <li>
+ Check the DOM for a <code><style></code> or
+ <code><link></code> node with that id. If found, check the
+ registry for an instance associated to its tagged id if present. If
+ found, return that instance. If not, use that node to seed a new
+ StyleSheet instance.
+ </li>
+ <li>
+ Check the string for a curly brace { character. If found, create a new
+ instance seeded with the string as initial <code>cssText</code>.
+ </li>
+ <li>
+ Create a new empty StyleSheet and register the instance by the provided
+ string.
+ </li>
+</ol>
+
+<h3 id="set">Creating and modifying CSS style rules</h3>
+
+<p>
+ The core method of StyleSheet instances is <code>set(selector,
+ style_properties)</code>. It will create or alter a CSS rule using the
+ property:value pairs in <code>style_properties</code> targeting the
+ provided <code>selector</code>. In essence, it looks very much like
+ natural CSS syntax, <em>except style properties must be in JavaScript's
+ camelCase</em>.
+</p>
+
+<pre class="code prettyprint">Y.StyleSheet('MyApp').set(
+ "q.uoted select.or[str=ing]", {
+ fontSize : "150%", // note the camel casing
+ background : "#030 url(/images/bg_image.png) scroll repeat-y top left",
+ cssFloat : "left",
+ opacity : 0.5
+ });</pre>
+
+
+<p>
+ Rather than continually add new rules that will override one another,
+ StyleSheet manages one rule per selector and modifies them in place. This
+ may be relevant if you have two or more rules with selectors of the same
+ specificity.
+</p>
+
+<p>
+ As with regular CSS syntax, comma-separated selectors are supported, but
+ internally StyleSheet splits them up into individual rules because browser
+ support for multiple selectors is not consistent. This means calling
+ <code>set(..)</code> with such a selector string <em>will incur multiple
+ repaints or reflows</em>, but limited to the number of atomic
+ selectors.
+</p>
+
+<pre class="code prettyprint">// This is valid, but will trigger 3 reflows
+Y.StyleSheet('MyApp').set(
+ '.foo, .bar, .baz', {
+ borderRight: "1em solid #f00"
+ });</pre>
+
+
+<h3 id="normalized_properties">Some style properties are normalized</h3>
+
+<p>
+ Two style properties have differing implementation between browsers, namely
+ <code>float</code> and <code>opacity</code>. StyleSheet instances will
+ normalize these properties for you.
+</p>
+
+<p>
+ Because "float" is a reserved word in JavaScript, it is supported
+ by the name <code>cssFloat</code> in W3C compliant browsers and
+ <code>styleFloat</code> in IE. StyleSheet will accept any of these to set
+ the <code>float</code> property.
+</p>
+
+<pre class="code prettyprint">// Any of these will work
+Y.StyleSheet('MyApp').set('.foo', {
+ "float" : "left", // "float" must be quoted
+ cssFloat : "right",
+ styleFloat : "none"
+});</pre>
+
+
+<p>
+ IE does not support the <code>opacity</code> style property, but has
+ equivalent functionality offered by its proprietary <code>filter</code>
+ property, though using a different value syntax. StyleSheet will translate
+ <code>opacity</code> to <code>filter</code> for IE, but it <em>will
+ not</em> translate <code>filter</code> to <code>opacity</code> for
+ W3C-compliant browsers.
+</p>
+
+<h3 id="unset">Removing and resetting CSS style rules</h3>
+
+<p>
+ When you want to remove a particular rule or style property from affecting
+ the cascade, use <code>unset(selector,propert[y|ies])</code>.
+</p>
+
+<p>
+ <code>unset(..)</code> can be called in any of the following ways, with the
+ noted result:
+</p>
+
+<ul>
+ <li>
+ <code>unset('.foo')</code> — removes the rule associated to the
+ selector entirely.
+ </li>
+ <li>
+ <code>unset('.foo','font')</code> — unsets the <code>font</code>
+ property and any child properties (e.g.
+ 'font-weight','font-variant','font-size','line-height', and
+ 'font-family'). If there are no set properties left, the rule is
+ removed.
+ </li>
+ <li>
+ <code>unset('.foo',['font','border',...])</code> — same as above,
+ but the rule is modified only once with the final applicable
+ <code>cssText</code>.
+ </li>
+</ul>
+
+<p>
+ It is important to note that there is a difference between setting a style
+ property to its default value and unsetting it. The former can be achieved
+ by calling <code>set(selector, { property: "auto" })</code> (or
+ the respective default value for that property).
+</p>
+
+<p>
+ However, as the CSS is reapplied to the page, the "auto" value
+ will override any value for that property that may have cascaded in from
+ another rule. This is different than removing the property assignment
+ entirely, as this allows cascading values through.
+</p>
+
+<pre class="code prettyprint">Y.StyleSheet('MyApp').set('.foo', { background: 'auto' });
+
+// is NOT the same as
+
+Y.StyleSheet('MyApp').unset('.foo','background');</pre>
+
+
+<h3 id="not_selector">A note on selector strings</h3>
+
+<p>
+ Though the StyleSheet Utility takes selector strings as input to its API,
+ it <em>does not</em> leverage the YUI selector engine. YUI's selector
+ functionality supplements native CSS support for DOM access, but
+ accomplishes this through efficient DOM traversal. Since the StyleSheet
+ Utility uses the browser's built-in stylesheet and rule objects, it can not
+ handle selectors that are not supported by the browser's native CSS
+ parser.
+</p>
+
+<pre class="code prettyprint">// This will not cause a style change in IE 6, for example
+Y.StyleSheet('MyApp').set('input[type=checkbox]:checked', {
+ verticalAlign : 'super'
+});</pre>
+
+
+<h3 id="disable">Disabling and enabling a StyleSheet</h3>
+
+<p>
+ Disabling a StyleSheet effectively turns it off; no CSS from that
+ stylesheet is applied to the page. Disabling a StyleSheet does not remove
+ the host node from the page, and style can be reapplied by enabling the
+ StyleSheet again.
+</p>
+
+<p>
+ When StyleSheets are disabled, it is still possible to change their style
+ rules via <code>set</code> and <code>unset</code>.
+</p>
+
+<pre class="code prettyprint">var sheet = Y.StyleSheet(styleNode);
+
+sheet.disable();
+sheet.set('.foo', { backgroundColor: '#900', color: '#fff' });
+sheet.set('.bar', { borderBottomColor: '#369' });
+sheet.unset('.baz');
+sheet.enable();</pre>
+
+
+<h3 id="static">Static methods</h3>
+
+<p>
+ <code>Y.StyleSheet</code> exposes a few static methods.
+</p>
+
+<div class="apisummary">
+<table>
+<thead>
+ <tr>
+ <th>Method</th>
+ <th>Use for</th>
+ </tr>
+</thead>
+<tbody>
+ <tr>
+ <td>
+<pre class="code prettyprint">Y.StyleSheet.register(instance, name)</pre>
+
+ </td>
+ <td>Use to assign a named registry entry for a StyleSheet instance.</td>
+ </tr>
+ <tr>
+ <td>
+<pre class="code prettyprint">Y.StyleSheet.toCssText(property_obj, starting_cssText)</pre>
+
+ </td>
+ <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 "before" state.</td>
+ </tr>
+</tbody>
+</table>
+</div>
+
+<p>
+ <code>Y.StyleSheet.toCssText</code> is used internally to assemble the
+ <code>cssText</code> strings for updating the stylesheet rules. However,
+ it may also be helpful for avoiding reflow overhead when substantially
+ modifying a single element's style.
+</p>
+
+<pre class="code prettyprint">var el = Y.one('some_element'),
+ changes = { color : '#684', fontWeight: 'bold', padding: '2em' },
+ currentStyle = el.getStyle('cssText');
+
+el.setStyle('cssText',
+ Y.StyleSheet.toCssText(changes, currentStyle));</pre>
+
+
+<h2 id="mechanism">How <code>Y.StyleSheet</code> works</h2>
+
+<p>
+ Browsers grant access via the DOM API to stylesheets included in markup as
+ <code><link></code> or <code><style></code> elements. Despite
+ differing implementations across the browser spectrum, they all support
+ adding, removing, and modifying CSS rules.
+</p>
+
+<p>
+ CSS rules are comprised of a selector and collection of style
+ property:value pairs enclosed in curly braces.
+</p>
+
+<pre class="code prettyprint">/* | This is a CSS rule |
+ | selectorText | style properties | */
+ div.this-is a .rule { font-color: #f00; }</pre>
+
+
+<p>
+ In JavaScript, each rule object has a <code>selectorText</code> property
+ and a <code>style</code> property that operates in the same way as the
+ <code>style</code> property on regular DOM elements, such as
+ <code><p></code> or <code><strong></code> elements.
+</p>
+
+<p>
+ Arguably the most valuable property of the style collection is
+ <code>cssText</code> which corresponds to the serialized summary of
+ property:value pairs applied by this collection (e.g. "font-size: 100%;
+ color: #FF0000;"). The reason this property is important is that
+ modifications to the string value will cause changes to repopulate the
+ individual style properties <em>while only triggering a single repaint or
+ reflow</em> by the browser.
+</p>
+
+<pre class="code prettyprint">var el = document.getElementById('some_element');
+
+el.style.borderBottom = '3px solid #eee'; // reflow
+el.style.borderTop = '3px solid #ccc'; // another reflow
+el.style.fontWeight = 'bold'; // another reflow
+
+// Vs. three changes in one reflow
+el.style.cssText += '; border-bottom: 3px solid #eee; border-top: 3px solid #ccc; font-weight: bold';</pre>
+
+
+<p>
+ <code>Y.StyleSheet</code> leverages this mechanism in addition to applying
+ modifications at the CSS rule level rather than modifying each targeted DOM
+ node directly. This means changing multiple style properties on multiple
+ elements (that can be identified by a single selector) will only ever incur
+ one repaint or reflow.
+</p>
+
+<p>
+ It must be noted that all reflows are not the same. The scope of a reflow
+ is greatly affected by what element triggered it. For example, changing a
+ style of an absolutely positioned element will trigger a very limited
+ reflow because the browser understands that not much <em>could</em> change
+ as a result. Stylesheet modifications on the other hand are not tied to an
+ element, but the page as a whole. The CSS cascade must be recalculated and
+ applied, resulting in a full page reflow. This means it may be more
+ efficient to individually update many elements than to change the
+ stylesheet.
+</p>
+
+<h2 id="knownissues">Known Issues</h2>
+
+<p>
+ <strong>Unable to set style values with
+ <code>!important</code></strong>.
+</p>
+
+<p>
+ CSS syntax for declaring that a style value has <code>important</code>
+ priority is to include the <code>!important</code> flag after the
+ value.
+</p>
+
+<pre class="code prettyprint">.some-class {
+ color: #000 !important;
+}</pre>
+
+
+<p>
+ However, the DOM API for modifying stylesheets does not parse out the
+ <code>!important</code> flag from the assigned value string, and thus
+ considers the entire string to be an invalid value.
+</p>
+
+<pre class="code prettyprint">el.style.color = "#000 !important"; // Error</pre>
+
+
+<p>
+ StyleSheet will support <code>!important</code> in the value string in a
+ future release, but for now the only way to assign an
+ <code>!important</code> style is by creating a new StyleSheet, passing a
+ CSS text string to the constructor.
+</p>
+
+<pre class="code prettyprint">var sheet = new Y.StyleSheet();
+sheet.set(".foo", { color: "#000 !important" }); // FAIL
+
+new Y.StyleSheet(".foo { color: #000 !important; }"); // WORKS</pre>
+
+</div>
+ </div>
+ </div>
+
+ <div class="yui3-u-1-4">
+ <div class="sidebar">
+
+ <div id="toc" class="sidebox">
+ <div class="hd">
+ <h2 class="no-toc">Table of Contents</h2>
+ </div>
+
+ <div class="bd">
+ <ul class="toc">
+<li>
+<a href="#getting-started">Getting Started</a>
+</li>
+<li>
+<a href="#using">Using the StyleSheet Utility</a>
+<ul class="toc">
+<li>
+<a href="#instantiating">Instantiating a <code>Y.StyleSheet</code></a>
+</li>
+<li>
+<a href="#registry">Getting a StyleSheet by registered name</a>
+</li>
+<li>
+<a href="#first_param">Summary of how the constructor handles the first argument</a>
+</li>
+<li>
+<a href="#set">Creating and modifying CSS style rules</a>
+</li>
+<li>
+<a href="#normalized_properties">Some style properties are normalized</a>
+</li>
+<li>
+<a href="#unset">Removing and resetting CSS style rules</a>
+</li>
+<li>
+<a href="#not_selector">A note on selector strings</a>
+</li>
+<li>
+<a href="#disable">Disabling and enabling a StyleSheet</a>
+</li>
+<li>
+<a href="#static">Static methods</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#mechanism">How <code>Y.StyleSheet</code> works</a>
+</li>
+<li>
+<a href="#knownissues">Known Issues</a>
+</li>
+</ul>
+ </div>
+ </div>
+
+
+
+ <div class="sidebox">
+ <div class="hd">
+ <h2 class="no-toc">Examples</h2>
+ </div>
+
+ <div class="bd">
+ <ul class="examples">
+
+
+ <li data-description="Use StyleSheet to adjust the CSS rules applying a page theme from user input">
+ <a href="stylesheet-theme.html">Adjusting a Page Theme on the Fly</a>
+ </li>
+
+
+
+
+ </ul>
+ </div>
+ </div>
+
+
+
+ <div class="sidebox">
+ <div class="hd">
+ <h2 class="no-toc">Examples That Use This Component</h2>
+ </div>
+
+ <div class="bd">
+ <ul class="examples">
+
+
+
+
+ <li data-description="Example Photo Browser application.">
+ <a href="../dd/photo-browser.html">Photo Browser</a>
+ </li>
+
+
+ </ul>
+ </div>
+ </div>
+
+ </div>
+ </div>
+ </div>
+</div>
+
+<script src="../assets/vendor/prettify/prettify-min.js"></script>
+<script>prettyPrint();</script>
+
+<script>
+YUI.Env.Tests = {
+ examples: [],
+ project: '../assets',
+ assets: '../assets/stylesheet',
+ name: 'stylesheet',
+ title: 'StyleSheet',
+ newWindow: '',
+ auto: false
+};
+YUI.Env.Tests.examples.push('stylesheet-theme');
+YUI.Env.Tests.examples.push('photo-browser');
+
+</script>
+<script src="../assets/yui/test-runner.js"></script>
+
+
+
+</body>
+</html>