--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/cm/media/js/lib/yui/yui_3.10.3/docs/datatable/migration.html Tue Jul 16 14:29:46 2013 +0200
@@ -0,0 +1,1185 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="utf-8">
+ <title>3.5.0+ Migration Guide</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>3.5.0+ Migration Guide</h1>
+ <div class="yui3-g">
+ <div class="yui3-u-3-4">
+ <div id="main">
+ <div class="content"><style>
+#docs-main li {
+ margin: 1ex 0;
+}
+
+li code,
+td code {
+ white-space: nowrap;
+ background: #fcfbfa;
+ border: 1px solid #d0d5ec;
+ padding: 0 3px;
+}
+li code {
+ border-color: #efeeed;
+}
+.yui3-skin-sam table {
+ width: auto;
+}
+.yui3-skin-sam td,
+.yui3-skin-sam th {
+ border: 0 none;
+}
+
+.demo { width: 40%; }
+.details { width: 60%; }
+.before, .after { width: 47%; }
+.after {
+ margin-left: 5%;
+}
+
+#quickref code em {
+ color: #900;
+}
+#quickref code strong {
+ color: #090;
+}
+#quickref pre.code {
+ margin-top: 0;
+ margin-bottom: 0;
+}
+
+.spendy {
+ color: #b00;
+}
+</style>
+<div class="intro">
+ <p>
+ DataTable and supporting modules were rebuilt in version 3.5.0. The
+ new architecture is <strong>not fully backward compatible</strong> with
+ versions 3.4.1 and prior. This guide is to help answer questions that
+ may come up when upgrading to the latest version.
+ </p>
+
+ <p>
+ This guide focuses on 3.4.1 API compatibility. It <strong>does not
+ describe new features added in 3.5.0</strong> (there were a lot).
+ Refer to the updated <a href="index.html">DataTable user guide</a> for
+ that.
+ </p>
+
+ <p>
+ If you are unable to upgrade due to unresolvable issues, you can use the
+ <a href="../datatable-deprecated/index.html"><code>datatable-deprecated</code></a>
+ module suite, which is equivalent to the 3.4.1 implementation. But be
+ aware that these modules will be removed in a future version of YUI.
+ </p>
+</div>
+
+<h2 id="overview">Overview of API changes from 3.4.1</h2>
+
+<p>
+ The architectural change resulted in the deprecation, replacement, or
+ removal of nearly all attributes and properties from the version 3.4.1
+ implementation. Here is a quick list of the changes most likely to affect
+ your upgrade:
+</p>
+
+<ol id="quickref">
+ <li>
+ <code>new <em>Y.DataTable.Base</em>(...)</code> →
+ <code>new <strong>Y.DataTable</strong>({ ... })</code>
+ </li>
+ <li>
+ <div class="yui3-g">
+ <div class="yui3-u">
+<pre class="code prettyprint">new Y.DataTable.Base({
+ columnset: [ ... ],
+ recordset: [ ... ]
+});</pre>
+
+ </div>
+ <p class="yui3-u" style="line-height: 72px; margin: 0 1em;">→</p>
+ <div class="yui3-u">
+<pre class="code prettyprint">new Y.DataTable({
+ columns: [ ... ],
+ data : [ ... ]
+});</pre>
+
+ </div>
+ </div>
+ </li>
+ <li>
+ (cells rendered as HTML by default) →
+ <code>columns: [ { key: 'email', <strong>allowHTML: true</strong> }, ... ]</code>
+ </li>
+ <li>
+ <code>table.plug(<em>Y.Plugin.DataTableSort</em>)</code> → <em>(plugin not needed)</em>
+ <a href="#features">See below</a> or read
+ <a href="index.html#sorting">the user guide</a>
+ </li>
+ <li>
+ <code>table.plug(<em>Y.Plugin.DataTableScroll</em>, ...)</code> →
+ <em>(plugin not needed)</em>
+ <a href="#features">See below</a> or read
+ <a href="index.html#scrolling">the user guide</a>
+ </li>
+ <li>
+ <code>columnset: [ { <em>formatter: function (o) { ... }</em> } ]</code>
+ →
+ (formatter changes)
+ <a href="#formatters">See below</a> or read
+ <a href="index.html#scrolling">the user guide</a>
+ </li>
+ <li>
+ <code>record.<em>getValue(fieldName)</em></code> →
+ <code>record.<strong>get(fieldName)</strong></code>
+ </li>
+</ol>
+
+<h2 id="instantiation">Instantiation and Instance Configuration Changes</h2>
+
+<p>
+ As of 3.5.0, <code>Y.DataTable</code> is no longer just a namespace, but is now the
+ preferred constructor for DataTable instances.
+</p>
+
+<pre class="code prettyprint">var table = new Y.DataTable({
+ // Column configuration looks much the same except the attribute name
+ columns: [
+ { key: 'name', label: 'Name', sortable: true, width: '200px' },
+ {
+ key: 'birthdate',
+ label: 'Age',
+ sortable: true,
+ formatter: function (o) {
+ var now = new Date(),
+ years = now.getYear() - o.value.getYear();
+
+ now.setYear(o.value.getYear());
+
+ return years - (o.value < now);
+ }
+ }
+ ],
+ // Passing in row data looks much the same except the attribute name
+ data: [
+ { name: 'Tom Brokaw', birthdate: new Date(1940, 1, 6) },
+ { name: 'Peter Jennings', birthdate: new Date(1938, 6, 29) },
+ { name: 'Katie Couric', birthdate: new Date(1957, 1, 7) },
+ { name: 'Brian Williams', birthdate: new Date(1958, 4, 5) },
+ { name: 'Matt Lauer', birthdate: new Date(1957, 11, 30) }
+ ]
+}).render('#over-there');</pre>
+
+
+<p>
+ The <code>Y.DataTable.Base</code> class still exists, but is useful primarily as a
+ superclass for extension. The attributes of <code>Y.DataTable.Base</code> are the
+ same as those of <code>Y.DataTable</code>, less any attributes added by class
+ extensions (<a href="#features">see below</a>).
+</p>
+
+<p>
+ Configuration attributes that have changed from 3.4.1 are:
+</p>
+
+<table>
+<thead>
+ <tr>
+ <th>Attribute</th>
+ <th>Change</th>
+ </tr>
+</thead>
+<tbody>
+ <tr>
+ <td><code>columnset</code></td>
+ <td>
+ <strong>Deprecated</strong>. Use <code>columns</code>. <code>columnset</code> will
+ behave as an alias for <code>columns</code> for a short time, but will be
+ removed in future versions. <a href="#columns">See below</a>.
+ </td>
+ </tr>
+ <tr>
+ <td><code>recordset</code></td>
+ <td>
+ <strong>Deprecated</strong>. Use <code>data</code>. <code>recordset</code> will
+ behave as an alias for <code>data</code> for a short time, but will be
+ removed in future versions. <a href="#data">See below</a>.
+ </td>
+ </tr>
+ <tr>
+ <td><code>tdValueTemplate</code></td>
+ <td>
+ <strong>Removed</strong>. Use column <code>formatter</code>, <code>cellTemplate</code>,
+ or override the <code>Y.DataTable.BodyView</code> instance's <code>CELL_TEMPLATE</code>.
+ </td>
+ </tr>
+ <tr>
+ <td><code>thValueTemplate</code></td>
+ <td>
+ <strong>Removed</strong>. Use column <code>label</code>, <code>headerTemplate</code>,
+ or override the <code>Y.DataTable.HeaderView</code> instance's <code>CELL_TEMPLATE</code>.
+ </td>
+ </tr>
+ <tr>
+ <td><code>trTemplate</code></td>
+ <td>
+ <strong>Removed</strong>. Use column <code>nodeFormatter</code> or override
+ the <code>Y.DataTable.BodyView</code> instance's <code>ROW_TEMPLATE</code>.
+ </td>
+ </tr>
+</tbody>
+</table>
+
+<h2 id="formatters">Table and Cell Formatting Changes</h2>
+
+<p>
+ The following changes apply to table and column cell formatting:
+</p>
+
+<ul>
+ <li>
+ If cell values include HTML, add <code>allowHTML: true</code> to the column
+ configuration. HTML is escaped by default for security.
+ </li>
+ <li>
+ <code>o.classnames</code> in the formatter parameter is now <code>o.className</code>.
+ </li>
+ <li>
+ <code>o.column</code> in the formatter parameter is now <a href="#columns">the
+ plain JavaScript object</a> containing the column configurations rather
+ than a <code>Y.Column</code> instance.
+ </li>
+ <li>
+ <code>o.record</code> in the formatter parameter is now <a href="#data">a Model
+ instance</a> instead of a <code>Y.Record</code> instance.
+ </li>
+ <li>
+ <code>this.createCell(o)</code>, <code>o.td</code>, <code>o.tr</code>, and <code>o.tbody</code> no longer exist on
+ the parameter passed to <code>formatter</code> functions. Use
+ <a href="index.html#nodeformatter"><code>nodeFormatter</code></a>s.
+ </li>
+ <li>
+ <code>o.headers</code> is now at <code>o.column._headers</code>, but is read-only for
+ <code>formatter</code> functions. If you need to change the cell's headers
+ attribute, add a {placeholder} for them to a custom <code>cellTemplate</code> for
+ the column, or use a <code>nodeFormatter</code>.
+ </li>
+ <li>
+ The table's <code>tdValueTemplate</code>, <code>thValueTemplate</code>, and <code>trTemplate</code> no
+ longer exist, nor do the DataTable instance properties <code>tdTemplate</code> and
+ <code>thTemplate</code>. Use <code>formatter</code> strings or functions to customize the
+ content of data cells in a column and <code>label</code> strings to customize the
+ content of header cells. To modify the <code><td></code> or <code><th></code> entirely, set
+ the column configuration <code>cellTemplate</code> or <code>headerTemplate</code>.
+ </li>
+</ul>
+
+<div class="yui3-g">
+ <div class="yui3-u before">
+ <h4 class="no-toc">3.4.1</h4>
+
+<pre class="code prettyprint">var table = new Y.DataTable.Base({
+ columnset: [
+ { key: "id",
+ emptyCellValue: "<em>new</em>" },
+ { key: "name" },
+ { key: "price", formatter: "${value}" },
+ { key: "price",
+ formatter: function (o) {
+ if (o.value > 4) {
+ o.classnames += "spendy";
+ }
+ return '$' + o.value.toFixed(2);
+ }
+ },
+ { key: "price",
+ formatter: function (o) {
+ var cell = this.createCell(o);
+
+ if (o.value > 4) {
+ cell.addClass('spendy');
+ }
+
+ cell.setHTML('$' + o.value);
+ }
+ }
+ ],
+ data: [
+ { id: 1, name: "Bread", price: 3.45 },
+ { id: 2, name: "Milk", price: 4.99 },
+ { id: 3, name: "Eggs", price: 2.75 }
+ ]
+}).render("#over-there");</pre>
+
+ </div>
+ <div class="yui3-u after">
+ <h4 class="no-toc">3.5.0</h4>
+
+<pre class="code prettyprint">var table = new Y.DataTable({
+ columns: [
+ { key: "id",
+ emptyCellValue: "<em>new</em>",
+ allowHTML: true },
+ { key: "name" },
+ { key: "price", formatter: "${value}" },
+ { key: "price",
+ formatter: function (o) {
+ if (o.value > 4) {
+ o.className += "spendy";
+ }
+ return '$' + o.value.toFixed(2);
+ }
+ },
+ { key: "price",
+ nodeFormatter: function (o) {
+ if (o.value > 4) {
+ o.cell.addClass('spendy');
+ }
+
+ o.cell.setHTML('$' + o.value);
+
+ return false;
+ }
+ }
+ ],
+ data: [
+ { id: 1, name: "Bread", price: 3.45 },
+ { id: 2, name: "Milk", price: 4.99 },
+ { id: 3, name: "Eggs", price: 2.75 }
+ ]
+}).render("#over-there");</pre>
+
+ </div>
+</div>
+
+<p>
+ Read the <a href="index.html#formatters">Formatting Cell Data</a> section in
+ the DataTable user guide for more details.
+</p>
+
+<h2 id="columns">Column Configuration Changes</h2>
+
+<p>
+ As of 3.5.0, the <code>Y.Columnset</code> and <code>Y.Column</code> classes have been deprecated.
+ The DataTable configuration attribute <code>columnset</code> has been deprecated in
+ favor of the <code>columns</code> attribute. The <code>columnset</code> attribute has been
+ retained for <em>partial</em> backward compatibility. Columns are now
+ stored as an array of simple JavaScript objects rather than class instances.
+</p>
+
+<pre class="code prettyprint">var table = new Y.DataTable({
+ columnset: [ 'name', 'age' ],
+ ...
+});
+
+// columnset passes through to columns
+var columns = table.get('columns'); // => Array, not Columnset instance
+
+table.set('columnset', [ ... (new column configurations) ... ]);
+
+// backward compatibility stops here
+var columnset = table.get('columnset'); // => Array, not Columnset instance</pre>
+
+
+<p>
+ Strings passed into the column configuration will become objects with those
+ strings as the value of the <code>key</code> property.
+</p>
+
+<p>
+ See the <a href="index.html#columns">Column configuration</a> section in
+ the user guide for more details.
+</p>
+
+<h2 id="data">Row Data Configuration Changes</h2>
+
+<p>
+ As of 3.5.0, DataTable uses <code>Y.Model</code> and <code>Y.ModelList</code> to store row data.
+ <code>Y.Recordset</code> and <code>Y.Record</code> haven't been deprecated, but may be in the
+ future. The <code>recordset</code> attribute has been retained for <em>partial</em>
+ backward compatibility. The <code>data</code> ModelList can be assigned to, but
+ retrieving the value of the attribute will return the ModelList, <em>not
+ a <code>Y.Recordset</code> instance</em>.
+</p>
+
+<pre class="code prettyprint">var table = new Y.DataTable({
+ columnset: [ ... ],
+ recordset: [
+ { name: 'Tom Brokaw', birthdate: new Date(1940, 1, 6) },
+ { name: 'Peter Jennings', birthdate: new Date(1938, 6, 29) },
+ { name: 'Katie Couric', birthdate: new Date(1957, 1, 7) },
+ ...
+ ]
+});
+
+// recordset passes through to data.
+var data = table.get('data'); // => ModelList instance
+
+table.set('recordset', [ ... (new data records) ... ]);
+
+// backward compatibility stops here
+var recordset = table.get('recordset'); // => ModelList, not Recordset</pre>
+
+
+<p>
+ <code>Y.Record</code> stores all values in a single attribute named <code>data</code>, where <code>Y.Model</code> uses individual attributes for each value.
+</p>
+
+<div class="yui3-g">
+ <div class="yui3-u before">
+ <h4 class="no-toc">3.4.1</h4>
+
+<pre class="code prettyprint">// Y.Record
+var record = oldTable.get('recordset').item(0);
+
+record.getValue('birthdate'); // => Date(1940, 1, 6)
+record.get('data').birthdate; // => same</pre>
+
+ </div>
+ <div class="yui3-u after">
+ <h4 class="no-toc">3.5.0</h4>
+<pre class="code prettyprint">// Y.Model
+var model = newTable.getRecord(0);
+
+model.get('birthdate'); // => Date(1940, 1, 6)</pre>
+
+ </div>
+</div>
+
+<p>
+ <strong>This change breaks column/record keys that contain periods</strong>.
+ Attribute treats periods as subproperty indicators, so periods are no
+ longer allowed; use an alternate character. In the case of remote data
+ that is parsed by <code>Y.Plugin.DataSourceJSONSchema</code>, use the <code>locator</code>
+ configuration for fields to extract subproperty values. A benefit to doing
+ this is that you may not need to specify a column <code>label</code>.
+</p>
+
+<div class="yui3-g">
+ <div class="yui3-u before">
+ <h4 class="no-toc">3.4.1</h4>
+
+<pre class="code prettyprint">var table = new Y.DataTable.Base({
+ columnset: [
+ { key: "id" },
+ { key: "Product.Name", label: "Product" },
+ { key: "Product.Price", label: "Price" }
+ ],
+ caption: "Price List"
+}).plug(Y.Plugin.DataTableDataSource, {
+ datasource: new Y.DataSource.IO({
+ source: "/service/price-list"
+ }).plug(Y.Plugin.DataSourceJSONSchema, {
+ schema: {
+ resultListLocator: "items",
+ resultFields: [
+ { key: "id" },
+ { key: "Product.Name" },
+ { key: "Product.Price" }
+ ]
+ }
+ })
+});
+
+table.datasource.load(...);</pre>
+
+ </div>
+ <div class="yui3-u after">
+ <h4 class="no-toc">3.5.0</h4>
+
+<pre class="code prettyprint">var table = new Y.DataTable({
+ columns: [ "id", "Product", "Price" ],
+ caption: "Price List"
+}).plug(Y.Plugin.DataTableDataSource, {
+ datasource: new Y.DataSource.IO({
+ source: "/service/price-list"
+ }).plug(Y.Plugin.DataSourceJSONSchema, {
+ schema: {
+ resultListLocator: "items",
+ resultFields: [
+ { key: "id" },
+ { key: "Product",
+ locator: "Product.Name" },
+ { key: "Price",
+ locator: "Product.Price" }
+ ]
+ }
+ })
+});
+
+table.datasource.load(...);</pre>
+
+ </div>
+</div>
+
+<p>
+ If you are using any Recordset plugins, your code will need to be modified.
+ Some loss of functionality may result.
+</p>
+
+<dl>
+ <dt><code>Y.Plugin.RecordsetSort</code></dt>
+ <dd>
+ This plugin was formerly applied by the <code>Y.Plugin.DataTableSort</code> plugin
+ to the DataTable's Recordset instance. Sorting is now enabled
+ <a href="#features">through a class extension</a>.
+ </dd>
+
+ <dt><code>Y.Plugin.RecordsetFilter</code></dt>
+ <dd>
+ The default ModelList implementation only supports a <code>filter(function)</code>
+ method. If you were relying on this plugin's <code>grep</code> or <code>reject</code>
+ methods or the <code>filter(key, value)</code> functionality, you will need to
+ replace that functionality through custom code.
+ </dd>
+
+ <dt><code>Y.Plugin.RecordsetIndexer</code></dt>
+ <dd>
+ The default ModelList implementation does not support multiple custom
+ indexes, though it does maintain an index for <code>id</code> (or another,
+ assigned primary key attribute) and <code>clientId</code>. See
+ <a href="../model/index.html">the Model user guide</a> for more
+ information on customizing the primary index. If multiple custom
+ indexes are required, DataTable supports the use of
+ <a href="#recordtype">custom Model subclasses</a> to store the record
+ data.
+ </dd>
+</ul>
+
+<p>
+ See the <a href="#data">Data Configuration section</a> of the DataTable
+ user guide for more information.
+</p>
+
+<h2 id="features">Feature Configuration Changes</h2>
+
+<p>
+ The two optional features available for DataTable in 3.4.1 were sorting and
+ scrolling. Both features exist in 3.5.0, but are implemented as class
+ extensions for <code>Y.DataTable</code>. Simply including the <code>datatable-sort</code> or
+ <code>datatable-scroll</code> module in your <code>use(...)</code> will enable the feature for
+ all new DataTables.
+</p>
+
+<pre class="code prettyprint">YUI().use('datatable-sort', 'datatable-scroll', function (Y) {
+
+ // Create a DataTable that is sortable by the "name" column, and is
+ // configured to scroll vertically within 300px. Because scrollable is
+ // set to "y", not "x" or "xy", it will not attempt to scroll horizontally.
+ // Instead the table width will be set to 100%.
+ var table = new Y.DataTable({
+ columns : [ { key: 'name', sortable: true }, ... ],
+ data : [ ... ],
+ scrollable: "y",
+ height : "300px",
+ width : "100%"
+ });
+
+ // No plugins necessary
+ table.render('#over-there');
+});</pre>
+
+
+<h3 id="sorting">Column Sorting Changes</h3>
+
+<p>
+ Configuring sortable columns may be done as it was in 3.4.1, by setting the
+ column configuration property <code>sortable: true</code>, but may also be done by
+ setting the DataTable's <code>sortable</code> configuration to <code>true</code> or an array of
+ column names.
+</p>
+
+<div class="yui3-g">
+ <div class="yui3-u before">
+ <h4 class="no-toc">3.4.1</h4>
+
+<pre class="code prettyprint">// Assumes use('datatable-sort') or use('datatable')
+var table = new Y.DataTable.Base({
+ columnset: [
+ { key: "id" },
+ { key: "name", sortable: true },
+ { key: "price", sortable: true }
+ ],
+ recordset: [
+ { id: 1, name: "Bread", price: 3.45 },
+ { id: 2, name: "Milk", price: 4.99 },
+ { id: 3, name: "Eggs", price: 2.75 },
+ ...
+ ],
+ caption: "Price List"
+});
+
+table.plug(Y.Plugin.DataTableSort);
+
+table.render('#sort-demo');
+
+// Sorting API is on the Recordset's plugin
+table.get("recordset").sort.sort("name");</pre>
+
+ </div>
+ <div class="yui3-u after">
+ <h4 class="no-toc">3.5.0</h4>
+
+<pre class="code prettyprint">// Assumes use('datatable-sort') or use('datatable')
+var table = new Y.DataTable({
+ columns: [ "id", "name", "price" ],
+ data: [
+ { id: 1, name: "Bread", price: 3.45 },
+ { id: 2, name: "Milk", price: 4.99 },
+ { id: 3, name: "Eggs", price: 2.75 },
+ ...
+ ],
+ sortable: [ "name", "price" ]
+});
+
+table.render('#sort-demo');
+
+// Sort method is on the instance
+table.sort("name");
+
+//-------------------------------------------------
+// Alternate methods
+//-------------------------------------------------
+
+var table = new Y.DataTable({
+ columns: [ "id", "name", "price" ],
+ data: [ ... ],
+ sortable: true // makes all columns sortable
+});
+
+// OR the old way works, too
+var table = new Y.DataTable({
+ columns: [
+ { key: "id" },
+ { key: "name", sortable: true },
+ { key: "price", sortable: true }
+ ],
+ data: [ ... ]
+});</pre>
+
+ </div>
+</div>
+
+<p>
+ Since there is no plugin, the <code>sort</code> method is now on the DataTable instance
+ itself, as are the related attributes. In particular, the <code>lastSortedBy</code>
+ attribute from the plugin implementation has been replaced by the <code>sortBy</code>
+ attribute added by the class extension.
+</p>
+
+<p>
+ As of 3.5.0, DataTables configured with <code>sortBy</code> will have their rows
+ sorted automatically upon inserting into the table. You do not need to
+ presort data for the initial render.
+</p>
+
+<p>
+ <strong>The <code>trigger</code> attribute of the sorting plugin was not retained in
+ the 3.5.0 class extension</strong>. If you require an alternate triggering
+ event, detach and replace the table's <code>_sortHandle</code> property after
+ <code>render()</code>.
+</p>
+
+<pre class="code prettyprint">var table = new Y.DataTable({ ... }).render("#over-there");
+
+table._sortHandle.detach();
+table._sortHandle = table.delegate(["dblclick", "keydown"],
+ table._onUITriggerSort, ".yui3-datatable-sortable-column", table);</pre>
+
+
+<p>
+ See the <a href="index.html#sorting">Column Sorting section</a> of the
+ user guide for details about the APIs and attributes.
+</p>
+
+<h3 id="scrolling">Scrollable Table Changes</h3>
+
+<p>
+ Like sorting, the scrolling functionality has been moved to a class
+ extension, making it unnecessary to plug the DataTable instance with the
+ (now deprecated) <code>Y.Plugin.DataTableScroll</code> plugin.
+</p>
+
+<p>
+ <strong><code>datatable-scroll</code> is no longer included in the <code>datatable</code>
+ rollup</strong>, and must be explicitly included in your <code>use()</code> statement.
+</p>
+
+<p>
+ To enable scrolling in 3.5.0, set the table's <code>scrollable</code> attribute to "x",
+ "y", or "xy". The configured <code>height</code> and <code>width</code> for the DataTable are
+ used to bound the overall widget dimesions. Scrolling will only be applied
+ on the axis or axes specified in <code>scrollable</code>. However, if <code>scrollable</code> is
+ set to "y", but the <code>height</code> isn't set, it will not be made scrollable.
+ Likewise for "x" and <code>width</code>.
+</p>
+
+<div class="yui3-g">
+ <div class="yui3-u before">
+ <h4 class="no-toc">3.4.1</h4>
+
+<pre class="code prettyprint">// Assumes use("datatable-scroll") or use("datatable")
+var table = new Y.DataTable.Base({
+ columnset: ["id", "name", "price"],
+ recordset: [
+ { id: 1, name: "Bread", price: 3.45 },
+ { id: 2, name: "Milk", price: 4.99 },
+ { id: 3, name: "Eggs", price: 2.75 },
+ ...
+ ]
+});
+
+table.plug(Y.Plugin.DataTableScroll, {
+ height: "175px"
+});
+
+table.render("#over-there");</pre>
+
+ </div>
+ <div class="yui3-u after">
+ <h4 class="no-toc">3.5.0</h4>
+
+<pre class="code prettyprint">// Assumes use("datatable-scroll")
+var table = new Y.DataTable({
+ columns: ["id", "name", "price"],
+ data: [
+ { id: 1, name: "Bread", price: 3.45 },
+ { id: 2, name: "Milk", price: 4.99 },
+ { id: 3, name: "Eggs", price: 2.75 },
+ ...
+ ],
+ scrollable: "y",
+ height: "175px"
+}).render("#over-there");</pre>
+
+ </div>
+</div>
+
+<h2 id="markup">Markup and CSS Changes</h2>
+
+<p>
+ DataTable in 3.5.0 applies more CSS classes to Nodes, stamps fewer nodes
+ with guid ids, and does not render header and cell liner <code><div></code>s.
+</p>
+
+<p>
+ Below are examples of the same table rendered in 3.4.1 and 3.5.0. The 3.5.0
+ table has comments indicating markup added by feature modules.
+</p>
+
+<h4 class="no-toc">3.4.1</h4>
+<pre class="code prettyprint"><div id="(guid)" class="yui3-widget yui3-datatable">
+ <div id="(guid)" class="yui3-datatable-content">
+ <table>
+
+ <caption>
+ Example table with simple columns
+ </caption>
+
+ <colgroup>
+ <col>
+ <col>
+ <col>
+ </colgroup>
+
+ <thead class="yui3-datatable-columns">
+ <tr id="" class="yui3-datatable-first yui3-datatable-last">
+ <th id="(guid)" rowspan="1" colspan="1" class="yui3-column-id" abbr="">
+ <div class="yui3-datatable-liner">
+ id
+ </div>
+ </th>
+ <th id="(guid)" rowspan="1" colspan="1" class="yui3-column-name" abbr="">
+ <div class="yui3-datatable-liner">
+ name
+ </div>
+ </th>
+ <th id="(guid)" rowspan="1" colspan="1" class="yui3-column-price" abbr="">
+ <div class="yui3-datatable-liner">
+ price
+ </div>
+ </th>
+ </tr>
+ </thead>
+
+ <tbody class="yui3-datatable-msg">
+ </tbody>
+
+ <tbody class="yui3-datatable-data" id="(guid)">
+ <tr id="(guid)" class="yui3-datatable-even">
+ <td headers="(guid)" class="yui3-column-id">
+ <div class="yui3-datatable-liner">
+ 1
+ </div>
+ </td>
+ <td headers="(guid)" class="yui3-column-name">
+ <div class="yui3-datatable-liner">
+ Bread
+ </div>
+ </td>
+ <td headers="(guid)" class="yui3-column-price">
+ <div class="yui3-datatable-liner">
+ 3.45
+ </div>
+ </td>
+ </tr>
+ <tr id="(guid)" class="yui3-datatable-odd">
+ <td headers="(guid)" class="yui3-column-id">
+ <div class="yui3-datatable-liner">
+ 2
+ </div>
+ </td>
+ <td headers="(guid)" class="yui3-column-name">
+ <div class="yui3-datatable-liner">
+ Milk
+ </div>
+ </td>
+ <td headers="(guid)" class="yui3-column-price">
+ <div class="yui3-datatable-liner">
+ 4.99
+ </div>
+ </td>
+ </tr>
+ <tr id="(guid)" class="yui3-datatable-even">
+ <td headers="(guid)" class="yui3-column-id">
+ <div class="yui3-datatable-liner">
+ 3
+ </div>
+ </td>
+ <td headers="(guid)" class="yui3-column-name">
+ <div class="yui3-datatable-liner">
+ Eggs
+ </div>
+ </td>
+ <td headers="(guid)" class="yui3-column-price">
+ <div class="yui3-datatable-liner">
+ 2.75
+ </div>
+ </td>
+ </tr>
+ </tbody>
+
+ </table>
+ </div>
+</div></pre>
+
+
+<h4 class="no-toc">3.5.0</h4>
+<pre class="code prettyprint"><div id="(guid)" class="yui3-widget yui3-datatable">
+ <div id="(guid)" class="yui3-datatable-content">
+ <table cellspacing="0" class="yui3-datatable-table" id="(guid)">
+
+ <caption class="yui3-datatable-caption">
+ Price List
+ </caption>
+
+ <!-- colgroup only renders if datatable-column-widths is use()d.
+ Note, datatable-column-widths is included in the datatable rollup -->
+ <colgroup id="(guid)">
+ <col>
+ <col>
+ <col>
+ </colgroup>
+
+ <thead class="yui3-datatable-columns" id="(guid)">
+ <tr>
+ <th id="(guid)" colspan="1" rowspan="1" class="yui3-datatable-header yui3-datatable-first-header yui3-datatable-col-id" scope="col" data-yui3-col-id="id">
+ id
+ </th>
+ <th id="(guid)" colspan="1" rowspan="1" class="yui3-datatable-header yui3-datatable-col-name" scope="col" data-yui3-col-id="name">
+ name
+ </th>
+ <th id="(guid)" colspan="1" rowspan="1" class="yui3-datatable-header yui3-datatable-col-price" scope="col" data-yui3-col-id="price">
+ price
+ </th>
+ </tr>
+ </thead>
+
+ <!-- The message tbody only renders if datatable-message is use()d.
+ Note, datatable-message is included in the datatable rollup -->
+ <tbody class="yui3-datatable-message" id="(guid)">
+ <tr>
+ <td class="yui3-datatable-message-content" colspan="3">
+ No data to display
+ </td>
+ </tr>
+ </tbody>
+
+ <tbody class="yui3-datatable-data">
+ <tr id="(guid)" data-yui3-record="record_1" class="yui3-datatable-even">
+ <td class="yui3-datatable-col-id yui3-datatable-cell">
+ 1
+ </td>
+ <td class="yui3-datatable-col-name yui3-datatable-cell">
+ Bread
+ </td>
+ <td class="yui3-datatable-col-price yui3-datatable-cell">
+ 3.45
+ </td>
+ </tr>
+ <tr id="(guid)" data-yui3-record="record_2" class="yui3-datatable-odd">
+ <td class="yui3-datatable-col-id yui3-datatable-cell">
+ 2</td>
+ <td class="yui3-datatable-col-name yui3-datatable-cell">
+ Milk
+ </td>
+ <td class="yui3-datatable-col-price yui3-datatable-cell">
+ 4.99
+ </td>
+ </tr>
+ <tr id="(guid)" data-yui3-record="record_3" class="yui3-datatable-even">
+ <td class="yui3-datatable-col-id yui3-datatable-cell">
+ 3
+ </td>
+ <td class="yui3-datatable-col-name yui3-datatable-cell">
+ Eggs
+ </td>
+ <td class="yui3-datatable-col-price yui3-datatable-cell">
+ 2.75
+ </td>
+ </tr>
+ </tbody>
+
+ </table>
+ </div>
+</div></pre>
+
+
+<h2 id="help-me">What Did I Miss?</h2>
+
+<p>
+ Obviously, there were a lot of changes to DataTable from 3.4.1 to 3.5.0.
+ It's entirely likely that I have missed something here. If you experience
+ trouble with your upgrade and find this migration guide is missing
+ something important, please <a href="/projects/yui3/newticket">file a
+ ticket</a> and I'll update it as soon as possible.
+</p>
+
+<p>
+ Additional resources to help with the upgrade include the
+ <a href="/forum">forums</a>, and the #yui IRC channel on freenode.net.
+</p>
+</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="#overview">Overview of API changes from 3.4.1</a>
+</li>
+<li>
+<a href="#instantiation">Instantiation and Instance Configuration Changes</a>
+</li>
+<li>
+<a href="#formatters">Table and Cell Formatting Changes</a>
+</li>
+<li>
+<a href="#columns">Column Configuration Changes</a>
+</li>
+<li>
+<a href="#data">Row Data Configuration Changes</a>
+</li>
+<li>
+<a href="#features">Feature Configuration Changes</a>
+<ul class="toc">
+<li>
+<a href="#sorting">Column Sorting Changes</a>
+</li>
+<li>
+<a href="#scrolling">Scrollable Table Changes</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#markup">Markup and CSS Changes</a>
+</li>
+<li>
+<a href="#help-me">What Did I Miss?</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="This example illustrates simple DataTable use cases.">
+ <a href="datatable-basic.html">Basic DataTable</a>
+ </li>
+
+
+
+ <li data-description="DataTable loaded with JSON data from a remote webservice via DataSource.Get">
+ <a href="datatable-dsget.html">DataTable + DataSource.Get + JSON Data</a>
+ </li>
+
+
+
+ <li data-description="DataTable loaded with XML data from a remote webservice via DataSource.IO.">
+ <a href="datatable-dsio.html">DataTable + DataSource.IO + XML Data</a>
+ </li>
+
+
+
+ <li data-description="Custom format data for display.">
+ <a href="datatable-formatting.html">Formatting Row Data for Display</a>
+ </li>
+
+
+
+ <li data-description="DataTable with nested column headers.">
+ <a href="datatable-nestedcols.html">Nested Column Headers</a>
+ </li>
+
+
+
+ <li data-description="DataTable with column sorting.">
+ <a href="datatable-sort.html">Column Sorting</a>
+ </li>
+
+
+
+ <li data-description="DataTable with vertical and/or horizontal scrolling rows.">
+ <a href="datatable-scroll.html">Scrolling DataTable</a>
+ </li>
+
+
+
+ <li data-description="Using DataTable's recordType attribute to create calculated, sortable columns.">
+ <a href="datatable-recordtype.html">Sortable generated columns</a>
+ </li>
+
+
+
+ <li data-description="Populating one DataTable from details in the data of another.">
+ <a href="datatable-masterdetail.html">Master and detail tables</a>
+ </li>
+
+
+
+ <li data-description="Checkbox column that retains checked state when sorting.">
+ <a href="datatable-chkboxselect.html">Checkbox select column</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="Shows how to instantiate multiple Panel instances, and use nested modality to interact with a Datatable.">
+ <a href="../panel/panel-form.html">Creating a Modal Form</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/datatable',
+ name: 'datatable',
+ title: '3.5.0+ Migration Guide',
+ newWindow: '',
+ auto: false
+};
+YUI.Env.Tests.examples.push('datatable-basic');
+YUI.Env.Tests.examples.push('datatable-dsget');
+YUI.Env.Tests.examples.push('datatable-dsio');
+YUI.Env.Tests.examples.push('datatable-formatting');
+YUI.Env.Tests.examples.push('datatable-nestedcols');
+YUI.Env.Tests.examples.push('datatable-sort');
+YUI.Env.Tests.examples.push('datatable-scroll');
+YUI.Env.Tests.examples.push('datatable-recordtype');
+YUI.Env.Tests.examples.push('datatable-masterdetail');
+YUI.Env.Tests.examples.push('datatable-chkboxselect');
+YUI.Env.Tests.examples.push('panel-form');
+
+</script>
+<script src="../assets/yui/test-runner.js"></script>
+
+
+
+</body>
+</html>