Home
Application
BLOG
Articles
Videos
Facebook RSS4.11.2 The datagrid element
Working draft
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
- 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, ordatalistelement. - Or: A single
tableelement. - Or: A single
selectelement. - Or: A single
datalistelement. - 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 sequenceCell; // Column, [Variadic] any (exact types expected depend on the column type)
typedef sequence<Cell> CellList;
typedef sequenceRow; // RowID, long, long, CellList, [Optional] boolean, [Optional] long
typedef sequence<Row> RowList;
typedef sequenceRowID;
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
datagridlistener, if any. Returns null if there is none.The listener is an object provided by the script author that receives notifications when the
datagridneeds 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. (TheDataGridListenerinterface used for this purpose is described in the next section.)Can be set, to change the current listener.
- datagrid .
renotify() -
Causes the
datagridto resend notifications to the listener (if any) for any rows or cells that thedatagriddoes 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
datagridto clear its position information for rows, sosetRows()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 thedatagrid. - 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_ERRexception if the arguments contradict each other or previously declared information (e.g. declaring that thedatagridhas 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 tosetRowCount()but not previously declared.The rows argument is an array of rows, each represented by a further array consisting of:
- A
RowIDobject identifying the row. - 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.
- 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.
- An array giving the data for zero or more cells in the row, as described below.
- 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.
- 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-
- A string giving the cell's value.
- Optionally, an
imgelement giving an icon for the cell.
editablecheckable-
- A string giving the cell's value.
- A boolean, indicating whether the cell is checked (true) or not (false).
- Optionally, a boolean indicating whether the value of the cell is obscured as indeterminate (true), or not (false).
- Optionally, an
imgelement giving an icon for the cell.
list-
- A string giving the cell's current value.
- A
selectelement giving the list of options. - Optionally, an
imgelement giving an icon for the cell.
progress-
- A value in the range 0.0 (no progress) to 1.0 (task complete).
meter-
- A number giving the cell's value.
- Optionally, a number giving the maximum value, if it's not 1.
- Optionally, a number giving the minimum value, if it's not 0.
- Optionally, a number giving the highest value that is considered "low".
- Optionally, a number giving the lowest value that is considered "high".
- Optionally, a number giving the value that is considered optimal.
custom-
- A number giving the minimum width of the cell, in CSS pixels, that is desired.
- A number giving the minimum height of the cell, in CSS pixels, that is desired.
- A function that is passed a
CanvasRenderingContext2Dobject, 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_ERRexception 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). - A
- datagrid .
insertRows(rows) -
Inserts the given rows into the
datagrid, increasing the numbers of rows that thedatagridassumes 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 thesetRows()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_ERRexception 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 thedatagridaccordingly. The argument is an array ofRowIDobjects identifying the rows to remove.Throws a
DATAGRID_MODEL_ERRexception if the argument includes a row thedatagriddoesn't know about. - datagrid .
repaint(row, column) -
If the given column's type is
custom, then causes thedatagridto reinvoke the function that obtains the desired rendering. - datagrid .
clearRows() -
Clears the
datagridof all row data, resetting it to empty.
