Add Console examples.

src/console/docs/component.json

@@ -9,7 +9,7 @@
 
     "examples": [
         {
-            "name"       : "console_basic",
+            "name"       : "console-basic",
 	        "displayName": "Creating a Console for Debugging",
 	        "description": "The basics of setting up a Console",
 	        "modules": ["console","console-filters"],
@@ -19,7 +19,7 @@
         },
 
         {
-            "name": "console_yui_config",
+            "name": "console-yui-config",
 	        "displayName": "YUI Configuration to Filter Log Messages",
 	        "description": "Using your YUI instance configuration to filter which messages are reported in the Console",
 	        "modules": ["console"],
@@ -31,7 +31,7 @@
         },
 
         {
-            "name": "console_global",
+            "name": "console-global",
 	        "displayName": "Creating a Universal Console",
 	        "description": "Using the Console's logSource attribute to consolidate log messages from multiple YUI instances into one Console",
 	        "modules": ["console"],

src/console/docs/console-basic.mustache

@@ -0,0 +1,109 @@
+{{>console-basic-css}}
+
+<div class="intro">
+    <p>This example walks through the basics of setting up and logging messages to a YUI Console instance.  Three Console instances are created with slightly different configurations.  All calls to `Y.log(..)` will be broadcast to every Console.</p>
+</div>
+
+<div class="example">
+    {{>console-basic-markup}}
+    {{>console-basic-js}}
+</div>
+
+<h3>Markup not required</h3>
+<p>The primary purpose of the Console is to aid in debugging your application.  As such, it doesn't make much sense to require your page to include markup for something that is not bound for production.</p>
+
+<p><em>However</em>, Console is built on the Widget framework, so it can be rendered into a containing element just as any other Widget.  We'll do that for the first two Consoles, then for the third we'll call `render` with no input, allowing the default behavior.</p>
+
+<p>For the first two cases, we need to set up some markup.  We'll throw in some placeholder content for the third.</p>
+
+```
+<h4>Basic Console</h4>
+<div id="basic"></div>
+
+<h4>New messages added to bottom</h4>
+<div id="add_to_bottom"></div>
+
+<h4>Custom strings</h4>
+<p><em>Rendered in default location (top right corner of page)</em></p>
+```
+
+<p>Then instantiate the Console instances.</p>
+
+```
+// Create a YUI instance and request the console module and its dependencies
+YUI().use("console", "console-filters", "dd-plugin", function (Y) {
+
+// Create and render the three Console instances
+var basic, newOnBottom, customStrings;
+
+basic = new Y.Console({
+    style: 'block' // keeps the Console in the page flow as a block element
+}).render( "#basic" ); // note the inline render()
+
+newOnBottom = new Y.Console({
+    style: 'inline', // keeps the Console in the page flow as an inline element
+    newestOnTop: false,
+    visible: false   // hidden at instantiation
+}).render( "#add_to_bottom" );
+
+customStrings = new Y.Console({
+    strings: {
+        title : 'Console with custom strings!',
+        pause : 'Wait',
+        clear : 'Flush',
+        collapse : 'Shrink',
+        expand : 'Grow'
+    },
+    visible: false  // hidden at instantiation
+}).plug(Y.Plugin.ConsoleFilters)
+  .plug(Y.Plugin.Drag, { handles: ['.yui3-console-hd'] })
+  .render();
+
+});
+```
+
+<h3>Log some messages</h3>
+<p>In your code, inserting calls to `Y.log(..)` will cause the content of those log messages to be broadcast to every Console instance present in the YUI instance.  We'll illustrate this by creating some buttons to log various types of messages.</p>
+
+```
+// Create a YUI instance and request the console module and its dependencies
+YUI().use("console", "console-filters", "dd-plugin", function (Y) {
+
+// Create and render the three Console instances
+var basic, newOnBottom, customStrings;
+
+...
+
+function report(e,type) {
+    Y.log(this.get('value'),type);
+}
+
+// Set the context of the event handler to the input text node
+// for convenience and pass the message type as a second arg
+Y.on('click', report, '#info',  Y.one('#info_text'),  'info');
+Y.on('click', report, '#warn',  Y.one('#warn_text'),  'warn');
+Y.on('click', report, '#error', Y.one('#error_text'), 'error');
+
+});
+```
+
+<h3 id="full_code_listing">Full Code Listing</h3>
+
+<h4>Markup</h4>
+
+```
+{{>console-basic-markup}}
+```
+
+<h4>JavaScript</h4>
+
+```
+{{>console-basic-js}}
+```
+
+<h4>CSS</h4>
+
+```
+{{>console-basic-css}}
+```
+

src/console/docs/console-global.mustache

@@ -0,0 +1,79 @@
+{{>console-global-css}}
+
+<div class="intro">
+    <p>In this example, three YUI instances are created, each binding a button to call `Y.log(...)`.  Then an additional, separate YUI instance is created that requests only the `console` module and creates a Console that listens for log events from all three.</p>
+</div>
+
+<div class="example">
+    {{>console-global-markup}}
+    {{>console-global-js}}
+</div>
+
+<h3 class="first">Multiple YUI instances</h3>
+<p>Each YUI instance is its own sandbox.  You can create as many YUI instances on a page as you want or need (though typically one is enough).  The variables, module configurations and instances are kept inside that instance unless you expressly expose them via a global variable.</p>
+
+```
+// Create the first YUI instance
+YUI($yuiConfig).use($requiredModules, function (Y) {
+
+    Y.one( "#yui1" ).on( "click", function () {
+        Y.log( "Message from YUI instance #1" );
+    });
+
+});
+
+// Create the second YUI instance
+YUI($yuiConfig).use($requiredModules, function (Y) {
+
+    Y.one( "#yui2" ).on( "click", function () {
+        Y.log( "I'm the second YUI instance" );
+    });
+
+});
+
+// Create a third YUI instance
+YUI($yuiConfig).use($requiredModules, function (Y) {
+
+    Y.one( "#yui3" ).on( "click", function () {
+        Y.log( "And this is #3 YUI" );
+    });
+
+});
+```
+
+<h3>Listening to `Y.Global`</h3>
+<p>To address debugging such an environment, Console can be configured to listen for log messages across all YUI instances by setting the Console instance's `logSource` configuration to `Y.Global`.</p>
+
+<p>We'll insert the universal Console into another YUI instance.</p>
+
+```
+// Create a separate YUI instance to listen to all instances' logging
+YUI($yuiConfig).use("console", function (Y) {
+
+    // Configure the Console's logSource to Y.Global to make it universal
+    new Y.Console({
+        logSource: Y.Global,
+        style: 'block',
+        newestOnTop: false,
+        width: "250px"
+    }).render( "#yconsole" );
+
+});
+```
+
+<h3>Full Code Listing</h3>
+
+<h4>Markup</h4>
+```
+{{>console-global-markup}}
+```
+
+<h4>JavaScript</h4>
+```
+{{>console-global-js}}
+```
+
+<h4>CSS</h4>
+```
+{{>console-global-css}}
+```

src/console/docs/console-yui-config.mustache

@@ -0,0 +1,160 @@
+{{>console-yui-config-css}}
+
+<div class="intro">
+    <p>This example illustrates how to configure your YUI instance to ignore certain log messages to aid in reducing the signal-to-noise ratio when debugging.</p>
+
+    <p>Log messages filtered out from the YUI config are permanently ignored.  If you want to be able to temporarily hide and reshow messages, use the <a href="../console-filters/">ConsoleFilters plugin</a>.  It is not uncommon to set up `logInclude` or `logExclude` in the YUI configuration and use the ConsoleFilters plugin.</p>
+
+    <p>Log messages can be ignored based on the source (e.g. `event` or `attribute`) or based on their log level (info, warn, error).</p>
+
+</div>
+
+<div class="example">
+{{>console-yui-config-markup}}
+{{>console-yui-config-js}}
+</div>
+
+<h3>Setting up filters in the YUI configuration</h3>
+<p>The configuration object passed to the YUI constructor supports a few settings that can help manage Console output while debugging.  These configuration options are `logExclude`, `logInclude`, `logLevel`, `filter`, and `filters`.</p>
+
+<p>This example will show the use of the `logInclude`, `logExclude`, and `logLevel` configurations.</p>
+
+<p>An example configuration might look like this:</p>
+
+```
+YUI({
+    filter : 'debug', // request -debug versions of modules for log statements
+    logExclude : {
+        event : true,     // Don't broadcast log messages from the event module
+        attribute : true, // or the attribute module
+        widget : true     // or the widget module
+    },
+    logLevel : 'error',       // Show only errors in the Console
+    useBrowserConsole : false // Don't use the browser's native console
+}).use('overlay','anim','console', function (Y) {
+
+/* Console instances will default to logLevel = "info" */
+
+});
+```
+
+<p>`logExclude` and `logInclude` prevent the logging subsystem from broadcasting filtered log messages.  `logLevel`, on the other hand is used by Console instances to filter messages received from the subsystem.</p>
+
+<p>Updating `Y.config.logExclude` or `Y.config.logInclude` at runtime will immediately change the subsystem filtering, but will not recover messages previously sent from that source.</p>
+
+```
+YUI({
+    logExclude : {
+        event : true
+    }
+}).use('console', function (Y) {
+
+/* In here, Y.config refers to the config object passed to the constructor */
+
+// Stop broadcasting log messages from the attribute module
+Y.config.logExclude.attribute = true;
+
+// Start broadcasting log messages from the event module again
+delete Y.config.logExclude.event;
+
+});
+```
+
+<p>When a Console is instantiated, barring explicit `logLevel` attribute configuration, the `logLevel` will be adopted from the YUI instance's configured `logLevel`, or `Y.Console.LOG_LEVEL_INFO` (&quot;info&quot;) as a fallback.  Unlike `logExclude`, changing the value in the YUI configuration will only affect instantiated Consoles from that point on.  Additionally, you can manually override the `logLevel` a Console instance will display by updating its `logLevel` attribute.</p>
+
+```
+YUI({ logLevel : "warn" }).use('console', function (Y) {
+
+var yconsole_1 = new Y.Console(); // logLevel == "warn"
+
+var yconsole_2 = new Y.Console({
+    logLevel : "info" // override at construction
+});
+
+// This will not affect yconsole_1 or yconsole_2
+Y.config.logLevel = "error";
+
+var yconsole_3 = new Y.Console(); // logLevel == "error"
+
+yconsole_1.set("logLevel", "info"); // update this instance
+
+});
+```
+
+<p>The interactive portion of this example illustrates the effect of various filter settings against logged messages.  In a real application, it is most likely that the logging configuration won't be changed at runtime but set once in the YUI configuration at construction.</p>
+
+<p>The most relevant portion of the <a href="#full_code_listing">code for the demo above</a> is the updating of the YUI config and Console attribute.</p>
+
+```
+// Create and render the Console
+var yconsole = new Y.Console({
+    boundingBox: '#console', // anchored to the page for the demo
+    style: "block"
+}).render();
+
+...
+
+// Source include or exclude select
+Y.on("change", function () {
+    if (this.get("value") === "logInclude") {
+        Y.config.logInclude = Y.config.logExclude;
+        delete Y.config.logExclude;
+    } else {
+        Y.config.logExclude = Y.config.logInclude;
+        delete Y.config.logInclude;
+    }
+    updatePreview();
+}, "#incexc");
+
+// These functions are called from a delegated event handler.
+// See the Full Code Listing for how they are called.
+function updateSourceFilters(source, checked) {
+    var disposition = Y.one("#incexc").get("value"),
+        cfg = Y.config[disposition]; // Y.config.logInclude or logExclude
+
+    if (checked) {
+        if (!cfg) {
+            cfg = Y.config[disposition] = {};
+        }
+        cfg[source] = true; // e.g. Y.config.logInclude.sourceA = true;
+    } else {
+        delete cfg[source];
+
+        if (!Y.Object.size(cfg)) {
+            delete Y.config[disposition];
+        }
+    }
+
+    updatePreview();
+}
+
+function updateLogLevel(level, checked) {
+    if (checked) {
+        Y.config.logLevel = level;
+        yconsole.set("logLevel", level);
+        updatePreview();
+    }
+}
+```
+
+<h3 id="full_code_listing">Full Code Listing</h3>
+
+<h4>Markup</h4>
+
+```
+{{>console-yui-config-markup}}
+```
+
+<h4>JavaScript</h4>
+
+```
+{{>console-yui-config-js}}
+```
+
+<h4>CSS</h4>
+
+```
+{{>console-yui-config-css}}
+```
+
+

src/console/docs/partials/console-basic-css.mustache

@@ -0,0 +1,18 @@
+<style scoped>
+#basic, #add_to_bottom {
+    margin-bottom: 1em;
+}
+
+#demo .yui3-console .yui3-console-title {
+    border: 0 none;
+    color: #000;
+    font-size: 13px;
+    font-weight: bold;
+    margin: 0;
+    text-transform: none;
+}
+#demo .yui3-console .yui3-console-entry-meta {
+    margin: 0;
+}
+</style>
+