Backpex.Filters.Range behaviour (Backpex v0.20.0)

The range filter renders two input fields of the same type. Backpex offers the :date, :datetime and the number type.

See the following example for an implementation of a date range filter.

defmodule MyAppWeb.Filters.DateRange do
  use Backpex.Filters.Range

  @impl Backpex.Filters.Range
  def type, do: :date

  @impl Backpex.Filter
  def label, do: "Date Range (begins at)"
end

Information

Note that the query function is already implemented via Backpex.Filters.Range.

`use Backpex.Filters.Range`

When you use Backpex.Filters.Range, the Backpex.Filters.Range module will set @behavior Backpex.Filters.Range. In addition it will add a render and render_form function in order to display the corresponding filter. It will also implement the Backpex.Filter.query function to define a range query.

Summary

Callbacks

type()

The type return value defines the rendered input fields of the range filter.

Functions

changeset(changeset, field, range_type)

Validates range filter values based on the filter type.

date?(date)

Checks if a string is a valid ISO 8601 date.

do_query(arg, query, attribute)

maybe_parse(type, value, is_end? \\ false)

Parses a single value based on the specified type.

maybe_parse_range(type, start_at, end_at)

Parses both start and end values for a range filter.

parse_float_or_int(value)

Parses a value as either an integer or float.

query(query, type, attribute, arg4, assigns)

range_input_set(assigns)

render(assigns)

render_form(assigns)

render_type(type)

Returns the render type for form inputs.

Callbacks

type()

@callback type() :: :date | :datetime | :number

The type return value defines the rendered input fields of the range filter.

Functions

changeset(changeset, field, range_type)

Validates range filter values based on the filter type.

Validates that:

Date values are valid ISO 8601 dates (for :date and :datetime types)
Number values are valid integers or floats (for :number type)
Start is not greater than end when both are provided

date?(date)

Checks if a string is a valid ISO 8601 date.

Examples

iex> Backpex.Filters.Range.date?("2024-01-01")
true

iex> Backpex.Filters.Range.date?("2023-12-31")
true

iex> Backpex.Filters.Range.date?("2000-06-15")
true

iex> Backpex.Filters.Range.date?("not-a-date")
false

iex> Backpex.Filters.Range.date?("2024-13-01")
false

iex> Backpex.Filters.Range.date?("2024-01-32")
false

iex> Backpex.Filters.Range.date?("")
false

do_query(arg, query, attribute)

maybe_parse(type, value, is_end? \\ false)

Parses a single value based on the specified type.

The third parameter is_end? determines whether to treat the value as an end boundary (which affects datetime parsing by adding 23:59:59 instead of 00:00:00). nil and "" return nil for every supported type. Date and datetime values may be ISO 8601 date strings or Date structs; number values may be numeric strings, integers, or floats. For these supported range types, invalid strings and unsupported value types return nil.

Examples

iex> Backpex.Filters.Range.maybe_parse(:number, "")
nil

iex> Backpex.Filters.Range.maybe_parse(:date, "")
nil

iex> Backpex.Filters.Range.maybe_parse(:datetime, "")
nil

iex> Backpex.Filters.Range.maybe_parse(:date, "2024-06-15")
"2024-06-15"

iex> Backpex.Filters.Range.maybe_parse(:date, "not-a-date")
nil

iex> Backpex.Filters.Range.maybe_parse(:date, "2024-13-45")
nil

iex> Backpex.Filters.Range.maybe_parse(:datetime, "2024-01-01", false)
"2024-01-01T00:00:00+00:00"

iex> Backpex.Filters.Range.maybe_parse(:datetime, "2024-12-31", true)
"2024-12-31T23:59:59+00:00"

iex> Backpex.Filters.Range.maybe_parse(:datetime, "invalid")
nil

iex> Backpex.Filters.Range.maybe_parse(:datetime, ~D[2024-12-31], true)
"2024-12-31T23:59:59+00:00"

iex> Backpex.Filters.Range.maybe_parse(:number, 42.5)
42.5

maybe_parse_range(type, start_at, end_at)

Parses both start and end values for a range filter.

Number boundaries accept numeric strings, integers, and floats. Date and datetime boundaries accept ISO 8601 date strings or Date structs. nil and the empty string mean an open boundary. For the supported range types, invalid strings and unsupported value types parse to nil.

Examples

iex> Backpex.Filters.Range.maybe_parse_range(:number, "10", "100")
{10, 100}

iex> Backpex.Filters.Range.maybe_parse_range(:number, "", "100")
{nil, 100}

iex> Backpex.Filters.Range.maybe_parse_range(:number, "10", "")
{10, nil}

iex> Backpex.Filters.Range.maybe_parse_range(:date, "2024-01-01", "2024-12-31")
{"2024-01-01", "2024-12-31"}

iex> Backpex.Filters.Range.maybe_parse_range(:datetime, "2024-01-01", "2024-12-31")
{"2024-01-01T00:00:00+00:00", "2024-12-31T23:59:59+00:00"}

iex> Backpex.Filters.Range.maybe_parse_range(:number, 10, 99.5)
{10, 99.5}

iex> Backpex.Filters.Range.maybe_parse_range(:date, ~D[2024-01-01], nil)
{"2024-01-01", nil}

parse_float_or_int(value)

Parses a value as either an integer or float.

Integers and floats are returned unchanged. Binary input must contain one complete integer or float representation; trailing characters are rejected. Unsupported values return nil. String input prefers integer representation for whole numbers.

Examples

iex> Backpex.Filters.Range.parse_float_or_int("42")
42

iex> Backpex.Filters.Range.parse_float_or_int("-10")
-10

iex> Backpex.Filters.Range.parse_float_or_int("0")
0

iex> Backpex.Filters.Range.parse_float_or_int("3.14")
3.14

iex> Backpex.Filters.Range.parse_float_or_int("-2.5")
-2.5

iex> Backpex.Filters.Range.parse_float_or_int("0.0")
0.0

iex> Backpex.Filters.Range.parse_float_or_int("not-a-number")
nil

iex> Backpex.Filters.Range.parse_float_or_int("abc123")
nil

iex> Backpex.Filters.Range.parse_float_or_int("12abc")
nil

iex> Backpex.Filters.Range.parse_float_or_int("")
nil

iex> Backpex.Filters.Range.parse_float_or_int(42)
42

iex> Backpex.Filters.Range.parse_float_or_int(3.5)
3.5

iex> Backpex.Filters.Range.parse_float_or_int(nil)
nil

query(query, type, attribute, arg4, assigns)

range_input_set(assigns)

Attributes

form (:any) (required)
type (:atom) (required)
value (:any) (required)
live_resource (:atom) (required)
errors (:list) - Defaults to [].

render(assigns)

Attributes

value (:map) (required)

render_form(assigns)

Attributes

form (:any) (required)
field (:atom) (required)
value (:any) (required)
type (:atom) (required)
live_resource (:atom) (required)
errors (:list) - Defaults to [].

render_type(type)

Returns the render type for form inputs.

Converts :datetime to :date since HTML date inputs are used for datetime filters.

Examples

iex> Backpex.Filters.Range.render_type(:datetime)
:date

iex> Backpex.Filters.Range.render_type(:date)
:date

iex> Backpex.Filters.Range.render_type(:number)
:number