selecto_components
v0.4.5

SelectoComponents.FilterSetsBehaviour behaviour (selecto_components v0.4.5)

Behavior for implementing persistent filter sets in SelectoComponents.

This behavior defines a contract for saving, loading, and managing filter sets to persistent storage. It enables users to save complex filter combinations, share them with others, and quickly apply commonly used filters.

overview

 Overview

The FilterSets behavior supports:

  • Personal filter sets: User-specific saved filters
  • Shared filter sets: Filters shared across users in a domain
  • System filter sets: Admin-configured default filters
  • Default filter sets: User's preferred default filter per domain
  • Usage tracking: Analytics on filter set usage

database-schema

 Database Schema

The typical database structure includes:

  • id: UUID primary key
  • name: String identifier for the filter set
  • description: Optional description
  • domain: String domain/context identifier
  • filters: Map/JSON containing the filter configuration
  • user_id: Owner of the filter set
  • is_default: Boolean flag for user's default
  • is_shared: Boolean flag for shared sets
  • is_system: Boolean flag for system sets
  • usage_count: Integer tracking usage
  • timestamps: Created/updated timestamps

integration-with-selectocomponents

 Integration with SelectoComponents

SelectoComponents automatically integrates with filter sets when:

  1. A module implementing this behavior is configured
  2. The filter_sets_adapter is set in the component assigns
  3. Users can then save/load filter sets through the UI

example-implementation

 Example Implementation 

defmodule MyApp.FilterSets do
  @behaviour SelectoComponents.FilterSetsBehaviour

  def list_personal_filter_sets(user_id, domain) do
    # Return user's personal filter sets for domain
  end

  def list_shared_filter_sets(user_id, domain) do
    # Return shared filter sets for domain
  end

  def list_system_filter_sets(domain) do
    # Return system filter sets for domain
  end

  # ... other callbacks
end

generator-support

 Generator Support

Use the Mix generator to create the implementation:

mix selecto.gen.filter_sets MyApp

This generates:

  • Migration for filter_sets table
  • Ecto schema for filter sets
  • Context module implementing this behavior

Link to this section Summary

Callbacks

create_filter_set(attrs)

Creates a new filter set.

delete_filter_set(id, user_id)

Deletes a filter set.

duplicate_filter_set(id, new_name, user_id)

Duplicates a filter set with a new name.

get_default_filter_set(user_id, domain)

Gets the user's default filter set for a domain.

get_filter_set(id, user_id)

Gets a specific filter set by ID.

increment_usage_count(id)

Increments the usage count for a filter set.

list_personal_filter_sets(user_id, domain)

Lists personal filter sets for a user and domain.

list_shared_filter_sets(user_id, domain)

Lists shared filter sets accessible to a user in a domain.

list_system_filter_sets(domain)

Lists system-provided filter sets for a domain.

set_default_filter_set(id, user_id)

Sets a filter set as the user's default for a domain.

update_filter_set(id, attrs, user_id)

Updates an existing filter set.

Link to this section Callbacks

Link to this callback

create_filter_set(attrs)

@callback create_filter_set(attrs :: map()) :: {:ok, map()} | {:error, any()}

Creates a new filter set.

parameters

 Parameters

  • attrs: Map containing filter set attributes
    • :name - Required string name
    • :description - Optional description
    • :domain - Required domain identifier
    • :filters - Required map of filter configuration
    • :user_id - Required owner ID
    • :is_default - Optional boolean (default: false)
    • :is_shared - Optional boolean (default: false)

returns

 Returns

  • {:ok, filter_set} on success
  • {:error, changeset} on validation failure
Link to this callback

delete_filter_set(id, user_id)

@callback delete_filter_set(id :: String.t(), user_id :: String.t()) ::
  {:ok, map()} | {:error, atom()}

Deletes a filter set.

parameters

 Parameters

  • id: Filter set ID
  • user_id: User performing the deletion (for access control)

returns

 Returns

  • {:ok, filter_set} on success
  • {:error, :not_found} if not found
  • {:error, :unauthorized} if user lacks permission
Link to this callback

duplicate_filter_set(id, new_name, user_id)

@callback duplicate_filter_set(
  id :: String.t(),
  new_name :: String.t(),
  user_id :: String.t()
) ::
  {:ok, map()} | {:error, atom()}

Duplicates a filter set with a new name.

parameters

 Parameters

  • id: Source filter set ID
  • new_name: Name for the duplicate
  • user_id: User creating the duplicate

returns

 Returns

  • {:ok, filter_set} on success
  • {:error, :not_found} if source not found
  • {:error, :unauthorized} if user lacks access to source
Link to this callback

get_default_filter_set(user_id, domain)

@callback get_default_filter_set(user_id :: String.t(), domain :: String.t()) ::
  map() | nil

Gets the user's default filter set for a domain.

parameters

 Parameters

  • user_id: User identifier
  • domain: Domain/context identifier

returns

 Returns

  • The default filter set if one exists
  • nil if no default is set
Link to this callback

get_filter_set(id, user_id)

@callback get_filter_set(id :: String.t(), user_id :: String.t()) ::
  {:ok, map()} | {:error, atom()}

Gets a specific filter set by ID.

parameters

 Parameters

  • id: Filter set ID
  • user_id: User requesting the filter set (for access control)

returns

 Returns

  • {:ok, filter_set} if found and accessible
  • {:error, :not_found} if not found
  • {:error, :unauthorized} if user lacks access
Link to this callback

increment_usage_count(id)

@callback increment_usage_count(id :: String.t()) :: :ok

Increments the usage count for a filter set.

parameters

 Parameters

  • id: Filter set ID

returns

 Returns

  • :ok on success
Link to this callback

list_personal_filter_sets(user_id, domain)

@callback list_personal_filter_sets(user_id :: String.t(), domain :: String.t()) :: [
  map()
]

Lists personal filter sets for a user and domain.

parameters

 Parameters

  • user_id: User identifier
  • domain: Domain/context identifier

returns

 Returns

List of filter set records owned by the user for the domain.

Link to this callback

list_shared_filter_sets(user_id, domain)

@callback list_shared_filter_sets(user_id :: String.t(), domain :: String.t()) :: [map()]

Lists shared filter sets accessible to a user in a domain.

parameters

 Parameters

  • user_id: User identifier (for access control)
  • domain: Domain/context identifier

returns

 Returns

List of shared filter set records for the domain.

Link to this callback

list_system_filter_sets(domain)

@callback list_system_filter_sets(domain :: String.t()) :: [map()]

Lists system-provided filter sets for a domain.

parameters

 Parameters

  • domain: Domain/context identifier

returns

 Returns

List of system filter set records for the domain.

Link to this callback

set_default_filter_set(id, user_id)

@callback set_default_filter_set(id :: String.t(), user_id :: String.t()) ::
  {:ok, map()} | {:error, atom()}

Sets a filter set as the user's default for a domain.

parameters

 Parameters

  • id: Filter set ID to make default
  • user_id: User setting the default

returns

 Returns

  • {:ok, filter_set} on success
  • {:error, :not_found} if not found
  • {:error, :unauthorized} if user lacks permission
Link to this callback

update_filter_set(id, attrs, user_id)

@callback update_filter_set(id :: String.t(), attrs :: map(), user_id :: String.t()) ::
  {:ok, map()} | {:error, atom() | any()}

Updates an existing filter set.

parameters

 Parameters

  • id: Filter set ID
  • attrs: Map of attributes to update
  • user_id: User performing the update (for access control)

returns

 Returns

  • {:ok, filter_set} on success
  • {:error, :not_found} if not found
  • {:error, :unauthorized} if user lacks permission
  • {:error, changeset} on validation failure