docs(grid): default filters in the state (#239)

Author: marin-bratanov

_contentTemplates/grid/state.md

@@ -177,6 +177,240 @@
 #end
 
 
+#filter-menu-default-filters
+>note There are default filters in the grid state for each column. This allows filter menu templates to work seamlessly and with little code. This, however, means that if you want to alter filters for a column, you must either modify the existing one, or remove it. Simply adding a filter will not show up in the UI because the grid will use the first filter for the given field it finds for the filtering UI.
+
+>caption Handling filter changes - unexpected addition that does not update the UI, replacement of one filter, replacecment of all filters
+
+````Component
+@using Telerik.DataSource
+
+To see the full effects of this behavior, filter a column such as the ID being less than or equal to 4.
+<br /> Then, click a button to see the different behavior each will have:
+<ul>
+    <li>
+        the first button will not show the new filter in the Team column header
+        <TelerikButton OnClick="@WrongFilterAdd">Add filter without replace - you will not see the change in the filter UI but the data will change</TelerikButton>
+    </li>
+    <li>
+        the second button will keep the ID column filter and add the Team filter
+        <TelerikButton OnClick="@SetFilterWithReplaceInCollection">Replace only Team filter</TelerikButton>
+    </li>
+    <li>
+        the third button will remove all filters and set only the custom Team filter
+        <TelerikButton OnClick="@SetFilterNewCollection">Replace all filters to filter by Team</TelerikButton>
+    </li>
+</ul>
+
+This flexibility lets you choose what behavior you want from the grid.
+
+
+
+<TelerikGrid Data="@MyData" Height="400px" @ref="@Grid"
+             Pageable="true" Sortable="true"
+             FilterMode="@GridFilterMode.FilterMenu">
+    <GridColumns>
+        <GridColumn Field="@(nameof(SampleData.Id))" Width="120px" />
+        <GridColumn Field="@(nameof(SampleData.Name))" Title="Employee Name" />
+        <GridColumn Field="@(nameof(SampleData.Team))" Title="Team" />
+        <GridColumn Field="@(nameof(SampleData.HireDate))" Title="Hire Date" />
+    </GridColumns>
+</TelerikGrid>
+
+
+
+@code{
+    // adds a filter without affecting the UI
+    async Task WrongFilterAdd()
+    {
+        // get state
+        var state = Grid.GetState();
+
+        // simply add a filter to the existing state and existing (default) filters
+        // PROBLEM - YOU WILL NOT SEE IT HIHGLIGHT THE UI BECAUSE THERE IS A DEFAULT FILTER ALREADY
+
+        state.FilterDescriptors.Add(new CompositeFilterDescriptor()
+        {
+            FilterDescriptors = new FilterDescriptorCollection()
+            {
+                new FilterDescriptor
+                {
+                    Member = "Team",
+                    Operator = FilterOperator.IsEqualTo,
+                    Value = "team 1",
+                    MemberType = typeof(string)
+                },
+                new FilterDescriptor()
+                {
+                    Member = "Team",
+                    Operator = FilterOperator.IsEqualTo,
+                    Value = null,
+                    MemberType = typeof(string)
+                }
+            },
+            LogicalOperator = FilterCompositionLogicalOperator.Or
+        });
+
+        // set state
+        await Grid.SetState(state);
+    }
+
+    // adds a filter
+    async Task SetFilterWithReplaceInCollection()
+    {
+        // get the current state
+        var state = Grid.GetState();
+
+        // remove the current filters for the Team field
+        // if you don't do this, the default or exiting fitlers will command the UI
+        // and you may not see the change from the new filter you will add
+        // see the extension methods related to GetFiltersForMember in the adjacent code tab
+        // create a new collection so we can iterate over it without it getting lost with the removal from the parent collection
+        List<IFilterDescriptor> teamFilters = new List<IFilterDescriptor>(state.FilterDescriptors.GetFiltersForMember("Team"));
+        
+        // remove the existing filters for the Team field from the current collection
+        for (int i = 0; i < teamFilters.Count(); i++)
+        {
+            state.FilterDescriptors.Remove(teamFilters.ElementAt(i) as FilterDescriptorBase);
+        }
+
+        // create the desired new filter for the Team field
+        CompositeFilterDescriptor theFilterDescriptor = new CompositeFilterDescriptor()
+        {
+            FilterDescriptors = new FilterDescriptorCollection()
+            {
+                new FilterDescriptor
+                {
+                    Member = "Team",
+                    Operator = FilterOperator.IsEqualTo,
+                    Value = "team 2",
+                    MemberType = typeof(string)
+                },
+                new FilterDescriptor()
+                {
+                    Member = "Team",
+                    Operator = FilterOperator.IsEqualTo,
+                    Value = null,
+                    MemberType = typeof(string)
+                }
+            },
+            LogicalOperator = FilterCompositionLogicalOperator.Or
+        };
+
+        // add the new filter so that it replaces the original filter(s)
+        state.FilterDescriptors.Add(theFilterDescriptor);
+
+        // set the updated state
+        await Grid.SetState(state);
+    }
+
+    // replaces all filters
+    async Task SetFilterNewCollection()
+    {
+        // get the current state
+        var state = Grid.GetState();
+
+        //replace the entire filters collection so it only has the new desired filter
+        state.FilterDescriptors = new List<FilterDescriptorBase>()
+        {
+            new CompositeFilterDescriptor()
+            {
+                FilterDescriptors = new FilterDescriptorCollection()
+                {
+                    new FilterDescriptor()
+                    {
+                        Member = "Team",
+                        Operator = FilterOperator.Contains,
+                        Value = "3",
+                        MemberType = typeof(string)
+                    },
+                    new FilterDescriptor()
+                    {
+                        Member = "Team",
+                        Operator = FilterOperator.IsEqualTo,
+                        Value = null,
+                        MemberType = typeof(string)
+                    }
+                },
+                LogicalOperator = FilterCompositionLogicalOperator.Or
+            }
+        };
+
+        // set the new state
+        await Grid.SetState(state);
+    }
+}
+
+@code {
+    TelerikGrid<SampleData> Grid { get; set; }
+
+    public IEnumerable<SampleData> MyData = Enumerable.Range(1, 30).Select(x => new SampleData
+    {
+        Id = x,
+        Name = "name " + x,
+        Team = "Team " + x % 5,
+        HireDate = DateTime.Now.AddDays(-x).Date
+    });
+
+    public class SampleData
+    {
+        public int Id { get; set; }
+        public string Name { get; set; }
+        public string Team { get; set; }
+        public DateTime HireDate { get; set; }
+    }
+}
+````
+````Extensions
+using Telerik.DataSource;
+
+//make sure the namespace matches your page, or add an appropriate using
+
+public static class FilterExtensions
+{
+    public static IEnumerable<CompositeFilterDescriptor> GetCompositeFiltersForMember(this IEnumerable<IFilterDescriptor> filtersCollection, string member)
+    {
+        var compositeFilters = filtersCollection.OfType<CompositeFilterDescriptor>();
+        return compositeFilters.GetFiltersForMember(member).Cast<CompositeFilterDescriptor>();
+    }
+
+    public static IEnumerable<IFilterDescriptor> GetAllFiltersForMember(this IEnumerable<IFilterDescriptor> filtersCollection, string member)
+    {
+        return filtersCollection.SelectMemberDescriptors().GetFiltersForMember(member);
+    }
+
+    public static IEnumerable<IFilterDescriptor> GetFiltersForMember(this IEnumerable<IFilterDescriptor> filtersCollection, string member)
+    {
+        return filtersCollection.Where(filter => filter.GetFilterMember() == member) ??
+               Enumerable.Empty<IFilterDescriptor>();
+    }
+
+    public static string GetFilterMember(this IFilterDescriptor filter)
+    {
+        var filterDescriptor = filter;
+        var isFilterDescriptor = filterDescriptor is FilterDescriptor;
+
+        while (!isFilterDescriptor)
+        {
+            var compositeDescriptor = filterDescriptor as CompositeFilterDescriptor;
+
+            if (compositeDescriptor == null)
+            {
+                break;
+            }
+
+            filterDescriptor = compositeDescriptor.FilterDescriptors?.ElementAtOrDefault(0);
+            isFilterDescriptor = filterDescriptor is FilterDescriptor;
+        }
+
+        return ((FilterDescriptor)filterDescriptor)?.Member;
+    }
+}
+````
+#end
+
+
+
 
 #group-from-code
 @using Telerik.DataSource;

components/grid/filter/filter-menu.md

@@ -81,6 +81,7 @@ You can set the grid filters from your code through the grid [state]({%slug grid
 @[template](/_contentTemplates/grid/state.md#filter-menu-from-code)
 ````
 
+@[template](/_contentTemplates/grid/state.md#filter-menu-default-filters)
 
 
 ## See Also

components/grid/state.md

@@ -395,6 +395,9 @@ The grid state allows you to control the behavior of the grid programmatically -
 @[template](/_contentTemplates/grid/state.md#expand-hierarchy-from-code)
 ````
 
+@[template](/_contentTemplates/grid/state.md#filter-menu-default-filters)
+
+
 ### Set Default (Initial) State
 
 If you want the grid to start with certain settings for your end users, you can pre-define them in the `OnStateInit event`.