specify title and type, use them in example, and document them

gordonwoodhull · gordonwoodhull · commit 53f21c42dd74 · 2018-08-01T09:18:11.000-04:00
diff --git a/README.md b/README.md
@@ -3,20 +3,35 @@
 The intent of this project is to integrate the powerful UI, styling, and plugins of
 [DataTables](https://datatables.net/) with dc.js filtered data.
 
-[Demo](https://dc-js.github.io/dc.datatables.js/) using the dc.js stock example, but with a
-DataTable to display the data in a flexible way.
+[Demo](https://dc-js.github.io/dc.datatables.js/) using the dc.js stock example, but displaying the
+data with a DataTable.
 
-For now the implementation is quite simple:
+Instead of generating an HTML table using `dc.dataTable` and then converting the DOM elements to a
+DataTable, use `dc.datatables.js` to import the data programmatically. This should be faster and
+less error-prone.
+
+Implementation:
 
 * `.render()` creates the DataTable object and maps
   [columns](https://dc-js.github.io/dc.js/docs/html/dc.dataTable.html#columns__anchor) defined
   similar to those in `dc.dataTable`
 * `.redraw()` pulls all the data (`.top(Infinity`) from the dimension and puts it into the
-  DataTable.
+  DataTable using [rows.add()](https://datatables.net/reference/api/rows.add())
 * `.dt()` fetches the underlying DataTable object for further customization.
 
-This method is much faster and more reliable than the old method of generating an HTML table using
-`dc.dataTable` and then converting the DOM elements to a DataTable.
+For control over column formatting and behavior, use the object form of columns
+
+* [columns.type](https://datatables.net/reference/option/columns.type), used for sorting, is 'num'
+  by default; use `type` to override this
+* [columns.name](https://datatables.net/reference/option/columns.name), used as a unique id, is read
+  from the `label`
+* [columns.title](https://datatables.net/reference/option/columns.title), used to provide heading
+  text, is read from the `label` and capitalized
+* [columns.render](https://datatables.net/reference/option/columns.render), used to fetch and format
+  the data, uses the function `format`
+
+In limited cases, you can also use the string form of columns. This will read the field with that
+name, use the default numeric ordering
 
 See something missing? [File an issue](https://github.com/dc-js/dc.datatables.js/issues) on this
 repo, or even better, fork this project and file a pull request!
diff --git a/src/datatable.js b/src/datatable.js
@@ -37,10 +37,13 @@ dc_datatables.datatable = function(selector, chartGroup) {
             .merge(table);
         _dt = $(table.node()).DataTable({
             columns: _table.columns().map(function(c) {
-                return {
+                var col = {
                     name: typeof c === 'string' ? c : c.label,
+                    type: typeof c === 'object' ? c.type : 'num',
                     render: columnRenderer(c)
                 };
+                col.title = col.name.charAt(0).toUpperCase() + col.name.slice(1);
+                return col;
             })
         });
         return _table.redraw();
diff --git a/web/stock.js b/web/stock.js
@@ -533,9 +533,15 @@ d3.csv('ndx.csv').then(function (data) {
         // There are several ways to specify the columns; see the data-table documentation.
         // This code demonstrates generating the column header automatically based on the columns.
         .columns([
-            // Use the `d.date` field; capitalized automatically
-            'date',
-            // Use `d.open`, `d.close`
+            // Use the `d.date` field; capitalized automatically; specify sorting order
+            {
+                label: 'date',
+                type: 'date',
+                format: function(d) {
+                    return d.date;
+                }
+            },
+            // Use `d.open`, `d.close`; default sorting order is numeric
             'open',
             'close',
             {
