Add DataTable examples.

src/datatable/docs/component.json

@@ -11,7 +11,7 @@
     "examples": [
 
         {
-            "name": "datatable_basic",
+            "name": "datatable-basic",
             "displayName": "Basic DataTable",
             "modules": ["datatable"],
             "description": "This example illustrates simple DataTable use cases.",
@@ -21,7 +21,7 @@
         },
 
         {
-            "name": "datatable_dsget",
+            "name": "datatable-dsget",
             "displayName": "DataTable + DataSource.Get + JSON Data",
             "modules": ["datatable"],
             "description": "DataTable loaded with JSON data from a remote webservice via DataSource.Get",
@@ -31,7 +31,7 @@
         },
 
         {
-            "name": "datatable_dsio",
+            "name": "datatable-dsio",
             "displayName": "DataTable + DataSource.IO + XML Data",
             "modules": ["datatable"],
             "description": "DataTable loaded with XML data from a remote webservice via DataSource.IO.",
@@ -41,7 +41,7 @@
         },
 
         {
-            "name": "datatable_formatting",
+            "name": "datatable-formatting",
             "displayName": "Formatting Row Data for Display",
             "modules": ["datatable"],
             "description": "Custom format data for display.",
@@ -51,7 +51,7 @@
         },
 
         {
-            "name": "datatable_nestedcols",
+            "name": "datatable-nestedcols",
             "displayName": "Nested Column Headers",
             "modules": ["datatable"],
             "description": "DataTable with nested column headers.",
@@ -61,7 +61,7 @@
         },
 
         {
-            "name": "datatable_sort",
+            "name": "datatable-sort",
             "displayName": "Column Sorting",
             "modules": ["datatable"],
             "description": "DataTable with column sorting.",
@@ -71,7 +71,7 @@
         },
 
         {
-            "name": "datatable_scroll",
+            "name": "datatable-scroll",
             "displayName": "Scrolling DataTable",
             "modules": ["datatable"],
             "description": "DataTable with vertical and/or horizontal scrolling rows.",

src/datatable/docs/datatable-basic.mustache

@@ -0,0 +1,66 @@
+<style scoped>
+/* custom styles for this example */
+.dt-example {margin:1em;}
+
+/* css to counter global site css */
+.dt-example th {text-transform:none;}
+.dt-example table {width:auto;}
+.dt-example caption {display:table-caption;}
+</style>
+
+<div class="intro">
+    <p>The DataTable widget displays data in a tabular format. Use plugins and extensions to add features and functionality to the `Y.DataTable.Base` class.</p>
+</div>
+
+<div class="example">
+    {{>datatable-basic-source}}
+</div>
+
+<h2>Simple DataTable Use Cases</h2>
+
+```
+<div id="example" class="yui3-skin-sam"></div>
+```
+
+
+<p>A basic table can be rendered into a given container by passing in a simple array of columns and an array of data objects into the constructor. As long as the columns map directly to the keys of the data objects, the table will be generated automatically from the data provided.</p>
+
+```
+YUI().use("datatable-base", function(Y) {
+    var cols = ["id","name","price"],
+    data = [
+        {id:"ga-3475", name:"gadget", price:"$6.99"},
+        {id:"sp-9980", name:"sprocket", price:"$3.75"},
+        {id:"wi-0650", name:"widget", price:"$4.25"}
+    ],
+    dt = new Y.DataTable.Base({
+        columnset: cols,
+        recordset: data,
+        summary: "Price sheet for inventory parts",
+        caption: "Example table with simple columns"
+    }).render("#example");
+});
+```
+
+<p>Your column definitions may be an array of object literals in order to support any number of configurations that are supported by the `Y.Column` class. For instance, you may wish to define a `label` that will be displayed in each column header. Use the `key` property to define where data for the column will be coming from.</p>
+
+```
+YUI().use("datatable-base", function(Y) {
+    var cols = [
+        { key: "mfr_parts_database_id", label: "Mfr Part ID", abbr: "ID"},
+        { key: "mfr_parts_database_name", label: "Mfr Part Name", abbr: "Name"},
+        { key: "mfr_parts_database_price", label: "Wholesale Price", abbr: "Price"}
+    ],
+    data = [
+        { mfr_parts_database_id: "ga_3475", mfr_parts_database_name: "gadget", mfr_parts_database_price: "$6.99"},
+        { mfr_parts_database_id: "sp_9980", mfr_parts_database_name: "sprocket", mfr_parts_database_price: "$3.75"},
+        { mfr_parts_database_id: "wi_0650", mfr_parts_database_name: "widget", mfr_parts_database_price: "$4.25"}
+    ],
+    dt = new Y.DataTable.Base({
+        columnset: cols,
+        recordset: data,
+        summary: "Price sheet for inventory parts",
+        caption: "These columns have labels and abbrs"
+    }).render("#example");
+});
+```

src/datatable/docs/datatable-dsget.mustache

@@ -0,0 +1,92 @@
+<style scoped>
+/* custom styles for this example */
+.dt-example {margin:1em;}
+
+/* css to counter global site css */
+.dt-example th {text-transform:none;}
+.dt-example table {width:auto;}
+.dt-example caption {display:table-caption;}
+</style>
+
+<div class="intro">
+    <p>This example shows how to populate a DataTable with data from the Yahoo! Local webservice retrieved via a YQL query. First we create a DataSource.Get instance pointing to YQL, then using the DataTableDataSource plugin we can load data for pizza places near our office.</p>
+
+    <p>In this example, we render the DataTable first, then load data into it in a separate call.</p>
+</div>
+
+<div class="example">
+    {{>datatable-dsget-source}}
+</div>
+
+<h2>Populating Your DataTable with Remote Data Using DataSource.Get</h2>
+
+<p>Your table can be easily popluated with remote JSON data from a webservice by creating a DataSource instance and using the DataTableDataSource plugin to load the data into a DataTable.</p>
+
+<p>Start with the `use()` statement:</p>
+
+```
+YUI().use("datasource-get", "datasource-jsonschema", "datatable-datasource", function(Y) {
+});
+```
+
+<p>Next create a DataSource.Get instance pointing to YQL. The <a href="http://developer.yahoo.com/yql/console/">YQL Console</a> makes it easy to determine the REST URL we want to send. You also need to define the correct schema for the DataSourceJSONSchema plugin. This is a good time to call `sendRequest` to make sure the data returns as expected.</p>
+
+```
+var dataSource = new Y.DataSource.Get({
+    source: "http://query.yahooapis.com/v1/public/yql?"+
+        "q=select%20*%20from%20local.search%20where%20zip%3D%2794089%27%20"+
+        "and%20query%3D%27pizza%27&format=json&"+
+        "env=store%3A%2F%2Fdatatables.org%2Falltableswithkeys"
+});
+
+dataSource.plug(Y.Plugin.DataSourceJSONSchema, {
+    schema: {
+        resultListLocator: "query.results.Result",
+        resultFields: ["Title", "Phone", "Rating.AverageRating"]
+    }
+});
+
+dataSource.sendRequest({
+    callback: {
+        success: function(e) {
+            Y.log(e);
+        }
+    }
+});
+```
+
+<p>Now that the DataSource is created properly, define the columns that you want your table to show. These columns map directly to the parameter names returned in the data.</p>
+
+```
+var cols = [
+    "Title",
+    "Phone",
+    { key: "Rating.AverageRating", label: "Rating" }
+];
+```
+
+<p>Now you are ready to create a DataTable using the columns you have defined. When you plug the instance with the DataTableDataSource plugin, point to your DataSource instance. After you render the table, load the data via the plugin.</p>
+
+```
+YUI().use("datasource-get", "datasource-jsonschema", "datatable-datasource", function(Y) {
+var table = new Y.DataTable.Base({
+    columnset: cols,
+    summary:"Pizza places near 98089",
+    caption:"Table with JSON data from YQL"
+});
+
+table.plug(Y.Plugin.DataTableDataSource, {
+    datasource: dataSource
+}).render("#pizza");
+
+table.datasource.load();
+```
+
+<p>One final change you can make is to split the URL between the DataSource `source` value and the `request` value sent to the DataTableDataSource plugin. Splitting the URL this way facilitates making future requests to the same DataSource.  You can see this in the <a href="#fullcode">Full Code Listing</a> below.</p>
+
+<h2 id="fullcode">Full Code Listing</h2>
+
+```
+    {{>datatable-dsget-source}}
+```
+

src/datatable/docs/datatable-formatting.mustache

@@ -0,0 +1,82 @@
+<style scoped>
+/* custom styles for this example */
+.dt-example {margin:1em;}
+
+/* css to counter global site css */
+.dt-example th {text-transform:none;}
+.dt-example table {width:auto;}
+.dt-example caption {display:table-caption;}
+</style>
+
+<div class="intro">
+    <p>Custom format row data for display with string templates or custom functions.</p>
+</div>
+
+<div class="example">
+    {{>datatable-formatting-source}}
+</div>
+
+<h2>Formatting Row Data for Display</h2>
+
+<p>Data can be stored in one format but be displayed in a different format. For instance, prices can be stored as numbers but be displayed as "$2.99", and birthdays can be stored as date objects but be displayed as "12/9/2009".
+
+<p>Simple formatting can be defined with a string template on the column definition.</p>
+
+```
+YUI().use("datatable-base", function(Y) {
+    var cols = ["id","name", {key:"price", formatter:"\${value}"}],
+    data = [
+        {id:"ga-3475", name:"gadget", price:6.99},
+        {id:"sp-9980", name:"sprocket", price:3.75},
+        {id:"wi-0650", name:"widget", price:4.25}
+    ],
+    table = new Y.DataTable.Base({
+        columnset: cols,
+        recordset: data,
+        caption: "Data formatting with string template"
+    }).render("#template");
+```
+
+<p>When a calculation is needed, define a custom function that generates markup for the data cell. The custom formatter function receives an object with the following properties: `{tbody, tr, td, classnames, headers, rowindex, record, column, data, value}`.</p>
+
+```
+// The custom formatter function recieves an object with the properties:
+// {tbody, tr, td, classnames, headers, rowindex, record, column, data, value}
+var calculate = function (o){
+    var record = o.record;
+    return "$"+(record.getValue("price") - record.getValue("cost"));
+},
+cols = ["id", "name", {key:"profit", formatter:calculate}],
+data = [
+    {id:"ga-3475", name:"gadget", price:6.99, cost:4.99},
+    {id:"sp-9980", name:"sprocket", price:3.75, cost:2.75},
+    {id:"wi-0650", name:"widget", price:4.25, cost:3.25}
+],
+dt = new Y.DataTable.Base({
+    columnset: cols,
+    recordset: data,
+    caption: "Data formatting with custom function"
+}).render("#function");
+```
+
+<p>The DataType utility can be used to help format date objects.</p>
+
+```
+YUI().use("datatype-date", "datatable-base", function (Y) {
+    // The custom formatter function recieves an object with the properties:
+    // {tbody, tr, td, classnames, headers, rowindex, record, column, data, value}
+    var formatDates = function (o){
+        return Y.DataType.Date.format(o.value, { format: "%m/%d/%Y" });
+    },
+    cols = ["id", "name", { key: "date", formatter: formatDates }],
+    data = [
+        {id:"ga-3475", name:"gadget", date:new Date(2006, 5, 1)},
+        {id:"sp-9980", name:"sprocket", date:new Date(2004, 8, 16)},
+        {id:"wi-0650", name:"widget", date:new Date(2005, 4, 23)}
+    ],
+    dt = new Y.DataTable.Base({
+        columnset: cols,
+        recordset: data,
+        caption: "Data formatting with DataType.Date"
+    }).render("#dates");
+```

src/datatable/docs/datatable-nestedcols.mustache

@@ -0,0 +1,26 @@
+<style scoped>
+/* custom styles for this example */
+.dt-example {margin:1em;}
+
+/* css to counter global site css */
+.dt-example th {text-transform:none;}
+.dt-example table {width:auto;}
+.dt-example caption {display:table-caption;}
+</style>
+
+<div class="intro">
+    <p>The DataTable widget supports nested column headers, which can be defined in the columnset definition using the `children` configuration.</p>
+</div>
+
+<div class="example">
+    {{>datatable-nestedcols-source}}
+</div>
+
+<h2>Using Nested Column Headers</h2>
+
+<p>Use nested columns to visually group related column headers. The `children` attribute associates a parent column to its descendants. Note that only bottom-level columns will have data values. Any parent columns are there for presentation purposes only and do not hold any data values directly &mdash; therefore parent columns may have a `label` value but a  `key` value is unnecessary.</p>
+
+```
+    {{>datatable-nestedcols-source}}
+```
+