Upsert Helpers

The upsert helpers turn the most common rules into a single call. Instead of adding a rule, setting FilterText, and attaching a visibility or enable action, ShowWhere, HideWhere, EnableWhere, and DisableWhere build the whole rule for you and apply it immediately. They are upserts: each is keyed by source, items-path, and target property, so calling the same helper again updates the existing rule in place rather than stacking duplicates. Reach for these for one-condition (or two-condition) visibility and enable filters; drop down to Rules and actions when you need several actions or custom values. This guide covers the four helpers, their single- and two-condition forms, the expression shortcuts, and the AApply flag.

Show, hide, enable, and disable

Each helper writes one well-known property based on the match:

Helper	On match	On no-match / inactive
`ShowWhere`	`Visible := True`	`Visible := False`
`HideWhere`	`Visible := False`	`Visible := True`
`EnableWhere`	`Enabled := True`	`Enabled := False`
`DisableWhere`	`Enabled := False`	`Enabled := True`

You pass the source, the items-path, the field, a TTMSFNCFilterBuilderExpressionOperator (feoStartsWith, feoEqual, feoContains, …), and the comparison value:

uses
  TMS.TMSFNCFilterRulesManager, TMS.TMSFNCFilterBuilder, System.Rtti;

{ Inside a method of your form: }
begin
  // Each helper upserts a rule keyed by source + items-path + target, and
  // applies immediately because AApply defaults to True here.
  FilterRulesManager1.ShowWhere(Planner1, 'Items[*]', 'Text',
    feoStartsWith, TValue.From<string>('B'));

  FilterRulesManager1.HideWhere(Planner1, 'Items[*]', 'Archived',
    feoEqual, TValue.From<Boolean>(True));

  FilterRulesManager1.EnableWhere(Planner1, 'Items[*]', 'Editable',
    feoEqual, TValue.From<Boolean>(True));

  FilterRulesManager1.DisableWhere(Planner1, 'Items[*]', 'Locked',
    feoEqual, TValue.From<Boolean>(True));
end;

Single- and two-condition variants

Each helper has overloads for one or two conditions, with optional explicit field types. The two-condition form inserts a TTMSFNCFilterBuilderGroupOperator (fgoAND or fgoOR) between the two field/operator/value triples. Overloads that omit the items-path evaluate the field on Source directly.

Expression shortcuts

When you want a named rule but not the full FilterText syntax, AddRuleEquals, AddRuleContains, AddRuleStartsWith, and AddRuleEndsWith generate the expression from the operator implied by their name. Unlike the Where helpers, these do not apply by default (AApply is False) and do not attach an action — you add an action and call Apply yourself:

uses
  TMS.TMSFNCFilterRulesManager, System.Rtti;

{ Inside a method of your form: }
begin
  // These shortcuts build the expression for you. Unlike the Where helpers,
  // AApply defaults to False, so nothing is written until you call Apply.
  FilterRulesManager1.AddRuleEquals('Open', Planner1, 'Items[*]', 'Status',
    TValue.From<string>('Open'));
  FilterRulesManager1.AddRuleContains('HasNote', Planner1, 'Items[*]', 'Notes', 'urgent');
  FilterRulesManager1.AddRuleStartsWith('CodeA', Planner1, 'Items[*]', 'Code', 'A');
  FilterRulesManager1.AddRuleEndsWith('Draft', Planner1, 'Items[*]', 'Name', '(draft)');

  // Each rule still needs an action; add one before applying, e.g.:
  FilterRulesManager1.Rules[0].AddVisibilityAction(True);

  FilterRulesManager1.Apply;   // required: the shortcuts do not auto-apply
end;

The AApply flag

Every helper ends with an AApply parameter controlling whether the manager applies right away:

ShowWhere/HideWhere/EnableWhere/DisableWhere default AApply to True — one call configures and applies.
AddRuleEquals/AddRuleContains/AddRuleStartsWith/AddRuleEndsWith default AApply to False.

When you set up several rules at once, pass AApply := False to all but the last (or call Apply once at the end) so the items are not re-evaluated after every helper.

Combining helpers

The helpers compose because each upserts under its own key. Here a grouped, two-condition ShowWhere and an EnableWhere are configured with AApply := False and applied together in one pass:

uses
  TMS.TMSFNCFilterRulesManager, TMS.TMSFNCFilterBuilder, System.Rtti;

{ Inside a method of your form. Defer applying until both rules are set up. }
begin
  // Two conditions joined with AND; pass AApply = False so the first call
  // does not apply before the second rule exists.
  FilterRulesManager1.ShowWhere(Planner1, 'Items[*]',
    'Priority', feoEqual, TValue.From<string>('High'),
    fgoAND,
    'Done', feoEqual, TValue.From<Boolean>(False),
    False);

  // A second helper targets a different property; both rules coexist because
  // they upsert under different target keys.
  FilterRulesManager1.EnableWhere(Planner1, 'Items[*]',
    'Editable', feoEqual, TValue.From<Boolean>(True), False);

  FilterRulesManager1.Apply;   // evaluate both rules together
end;

Common pitfalls

Shortcuts don't auto-apply. AddRule* leaves AApply False and adds no action — attach an action and call Apply, or nothing happens.
Re-calling a helper updates, it does not duplicate. Same source + path + target = the same rule. To run two independent filters on one property, that is a single rule with combined conditions, not two helper calls.
Avoid applying after every call. Leaving AApply True while adding many rules re-evaluates all items each time; batch with AApply := False and a final Apply.
Match the operator to the value type. feoStartsWith/feoContains are text operators; numeric comparisons use feoLargerThan and friends.

Table of Contents