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.

Apr 14, 2010 fnagel said: Perhaps you would like to take a look at my widgets sortTables in conformance to WAI ARIA and WCAG 2.0 http://github.com/fnagel/jQuery-Accessible-RIA