dgrid Documentation

dgrid is a library of widgets for displaying lists of data. Its functionality is organized into several categories:

• Core Components: The fundamental building blocks like List, Grid, GridFromHtml, and OnDemandList/OnDemandGrid for handling large datasets.
• Mixins: Reusable logic that can be added to components to provide specific behaviors, such as Keyboard navigation, Selection (row/cell), Tree structures, and Editor capabilities.
• Extensions: Higher-level features that extend the grid's interface, including ColumnReorder, ColumnResizer, ColumnHider, Pagination, and DnD (Drag and Drop).
• Utilities: Helper functions like touch for mobile support and other miscellaneous utilities.

When using CompoundColumns alongside other dgrid extensions, the order in which you mix them into your class is critical for correct behavior:

1. Before ColumnSet: Mix in CompoundColumns before ColumnSet. This ensures the column structure is normalized before ColumnSet executes its logic.
2. After ColumnResizer and ColumnHider: Mix in CompoundColumns after ColumnResizer and ColumnHider. CompoundColumns extends methods from these extensions to handle its specific spanning header behavior.

The selectionMode property determines how the grid responds to mouse and keyboard interactions. Supported values include:

• extended (default): Allows multiple selection via keyboard modifiers (Shift for ranges, Ctrl/Cmd for multiple separate rows). Clicks without modifiers select only the target.
• multiple: Similar to extended, but clicks/keypresses without modifiers add to the existing selection.
• single: Only one row can be selected at a time.
• toggle: Toggles the selected state of the row (useful for touch).
• none: Disables direct selection via keyboard or mouse, but allows selection via API calls or a Selector column.

When switching from the standard Selection mixin to CellSelection, note the following behavioral and API changes:

• Selection Data Structure: The selection object uses a nested hash. The outer hash is keyed by item ID, and the inner hashes are keyed by column ID.
• Events: The dgrid-select and dgrid-deselect events still fire, but the event object contains a cells property (an array of cell objects) instead of a rows property.
• Lookup Methods: The select, deselect, and isSelected methods use the Grid's cell method for lookups instead of the List's row method.
• Selection Logic: The allowSelect method now receives a cell object as an argument instead of a row object.

Since dgrid does not emphasize row indices, use the row() or cell() methods to retrieve item information. These methods can accept a child node or an event object that fired on a row/cell.

// Example: retrieving data from a click event
grid.on('click', function(evt) {
    var item = grid.row(evt);
    console.log(item.data); // Access the underlying data object
});

If you use custom renderRow or renderCell functions to populate rows or cells with Dijit widget instances, you must manually manage their destruction to prevent memory leaks.

Do not rely solely on the grid's destroy method, as this will not clean up widgets in components like OnDemandList or OnDemandGrid when rows are scrolled out of view. Instead, perform cleanup within the removeRow method. This method is triggered whenever a row is undrawn, including during scroll operations in on-demand components and when the grid itself is destroyed.

removeRow: function (rowElement) {
    // destroy our widget during the row removal operation
    var cellElement = grid.cell(rowElement, column.id).element,
        widget = cellElement.widget;
    if (widget) {
        widget.destroyRecursive();
    }

    this.inherited(arguments);
}

The Grid emits a dgrid-sort event when a header cell is clicked. This event is cancelable and bubbles. If you cancel the event, the sort order will not be applied.

Event Properties:

• grid: The Grid instance.
• parentType: The original event type (click or keydown).
• sort: An array of objects { property, descending? } representing the new sort order.

If you cancel the event to implement custom logic, you must call grid.updateSortArrow(sort) manually to update the UI.

In a column definition, the formatter and renderCell properties control how data is displayed.

• Default Behavior: The default renderCell logic automatically honors any formatter defined on the column.
• Custom Behavior: If you provide a custom renderCell function, it will override the default logic. Consequently, the custom renderCell will take precedence and will not automatically apply the formatter unless you manually invoke it within your custom function.

The Pagination extension retrieves UI strings from dgrid/extensions/nls via the dojo/i18n! plugin. These strings are stored in the i18nPagination property on the grid instance.

To override these strings, the optimal lifecycle points are:

1. Inside postMixInProperties.
2. Inside buildRendering before calling this.inherited(arguments).

dgrid supports RTL rendering by detecting standard document direction settings. It looks for:

• <html dir="rtl">
• <body dir="rtl">
• <body style="direction: rtl">

Important: Setting direction: rtl via a CSS class or external stylesheet on the body will not work; it must be set directly on the style attribute of the body element.