DATAGRID. ONE OF THE REVOLUTIONARY ROAD OF HTML5

HTML5, when it will be a reality on our browser? Yet we can not know it. What we know for sure is that the innovations that are coming on our monitors are many and are one more useful and interesting than the other. Last, but not least, this news from the site w3c draft:

4.11.2 The datagrid element

Working draft

#datagrid

Tests: 0

Demos: 0

Latest Internet Explorer beta: no support whatsoever

Latest Firefox trunk nightly build: no support whatsoever

Latest WebKit or Chromium trunk build: no support whatsoever

Latest Opera beta or preview build: no support whatsoever

JavaScript libraries, plugins, etc: no support whatsoever

2007-12-08 Hixie

Edit

Categories

Flow content.

Interactive content.

Sectioning root.

Contexts in which this element may be used:

Where flow content is expected.

Content model:

Either: Nothing.

Or: Flow content, but where the first element child node, if any, is not a table, select, or datalist element.

Or: A single table element.

Or: A single select element.

Or: A single datalist element.

Content attributes:

Global attributes

disabled

DOM interface:

interface HTMLDataGridElement : HTMLElement {
          attribute boolean multiple;
          attribute boolean disabled;
          attribute DataGridListener listener;

 // columns
 void addColumn(in Column id, in DOMString label, in DOMString type, [Optional] in HTMLImageElement icon, [Optional] in boolean sortable, [Optional] in boolean visible);
          attribute DOMString sortColumn;
          attribute boolean sortAscending;
 void clearColumns();

 // rows
 void renotify();
 void setRowCount(in long childCount, in long rowCount);
 void setRows(in RowList rows);
 void insertRows(in RowList rows);
 void deleteRows(in RowIDList rows);
 void repaint(in RowID row, in DOMString column);
 void clearRows();

};

typedef DOMString Column;
typedef sequence<Column> ColumnList;
typedef sequence Cell; // Column, [Variadic] any (exact types expected depend on the column type)
typedef sequence<Cell> CellList;
typedef sequence Row; // RowID, long, long, CellList, [Optional] boolean, [Optional] long
typedef sequence<Row> RowList;
typedef sequence RowID;
typedef sequence<RowID> RowIDList;

[Callback=FunctionOnly, NoInterfaceObject]
interface RenderingContext2DCallback {
 DOMString handleEvent(in CanvasRenderingContext2D context, in unsigned long width, in unsigned long height);
};

The datagrid element represents an interactive representation of tree, list, or tabular data.

The data being presented is provided by script using the methods described in the following sections.

The disabled attribute is a boolean attribute used to disable the control. When the attribute is set, the user agent must disable the datagrid, preventing the user from interacting with it. The datagrid element should still continue to update itself when the underlying data changes, though, as described in the next few sections. However, conformance requirements stating that datagrid elements must react to users in particular ways do not apply when the datagrid is disabled.

The disabled DOM attribute must reflect the content attribute of the same name.

4.11.2.1 Introduction

This section is non-normative.

In the datagrid data model, data is structured as a set of rows representing a tree, each row being split into a number of columns. The columns are always present in the data model, although individual columns might be hidden in the presentation.

---

Each row can have child rows. Child rows may be hidden or shown, by closing or opening (respectively) the parent row.

Rows are referred to by the path along the tree that one would take to reach the row, using zero-based indices. Thus, the first row of a list is row "0", the second row is row "1"; the first child row of the first row is row "0,0", the second child row of the first row is row "0,1"; the fourth child of the seventh child of the third child of the tenth row is "9,2,6,3", etc.

The chains of numbers that give a row's path, or identifier, are represented by arrays of positions, represented in IDL by the RowID interface.

The root of the tree is represented by an empty array.

---

Each column has a string that is used to identify it in the API, a label that is shown to users interacting with the column, a type, and optionally an icon.

The possible types are as follows:

Keyword	Description
text	Simple text.
editable	Editable text.
checkable	Text with a check box.
list	A list of values that the user can switch between.
progress	A progress bar.
meter	A gauge.
custom	A canvas onto which arbitrary content can be drawn.

Each column can be flagged as sortable, in which case the user will be able to sort the view using that column.

Columns are not necessarily visible. A column can be created invisible by default. The user can select which columns are to be shown.

When no columns have been added to the datagrid, a column with no name, whose identifier is the empty string, whose type is text, and which is not sortable, is implied. This column is removed if any explicit columns are declared.

Each cell uses the type given for its column, so all cells in a column present the same type of information.

4.11.2.1.1 Example: a datagrid backed by a static table element

...

4.11.2.1.2 Example: a datagrid backed by nested ol elements

...

4.11.2.1.3 Example: a datagrid backed by a server

...

4.11.2.2 Populating the datagrid

datagrid . listener [ = value ]

Return the current object that is configured as the datagrid listener, if any. Returns null if there is none.

The listener is an object provided by the script author that receives notifications when the datagrid needs row data to render itself, when the user opens and closes rows with children, when the user edits a cell, and when the user invokes a row's context menu. (The DataGridListener interface used for this purpose is described in the next section.)

Can be set, to change the current listener.

datagrid . renotify()

Causes the datagrid to resend notifications to the listener (if any) for any rows or cells that the datagrid does not yet have information for.

datagrid . addColumn(id, label, type [, icon [, sortable [, visible ] ] ] )

Adds a column to the datagrid.

If a column with the given identifier has already been added, it just replaces the information for that column.

The possible types are enumerated in the previous section.

datagrid . sortColumn [ = value ]

Returns the identifier of the column by which the data is to be sorted.

Can be set, to indicate that the sort order has changed. This will cause the datagrid to clear its position information for rows, so setRows() will have to be called again with the new sort order.

The columns are not actually sorted by the datagrid; the data has to be sorted by the script that adds the rows to the datagrid.

datagrid . sortAscending [ = value ]

Returns true if the data is to be sorted with smaller values first; otherwise, returns false, indicating that bigger values are to be put first.

Can be set, to indicate that the order is about to change.

datagrid . clearColumns()

Removes all the columns in the datagrid, reinstating the implied column.

datagrid . setRowCount(childCount, rowCount)

Sets the numbers of rows in the datagrid, excluding rows that are descendants of rows that are closed.

Throws a DATAGRID_MODEL_ERR exception if the arguments contradict each other or previously declared information (e.g. declaring that the datagrid has three rows when the 12th row has been declared).

datagrid . setRows(rows)

Updates data for rows in the datagrid, or fills in data for rows previously implied by a call to setRowCount() but not previously declared.

The rows argument is an array of rows, each represented by a further array consisting of:

1. A RowID object identifying the row.
2. An integer giving the position of the row in its parent, given the current sort order, or −1 to set other row data without setting a position or changing a previously declared position.
3. An integer giving the number of children of the row, or 0 if the row has no children, or −1 if the row has children but the count is currently unknown. If the number of children has already been set to 0 or a positive integer, then passing −1 leaves the previous count unchanged.
4. An array giving the data for zero or more cells in the row, as described below.
5. A boolean declaring whether the row is open or not. This entry, if omitted, is assumed to be false (closed), unless the row has already been declared as open.
6. An integer giving the number of rows that are descendants of this row, excluding those that are descendants of descendants of this row that are closed. This entry can be omitted if the row is closed or if it has already been declared.

The array giving the data for the cells in the row consists of a further set of arrays, one per cell. The first item of each of these arrays is the column's identifier; the subsequent values vary based on the type of the column, as follows:

text

1. A string giving the cell's value.
2. Optionally, an img element giving an icon for the cell.

editable

1. A string giving the cell's value.
2. Optionally, a datalist element giving a set of predefined options.
3. Optionally, an img element giving an icon for the cell.

checkable

1. A string giving the cell's value.
2. A boolean, indicating whether the cell is checked (true) or not (false).
3. Optionally, a boolean indicating whether the value of the cell is obscured as indeterminate (true), or not (false).
4. Optionally, an img element giving an icon for the cell.

list

1. A string giving the cell's current value.
2. A select element giving the list of options.
3. Optionally, an img element giving an icon for the cell.

progress

1. A value in the range 0.0 (no progress) to 1.0 (task complete).

meter

1. A number giving the cell's value.
2. Optionally, a number giving the maximum value, if it's not 1.
3. Optionally, a number giving the minimum value, if it's not 0.
4. Optionally, a number giving the highest value that is considered "low".
5. Optionally, a number giving the lowest value that is considered "high".
6. Optionally, a number giving the value that is considered optimal.

custom

1. A number giving the minimum width of the cell, in CSS pixels, that is desired.
2. A number giving the minimum height of the cell, in CSS pixels, that is desired.
3. A function that is passed a CanvasRenderingContext2D object, along with the width and height (in CSS pixels) of the cell that the context will draw on.

While the rows in a single call to the setRows() method can be in any order, for each row, it is important that all its ancestor rows and all its open previous siblings are also declared, either in the same call or in an earlier one.

Throws a DATAGRID_MODEL_ERR exception if the arguments contradict each other or previously declared information (e.g. saying that a row's position is 5 when the parent row only has 3 children, or naming a column that doesn't exist, or declaring a row without declaring its parent, or changing the number of children that a row has while that row and its ancestors are all open).

datagrid . insertRows(rows)

Inserts the given rows into the datagrid, increasing the numbers of rows that the datagrid assumes are present.

The rows argument is an array of rows in the same structure as the argument to the setRows() method described above, with the same expectations of consistency (a given row's ancestors and earlier open siblings being listed either earlier or in the same call as a given row). However, unlike with the setRows() method, if a row is inserted along with its child, the child is not included in the child and row counts of the parent row; every row in the rows argument will increase its parent's counts automatically.

Throws a DATAGRID_MODEL_ERR exception if the arguments contradict each other or previously declared information.

datagrid . deleteRows(rows)

Removes the given rows from the datagrid, and updates the number of rows known to be in the datagrid accordingly. The argument is an array of RowID objects identifying the rows to remove.

Throws a DATAGRID_MODEL_ERR exception if the argument includes a row the datagrid doesn't know about.

datagrid . repaint(row, column)

If the given column's type is custom, then causes the datagrid to reinvoke the function that obtains the desired rendering.

datagrid . clearRows()

Clears the datagrid of all row data, resetting it to empty.