Concepts

Core Concepts

Core Concepts

Match Criteria & Filtering

After a location strategy finds candidate elements, match criteria filter that set to only the elements you actually want. This two-layer approach. Find then filter, is specific to browser automation and keeps selectors both broad and precise.

Two Layers of Filtering

The first layer is the location strategy (WithCSS, WithXPath, etc.). It finds a candidate set of elements. The second layer is match criteria. It filters that set to only elements meeting additional conditions: exact match, contains, or regex against text, value, href, src, placeholder, or any attribute. Match criteria apply to browser automation only.

Match Methods

Every matchable field -- text content, attribute values, href, placeholder, and more -- supports three comparison modes: exact match, contains, and regex. Multiple criteria can be chained together, and an element must satisfy all of them to make it into the final matched set.

// Find all links whose href contains "/products/"

var links = GPAL.Selector

.WithCSS("a")

.ContainsHRef("/products/")

.ToGPALObject();

// Find inputs with a specific placeholder (exact)

var searchBox = GPAL.Selector

.WithCSS("input")

.MatchPlaceholder("Search...")

.ToGPALObject();

// Custom delegate for complex logic

var activeItems = GPAL.Selector

.WithCSS(".menu-item")

.MatchFunction((found, out matched, out all, sel, exact) => {

matched = found.Where(e =>

e.GetAttribute("class").Contains("active")).ToList();

all = matched.Count == found.Count;

return CallIfStatus.Handled;

})

.ToGPALObject();

TIP

MatchFunction runs before standard match criteria. It receives the full found list, sets the matched list and an all-matched flag, and returns a CallIfStatus value: Handled (done -- skip remaining custom handlers), NotHandled (pass to the next custom handler in the chain), Terminate (exit the operation now), or TryNextSelector (move to the next selector strategy). Any elements it sets then feed into the remaining simple match criteria on the selector.

Partial vs Full Match

When criteria filter the found set, UnitOfWork.PartialMatch indicates whether some but not all found elements passed. This lets callbacks distinguish between a page where no matching elements exist versus one where elements exist but none met your criteria.

WARNING

Regex match criteria use standard .NET regular expression syntax, not JavaScript regex syntax. If a pattern works in a browser console but not in a GPAL selector, check for syntax differences between the two flavors.

On this page

Core Concepts
Match Criteria & Filtering
  • Two Layers of Filtering
  • Match Methods
  • Partial vs Full Match