@memberjunction/ng-filter-builder

A modern, intuitive Angular filter builder component for creating complex boolean filter expressions. Outputs portable, Kendo-compatible CompositeFilterDescriptor JSON for seamless integration with MemberJunction views and grids.

Installation

npm install @memberjunction/ng-filter-builder

Overview

The Filter Builder provides a visual interface for constructing nested AND/OR filter expressions against entity fields. It supports multiple field types (string, number, boolean, date, lookup), nested groups up to a configurable depth, and generates a human-readable summary of the active filter.

graph TD
    A["FilterBuilderComponent"] --> B["FilterGroupComponent"]
    B --> C["FilterRuleComponent"]
    B --> D["FilterRuleComponent"]
    B --> E["Nested FilterGroupComponent"]
    E --> F["FilterRuleComponent"]
    A --> G["CompositeFilterDescriptor JSON"]

    style A fill:#2d6a9f,stroke:#1a4971,color:#fff
    style B fill:#7c5295,stroke:#563a6b,color:#fff
    style C fill:#2d8659,stroke:#1a5c3a,color:#fff
    style D fill:#2d8659,stroke:#1a5c3a,color:#fff
    style E fill:#7c5295,stroke:#563a6b,color:#fff
    style F fill:#2d8659,stroke:#1a5c3a,color:#fff
    style G fill:#b8762f,stroke:#8a5722,color:#fff

Usage

Module Import

import { FilterBuilderModule } from '@memberjunction/ng-filter-builder';

@NgModule({
  imports: [FilterBuilderModule]
})
export class YourModule {}

Basic Usage

<mj-filter-builder
  [fields]="filterFields"
  [filter]="currentFilter"
  (filterChange)="onFilterChange($event)">
</mj-filter-builder>

Defining Fields

import { FilterFieldInfo } from '@memberjunction/ng-filter-builder';

filterFields: FilterFieldInfo[] = [
  { name: 'Name', displayName: 'Name', type: 'string' },
  { name: 'Age', displayName: 'Age', type: 'number' },
  { name: 'IsActive', displayName: 'Active', type: 'boolean' },
  { name: 'CreatedAt', displayName: 'Created Date', type: 'date' },
  { name: 'CategoryID', displayName: 'Category', type: 'lookup', lookupEntityName: 'Categories' }
];

Configuration Options

<mj-filter-builder
  [fields]="filterFields"
  [config]="{
    maxDepth: 3,
    allowGroups: true,
    showClearButton: true,
    showApplyButton: false,
    applyOnChange: true
  }"
  [showSummary]="true"
  [disabled]="false"
  (filterChange)="onFilterChange($event)"
  (apply)="onApply($event)"
  (clear)="onClear()">
</mj-filter-builder>

Components

| Component | Selector | Purpose | |-----------|----------|---------| | FilterBuilderComponent | mj-filter-builder | Top-level container with config, summary, and clear/apply buttons | | FilterGroupComponent | internal | Renders a group of rules combined by AND/OR logic | | FilterRuleComponent | internal | Renders a single filter rule (field, operator, value) |

Supported Operators by Field Type

| Type | Operators | |------|-----------| | String | contains, does not contain, equals, not equals, starts with, ends with, is empty, is not empty | | Number | equals, not equals, greater than, greater/equal, less than, less/equal, is empty, is not empty | | Boolean | is, is not, is empty, is not empty | | Date | equals, not equals, is after, is on or after, is before, is on or before, is empty, is not empty | | Lookup | equals, not equals, contains, does not contain, starts with, ends with, is empty, is not empty |

Exported Types

• FilterOperator -- Union type of all operator strings
• FilterLogic -- 'and' | 'or'
• FilterDescriptor -- Single filter condition
• CompositeFilterDescriptor -- Group of filters with AND/OR logic
• FilterFieldInfo -- Field metadata for the builder
• FilterBuilderConfig -- Configuration options
• FilterValueOption -- Value option for dropdown fields

Utility Functions

• createEmptyFilter() -- Creates a new empty CompositeFilterDescriptor
• createFilterRule(field, type) -- Creates a new filter rule with defaults
• isCompositeFilter(filter) -- Type guard for composite filters
• isSimpleFilter(filter) -- Type guard for simple filter descriptors
• getOperatorsForType(type) -- Returns available operators for a field type
• operatorRequiresValue(operator) -- Checks if an operator needs a value input