flop_phoenix

# Flop Phoenix

![CI](https://github.com/woylie/flop_phoenix/workflows/CI/badge.svg) [![Hex](https://img.shields.io/hexpm/v/flop_phoenix)](https://hex.pm/packages/flop_phoenix) [![Coverage Status](https://coveralls.io/repos/github/woylie/flop_phoenix/badge.svg)](https://coveralls.io/github/woylie/flop_phoenix)

Flop Phoenix provides Phoenix components for pagination, sortable tables, and
filter forms with [Flop](https://hex.pm/packages/flop) and
[Ecto](https://hex.pm/packages/ecto).

## Installation

Add `flop_phoenix` to your list of dependencies in the `mix.exs` of your Phoenix
application.

```elixir
def deps do
  [
    {:flop_phoenix, "~> 0.27.0"}
  ]
end
```

Next, set up your business logic following the
[Flop documentation](https://hex.pm/packages/flop).

### Supported versions

Flop Phoenix is tested against the Elixir and OTP versions that are still
maintained. `mix.exs` allows older Elixir versions, but they are untested.

## Context

Define a context function that performs a list query using Flop.

```elixir
defmodule MyApp.Pets do
  alias MyApp.Pet

  def list_pets(params) do
    Flop.validate_and_run!(Pet, params, for: Pet, replace_invalid_params: true)
  end
end
```

Note the usage of the `replace_invalid_params` option, which lets Flop ignore
invalid parameters instead of producing an error.

## LiveView

In the `handle_params` function of your LiveView module, pass the parameters
to the list function to fetch the data and assign both the data and the meta
struct to the socket.

```elixir
defmodule MyAppWeb.PetLive.Index do
  use MyAppWeb, :live_view

  alias MyApp.Pets

  @impl Phoenix.LiveView
  def handle_params(params, _, socket) do
    {pets, meta} = Pets.list_pets(params)
    {:noreply, assign(socket, pets: pets, meta: meta)}
  end
end
```

## Sortable table and pagination

Add a sortable table and pagination to your HEEx template:

```heex
<Flop.Phoenix.table items={@pets} meta={@meta} path={~p"/pets"}>
  <:col :let={pet} label="Name" field={:name}>{pet.name}</:col>
  <:col :let={pet} label="Age" field={:age}>{pet.age}</:col>
</Flop.Phoenix.table>

<Flop.Phoenix.pagination meta={@meta} path={~p"/pets"} />
```

The `path` attribute points to the current route, and Flop Phoenix appends
pagination, filtering, and sorting parameters to it. You can use verified
routes, route helpers, or custom path builder functions. For a
description of the different formats, refer to the documentation of
`Flop.Phoenix.build_path/3`.

The `field` attribute in the `:col` slot is optional. If set and the field
is defined as sortable in the Ecto schema, the table header for
that column will be interactive, allowing users to sort by that column. However,
if the field isn't defined as sortable, or if the field attribute is omitted, or
set to `nil` or `false`, the table header will not be clickable.

By using the `for` option in your Flop query, Flop Phoenix can identify which
table columns are sortable. Additionally, it omits the `order` and `page_si