# API Comparison Between dojox/grid and dgrid

## dojox/grid properties

### sortInfo

The way in which dgrid represents current sort order is significantly different
than `dojox/grid`.  dgrid stores the current sort options, as they would be passed
via a store's `sort` method; these options are retrievable via the sort getter
(e.g. `grid.get("sort")`).

### rowSelector and indirect selection

Indirect selection is available in dgrid via the [Selector](../components/mixins/Selector.md) mixin.
This achieves similar effects to the DataGrid's `_CheckBoxSelector` and
`_RadioButtonSelector` view types, and EnhancedGrid's IndirectSelection plugin.

dgrid does not feature a direct analog to the `rowSelector` property.

### selectionMode

dgrid supports this property via the [Selection](../components/mixins/Selection.md) and
[CellSelection](../components/mixins/CellSelection.md) mixins.
It recognizes the same values supported by `dojox/grid` components
(`none`, `single`, `multiple`, and `extended`, the latter being the default).

### keepSelection

This is roughly the inverse equivalent to the `deselectOnRefresh` property
supported by dgrid's [Selection](../components/mixins/Selection.md)
(and [CellSelection](../components/mixins/CellSelection.md)) mixin.  Both `dojox/grid`
and dgrid default to *not* maintaining selection between refreshes, sorts, etc.

### columnReordering

Setting this `dojox/grid` property to `true` allows reordering of columns
in grids with basic structures via drag'n'drop operations on column header cells.

This feature is available in dgrid via the [ColumnReorder](../components/extensions/ColumnReorder.md) extension.

### headerMenu and other context menu scenarios

dgrid does not directly offer context menu functionality via an extension, but
it is easily possible to delegate to the `contextmenu` event of
cells or rows in the grid's body or header, to perform custom logic.  Here are
the basic steps one would need to follow:

* An event handler listening for `contextmenu` events against a particular selector;
  for example:
    * `.dgrid-header:contextmenu` for a general header context menu
    * `.dgrid-content .dgrid-row:contextmenu` for a general body context menu
    * `.dgrid-header .field-foo:contextmenu` for a context menu for a specific header cell
    * `.dgrid-content .field-foo:contextmenu` for a context menu for body cells in
      a particular column
* within the event handler:
    * Call `preventDefault` on the event object, to stop the default
      browser context menu from displaying.
    * Call `grid.row()` or `grid.cell()` to retrieve information on the
      pertinent row or cell.  If the menu is intended to apply to selected items,
      `grid.selection` can be checked for entries, and then `grid.row()` can be
      called with the IDs found.
    * If `dijit/Menu` is being used, it unfortunately does not provide any
      directly-accessible public API for simply opening the menu around the mouse,
      as it is normally expected to be pre-attached to nodes; however, depending
      on use-case, attaching it to an entire section of the grid may be inappropriate.
      In such a case, the menu can be directly opened within a `contextmenu`
      event handler, by calling `_scheduleOpen(this, null, { x: evt.pageX, y: evt.pageY }`.

### autoHeight

Automatic height can be achieved by adding the `dgrid-autoheight` class to a List
or Grid's `domNode`.  There is no direct programmatic support for this
(i.e. there is no built-in support for automatically sizing to a certain number of rows).

Examples of an auto-height grid can be found in the `autoheight.html` and
`extensions/Pagination.html` test pages.

### autoWidth

Not supported.

### initialWidth

Not supported.  Width (and height) should be dictated via CSS.

### singleClickEdit

The effect of the `singleClickEdit` property can be achieved by specifying
`editOn: "click"` in a column definition when the [Editor](../components/mixins/Editor.md) mixin is in use.
(Alternatively, `dojox/grid`'s default double-click behavior can be
achieved by specifying `editOn: "dblclick"` instead.)

### loadingMessage, noDataMessage, errorMessage

Store-backed grid instances support `loadingMessage` and `noDataMessage`.
There is currently no direct support for an error message, but when a
store-related error occurs within dgrid's own logic, it will emit a `dgrid-error`
event.  When `grid.save()` is called directly, it will return a promise which
will reject if an error occurs.

The messages demo in the
[Using Grids and Stores tutorial](http://dgrid.io/tutorials/0.4/grids_and_stores/)
provides an example of showing an error notification when `dgrid-error` fires.

### selectable

This is automatically managed by the [Selection](../components/mixins/Selection.md) mixin by default.
Standard browser text selection is disabled when a `selectionMode` other than `none` is in use.
Otherwise, text selection operates as normal.  This can be overridden via the `allowTextSelection` property.

### formatterScope

dgrid supports this option.

### updateDelay

dgrid does not support this, as it is generally not applicable, due to the
difference in how dgrid components update from observed store changes.

### escapeHTMLInData

Not supported.  By default, dgrid components will escape HTML in data, as it
should generally be devoid of HTML in most cases, and presence of HTML in data
might suggest a cross-site scripting attempt.

The `formatter` or `renderCell` functions in the column definition may be
overridden to explicitly render data as received, in cases where that is truly
desired.

## Column Definitions

Whereas `dojox/grid` always expects cell definitions to be specified via a
`structure` property, dgrid expects one of the following properties to be specified:

* `columns`: an array or object hash, for simple single-row grid configurations
* `subRows`: an array of arrays, for grid configurations with multiple sub-rows per item
* `columnSets` (only when the [ColumnSet](../components/mixins/ColumnSet.md) mixin is in use):
  a nested array for grid configurations containing distinct horizontal regions of one or more rows
  (analogous to multiple views in a `dojox/grid` instance)

The following subsections outline how features of `dojox/grid` cell definitions
are available in dgrid column definitions.

### field

Supported by dgrid, including the special `"_item"` value supported by
`dojox/grid` in Dojo >= 1.4.

Also note that dgrid also supports specifying `columns` as an object hash instead
of an array, in which case the key of each property is interpreted as the `field` by default.

### fields

Not supported by dgrid.  If a compound value is desired, define a custom `get`
function in a column definition.

### width

Use CSS with `.field-<fieldname>` (or custom `className`) selectors instead.

The only time a `width` column property is supported is when using the
[ColumnResizer](../components/extensions/ColumnResizer.md) extension, specifically
for the purpose of allowing column sizes to be programmatically restored if they
are persisted (e.g. via `localStorage`).  In all other cases, using CSS to set column widths
is heavily recommended.

### cellType, widgetClass

The [Editor](../components/mixins/Editor.md) mixin provides capabilities equivalent to these properties.
It accepts an `editor` property, which can be either a widget constructor or a
string indicating a native HTML input type.

### options

Not directly applicable; in `dojox/grid` this applies only to cell definitions
where `cellType` is set to `dojox.grid.cells.Select`.

The [Editor](../components/mixins/Editor.md) mixin does not currently offer support for standard HTML
select components; however, similar behavior can be achieved using the
`dijit/form/Select` widget as the `editor`, and specifying `options` for the
widget within the `editorArgs` property of the column definition object.

### editable

In dgrid, cells are uneditable by default, and are made editable by including
the [Editor](../components/mixins/Editor.md) mixin and specifying an `editor` in each editable column's definition.

### draggable

Only applicable to `dojox/grid` instances with `columnReordering` set to `true`,
the `draggable` property determines whether a particular column can be
reordered via drag'n'drop.

The ColumnReorder dgrid extension provides an equivalent via the `reorderable`
column definition property.  It defaults to `true`, but if set explicitly to
`false`, the given column's header node will not be registered as a DnD item.

### formatter

dgrid supports formatter functions, but doesn't support returning a widget from
them.

dgrid also has `renderCell`, which is expected to return a DOM node.  This could
ostensibly be used for displaying widgets (and the Editor mixin does
exactly this).

Note that for cell editing purposes, use of the Editor mixin is highly
encouraged.

### get

dgrid supports the `get` function on column definitions; however, note that it
only receives one parameter: the object for the item represented by the current
row being rendered.  (dgrid generally has no concept of row index, since
row identities are generally far more meaningful.)

### hidden

The `hidden` property on column definitions is only supported by the
[ColumnHider](../components/extensions/ColumnHider.md) extension.
Otherwise, columns would ordinarily be suppressed simply by excluding them from the
`columns`, `subRows` or `columnSets` property outright.

## DataGrid methods

### getItem(rowIndex), getItemIndex(item)

These are somewhat inapplicable, since again, dgrid components do not put any
emphasis on index in terms of order of appearance in the component.

On the other hand, when dealing with events on nodes in a list or grid, it is
possible to retrieve the associated item via the `data` property of the object
returned by the `row` or `cell` functions.  These functions can look up based on
a variety of argument types, including a child node of the target row/cell, or
an event object which fired on such a node.

### setStore

Store-backed dgrid components support this via `set("collection", store)`.

### setQuery

Store-backed dgrid components support passing not only a root store, but also a
filtered collection, e.g. `set("collection", store.filter(filterOptions))`.

### setItems

While it is unclear what exact purpose this serves in `dojox/grid/DataGrid`, and
whether or not it is truly intended to be public, it is probably analogous to
calling `renderArray` directly on a dgrid component.  Note, however, that
generally `renderArray` is not expected to be called directly on store-backed
instances.

### filter

This is likely closest in behavior to the `refresh` method on dgrid components.

### sort

dgrid components have a sort setter (e.g. `grid.set("sort", ...)` which takes
two arguments:

* the name of the field to sort by
* optionally, a flag as to whether to sort descending (defaults to `false`)

Like the `sort` method in `dojox/grid` components, this can even be called to
sort columns that ordinarily wouldn't be sortable via the UI.

### canSort

`dojox/grid` components refer to this method when a sort request is initiated
via the UI.  dgrid does not have such a method; instead, it relies on the
`sortable` property of each column definition (which defaults to `true`).

### removeSelectedRows

dgrid has no direct analog to this method, but the same effect can be achieved
on a store-backed, Selection-enabled list or grid instance as follows:

```js
for(var id in grid.selection){
    grid.collection.remove(id);
}
```