Filter Component

Filter component system for creating filterable data views.

This module provides a comprehensive filtering system that allows users to filter data in views by applying comparison operators to field values. It supports defining reusable filter configurations with customizable display options and default filters.

Main Components

Filter Operators:

FilterOperator enum defines all supported comparison operators:

Numeric/Date/Time/DateTime operators:

• EQUAL, NOT_EQUAL: Equality comparisons

• GREATER_THAN, LESS_THAN: Strict inequality comparisons

• GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL: Inclusive inequality comparisons

• BETWEEN: Range queries (inclusive)

Text operators:

• EQUAL, NOT_EQUAL: Exact match comparisons

• CONTAINS, NOT_CONTAINS: Substring searches

• BEGINS_WITH, ENDS_WITH: Prefix/suffix matching

Boolean operators:

• EQUAL, NOT_EQUAL: Boolean value comparisons

Object operators:

• OBJECT_CONTAINS, OBJECT_NOT_CONTAINS: Membership tests for object references

Default Filter Classes:

Pre-applied filters that automatically filter data when a view loads:

• DefaultFilter: Abstract base class for all default filters

• SingleValueDefaultFilter: Compares against one value (EQUAL, GREATER_THAN, etc.)

• TwoValueDefaultFilter: Compares against two values (BETWEEN ranges)

• MultiValueDefaultFilter: Compares against 3+ values (OBJECT_CONTAINS, etc.)

Filter Configuration:

• FilterField: Defines a single filterable field with display configuration

• FilterComponent: Main class for creating reusable filter configurations

• FilterableView: Mixin class for views that support filtering

Operator Validation

The module automatically validates that operators are compatible with field types:

• Numeric fields (INTEGER, DECIMAL): Support comparison and range operators

• Text fields (STRING): Support equality and text-search operators

• Boolean fields: Support only equality operators

• Date/Time/DateTime fields: Support comparison and range operators

• Object fields: Support only membership operators

Invalid operator/field combinations raise ValueError with helpful error messages.

Filter Architecture

Filters are organized in a three-tier structure:

1. FilterField: Defines individual filterable fields - Specifies field to filter, display name, and formatting - For object fields, can specify which referenced field to display

2. FilterComponent: Groups filter fields and default filters - Defines source table for filter data - Contains list of available filter options (FilterField instances) - Contains list of default filters pre-applied on view load - Reusable across multiple views

3. FilterableView: Mixin for views supporting filters - Attaches a FilterComponent to enable filtering in a view

Examples

Creating a basic filter component:

# Create filter for a products table
product_filter = FilterComponent(
    filter_name="product_filter",
    source_table=products_table
)

# Add filterable fields
product_filter.add_filter_option(
    field=products_table.name_field,
    display_name="Product Name"
)

product_filter.add_filter_option(
    field=products_table.price_field,
    display_name="Price",
    display_format="${value}"
)

Adding default filters:

from daitum_ui.data import IntegerValue, StringValue

# Single-value filter: Show only active products
product_filter.add_default_filter(
    field=products_table.status_field,
    operator=FilterOperator.EQUAL,
    StringValue("active")
)

# Range filter: Show products between $10-$100
product_filter.add_default_filter(
    field=products_table.price_field,
    operator=FilterOperator.BETWEEN,
    IntegerValue(10),
    IntegerValue(100)
)

Filtering object fields:

# Filter by category (object reference)
product_filter.add_filter_option(
    field=products_table.category_field,
    display_name="Category",
    display_field=category_table.name_field  # Show category name, not ID
)

# Default filter: Show products in specific categories
from daitum_ui.data import ObjectValue

product_filter.add_default_filter(
    field=products_table.category_field,
    operator=FilterOperator.OBJECT_CONTAINS,
    ObjectValue(row_num=1),
    ObjectValue(row_num=3),
    ObjectValue(row_num=7)
)

Attaching filter to a view:

from daitum_ui.view import TabularView

# Create a filterable view
class ProductTableView(TabularView, FilterableView):
    def __init__(self):
        TabularView.__init__(self, ...)
        FilterableView.__init__(self, use_filter=product_filter)

Text search example:

# Add text search on product descriptions
product_filter.add_filter_option(
    field=products_table.description_field,
    display_name="Description"
)

# Default filter: Show products containing "organic"
product_filter.add_default_filter(
    field=products_table.description_field,
    operator=FilterOperator.CONTAINS,
    StringValue("organic")
)

Date range filtering:

from daitum_ui.data import DateValue
from datetime import date

# Filter orders by date range
order_filter.add_filter_option(
    field=orders_table.order_date_field,
    display_name="Order Date"
)

# Default: Show orders from last month
order_filter.add_default_filter(
    field=orders_table.order_date_field,
    operator=FilterOperator.BETWEEN,
    DateValue(date(2024, 1, 1)),
    DateValue(date(2024, 1, 31))
)

class FilterOperator(*values)

Bases: Enum

Defines the supported operators for filtering values.

This enumeration contains all valid comparison operators that can be used when defining filter conditions in a FilterView. The available operators depend on the field type being filtered.

Operators for numeric, date, time, and datetime fields:

• EQUAL: Field equals the specified value

• NOT_EQUAL: Field does not equal the specified value

• GREATER_THAN: Field is greater than the specified value

• LESS_THAN: Field is less than the specified value

• GREATER_THAN_OR_EQUAL: Field is greater than or equal to the specified value

• LESS_THAN_OR_EQUAL: Field is less than or equal to the specified value

• BETWEEN: Field is between two specified values (inclusive)

Operators for text fields:

• EQUAL: Field exactly matches the specified value

• NOT_EQUAL: Field does not match the specified value

• CONTAINS: Field contains the specified substring

• NOT_CONTAINS: Field does not contain the specified substring

• BEGINS_WITH: Field starts with the specified value

• ENDS_WITH: Field ends with the specified value

Operators for boolean fields:

• EQUAL: Field equals the specified boolean value

• NOT_EQUAL: Field does not equal the specified boolean value

Operators for object fields:

• OBJECT_CONTAINS: Object field contains any of the specified values

• OBJECT_NOT_CONTAINS: Object field does not contain any of the specified values

GREATER_THAN = 'GREATER_THAN'

LESS_THAN = 'LESS_THAN'

GREATER_THAN_OR_EQUAL = 'GREATER_THAN_OR_EQUAL'

LESS_THAN_OR_EQUAL = 'LESS_THAN_OR_EQUAL'

EQUAL = 'EQUAL'

NOT_EQUAL = 'NOT_EQUAL'

CONTAINS = 'CONTAINS'

NOT_CONTAINS = 'NOT_CONTAINS'

BEGINS_WITH = 'BEGINS_WITH'

ENDS_WITH = 'ENDS_WITH'

BETWEEN = 'BETWEEN'

OBJECT_CONTAINS = 'OBJECT_CONTAINS'

OBJECT_NOT_CONTAINS = 'OBJECT_NOT_CONTAINS'

class DefaultFilter(field, operator)

Bases: ABC, Buildable

Abstract base class for a default filter.

A default filter defines an initial filtering rule that is applied when a view is first loaded. This allows you to pre-filter data before the user interacts with the filter UI.

field_name

The name of the field this filter applies to.

Type:

str

operator

The operator used to evaluate the filter.

Type:

FilterOperator

__init__(field, operator)

Initialize a default filter with a field and operator.

Parameters:

• field (Field) – The field to apply the filter to.

• operator (FilterOperator) – The comparison operator to use for filtering.

Raises:

ValueError – If the operator is not valid for the field’s data type.

class SingleValueDefaultFilter(field, operator, value)

Bases: DefaultFilter

A default filter that compares a field against a single value.

This filter type is used for operators that compare against one value, such as EQUAL, NOT_EQUAL, GREATER_THAN, LESS_THAN, CONTAINS, etc.

field_name

The name of the field this filter applies to (inherited).

Type:

str

operator

The comparison operator (inherited).

Type:

FilterOperator

value

The value to compare against.

Type:

Value | Calculation

__init__(field, operator, value)

Initialize a single-value default filter.

Parameters:

• field (Field) – The field to filter.

• operator (FilterOperator) – The comparison operator. Must be a single-value operator like EQUAL, GREATER_THAN, CONTAINS, etc.

• value (Value | Calculation) – The value to compare against.

Raises:

ValueError – If the operator is not valid for the field’s data type, or if the operator requires a different number of values.

class TwoValueDefaultFilter(field, operator, first_value, second_value)

Bases: DefaultFilter

A default filter that compares a field against two values.

This filter type is used for operators that require two values, such as BETWEEN (for range queries).

field_name

The name of the field this filter applies to (inherited).

Type:

str

operator

The comparison operator (inherited).

Type:

FilterOperator

first_value

The first value. Can be a static Value or a dynamic Calculation.

Type:

Any

second_value

The second value. Can be a static Value or a dynamic Calculation.

Type:

Any

__init__(field, operator, first_value, second_value)

Initialize a two-value default filter.

Parameters:

• field (Field) – The field to filter.

• operator (FilterOperator) – The comparison operator. Typically BETWEEN.

• first_value (Value | Calculation) – The first comparison value. Can be a static Value or a dynamic Calculation.

• second_value (Value | Calculation) – The second comparison value. Can be a static Value or a dynamic Calculation.

Raises:

ValueError – If the operator is not valid for the field’s data type, or if the operator requires a different number of values.

class MultiValueDefaultFilter(field, operator, values)

Bases: DefaultFilter

A default filter that compares a field against multiple values.

This filter type is used for operators that require three or more values, such as OBJECT_CONTAINS and OBJECT_NOT_CONTAINS (for checking membership in a collection).

field_name

The name of the field this filter applies to (inherited).

Type:

str

operator

The comparison operator (inherited).

Type:

FilterOperator

values

The list of values to compare against. Each value can be a static Value or a dynamic Calculation.

Type:

list[Any]

__init__(field, operator, values)

Initialize a multi-value default filter.

Parameters:

• field (Field) – The field to filter.

• operator (FilterOperator) – The comparison operator. Typically OBJECT_CONTAINS or OBJECT_NOT_CONTAINS.

• values (list[Value | Calculation]) – A list of values to compare against. Each value can be a static Value or a dynamic Calculation. Must contain at least 3 values.

Raises:

ValueError – If the operator is not valid for the field’s data type, or if the operator requires a different number of values.

values: list[Any] | None

class FilterField(field, display_name, display_field=None, display_format=None, include_in_search=False)

Bases: Buildable

Represents a single filter component used in a view filter definition.

A filter component defines a field that users can filter on in the UI. It specifies how the field should be displayed and formatted.

field_name

The underlying field name used for filtering.

Type:

str

display_name

The user-facing name shown in the UI.

Type:

str

display_field

The field used for display purposes. Only applicable when the filter component refers to an object type and needs to resolve a column from a referenced table.

Type:

str | None

display_format

The format string used to render the display value.

Type:

str | None

include_in_search

A boolean indicating if the field can be searched.

Type:

bool

__init__(field, display_name, display_field=None, display_format=None, include_in_search=False)

Initialize a filter component.

Parameters:

• field (Field) – The field that this filter component operates on.

• display_name (str | None) – The name to display in the UI. If None, defaults to the field_id.

• display_field (str | None) – For object-type fields, specifies which field from the referenced table to display. Default is None.

• display_format (str | None) – A format string for rendering values (e.g., “${value}” for currency). Default is None.

• include_in_search (bool) – A boolean indicating if the field can be searched. Default is False.

class HorizontalAlignment(*values)

Bases: Enum

Defines horizontal alignment options for filter components.

This enumeration specifies how filter content should be aligned horizontally within its container.

LEFT

Align content to the left edge.

RIGHT

Align content to the right edge.

JUSTIFIED

Distribute content evenly across the full width.

LEFT = 'LEFT'

RIGHT = 'RIGHT'

JUSTIFIED = 'JUSTIFIED'

class SearchType(*values)

Bases: Enum

Defines search behavior for filter search functionality.

This enumeration specifies how search queries should match against filterable data.

CONTAINS_PHRASE

Match the exact phrase in the specified order. Example: “hello world” matches “hello world” but not “world hello”.

CONTAINS_WORDS

Match all words regardless of order. The query is split by spaces into individual words. A record matches if every word is contained within the field value, in any order and at any position. Example: “hello world” matches both “hello world” and “world hello”.

CONTAINS_PHRASE = 'CONTAINS_PHRASE'

CONTAINS_WORDS = 'CONTAINS_WORDS'

class SearchConfiguration(search_type)

Bases: Buildable

Configuration for search functionality in filter components.

This class defines how search queries should be processed when users search through filter options.

search_type

The type of search behavior to use (phrase or word matching).

Type:

SearchType

search_type: SearchType

class FilterComponent(filter_name, source_table, collapsible=True, opacity=1.0)

Bases: Buildable

Defines a set of filters that can be applied to a view.

A FilterComponent allows you to create a reusable filter configuration that can be attached to multiple views. It defines which fields can be filtered, how they should be displayed, and any default filter values that should be pre-applied.

filter_name

The unique name of this filter definition.

Type:

str

source_table

The table from which filter values are sourced.

Type:

str

filter_options

The list of available fields that users can filter on.

Type:

list[FilterComponent]

default_filters

The list of default filters automatically applied when the view loads.

Type:

list[DefaultFilter]

collapsible

Whether the filter component can be collapsed/expanded in the UI.

Type:

bool

opacity

The opacity level of the filter component (0.0 to 1.0).

Type:

float

search_configuration

Configuration for search functionality, or None if search is not enabled.

Type:

SearchConfiguration | None

horizontal_alignment

The horizontal alignment of filter content, or None for default alignment.

Type:

HorizontalAlignment | None

size

The CSS size of the element along the main axis. When the layout is horizontal, this represents the width. When the layout is vertical, this represents the height. Accepts any valid CSS size value (e.g., “100px”, “50%”, “auto”).

Type:

str | None

__init__(filter_name, source_table, collapsible=True, opacity=1.0)

Initialize a FilterComponent.

Parameters:

• filter_name (str) – The unique identifier for this filter definition.

• source_table (Table) – The table that provides the data to filter.

• collapsible (bool) – Whether the filter can be collapsed/expanded. Defaults to True.

• opacity (float) – The opacity level (0.0 to 1.0). Defaults to 1.0 (fully opaque).

filter_options: list[FilterField]

default_filters: list[DefaultFilter]

search_configuration: SearchConfiguration | None

horizontal_alignment: HorizontalAlignment | None

filter_only: bool

search_only: bool

default_collapsed: bool

size: str | None

set_horizontal_alignment(horizontal_alignment)

Sets the horizontal alignment of filter content.

Return type:

FilterComponent

set_filter_only(filter_only)

Sets whether to render only the filter component.

Return type:

FilterComponent

set_search_only(search_only)

Sets whether to render only the search component.

Return type:

FilterComponent

set_default_collapsed(default_collapsed)

Configures whether the filter and search component are collapsed by default.

Return type:

FilterComponent

set_size(size)

Sets the CSS size of the element along the main axis.

Return type:

FilterComponent

add_filter_option(field, display_name, display_field=None, display_format=None)

Add a filterable field to this filter view.

This method registers a field as available for filtering in the UI. Users will be able to select this field and apply filter conditions to it.

Parameters:

• field (Field) – The field to make filterable.

• display_name (str | None) – The name to show in the filter UI. If None, uses the field’s ID.

• display_field (str | None) – For object-type fields, specifies which field from the referenced table should be displayed to the user. Default is None.

• display_format (str | None) – A format string for displaying values. Default is None.

Return type:

None

add_default_filter(field, operator, *values)

Add a default filter that is automatically applied when the view loads.

Default filters pre-filter the data before the user interacts with the UI, allowing you to set initial filter conditions. The type of default filter created depends on the number of values provided and the operator used.

Filter type selection:

• 1 value -> SingleValueDefaultFilter (for EQUAL, GREATER_THAN, etc.)

• 2 values -> TwoValueDefaultFilter (for BETWEEN)

• 3+ values -> MultiValueDefaultFilter (for OBJECT_CONTAINS, etc.)

Parameters:

• field (Field) – The field to apply the default filter to.

• operator (FilterOperator) – The comparison operator to use. Must be valid for the field’s data type.

• *values (Value | Calculation) – One or more values to filter by. Each value can be a static Value or a dynamic Calculation. The number of values must match the operator’s requirements.

Raises:

ValueError – If no values are provided, if the number of values doesn’t match the operator’s requirements, or if the operator is not valid for the field’s data type.

Return type:

None

set_search_configuration(search_type)

Configure the search behavior for this filter component.

This method sets how search queries should match against filter options. Once configured, users can search through available filter values using the specified search type.

Parameters:

search_type (SearchType) – The type of search behavior to use. Use CONTAINS_PHRASE for exact phrase matching or CONTAINS_WORDS for flexible word matching.

class FilterableView(use_filter=None)

Bases: Buildable

A mixin class for views that support filtering functionality.

This class allows other view types (e.g., TabularView, CardView) to attach a FilterComponent, enabling users to filter the displayed data.

use_filter

The name of the FilterComponent to use for filtering, or None if no filter is attached.

Type:

str | None

show_filter

The name of the FilterComponent to display in the UI, or None if no filter should be shown.

Type:

str | None

__init__(use_filter=None)

Initialize a filterable view.

Parameters:

use_filter (FilterComponent | None) – The FilterComponent to attach to this view. If provided, the filter will be available in the UI for this view. Default is None.