AyCode.Blazor/AyCode.Blazor.Components/docs/MGGRID/MGGRID_PARAMETERS.md

MgGrid — Parameters & Events

Part of the MgGrid system. See README.md for overview and component hierarchy.

Required Parameters

Parameter	Type	Description
SignalRClient	AcSignalRClientBase	SignalR client for server communication
Logger	TLoggerClient	Logger instance
GetAllMessageTag	int	SignalR tag for loading all items

CRUD Message Tags

Parameter	Type	Description
GetAllMessageTag	int	Tag for "get all items" request
GetItemMessageTag	int	Tag for "get single item" request
AddMessageTag	int	Tag for "add item" request
UpdateMessageTag	int	Tag for "update item" request
RemoveMessageTag	int	Tag for "remove item" request

These are bundled into a SignalRCrudTags during OnInitializedAsync. See AyCode.Services/docs/SIGNALR_DATASOURCE/README.md (in AyCode.Core repo) for details.

Data & Context Parameters

Parameter	Type	Description
DataSource	IList<TDataItem>	Bind with AcObservableCollection<TDataItem> for external data. If not set, grid creates its own.
ParentDataItem	IId<TId>?	Parent entity for detail grids. null = master grid.
KeyFieldNameToParentId	string?	Property name on TDataItem that references the parent's ID
ContextIds	object[]?	Additional context passed to AcSignalRDataSource constructor
CustomFilterCriteria	string?	Consumer-supplied base filter criteria (a DevExpress criteria string) — propagated to the data source, triggers reload; server parses + whitelists it. AND-merged with the grid's automatic FilterCriteria (ADR-0004 unified model). Renamed FilterText → CustomFilterText → CustomFilterCriteria (2026-07-16).

Display & Behavior Parameters

Parameter	Type	Default	Description
Caption	string	typeof(TDataItem).Name	Grid title (shown in fullscreen header)
GridName	string	"{TDataItem.Name}Grid"	Name used in log messages
AutoSaveLayoutName	string?	"Grid{TDataItem.Name}"	Base name for layout storage keys
EnableServerLayouts	bool	true	Roams the UserSave layout tier via the SignalR server endpoint (see MGGRID_LAYOUT.md → Server Roaming). Server calls happen only on the Save/Load layout buttons.

Quick-Filter Panel

Parameter	Type	Default	Description
FilterPanel	RenderFragment?	null	Quick-filter controls rendered below the toolbar (composed into the grid's ToolbarTemplate); the slot wraps them in a styled .mg-grid-filter-panel container. When set, the toolbar shows a Show/Hide Filters toggle (MGGRID_TOOLBAR.md).
ShowFilterPanel	bool	true	Initial visibility of the filter panel; the toolbar toggle flips it at runtime (IsFilterPanelVisible / ToggleFilterPanel).

Place MgTagBox controls (from Components/) in the slot. Each control applies a per-field IN(FieldName, selected...) criteria via IMgGridBase.SetFieldQuickFilter → DevExpress SetFieldFilterCriteria; DevExpress AND-combines the per-field criteria with each other and with the user's filter row automatically (no clobber). Empty selection clears that field's filter. Several controls in one panel therefore narrow the grid cumulatively (field A and field B).

<FilterPanel>
    <MgTagBox TData="string" TValue="string" FieldName="Status"
              Data="@_statusOptions" NullText="All statuses" />
</FilterPanel>

Lookup (foreign-key) columns. When the target column holds an ID (e.g. PartnerId) but users pick by name, bind the tag box to the lookup objects and let ValueFieldName supply the IDs. FieldName still names the grid column, so the emitted IN(PartnerId, 3, 7) matches the underlying data field — not the cell's display template:

<FilterPanel>
    <MgTagBox TData="Partner" TValue="int" FieldName="PartnerId"
              Data="@Partners" ValueFieldName="Id" TextFieldName="Name"
              NullText="All partners" />
</FilterPanel>

A nullable FK column (int?) behaves the same — rows whose value is null match no selection.

Sizing. MgTagBox defaults its SizeMode to the grid's (IMgGridBase.GridSizeMode) when the consumer leaves it unset, so the panel matches the grid's density with no per-control declaration. An explicit SizeMode on the control always wins.

Layout. The panel is a flex row: controls sit side by side sharing the width and wrap to the next line only when they no longer fit (.mg-grid-filter-panel > * — flex / min-width / max-width in mg-grid-info-panel.css; tune there for a different density). It is styled to read as its own band between the toolbar and the group panel, aligned with the native group panel via the grid's own SizeMode-adaptive tokens (--dxbl-grid-group-panel-container-padding-*). Since it is composed into the ToolbarTemplate it physically lives inside .dxbl-grid-toolbar-container; that container's padding is zeroed (:has(.mg-grid-toolbar-with-filter)) and each row supplies its own: the toolbar row (.mg-grid-toolbar-row) reuses the container's native padding tokens, the band reuses the group panel's. Separator above = the band's border-top; below = the container's native border-bottom. A consumer .hide-toolbar class (detail grids) therefore hides the panel together with the toolbar.

Implementation note: imperative parameter writes inside DevExpress editors (Values, SizeMode) must be wrapped in BeginUpdate()/EndUpdate() (the parameter tracker throws otherwise) — MgTagBox handles this internally.

Design + the server-side forward path (FilterMode.Server): AyCode.Core repo docs/adr/0004-signalr-datasource-server-side-filtering.md.

Event Callbacks

All grid events are re-exposed with OnGrid prefix to avoid collisions with DxGrid base events:

Event	DxGrid Equivalent	When Fired
OnGridItemDeleting	DataItemDeleting	Before item removal (can cancel via e.Cancel)
OnGridEditModelSaving	EditModelSaving	Before item save (can cancel via e.Cancel)
OnGridEditStart	EditStart	When edit mode begins
OnGridCustomizeEditModel	CustomizeEditModel	When edit model is being prepared
OnGridFocusedRowChanged	FocusedRowChanged	When focused row changes
OnDataSourceChanged	—	After data source is loaded/reloaded
OnGridItemChanged	—	After server confirms a CRUD operation
OnGridItemChanging	—	Before a CRUD operation is sent to server

Internal event wiring (in SetParametersAsyncCore, first call):

DxGrid Event	→ Internal Handler
DataItemDeleting	OnItemDeleting
EditModelSaving	OnItemSaving
CustomizeEditModel	OnCustomizeEditModel
FocusedRowChanged	OnFocusedRowChanged
EditStart	OnEditStart
EditCanceling	OnEditCanceling

Default Grid Settings

Set in SetParametersAsyncCore (first call only):

Setting	Value
KeyFieldName	"Id"
TextWrapEnabled	false
AllowSelectRowByClick	true
HighlightRowOnHover	true
AutoCollapseDetailRow	true
AutoExpandAllGroupRows	false

Project adapters typically add more defaults in OnParametersSet (e.g., EditMode, FocusedRowEnabled, PageSize, ShowFilterRow, SizeMode based on IsMasterGrid).