MudDataGrid: FilterTemplate for DataGridFilterMode.Simple

[mmaestro16]

Description

This PR extends Column.FilterTemplate support to DataGridFilterMode.Simple and aligns custom filter actions with the UI surface that owns the filter experience. Additionally includes a Docs rewrite so everything makes sense.

Before this change:

• Column.FilterTemplate worked in ColumnFilterMenu and ColumnFilterRow
• Simple mode always used the built-in editor for each filter row
• custom FilterFunction predicates could remain attached when a Simple filter row was switched to another column

With this change:

• Column.FilterTemplate can now customize individual filter rows in DataGridFilterMode.Simple
• FilterContext.Actions are bound by the active filter UI owner:
  • MudDataGrid in Simple
  • HeaderCell in ColumnFilterMenu
• custom predicates are cleared when a filter row changes columns, preventing stale filtering behavior
• c

Fixes

• Closes MudDataGrid: FilterTemplate does not work in DataGridFilterMode.Simple #7453
• Closes MudDataGrid: FilterTemplate is ignored in DataGridFilterMode.Simple #12130

Changes

Core Implementation

• MudDataGrid.razor
  • renders Column.FilterTemplate inside built-in Simple filter rows
• MudDataGrid.razor.cs
  • creates Simple-mode FilterContext instances with grid-owned actions
  • adds grid-owned apply/clear behavior for Simple filter rows
  • adds CloseFilterUIAsync() for the Simple filter panel
  • clarifies panel-close cleanup behavior
• FilterContext.cs
  • keeps a single FilterContext<T> type
  • allows actions to be rebound internally by the owning UI surface
  • adds FilterActions.CloseFilterUIAsync
• HeaderCell.razor.cs
  • keeps menu-owned filter actions for ColumnFilterMenu
  • adds internal close support for the column filter popover
  • updates active-filter detection so empty value-required filters are not shown as active
• Filter.cs
  • clears FilterDefinition.FilterFunction when a filter row changes columns

Documentation

• DataGridPage.razor
  • restructures filtering docs
  • adds FilterContext<T> and Actions guidance where filter templates are introduced
  • removes duplicated FilterCaseSensitivity explanation
• DataGridFilteringExample.razor
  • refreshes the basic filtering example
• DataGridFilterTemplateSimpleModeExample.razor
  • shows the difference between:
    • column-level FilterTemplate
    • grid-level MudDataGrid.FilterTemplate
  • demonstrates live syncing and explicit close behavior in Simple mode
• DataGridAdvancedFilteringExample.razor
  • demonstrates Column.FilterTemplate in ColumnFilterRow and ColumnFilterMenu

Usage

Column template in Simple mode

<PropertyColumn Property="x => x.Department">
    <FilterTemplate>
        <MudSelect T="string"
                   MultiSelection="true"
                   SelectedValues="@GetFilterValues(context.FilterDefinition!)"
                   SelectedValuesChanged="@(values => SetColumnFilterValues(context, values))">
            @foreach (var department in _departments)
            {
                <MudSelectItem T="string" Value="@department">@department</MudSelectItem>
            }
        </MudSelect>
    </FilterTemplate>
</PropertyColumn>
<!-- SetColumnFilterValues is a method that activates FitlerContext<T>.Actions to ApplyFilters -->

Tests

• adds regression coverage for:
  • Column.FilterTemplate rendering and filtering in Simple
  • stale FilterFunction being cleared when a filter row changes columns
  • FilterContext.Actions apply/clear behavior in Simple
  • FilterContext.Actions.CloseFilterUIAsync() in both Simple and ColumnFilterMenu
  • empty value-required filters not being shown as active

Notes

• FilterContext.Actions now follow the visible filter UI owner instead of always routing through HeaderCell
• MudDataGrid.CloseFilterUIAsync() closes the Simple filter panel and removes incomplete value-required filters
• V10 note to update the FitlerContext actions to not auto close the UI

Screenshots

The SimpleFilterTemplate allows replacing the default text input with custom controls like dropdowns in Simple filter mode, providing a better user experience for fields with predefined values.

Before

After

Checklist:

• I've read the contribution guidelines
• My code follows the style of this project
• I've added or updated relevant unit tests

[versile2]

I've done some cursory looking and have two questions for when I get home tonight.

1. why doesn't the trymud work on your issue example, hard for me to visualize.
2. is this a bug like should FilterTemplate work or do we need a new property. I'm not against adding I the API just want to make sure it's necessary.

[mmaestro16]

I've done some cursory looking and have two questions for when I get home tonight.

1. why doesn't the trymud work on your issue example, hard for me to visualize.

Hard to tell. It works fine in docs solution.

2. is this a bug like should FilterTemplate work or do we need a new property. I'm not against adding I the API just want to make sure it's necessary.

Currently is not possible to have dropdown filter especially not with multiselect values.

What this enables:
Users can now filter by multiple categories simultaneously, which is a common requirement for data grids but currently impossible with the standard API.
The API addition is necessary because without exposing FilterFunction as settable on FilterDefinition, there's no way for developers to implement multi-value filtering logic.
I think this is a great benefit.

[versile2]

I've done some cursory looking and have two questions for when I get home tonight.

1. why doesn't the trymud work on your issue example, hard for me to visualize.

Hard to tell. It works fine in docs solution.

2. is this a bug like should FilterTemplate work or do we need a new property. I'm not against adding I the API just want to make sure it's necessary.

Currently is not possible to have dropdown filter especially not with multiselect values.

What this enables:
Users can now filter by multiple categories simultaneously, which is a common requirement for data grids but currently impossible with the standard API.
The API addition is necessary because without exposing FilterFunction as settable on FilterDefinition, there's no way for developers to implement multi-value filtering logic.
I think this is a great benefit.

Well thank you very much for the work on it I will take a look when I get back home I appreciate it

[ScarletKuro]

why doesn't the trymud work on your issue example, hard for me to visualize.

Hard to tell. It works fine in docs solution.

Are we talking about example from #12130?

I’m not sure why it would be hard to tell, there are specific errors listed. nullable isn’t allowed, and the grid variable is declared but never used because @ref was forgotten. Those should just need to be fixed:
https://try.mudblazor.com/snippet/ckcgYdldkHgkvKIH

[versile2]

First, I need you to fix the try mud example so I can use it as a reference example. Edit the linked issue and make one that works with try mud, compiles, and allows me visibility.

Second, I’m not objecting to adding API surface if it is truly necessary, but I want the necessity explained clearly. We already have FilterTemplate. What concrete capability does SimpleFilterTemplate add that could not be provided by rendering FilterTemplate in DataGridFilterMode.Simple with the existing FilterContext?

Right now the PR proves that simple mode does not render FilterTemplate, but that only shows a gap in the current implementation. It does not yet show that a new public property is required.

If the real requirement is multi-value filtering, then the important question is whether that needs a new template API, or whether simple mode should reuse FilterTemplate and expose the same filter context/actions there as well.

[mmaestro16]

First, I need you to fix the try mud example so I can use it as a reference example. Edit the linked issue and make one that works with try mud, compiles, and allows me visibility.

Second, I’m not objecting to adding API surface if it is truly necessary, but I want the necessity explained clearly. We already have FilterTemplate. What concrete capability does SimpleFilterTemplate add that could not be provided by rendering FilterTemplate in DataGridFilterMode.Simple with the existing FilterContext?

Right now the PR proves that simple mode does not render FilterTemplate, but that only shows a gap in the current implementation. It does not yet show that a new public property is required.

If the real requirement is multi-value filtering, then the important question is whether that needs a new template API, or whether simple mode should reuse FilterTemplate and expose the same filter context/actions there as well.

I dropped everything and implemented with FilterTemplate.

[versile2]

Just note it was a question not a change request direction. It may really need to be done separately. You aren't sure why?

I'm looking through all the code now fyi.

[versile2]

I like the move to reuse FilterTemplate in simple mode instead of adding SimpleFilterTemplate. That feels like the right direction.

My remaining concern is the implementation. The built-in simple rows support multiple filters on the same column independently, but the custom FilterTemplate path looks like it reuses the shared column FilterContext and swaps the FilterDefinition while rendering. I think this needs a per-filter FilterContext in simple mode so custom filters behave the same as the built-in ones.

I’d also want one regression test for that case, and the docs example should be clearer about when it is using custom filter logic versus standard behavior.

Lastly doing it this way gives access to the Apply and Clear actions of FilterTemplate context (HeaderCell) and they should work if you wanted to update the example to use that context action.

[mmaestro16]

Please take a look at the latest changes.

[danielchalmers]

Thank you!