--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/cm/media/js/lib/yui/yui_3.10.3/docs/cookie/index.html Tue Jul 16 14:29:46 2013 +0200
@@ -0,0 +1,412 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="utf-8">
+ <title>Cookie Utility</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>Cookie Utility</h1>
+ <div class="yui3-g">
+ <div class="yui3-u-3-4">
+ <div id="main">
+ <div class="content"><div class="intro">
+ <p>The YUI Cookie utility provides a simple API for interacting with cookies, including the creation and manipulation of subcookies.</p>
+
+ <p><strong>Note about HTTPOnly Cookies:</strong> HTTPOnly cookies are cookies that may be set either by JavaScript or by the server but cannot be read from JavaScript. The YUI Cookie utility does not provide support for setting HTTPOnly cookies because browser support is not well-established and there is no fallback mechanism. Setting an HTTPOnly cookie on a browser that doesn't support it is the same as setting any other cookie (no error is thrown). When all A-grade browsers support setting HTTPOnly cookies by JavaScript, we will revisit adding support for it in the Cookie utility.</p>
+</div>
+
+<h2 id="getting-started">Getting Started</h2>
+
+<p>
+To include the source files for Cookie Utility 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('cookie', function (Y) {
+ // Cookie Utility 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 Cookie Utility</h2>
+
+<h3 id="create">Creating Cookies</h3>
+
+<p>The simplest way to create a cookie is to provide a name and a value to the <code>set()</code> method:</p>
+
+<pre class="code prettyprint">// Create a YUI instance and use the cookie module.
+YUI().use('cookie', function(Y) {
+ Y.Cookie.set("name", "value");
+});</pre>
+
+
+<p>This example creates a cookie called "name" that has a value of "value". Since
+this cookie is created with all of the default settings, it becomes a session cookie.</p>
+
+<p>There is a third argument for <code>set()</code>, which is an object containing additional settings for the cookie. To create a persistent cookie, you can specify an expiration date by supplying a <code>Date</code> object:</p>
+
+<pre class="code prettyprint">// Create a YUI instance and use the cookie module.
+YUI().use('cookie', function(Y) {
+ Y.Cookie.set("name", "value", { expires: new Date("January 12, 2025") });
+});</pre>
+
+
+<p>By providing an "expires" option in the third argument, the cookie persists until the given date. In this example,
+the cookie will remain until January 12, 2025. The value for "expires" must be a <code>Date</code> object, otherwise
+it is ignored.</p>
+
+<p>It's possible to restrict access to a cookie by setting path and/or domain information. Setting a path on the cookie restricts access to pages that match that path; setting a domain restricts access to pages on a given domain (typically used to allow cookie access across subdomains). Both options can be easily set using the "path" and "domain" options:</p>
+
+<pre class="code prettyprint">// Create a YUI instance and use the cookie module.
+YUI().use('cookie', function(Y) {
+ Y.Cookie.set("name", "value", {
+ path: "/", //all pages
+ domain: "yahoo.com" //any subdomain of yahoo.com, including www.yahoo.com
+ });
+});</pre>
+
+
+<p>In this example, a cookie is created that can be accessed from all pages on a yahoo.com subdomain. This cookie would
+then be accessible from pages on <a href="http://sports.yahoo.com">sports.yahoo.com</a> as well as <a href="http://www.yahoo.com">www.yahoo.com</a>.
+The "path" and "domain" options need not be used together; they may be used independently as well.</p>
+
+<p>The last option is "secure", which indicates that the cookie should only be accessible via SSL on a page
+using the HTTPS protocol. All other aspects of the cookie remain the same based on the other options provided. To set a
+secure cookie, use the "secure" option:</p>
+
+<pre class="code prettyprint">// Create a YUI instance and use the cookie module.
+YUI().use('cookie', function(Y){
+ Y.Cookie.set("name", "value", { secure: true });
+});</pre>
+
+
+<p>This code creates a secure cookie by setting the "secure" option to <code>true</code>. Note that this will only work if the page calling this code uses the HTTPS protocol, otherwise the cookie will be created with default options.</p>
+
+<p>There is one more option called "raw". When this option is specified, the cookie will not be URL-encoded before being set. Setting a "raw" cookie typically means that you have specialized server-side logic to deal with cookies that aren't URL-encoded. This is considered an advanced option that should only be used when necessary. Example usage:</p>
+
+<pre class="code prettyprint">// Create a YUI instance and use the cookie module.
+YUI().use('cookie', function(Y){
+ Y.Cookie.set("name", "value", { raw: true });
+});</pre>
+
+
+<h3 id="read">Reading Cookies</h3>
+
+<p>The <code>get()</code> method retrieves cookies that are accessible by the current page. If a cookie doesn't exist, <code>get()</code> returns <code>null</code>.</p>
+
+<pre class="code prettyprint">// Create a YUI instance and use the cookie module.
+YUI().use('cookie', function(Y){
+ var value = Y.Cookie.get("name");
+});</pre>
+
+
+<p>This example retrieves the cookie called "name" and stores its value in the variable <code>value</code>. By default, values returned by <code>get()</code> are strings (if the cookie exists) or <code>null</code> (if the cookie doesn't exist). You can change the return value by providing a conversion function as the second argument. For example, to return a number, you can pass in the native <code>Number()</code> function:</p>
+
+<pre class="code prettyprint">// Create a YUI instance and use the cookie module.
+YUI().use('cookie', function(Y){
+ var value = Y.Cookie.get("age", Number);
+});</pre>
+
+
+<p>In this code, the returned cookie value will be a number if the cookie exists (it will still be <code>null</code> if the cookie doesn't exist). Other native functions that convert values are <code>Boolean()</code> and <code>Date</code>, or you can define your own conversion function:</p>
+
+<pre class="code prettyprint">// Create a YUI instance and use the cookie module.
+YUI().use('cookie', function(Y){
+ var value = Y.Cookie.get("code", function(stringValue){
+ return parseInt(stringValue, 16); // Create a number from a hexadecimal code
+ });
+});</pre>
+
+
+<p>Conversion functions accept a single argument, the string value of the cookie, and must return a value. In this example, the conversion function expects a hexadecimal code to be returned and passes it into <code>parseInt()</code> to convert the value into a number. Note that the conversion function is never called if the cookie doesn't exist (<code>get()</code> always returns <code>null</code> when the cookie doesn't exist).</p>
+
+<p>The second argument can optionally be an object if you'd like to read a raw cookie. As with, writing cookies, it's possible to read a cookie without URL-decoding the value. To specify this, the second argument should be an object, such as:</p>
+
+<pre class="code prettyprint">// Create a YUI instance and use the cookie module.
+YUI().use('cookie', function(Y){
+ var value = Y.Cookie.get("code", { raw: true });
+});</pre>
+
+
+<p>If you'd like to use a converter on a raw cookie, you can specify this using the "converter" option:</p>
+
+<pre class="code prettyprint">// Create a YUI instance and use the cookie module.
+YUI().use('cookie', function(Y){
+ var value = Y.Cookie.get("code", {
+ raw: true,
+ converter: function(stringValue){
+ return parseInt(stringValue, 16); // Create a number from a hexadecimal code
+ }
+ });
+});</pre>
+
+
+<h3 id="delete">Deleting Cookies</h3>
+
+<p>When a cookie is no longer need, it can be removed from the browser by calling the <code>remove()</code> method. This method takes two arguments: the name of the cookie to remove and an optional cookie options object. A cookie created with specific options can only be deleted by specifying the same options. For instance, a cookie created with a <code>domain</code> property of "yahoo.com" can only be deleted by also specifying the <code>domain</code> property as "yahoo.com". Examples:</p>
+
+<pre class="code prettyprint">// Create a YUI instance and use the cookie module.
+YUI().use('cookie', function(Y){
+ //delete the cookie named "code"
+ Y.Cookie.remove("code");
+
+ //delete the cookie named "info" on the "yahoo.com" domain
+ Y.Cookie.remove("info", { domain: "yahoo.com" });
+
+ //delete a secure cookie named "username"
+ Y.Cookie.remove("username", { secure: true });
+});</pre>
+
+
+<h3 id="sub">Subcookies</h3>
+
+<p>Each browser has a limit to the number of cookies that can be set per domain. These limits can be problematic for domains with different sites under different subdomains. Since cookie name-value pairs are rarely large enough to reach the byte limit for an individual cookie, it represents an opportunity to store multiple name-value pairs in a single cookie; these are called subcookies.</p>
+
+<p>A subcookie string looks similar to a URL and takes the following form:</p>
+
+<p><code>cookiename=name1=value1&name2=value2&name3=value3</code></p>
+
+<p>The Cookie utility supports this style of subcookies to allow multiple values to be stored in a single cookie. To set a subcookie value, use the <code>setSub()</code> method. This method accepts four arguments: the cookie name, the subcookie name, the subcookie value, and an optional options object. Note that the options object works on the entire cookie, it is not specific to the subcookie.</p>
+
+<pre class="code prettyprint">// Create a YUI instance and use the cookie module.
+YUI().use('cookie', function(Y){
+
+ //set a cookie named "name" with a subcookie named "subname" whose value is "value"
+ Y.Cookie.setSub("name", "subname", "value");
+
+ //set a second subcookie on "name", with a name of "subname2" and a value of "value2"
+ Y.Cookie.setSub("name", "subname2", "value2");
+
+ //set subcookie on the "yahoo.com" domain
+ Y.Cookie.setSub("info", "age", 22, { domain: "yahoo.com" });
+
+ //set subcookie to a secure cookie named "user"
+ Y.Cookie.setSub("user", "name", "ace123", { secure:true });
+});</pre>
+
+
+<p>It's possible to set the entire contents of a subcookie by using the <code>setSubs()</code> method, which accepts three arguments:
+the name of the cookie, and object containing name-value pairs, and an optional cookie options object. For instance, this code
+sets three subcookies at once:</p>
+
+<pre class="code prettyprint">// Create a YUI instance and use the cookie module.
+YUI().use('cookie', function(Y){
+
+ var data = {
+ name: "ace123",
+ age: 22,
+ track: true
+ };
+
+ //set a cookie named "user" with subcookies
+ Y.Cookie.setSubs("user", data);
+
+});</pre>
+
+
+<p>Note that calls to <code>setSubs()</code> will always completely overwrite the cookie.</p>
+
+<p>To retrieve subcookie values, there are two methods. The first is <code>getSub()</code>, which retrieves a single subcookie value.
+This method accepts three arguments: the cookie name, the subcookie name, and an optional converter function. As with <code>get()</code>,
+the converter function changes the data or type of data retrieved from the cookie before it's returned (and isn't called at all
+if the cookie or subcookie doesn't exist):</p>
+
+<pre class="code prettyprint">// Create a YUI instance and use the cookie module.
+YUI().use('cookie', function(Y){
+
+ //get subcookie
+ var stringValue = Y.Cookie.getSub("name", "subname");
+
+ //get subcookie and convert to number
+ var numberValue = Y.Cookie.getSub("user", "age", Number);
+
+ //get subcookie and convert from hex code to decimal number
+ var integerValue = Y.Cookie.getSub("settings", "bgcolor", function(stringValue){
+ return parseInt(stringValue, 16); // Create a number from a hexadecimal code
+ });
+
+});</pre>
+
+
+<p>The second method to retrieve subcookies is <code>getSubs()</code>, which retrieves all subcookies and returns an object
+with name-value pairs for each subcookie. The <code>getSubs()</code> method takes a single argument, the name of the cookie
+containing subcookies to retrieve. The returned value is either an object or <code>null</code> if the cookie doesn't exist.</p>
+
+<pre class="code prettyprint">// Create a YUI instance and use the cookie module.
+YUI().use('cookie', function(Y){
+
+ //get all subcookies
+ var data = Y.Cookie.getSubs("name");
+ var subValue = data.subname;
+
+ //get all subcookies
+ var user = Y.Cookie.getSubs("user");
+ var userName = user.name;
+
+});</pre>
+
+
+<p>Removing subcookies is accomplished using the <code>removeSub()</code> method. This method accepts three arguments: the cookie name, the subcookie name, and an optional cookie options object. The options object, if specified, must have the same options
+as when the cookie was originally created. Example:</p>
+
+<pre class="code prettyprint">// Create a YUI instance and use the cookie module.
+YUI().use('cookie', function(Y){
+
+ //set subcookie on the "yahoo.com" domain
+ Y.Cookie.setSub("info", "age", 22, { domain: "yahoo.com" });
+
+ //remove the subcookie
+ Y.Cookie.removeSub("info", "age", { domain: "yahoo.com" });
+});</pre>
+
+
+<p>Removing a subcookie keeps all other subcookies for that cookie intact. If you want to remove all subcookies, it's easiest to use <code>remove()</code> to remove the entire cookie.</p>
+
+<p>When the last subcookie is removed, the overall cookie still remains. If you'd like to remove the cookie when the last subcookie is removed, then specify the "removeIfEmpty" option:</p>
+
+<pre class="code prettyprint">// Create a YUI instance and use the cookie module.
+YUI().use('cookie', function(Y){
+
+ //remove the subcookie
+ Y.Cookie.removeSub("info", "age", { removeIfEmpty: true });
+});</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 Cookie Utility</a>
+<ul class="toc">
+<li>
+<a href="#create">Creating Cookies</a>
+</li>
+<li>
+<a href="#read">Reading Cookies</a>
+</li>
+<li>
+<a href="#delete">Deleting Cookies</a>
+</li>
+<li>
+<a href="#sub">Subcookies</a>
+</li>
+</ul>
+</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="Demonstrates basic usage of the Cookie utility for reading and writing cookies.">
+ <a href="cookie-simple-example.html">Simple Cookie Example</a>
+ </li>
+
+
+
+ <li data-description="Demonstrates using the Cookie utility to get, set and remove cookies.">
+ <a href="cookie-advanced-example.html">Advanced Cookie Example</a>
+ </li>
+
+
+
+ <li data-description="Demonstrates using the Cookie utility to get and set subcookies.">
+ <a href="cookie-subcookie-example.html">Subcookie Example</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/cookie',
+ name: 'cookie',
+ title: 'Cookie Utility',
+ newWindow: '',
+ auto: false
+};
+YUI.Env.Tests.examples.push('cookie-simple-example');
+YUI.Env.Tests.examples.push('cookie-advanced-example');
+YUI.Env.Tests.examples.push('cookie-subcookie-example');
+
+</script>
+<script src="../assets/yui/test-runner.js"></script>
+
+
+
+</body>
+</html>