Jump to main content Jump to doc navigation

MODx.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.

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

  1. MODExt MODx Object
  2. MODExt Tutorials
    1. Ext JS Tutorial - Message Boxes
    2. Ext JS Tutorial - Ajax Include
    3. Ext JS Tutorial - Animation
    4. Ext JS Tutorial - Manipulating Nodes
    5. Ext JS Tutorial - Panels
    6. Ext JS Tutoral - Advanced Grid
    7. Ext JS Tutorial - Inside a CMP
  3. MODx.combo.ComboBox
  4. MODx.Console
  5. MODx.FormPanel
  6. MODx.grid.Grid
  7. MODx.grid.LocalGrid
  8. MODx.msg
  9. MODx.tree.Tree
  10. 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

  • modmore
  • STERC
  • Digital Penguin
  • Jens Wittmann – Gestaltung & Entwicklung
  • CrewMark
  • Fabian Christen
  • Sepia River Studios
  • Dannevang Digital
  • A. Moreno
  • Alex
  • Chris Fickling
  • Stéphane Jäggi
  • YJ
  • Murray Wood
  • JT Skaggs
  • Anton Tarasov
  • deJaya
  • Lefthandmedia
  • eydolan
  • Following Sea
  • Guido Gallenkamp
  • Raffy
  • Snow Creative
  • Nick Clark
  • Guest
  • Helen
  • krisznet
  • Yanni
  • Richard

Budget

$185 per month—let's make that $500!

Learn more