Cinder.UrlManager (Cinder v0.5.0)

View Source

URL state management for Cinder table components.

Handles encoding and decoding of table state (filters, pagination, sorting) to/from URL parameters for browser history and bookmark support.

Summary

Functions

Decodes filters from URL parameters using column definitions.

Decodes page number from URL parameter.

Decodes sort string from URL parameters.

Decodes URL parameters into table state components.

Encodes filters for URL parameters.

Encodes sort state for URL parameters.

Encodes table state into URL parameters.

Ensures multi-select fields are included in filter parameters.

Sends state change notification to parent LiveView.

Validates URL parameters for potential security issues.

Types

filter()

@type filter() :: %{type: atom(), value: filter_value(), operator: atom()}

filter_value()

@type filter_value() ::
  String.t()
  | [String.t()]
  | %{from: String.t(), to: String.t()}
  | %{min: String.t(), max: String.t()}

sort_by()

@type sort_by() :: [{String.t(), :asc | :desc}]

table_state()

@type table_state() :: %{
  filters: %{required(String.t()) => filter()},
  current_page: integer(),
  sort_by: sort_by()
}

url_params()

@type url_params() :: %{required(atom()) => String.t()}

Functions

decode_filters(url_params, columns)

Decodes filters from URL parameters using column definitions.

Uses column metadata to properly parse filter values according to their types.

decode_page(page_param)

Decodes page number from URL parameter.

Returns 1 for invalid or missing page parameters.

Examples

iex> Cinder.UrlManager.decode_page("5")
5

iex> Cinder.UrlManager.decode_page("invalid")
1

iex> Cinder.UrlManager.decode_page(nil)
1

decode_sort(url_sort)

Decodes sort string from URL parameters.

Parses Ash sort string format into sort tuples. Fields prefixed with "-" are descending, others are ascending.

Examples

iex> Cinder.UrlManager.decode_sort("-title,created_at")
[{"title", :desc}, {"created_at", :asc}]

decode_state(url_params, columns)

Decodes URL parameters into table state components.

Takes URL parameters and column definitions to properly decode filter values based on their types.

Examples

iex> url_params = %{"title" => "test", "page" => "2", "sort" => "-title"}
iex> columns = [%{field: "title", filterable: true, filter_type: :text}]
iex> Cinder.UrlManager.decode_state(url_params, columns)
%{
  filters: %{"title" => %{type: :text, value: "test", operator: :contains}},
  current_page: 2,
  sort_by: [{"title", :desc}]
}

encode_filters(filters)

Encodes filters for URL parameters.

Converts filter values to strings appropriate for URL encoding. Different filter types are encoded differently:

  • Multi-select: comma-separated values
  • Date/number ranges: "from,to" or "min,max" format
  • Others: string representation

encode_sort(sort_by)

Encodes sort state for URL parameters.

Converts sort tuples to Ash-compatible sort string format. Descending sorts are prefixed with "-".

Examples

iex> Cinder.UrlManager.encode_sort([{"title", :desc}, {"created_at", :asc}])
"-title,created_at"

encode_state(map)

Encodes table state into URL parameters.

Examples

iex> state = %{
...>   filters: %{"title" => %{type: :text, value: "test", operator: :contains}},
...>   current_page: 2,
...>   sort_by: [{"title", :desc}]
...> }
iex> Cinder.UrlManager.encode_state(state)
%{title: "test", page: "2", sort: "-title"}

ensure_multiselect_fields(filter_params, columns)

Ensures multi-select fields are included in filter parameters.

Multi-select filters that have no selected values need to be explicitly included as empty arrays to distinguish from filters that weren't processed.

notify_state_change(socket, state)

Sends state change notification to parent LiveView.

Used by components to notify their parent when table state changes, allowing the parent to update the URL accordingly.

validate_url_params(params)

Validates URL parameters for potential security issues.

Performs basic validation to ensure URL parameters are safe to process. Returns {:ok, params} for valid parameters or {:error, reason} for invalid ones.