MODx.grid.Grid
Last updated Oct 11th, 2026 | Page history | Improve this page | Report an issue
Support the team building MODX with a monthly donation.
The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.
Backers
Budget
$185 per month—let's make that $500!
Learn moreMODx.grid.Grid¶
Extends: Ext.grid.EditorGridPanel Key Features: Connector functionality; easily integrate toolbar items and MODx.Window; built-in context menu functionality.
When instantiating this into a tabbed interface, it’s recommended to set preventRender: true in its config to prevent JS rendering issues.

MODExt Grids display tabular data with a ColumnModel, top toolbar (tbar), bottom toolbar (bbar) and paging. Data loads remotely from a connector request returning JSON.
A right-click context menu per row comes from a “menu” key in each data row of your processor:
foreach( $items as $item ) {
$data[] = array(
'id' => $obj->get( 'id' ),
'name' => $obj->get( 'name' ),
'menu' => array(
array(
'text' => $modx->lexicon( 'my_lexicon' ),
'handler' => 'this.myHandler'
)
)
);
}
Each item gets a context menu entry with the text from lexicon key my_lexicon and the handler myHandler, registered on your Grid object.
Menus can also (and preferably) be created by extending the JS Grid and adding a “getMenu” method:
getMenu: function() {
var m = [];
m.push({
text: _('my_lexicon_key')
,handler: this.myHandler
});
return m;
}
Returning an array of items from getMenu adds them to the context menu.
Revolution 2.0.x grids cannot return the array — they must call this.addContextMenuItem(m); before the end of the function. Returning the array was added in 2.1.
MODExt-Specific Parameters¶
The grid loads its data from the “url” config parameter, with baseParams that default to:
baseParams: { action: 'getList' }
Override baseParams in your config. The grid adds parameters not found in typical Ext.grid.Grid objects:
| Name | Description | Default |
|---|---|---|
| url | The URL of the connector to load this grid from. | |
| paging | If true, will enable paging and add the PagingToolbar automatically to the bottom of the grid. | false (set automatically when a bbar is passed) |
| pageSize | The number of items to page by, if paging == true. Defaults to the System Setting of “default_per_page”, which is 20. | 20 |
| pageStart | The index to start the paging on. | 0 |
| showPerPage | Whether or not to show the “Per Page” textbox. Defaults to true. | true |
| pagingItems | Any items to add to the right of the “Per Page” textbox on the paging toolbar. Useful for adding extra buttons. | [] |
| grouping | If true, will automatically enable grouping on this grid. | false |
| groupBy | The column to group by. Note that the column must be in the column model. | name |
| pluralText | The text for a plural amount of items in the grouped column, ie: “Rows” | Records |
| singleText | The text for a single amount of items in the grouped column, ie: “Row” | Record |
| sortBy | The default column to sort by when grouping and remoteSort are true. | id |
| sortDir | The default direction to sort by when grouping and remoteSort are true. | ASC |
| preventRender | Prevent the grid from rendering. Useful when putting the grid in panels or tabs. | 1 |
| autosave | If true, will automatically fire the ‘updateFromGrid’ processor (or the processor in the saveUrl config param) for this connector when doing in-line editing in the grid. | false |
| saveUrl | The connector URL to call when inline-editing with autosave on. | The value of config.url |
| save_action | The processor action to call when inline-editing with autosave on. | updateFromGrid |
| saveParams | A JS object of parameters to also send to the saveUrl when auto-saving or when using MODx.grid.Grid’s remove method. | {} |
| save_callback | After auto-saving, run this method. | null |
| preventSaveRefresh | If autosave is true, after saving, will prevent the grid from refreshing. Makes for a more seamless editing experience. | 1 |
| primaryKey | If your grid items have a primary key that’s not ID, set it here. | id |
| storeId | A custom ID to give the store for this grid. Will default to a unique Ext ID. | Ext.id() |
| showActionsColumn | If true, append an actions column (modx-actions) with icon buttons. Added in MODX 3.0. |
true |
| actionsColumnWidth | Width of the actions column. Auto: 50 for pixel column models, 0.1 when all column widths are ≤ 1. |
auto |
| disableContextMenuAction | If true, omit the default gear icon that opens the row context menu, and suppress that actions menu path. | false |
For a complete list of all parameters not listed here for grids, see the ExtJS documentation.
Actions column (MODX 3.0+)¶
MODx.grid.Grid and MODx.grid.LocalGrid share MODx.grid.GridBase. When showActionsColumn is true, MODX adds a fixed column whose renderer calls getActions().
Override getActions to return extra icon buttons. Each item needs action, icon, and text. A click looks for a method named after action (or Capitalized action) on the grid.
getActions: function(value, metaData, record, rowIndex, colIndex, store) {
return [{
action: 'removeElement',
icon: 'trash-o',
text: _('delete')
}];
}
Unless disableContextMenuAction is true, MODX also appends a gear action that opens the same menu as a right-click (getMenu / processor menu data).
Turn the whole column off:
Ext.applyIf(config, {
showActionsColumn: false
});
Editable column hover (MODX 3.0+)¶
Columns that define an editor automatically receive the CSS class x-editable-column through renderEditableColumn. The manager theme shows a hover cue (pen icon). There is no separate config flag: add an editor when the cell is inline-editable.
Column links (MODX 3.0+)¶
Use renderLink(content, attributes, isSimulated, isSimulatedTag) in a column renderer to wrap values in an <a class="x-grid-link"> (or a simulated span link).
renderer: {
fn: function(value, metaData, record) {
return this.renderLink(value, {
href: '?a=context/update&key=' + record.data.key,
title: _('edit')
});
},
scope: this
}
Related helper: getLinkTemplate(controllerPath, displayValueIndex, options) for xtype: 'templatecolumn' layouts.
Custom Events¶
MODx.grid.Grid adds a few extra events not found in Ext.grid.Grid objects:
| Name | Description |
|---|---|
| beforeRemoveRow | Fires before a row is removed when calling the remove() method on the grid (usually done in a context menu) |
| afterRemoveRow | Fires after a row is removed when calling the remove() method on the grid (usually done in a context menu) |
| afterAutoSave | Fires after an inline-edit save is done, if autosave is set to true. |
Other Unique Functions¶
Custom Store Exception Messages¶
Store load exceptions are handled by onStoreException: the message is wrapped in an error-with-icon block shown above the grid. In debug mode (MODx.config.debug > 0) the raw message is also placed into the grid’s emptyText; with debug off the details are only logged. A common usage is to use $modx->error->failure(‘Message here’) in your processors.
loadWindow¶
Loads and shows a window of any given xtype:
grid.loadWindow({
xtype: 'my-xtype-for-the-window'
,blankValues: true /* blanks the values of the window, good for New Object windows, set false for Update windows */
});
If blankValues is not true, the currently selected row’s data is passed into the Window and set in the form (assuming your window extends MODx.Window.)
remove¶
remove() sends an AJAX request to the connector in config.url with the action “remove” and the ID (or primaryKey) of the selected row — useful for context menus.
The one parameter, text, is the confirm-dialog message shown before the row is removed. The beforeRemoveRow event fires before the confirm dialog loads:
grid.remove("Are you sure you want to remove this Item?");
confirm¶
Shows a confirmation dialog before executing an action:
grid.confirm("approve","Are you sure you want to approve this article?");
Like remove, it sends the ID/primaryKey of the selected row to the processor action in the first parameter, then refreshes the grid.
refresh¶
Refreshes the grid.
encodeModified¶
Returns a JSON object of all modified (dirty) rows and fields. Useful when autosave is off.
encode¶
Returns a JSON object of all rows.
removeActiveRow¶
Removes the currently selected row from the grid’s store and view without firing a connector request — useful after a successful remove call you handled yourself. Note: the record argument is currently ignored; the method always removes the selected row (#17050):
grid.removeActiveRow(record);
Row expander helpers¶
Grids using a row-expander plugin can toggle all rows with expandAll() / collapseAll(); findExpanderPlugin() locates the expander plugin instance on the grid.
Permission-aware cells¶
setEditableCellClasses(), userCanEditRecord(record) and userHasRecordPermissions(record) decide whether a record/cell is editable for the current user, based on record permissions returned by your processor.
See Also¶
- MODExt MODx Object
- MODExt Tutorials
- MODx.combo.ComboBox
- MODx.Console
- MODx.FormPanel
- MODx.grid.Grid
- MODx.grid.LocalGrid
- MODx.msg
- MODx.tree.Tree
- MODx.Window
Support the team building MODX with a monthly donation.
The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.
Backers
Budget
$185 per month—let's make that $500!
Learn more










