index.mustache revision 9533104fb7447a0765dc2aafec105c729d2c1be7
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith<style type="text/css">
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith .yui3-datatable table {
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith width: auto;
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith .yui3-datatable td, .yui3-datatable th {
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith border: 0 none;
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<div class="intro component">
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The DataTable widget is responsible for rendering columnar data into a
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith highly customizable and fully accessible HTML table. The core
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith functionality of DataTable is to visualize structured data as a table.
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith A variety of class extensions can then be used to add features to the
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith table such as sorting and scrolling.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith{{>getting-started}}
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h2 id="using">Using DataTables</h2>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="basics">DataTable basics</h3>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith A basic DataTable is comprised of columns and rows. Define the columns you
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith want to display in your DataTable with the `columns` attribute. Rows are
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith created for you based on the data you provide to the `data` attribute.
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith Under the hood, the DataTable class uses a ModelList instance to manage the
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith row data properties.
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith// Columns must match data object property names
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { id: "ga-3475", name: "gadget", price: "$6.99", cost: "$5.99" },
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { id: "sp-9980", name: "sprocket", price: "$3.75", cost: "$3.25" },
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { id: "wi-0650", name: "widget", price: "$4.25", cost: "$3.75" }
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smithvar table = new Y.DataTable({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: ["id", "name", "price"],
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // Optionally configure your table with a caption
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith caption: "My first DataTable!",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // and/or a summary (table attribute)
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith summary: "Example DataTable showing basic instantiation configuration"
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith<p>This code produces this table:</p>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith<div id="example1" class="yui3-skin-sam"></div>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke SmithYUI().use('datatable-base', function (Y) {
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // Columns must match data object property names
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith var data = [
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { id: "ga-3475", name: "gadget", price: "$6.99", cost: "$5.99" },
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { id: "sp-9980", name: "sprocket", price: "$3.75", cost: "$3.25" },
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { id: "wi-0650", name: "widget", price: "$4.25", cost: "$3.75" }
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith var table = new Y.DataTable({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: ["id", "name", "price"],
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith caption: "My first DataTable!",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith summary: "Example DataTable showing basic instantiation configuration"
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith<h3 id="columns">Working with columns</h3>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith The `columns` attribute is an array of field names that correspond to
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith property names in the `data` objects. These field names are called "keys".
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith As long as these keys exist in your data, DataTable will display these
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns in the table.
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith For greater flexibility, columns can also be identified with configuration
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith objects. When identifying a column with a configuration object, use the
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith `key` property to reference the column name string. Otherwise, these
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith objects let you customize how your data renders in many ways, depending on
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith which table extensions or plugins you have included.
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith Here's an example of a `columns` setup using a number of other configurations:
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// The attr attribute enhances the screen-reader experience
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // The key relates this column to a data field
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith key: "mfr-parts-database-id",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // The label is the text that will be rendered in the table head
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith label: "Mfr Part ID",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // The abbr sets the <th>s abbr attribute
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith key: "mfr-parts-database-name",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith label: "Mfr Part Name",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith abbr: "Name",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // Allows user clicks on the header to sort the table rows by the
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // values in this column. Requires the `datatable-sort` module.
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith sortable: true
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith key: "mfr-parts-database-price",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith label: "Wholesale Price",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith abbr: "Price",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // The emptyCellValue provides default content if a data row has no
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // value for this field
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith emptyCellValue: '<em>(not set)</em>',
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // The allowHTML configuration permits markup in data values to pass
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // directly into the cell's innerHTML.
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith allowHTML: true,
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith sortable: true
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smithvar data = ...
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smithvar table = new Y.DataTable({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: cols,
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith<p>This code produces this table:</p>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith<div id="example2" class="yui3-skin-sam"></div>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke SmithYUI().use('datatable-sort', function (Y) {
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith var cols = [
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith key: "mfr-parts-database-id",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith label: "Mfr Part ID",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith key: "mfr-parts-database-name",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith label: "Mfr Part Name",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith abbr: "Name",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith sortable: true
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith key: "mfr-parts-database-price",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith label: "Wholesale Price",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith abbr: "Price",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith emptyCellValue: '<em>(not set)</em>',
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith allowHTML: true,
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith sortable: true
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith var data = [
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { "mfr-parts-database-id": "ga-3475", "mfr-parts-database-name": "gadget", "mfr-parts-database-price": "$6.99", cost: "$5.99" },
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { "mfr-parts-database-id": "sp-9980", "mfr-parts-database-name": "sprocket", "mfr-parts-database-price": "$3.75", cost: "$3.25" },
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { "mfr-parts-database-id": "wi-0650", "mfr-parts-database-name": "widget", "mfr-parts-database-price": "", cost: "$3.75" },
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { "mfr-parts-database-id": "nu-0001", "mfr-parts-database-name": "nut", "mfr-parts-database-price": "$0.25", cost: "$3.75" }
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith var table = new Y.DataTable({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: cols,
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith<h4 id="nested">Multi-row Headers</h4>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith Use the `children` column configuration to created nested column headers.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Parent columns are for display purposes only, not associated with any data,
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith and <em>should not have a `key` attribute</em> of their own.
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith The `children` configuration takes an array of column configurations, just
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith like the `columns` attribute itself.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar nestedCols = [
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // Important: Parent columns do NOT get a key
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // All Parent columns should have a label for the header content
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith label: "Train Schedule",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // Pass an array of column configurations (strings or objects) as children
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith label: "Route",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "from" },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "to" }
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { track: "1", from: "Paris", to: "Amsterdam" },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { track: "2", from: "Paris", to: "London" },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { track: "3", from: "Paris", to: "Zurich" }
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar table = new Y.DataTable.Base({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: nestedCols,
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith data : data,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith caption: "Table with nested column headers"
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith}).render("#example3");
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith<p>This code produces this table:</p>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith<div id="example3" class="yui3-skin-sam"></div>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke SmithYUI().use('datatable-base', function (Y) {
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smithvar nestedCols = [
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith label: "Train Schedule",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith label: "Route",
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith children: [ { key: "from" }, { key: "to" } ]
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { track: "1", from: "Paris", to: "Amsterdam" },
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { track: "2", from: "Paris", to: "London" },
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { track: "3", from: "Paris", to: "Zurich" }
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar table = new Y.DataTable.Base({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: nestedCols,
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith data : data,
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith caption: "Table with nested column headers"
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith}).render("#example3");
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith<h3 id="data">Working with row data</h3>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith Pass an array of data to the `data` attribute and DataTable will create a
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith `ModelList` and populate it with instances of a `Model` subclass tailor
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith made for your data. If you want to work with a specific Model class, pass
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith that class to the DataTable's `recordType` attribute at instantiation. If
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith you want to work with a specific ModelList instance, pass the instance to
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith the `data` attribute.
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith The important thing to remember about your Model data is that <strong>it
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith should be stored as pure data</strong>, not values formatted for display.
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith For example, the `datatable-sort` module adds the ability to sort your
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith table, but to do so, it needs to sort your data. If you are storing
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith numbers as strings, "10" will sort ahead of "2".
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith DataTable has a variety of <a href="#formatter">ways to format your data
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith for display</a>. But keep your Model data as free from UI concerns as
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith<h4 id="formatter">Formatting Cell Data</h4>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith<p>DataTable provides three primary ways to format cell data, all defined in the column configuration:</p>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith { label: 'formatter', children: [
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // 1. formatter strings
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // mix the field value into the {value} placeholder
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith key: 'price',
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith label: 'string',
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith formatter: '${value}'
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // 2. formatter functions
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // can provide alternate content, add cell classes, refer to other data
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // fields, etc (more below)
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith key: 'price',
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith label: 'function',
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith formatter: function (o) {
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith o.className += ' yellow-background';
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith return '$' + (o.value * 0.75).toFixed(2);
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // 3. nodeFormatter functions
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // have access to the cell Node in the DOM, up to the <tbody> Node.
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // Caveats apply; see below.
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith key: 'price',
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith label: 'nodeFormatter',
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith nodeFormatter: functions (o) {
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith // Add a class to the <tr>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith o.cell.ancestor().addClass('red-text');
9533104fb7447a0765dc2aafec105c729d2c1be7Luke SmithINSERT CAVEAT ABOUT allowHTML vs formatters
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <th>Property</th>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <th>Value</th>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>`tbody`</td>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>The `<tbody>` node containing the cell.</td>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>`tr`</td>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>The `<tr>` node containing the cell.</td>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>`td`</td>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>The cell `<td>` node. As of 3.4.1, this property
4783faf4ee88fa40a0860cea77b3a88086c53e5fLuke Smith is <strong>not provided by default</strong>, but can be generated by the
4783faf4ee88fa40a0860cea77b3a88086c53e5fLuke Smith <a href="{{apiDocs}}/classes/DataTable.html#methods_createCell">createCell</a>
4783faf4ee88fa40a0860cea77b3a88086c53e5fLuke Smith method.</td>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>`value`</td>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>Usually the value stored in the `Record` for the column. This is the default content that will be displayed.</td>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>`record`</td>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>The `Record` instance containing the data for all cells in the row.</td>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>`data`</td>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>The raw data collection from the `Record` instance.</td>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>`rowindex`</td>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>The row number of the `<tr>` node containing the cell (zero based).</td>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>`column`</td>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>The `Column` instance for the cell's column.</td>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>`classnames`</td>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>The classname corresponding to the ID of the cell's column.</td>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>`headers`</td>
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith <td>The Array of IDs from all `<th>`s corresponding to the cell (mostly relevant to nested headers).</td>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// The custom formatter function recieves an object
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar calculate = function (o) {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith var cost = o.record.getValue("cost"),
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith price = o.record.getValue("price");
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith return "$" + (price - cost).toFixed(2);
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// Assign the custom formatter in the column definition
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar cols = [ "id", "name", { key: "profit", formatter: calculate } ];
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { id: "ga-3475", name: "gadget", price: 6.99, cost: 4.99 },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { id: "sp-9980", name: "sprocket", price: 3.75, cost: 2.75 },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { id: "wi-0650", name: "widget", price: 4.25, cost: 3.25 }
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar table = new Y.DataTable.Base({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: cols,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith caption: "Data formatting with custom function"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith}).render("#function");
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Integrate with the <a href="../datasource/">DataSource</a> data abstraction
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith utility to easily load data from remote sources and implement features such
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith as caching and polling.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Rating.AverageRating", label: "Rating" }
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar myDataSource = new Y.DataSource.Get({
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith source: "http://query.yahooapis.com/v1/public/yql?&format=json&env=store%3A%2F%2Fdatatables.org%2Falltableswithkeys"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithmyDataSource.plug(Y.Plugin.DataSourceJSONSchema, {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith resultListLocator: "query.results.Result",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith resultFields: [ "Title", "Phone", "Rating.AverageRating" ]
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar table = new Y.DataTable.Base({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: cols,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith summary: "Pizza places near 98089"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith datasource: myDataSource
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// Load the data into the table
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith request: "&q=select%20*%20from%20local.search%20where%20zip%3D%2794089%27%20and%20query%3D%27pizza%27"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// Make another request later
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith request: "&q=select%20*%20from%20local.search%20where%20zip%3D%2794089%27%20and%20query%3D%27chinese%27"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Enable DataSource caching.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Rating.AverageRating", label: "Rating" }
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar myDataSource = new Y.DataSource.Get({
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith source: "http://query.yahooapis.com/v1/public/yql?format=json&env=store%3A%2F%2Fdatatables.org%2Falltableswithkeys"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith resultListLocator: "query.results.Result",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith resultFields: ["Title", "Phone", "Rating.AverageRating"]
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar table = new Y.DataTable.Base({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: cols,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith summary: "Pizza places near 98089",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith caption: "Table with JSON data from YQL"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith datasource: myDataSource
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith .render("#pizza");
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith request: "&q=select%20*%20from%20local.search%20where%20zip%3D%2794089%27%20and%20query%3D%27chinese%27"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Enable DataSource polling.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar cols = ["Title", "Phone", "Rating"];
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar myDataSource = new Y.DataSource.IO({
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith resultListLocator: "Result",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith resultFields: [
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Title", locator: "*[local-name() ='Title']" },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Phone", locator: "*[local-name() ='Phone']" },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Rating", locator: "*[local-name()='Rating']/*[local-name()='AverageRating']" }
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar table = new Y.DataTable.Base({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: cols,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith summary: "Chinese restaurants near 98089",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith caption: "Table with XML data from same-domain script"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith datasource: myDataSource,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith initialRequest: "zip=94089&query=chinese"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith .render("#chinese");
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith request: "zip=94089&query=chinese",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith success: Y.bind(table.datasource.onDataReturnInitializeTable, table.datasource),
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith failure: Y.bind(table.datasource.onDataReturnInitializeTable, table.datasource)
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="sorting">Column sorting</h3>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Column sorting functionality can be added with the DataTableSort plugin
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith (provided by the `datatable-sort` module, or in the
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith `datatable` rollup module). Indicate which columns are sortable
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith by setting `sortable: true` in your column definitions.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Company", sortable: true },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Phone" },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Contact", sortable: true }
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { Company: "Company Bee", Phone: "415-555-1234", Contact: "Sally Spencer"},
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { Company: "Acme Company", Phone: "650-555-4444", Contact: "John Jones"},
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { Company: "Indutrial Industries", Phone: "408-555-5678", Contact: "Robin Smith"}
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar table = new Y.DataTable.Base({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: cols,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith summary: "Contacts list",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith caption: "Table with simple column sorting",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith}).render("#sort");
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="scrolling">Scrolling</h3>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <strong>Note:</strong> Scrolling is not currently supported on the Android
5992781dfab2b64f79fee03abd15d9a91e2f5b77Luke Smith WebKit browser.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Scrolling functionality can be added with the DataTableScroll plugin
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith (provided by the `datatable-scroll` module or in the
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith `datatable` rollup module). Horizontal scrolling is enabled by
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith setting a `width` attribute value; fixed header vertical
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith scrolling is enabled by setting a `height` attribute value; and
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith xy-scrolling is enabled by setting both `width` and
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith `height` values.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Company" },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Phone" },
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { key: "Contact" }
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { Company: "Company Bee", Phone: "415-555-1234", Contact: "Sally Spencer"},
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { Company: "Acme Company", Phone: "650-555-4444", Contact: "John Jones"},
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith { Company: "Indutrial Industries", Phone: "408-555-5678", Contact: "Robin Smith"}
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar table = new Y.DataTable.Base({
9533104fb7447a0765dc2aafec105c729d2c1be7Luke Smith columns: cols,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith width: "300px",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith height: "200px"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith .render("#scroll");
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h2 id="knownissues">Known Issues</h2>
f85539ee51e30adb584249d2c134280e8191447dLuke Smith Scrolling is
f85539ee51e30adb584249d2c134280e8191447dLuke Smith <a href="http://yuilibrary.com/projects/yui3/ticket/2529761">not
f85539ee51e30adb584249d2c134280e8191447dLuke Smith currently supported on Android</a> WebKit browser.
f85539ee51e30adb584249d2c134280e8191447dLuke Smith <li>Scrolling DataTable does
f85539ee51e30adb584249d2c134280e8191447dLuke Smith <a href="http://yuilibrary.com/projects/yui3/ticket/2531047">not appear
f85539ee51e30adb584249d2c134280e8191447dLuke Smith scrollable</a> in iOS and OS X 10.7 in Safari 5.1+ and Chrome 15+.