type: widget

release: 0.0

status: on hold

documentation: N/A

demo: N/A

TODOs

Missing, based on the original planning notes:

Trim cell contents
Column higlighting
Column/Cell alignment
Show row # in column (dynamic column)
Theming

Striping
Hover row/column/cell

1 - Description:

Implement the simplest grid possible, by enhancing a regular html table. Enhancements include:

Injecting markup to allow styling the table with the CSS framework (eg. make it ThemeRoller-ready)
Creating a titlebar based on the table's caption, if present.
Markup and styles necessary for scrolling of the table body, while keeping the header visible.
Trimming cell contents to prevent wrapping, and forcing equal heights for all rows.

It also provides the API to allow integration with other components, like the dataview and observable.

2 - Visual Design:

3 - Functional Specification:

Grid consists of main wrapper div with head div, body div, and foot div, each containing table. This allows for fixed column headers and footers and scolling body rows in all supported browsers.
Original table becomes body table, keeping only the tbody.
Original caption and thead are moved to head table.
Original tfoot is moved to foot table
Head, body, and foot tables are given width 100%. An explicit width is required in order for border-layout: fixed to work, which handles clipping, overflow, and being able to set an actual column width (as opposed to a min width)
Column sizing is done by

1. Calculating the relative size of each column on the original before turning it into a grid. This finds a decent compromise between sizing based on column header and body cell contents as well as using the browser's wrapping and table column sizing
2. A <col> element is created for each column and given a % width based on above calculation
3. The <col> element with % width are put in a <colgroup> element in both head and body tables. With identical % widths (and identical table sizes) the columns have the same width and align

Vertical scrolling is done by putting an explicit height on the .ui-grid-body wrapper and setting overflow to auto. After that it's required to call the .grid("refresh") method which puts a padding-right on the head and foot wrappers and head and foot tables to adjust the width of the wrappers, accounting for the width of the scrollbar.

Options

columns (array, default: null)

Specifies what columns to deal with.

If just an array of strings, will generate an object for each column containing a "property"-property, matching each string value.
If array of objects, must have at least a "property"-property for each item. Can also contain those listed in dataFields or other custom properties.

Generated based on data-attributes (via dataFields option) if null

dataFields (array, default: [ "type", "editor", "editorOptions", "templatate", "culture", "format" ]

Column configuration properties to read from data-attributes if columns option isn't specified

heightStyle (string, default: "auto")

How to handle the height of the table body
auto: Adapt the height when the content changes
fill: Use a fixed height, using scroll overflow when the content becomes bigger then the table body

rowTemplate (string, default: null)

Template to use for rendering each row
Generated based on columns option if null

source (observable array, default: null)

Input data to render
If $.observable is used to update it, the grid will automatically refresh

Methods

refresh

Manually refresh the grid, rendering all rows

refreshItem(item)

Refresh a single row

Events

refresh

triggered after rerendering the grid's content (after calling refresh)

4 - Markup & Style:

See Grid-Markup.

ARIA Spec for tree grid http://www.w3.org/TR/wai-aria/roles#treegrid

from Mozilla site: https://wiki.mozilla.org/Accessibility/TreeGrid

5 - Latest version of plugin:

6 - Open issues being discussed

How will a11y work with two separate tables. aria-labelledby?
We need additional styles not currently provided by the jQuery UI CSS Framework and the current version of ThemeRoller. Discussion athttps://forum.jquery.com/topic/we-need-some-theme-ready-alternate-background-color-styles

Apr 9, 2009 Todd Parker said: Here are a few guidelines for making tabular data accessible that we really should try to respect when building the grid (grabbed fromhttp://jimthatcher.com/webcourse9.htm):

Use caption element as a title for the data table and and/or use the summary attribute to give a brief overview of the structure of the table.
And markup all table header cells

Use the table header element, th, for all header cells and add the scope attribute when that scope is ambiguous (corners).
Or use td together with the scope to specify header cells
Or use id attributes on the header cells and the headers attribute on the data cells to explicitly associate header information with data cells. This is essential if there are data cells whose header information is not in the same row and the same column as that cell.