Table of Contents

Filter Builder

TTMSFNCFilterBuilder builds and evaluates complex multi-rule filter expressions. It is the shared filtering engine used by TTMSFNCDataGrid, TTMSFNCDataSetFilterDialog, and other FNC components.

Key class: TTMSFNCFilterBuilder

Tip

Before using TTMSFNCFilterBuilder directly, prefer the built-in filtering UI of controls that integrate it (e.g. TTMSFNCDataGrid's column filter). Direct use is for programmatic filter evaluation or sharing a single filter across multiple components.

Quick Start

Create a local instance or use the global TMSFNCFilterBuilder:

uses
  TMS.TMSFNCFilterBuilder;

var
  fb: TTMSFNCFilterBuilder;
begin
  fb := TTMSFNCFilterBuilder.Create;
  try
    fb.ParseExpression('[Name] LIKE ' + QuotedStr('C%'));
  finally
    fb.Free;
  end;

  // Or use the global instance:
  TMSFNCFilterBuilder.ParseExpression('[Name] LIKE ' + QuotedStr('C%'));
end;

Parsing Filter Text

ParseExpression converts a filter string into structured Groups and Expressions. It returns True on success, or fires parse-error events for malformed input.

Default format (fftDelphiDataSet):

[Name] LIKE 'K*' AND [Status] LIKE 'Abroad') OR ([Name] LIKE 'S%' AND [Progress] > 50) OR [Available] = True

Universal expression format (fftUniversalExpressionFormat):

[Name] = "K*" & [Status] = "Abroad") | ([Name] = "S*" & [Progress] > 50) | [Available] = True

Building Filter Expressions Programmatically

uses
  TMS.TMSFNCFilterBuilder, FMX.TMSFNCValue;

var
  g1, g2: TTMSFNCFilterBuilderGroup;
begin
  TMSFNCFilterBuilder.ClearFilter;
  TMSFNCFilterBuilder.Filter.GroupOperator := fgoOR;

  g1 := TMSFNCFilterBuilder.Filter.AddANDGroup;
  g1.AddExpression('Name', feoStartsWith, 'K');
  g1.AddExpression('Status', feoEqual, 'Abroad');

  g2 := TMSFNCFilterBuilder.Filter.AddANDGroup;
  g2.AddExpression('Name', feoStartsWith, 'S');
  g2.AddExpression('Progress', feoLargerThan, 50);

  TMSFNCFilterBuilder.Filter.AddExpression('Available', feoEqual, True);

  ShowMessage(TMSFNCFilterBuilder.FilterText);
  // ([Name] LIKE 'K%' AND [Status] = Abroad) OR ([Name] LIKE 'S%' AND [Progress] > 50) OR [Available] = True
end;

Validating Data Against a Filter

Single Row

TMSFNCFilterBuilder.DataColumn['Name'].DataType := fdtText;
TMSFNCFilterBuilder.DataColumn['Status'].DataType := fdtText;
TMSFNCFilterBuilder.DataColumn['Progress'].DataType := fdtNumber;
TMSFNCFilterBuilder.DataColumn['Available'].DataType := fdtBoolean;

InputRow := ['Sarah', 'Abroad', 60, False];
if TMSFNCFilterBuilder.ValidateFilterRow(InputRow) then
  ShowMessage('Matches Filter');

Multiple Rows

// Data organized as columns (default, AByRow = False):
InputArray := [
  ['Sarah', 'Sarah', 'Kurt', 'Alex', 'Alex'],
  ['Abroad', 'Abroad', 'Abroad', 'Abroad', 'Abroad'],
  [60, 40, 40, 40, 40],
  [False, False, False, False, True]
];
OutputArray := TMSFNCFilterBuilder.ValidateFilterArray(InputArray, False);

// Data organized as rows (AByRow = True):
InputArray := [
  ['Sarah', 'Abroad', 60, False],
  ['Kurt', 'Abroad', 40, False],
  ['Alex', 'Abroad', 40, True]
];
OutputArray := TMSFNCFilterBuilder.ValidateFilterArray(InputArray, True);
// [True, False, True, False, True]

Properties

Property Description
DataColumn['Name'] Returns (or creates) a column by name
DataColumnDisplayName['Name'] User-friendly display name for a column
DataColumnType['Name'] Data type of the column
ParseFormat Format settings for parsing filter text
FilterText Raw filter expression text
DisplayFilterText FilterText with column display names substituted
Filter Root TTMSFNCFilterBuilderGroup of the filter structure
DataColumns Collection of all defined columns
FormatType Output format type (default: fftDelphiDataSet)

Methods

Method Description
ParseExpression(AFilterText) Parse text into groups/expressions
ClearFilter Reset all groups and expressions
ValidateFilterRow(AInputData) Validate one row
ValidateFilterArray(AInputArray, AByRow) Validate multiple rows
AddDataColumn(AName, ADataType, ADisplayName) Add a column definition
GetFilterText Generate filter text from current groups/expressions
DeleteGroup(AGroup) / DeleteExpression(AExpression) Remove a group or expression

Events

Event Description
OnParseError General parse error
OnParseErrorParenthesis Mismatched parentheses
OnParseErrorOperatorMismatch Operator mismatch within a group
OnParseErrorOperatorPosition Operator in wrong position
OnParseErrorInvalidExpression Invalid expression syntax
OnFilterTextParsed Full filter text successfully parsed
OnExpressionTextParsed Single expression successfully parsed
OnValidateFilter / OnValidateGroup / OnValidateExpression Custom validation hooks
OnGetFilterText / OnGetGroupText / OnGetExpressionText Customize text generation
OnExpressionAdded A new expression was added

TTMSFNCFilterBuilderColumn

Property Description
Name Internal column name used in filter expressions
DisplayName User-visible name shown in the UI
DataType fdtText, fdtNumber, fdtBoolean, fdtDate, fdtAutomatic

TTMSFNCFilterBuilderGroup

Groups combine expressions using AND or OR. The Filter property of TTMSFNCFilterBuilder is the root group.

Property Description
GroupOperator fgoAND or fgoOR
Groups Nested subgroups
Expressions Filter expressions in this group
FilterText Textual representation of this group

TTMSFNCFilterBuilderExpression

Property Description
Column The column being tested
ExpressionOperator feoEqual, feoContains, feoStartsWith, feoLargerThan, feoNotEmpty, etc.
Value The comparison value
IsInverted Invert the condition (e.g. "not contains")
CaseSensitive Case-sensitive text comparison (default: False)

Parse Format Reference

Property Delphi DataSet Universal Expression
StringDelimiter ' "
AndOperator AND &
OrOperator OR \|
EqualStrOperator LIKE '#VALUE' = "#VALUE"
ContainsOperator LIKE '%#VALUE%' = "*#VALUE*"
StartsWithOperator LIKE '#VALUE%' = "#VALUE*"
MultiCharWildCard % *

Set FormatType to fftDelphiDataSet (default) or fftUniversalExpressionFormat, or configure ParseFormat properties individually.

See Also