ngx-column-filter-popup 1.0.2 → 1.0.4

package/DOCUMENTATION.md

@@ -24,11 +24,12 @@ This is a **reusable Angular column filter component** that provides advanced fi
    - **Match All Rules** (AND Logic): When multiple rules exist, **all rules** must match
    - **Match Any Rule** (OR Logic): When multiple rules exist, **any one rule** can match (Default)
 
-5. **Visual Feedback**: Filter icon changes when active
-6. **Fully Customizable**: Easily configure according to your data
-7. **Single Filter Open**: Only one filter dropdown can be open at a time
-8. **ESC Key Support**: Press ESC to close the open filter
-9. **Programmatic Control**: Clear filters programmatically using `clearFilter()` method
+5. **Visual Feedback**: Blinking red filter icon with X mark when active - smooth animation clearly indicates applied filters
+6. **Backend Mode**: Send filter payloads directly to your backend API instead of filtering locally
+7. **Fully Customizable**: Easily configure according to your data
+8. **Single Filter Open**: Only one filter dropdown can be open at a time
+9. **ESC Key Support**: Press ESC to close the open filter
+10. **Programmatic Control**: Clear filters programmatically using `clearFilter()` method
 
 ---
 
@@ -608,6 +609,178 @@ const matches = itemMatchesFilter(
 
 ---
 
+## Backend Mode (Backend API Integration)
+
+### What is Backend Mode?
+
+When `backendMode` is enabled, the component **does not apply any frontend filtering**. Instead, it collects all filter values and emits them as a structured payload ready to be sent to your backend API.
+
+### When to Use Backend Mode:
+
+- ✅ When you have large datasets and want server-side filtering
+- ✅ When your filtering logic is complex and handled by backend
+- ✅ When you need to send filter parameters to a REST API
+- ✅ When combining frontend filters (some columns) with backend filters (other columns)
+
+### How to Use Backend Mode:
+
+**1. Enable backend mode on specific columns:**
+
+```html
+<lib-column-filter
+  columnName="first name"
+  columnKey="firstName"
+  [backendMode]="true"
+  (filterApplied)="onFilterApplied('firstName', $event)"
+  (filterCleared)="onFilterCleared('firstName')">
+</lib-column-filter>
+
+<lib-column-filter
+  columnName="email"
+  columnKey="email"
+  [backendMode]="true"
+  (filterApplied)="onFilterApplied('email', $event)"
+  (filterCleared)="onFilterCleared('email')">
+</lib-column-filter>
+```
+
+**2. Use generic handlers with Map-based storage:**
+
+```typescript
+import { Component } from '@angular/core';
+import { ColumnFilterComponent } from 'ngx-column-filter-popup';
+import { FilterConfig } from 'ngx-column-filter-popup';
+
+@Component({
+  selector: 'app-example',
+  imports: [ColumnFilterComponent],
+  template: `<!-- HTML from above -->`
+})
+export class ExampleComponent {
+  // Unified filter storage
+  filters = new Map<string, FilterConfig | null>();
+
+  // Configuration: Which columns use backend mode
+  readonly backendModeColumns = new Set<string>(['firstName', 'email']);
+
+  // Generic filter handler
+  onFilterApplied(columnKey: string, filterConfig: FilterConfig) {
+    this.filters.set(columnKey, filterConfig);
+    
+    if (this.isBackendMode(columnKey)) {
+      this.sendAllBackendFiltersToBackend();
+    }
+  }
+
+  onFilterCleared(columnKey: string) {
+    this.filters.set(columnKey, null);
+    
+    if (this.isBackendMode(columnKey)) {
+      this.sendAllBackendFiltersToBackend();
+    }
+  }
+
+  isBackendMode(columnKey: string): boolean {
+    return this.backendModeColumns.has(columnKey);
+  }
+
+  private sendAllBackendFiltersToBackend() {
+    const activeFilters: Array<{
+      field: string;
+      matchType: string;
+      value: string;
+      fieldType: string;
+    }> = [];
+
+    // Collect all active backend filters
+    this.backendModeColumns.forEach(columnKey => {
+      const filterConfig = this.filters.get(columnKey);
+      if (filterConfig && filterConfig.rules.length > 0) {
+        filterConfig.rules.forEach(rule => {
+          if (rule.value && rule.value.trim() !== '') {
+            activeFilters.push({
+              field: columnKey,
+              matchType: rule.matchType,
+              value: rule.value.trim(),
+              fieldType: filterConfig.fieldType || 'text'
+            });
+          }
+        });
+      }
+    });
+
+    const payload = {
+      activeFilters: activeFilters,
+      count: activeFilters.length
+    };
+
+    // Send to your backend API
+    // this.httpClient.post('/api/filters', payload).subscribe({
+    //   next: (response) => {
+    //     this.filteredData = response.data;
+    //   }
+    // });
+    
+    console.log('Backend payload:', payload);
+  }
+}
+```
+
+### Backend Payload Format:
+
+The component emits filter data in this format:
+
+```json
+{
+  "activeFilters": [
+    {
+      "field": "firstName",
+      "matchType": "contains",
+      "value": "John",
+      "fieldType": "text"
+    },
+    {
+      "field": "email",
+      "matchType": "contains",
+      "value": "example",
+      "fieldType": "text"
+    }
+  ],
+  "count": 2
+}
+```
+
+### Mixed Mode (Frontend + Backend):
+
+You can use both frontend and backend filters together:
+
+```typescript
+// Some columns use frontend filtering
+<lib-column-filter columnKey="lastName" [backendMode]="false" ...>
+
+// Other columns use backend filtering
+<lib-column-filter columnKey="firstName" [backendMode]="true" ...>
+```
+
+In `applyAllFilters()`, skip backend mode columns:
+
+```typescript
+private applyAllFilters() {
+  let result = [...this.originalData];
+
+  this.filters.forEach((filterConfig, columnKey) => {
+    // Skip backend mode columns (handled by backend)
+    if (filterConfig && !this.isBackendMode(columnKey)) {
+      result = applyColumnFilter(result, columnKey, filterConfig);
+    }
+  });
+
+  this.filteredData = result;
+}
+```
+
+---
+
 ## Programmatic Control
 
 ### Clearing Filters Programmatically
@@ -680,6 +853,8 @@ export class ExampleComponent {
 ✅ **What it does**: Provides advanced column filtering for tables/lists  
 ✅ **Data adaptation**: Simply update `columnKey` and `columnName` in HTML  
 ✅ **Match All Rules**: Feature to combine multiple rules with AND/OR logic  
+✅ **Backend Mode**: Send filter payloads directly to backend API  
+✅ **Visual Feedback**: Blinking red icon clearly indicates active filters  
 ✅ **Easy to Use**: Simple API, fully customizable  
 ✅ **Multiple Field Types**: Support for text, currency, age, date, and status fields  
 ✅ **Programmatic Control**: Clear filters programmatically