Cinder.UrlManager (Cinder v0.5.0)
View SourceURL 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
@type filter() :: %{type: atom(), value: filter_value(), operator: atom()}
@type sort_by() :: [{String.t(), :asc | :desc}]
Functions
Decodes filters from URL parameters using column definitions.
Uses column metadata to properly parse filter values according to their types.
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
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}]
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}]
}
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
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"
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"}
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.
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.
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.