# flop_phoenix

> Phoenix components for pagination, sortable tables and filter forms using Flop.

## Docs

### Flop.Phoenix (module)

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

### Introduction - Flop.Phoenix (module)

Please refer to the [Readme](README.md) for an introduction.

### Customization - Flop.Phoenix (module)

The default classes, attributes, texts and symbols can be overridden by
passing the `opts` assign. Since you probably will use the same `opts` in all
your templates, you can globally configure an `opts` provider function for
each component.

The functions have to return the options as a keyword list. The overrides
are deep-merged into the default options.

    defmodule MyAppWeb.CoreComponents do
      use Phoenix.Component

      def pagination_opts do
         [
          ellipsis_attrs: [class: "ellipsis"],
          ellipsis_content: "‥",
          next_link_attrs: [class: "next"],
          next_link_content: next_icon(),
          page_links: {:ellipsis, 7},
          pagination_link_aria_label: &"#{&1}ページ目へ",
          previous_link_attrs: [class: "prev"],
          previous_link_content: previous_icon()
        ]
      end

      defp next_icon do
        assigns = %{}

        ~H"""
         
        """
      end

      defp previous_icon do
        assigns = %{}

        ~H"""
         
        """
      end

      def table_opts do
        [
          container: true,
          container_attrs: [class: "table-container"],
          no_results_content: no_results_content(),
          table_attrs: [class: "table"]
        ]
      end

      defp no_results_content do
        assigns = %{}

        ~H"""
         Nothing found. 
        """
      end
    end

Refer to `t:pagination_option/0` and `t:table_option/0` for a list of
available options and defaults.

Once you have defined these functions, you can reference them with a
module/function tuple in `config/config.exs`.

```elixir
config :flop_phoenix,
  pagination: [opts: {MyApp.CoreComponents, :pagination_opts}],
  table: [opts: {MyApp.CoreComponents, :table_opts}]
```

### Hiding default parameters - Flop.Phoenix (module)

Default values for page size and ordering are omitted from the query
parameters. If you pass the `:for` assign, the Flop.Phoenix function will
pick up the default values from the schema module deriving `Flop.Schema`.

### Links - Flop.Phoenix (module)

Links are generated with `Phoenix.Components.link/1`. This will
lead to ` ` tags with `data-phx-link` and `data-phx-link-state` attributes,
which will be ignored outside of LiveViews and LiveComponents.

When used within a LiveView or LiveComponent, you will need to handle the new
params in the `c:Phoenix.LiveView.handle_params/3` callback of your LiveView
module.

### Using JS commands - Flop.Phoenix (module)

You can pass a `Phoenix.LiveView.JS` command as `on_paginate` and `on_sort`
attributes.

If used with the `path` attribute, the URL will be patched _and_ the given
JS command will be executed.

If used without the `path` attribute, you will need to include a `push`
command to trigger an event when a pagination or sort link is clicked.

You can set a different target by assigning a `:target`. The value
will be used as the `phx-target` attribute.

     

     

You will need to handle the event in the `c:Phoenix.LiveView.handle_event/3`
or `c:Phoenix.LiveComponent.handle_event/3` callback of your
LiveView or LiveComponent module. The event name will be the one you set with
the `:event` option.

    def handle_event("paginate-pets", %{"page" => page}, socket) do
      flop = Flop.set_page(socket.assigns.meta.flop, page)

      with {:ok, {pets, meta}} <- Pets.list_pets(flop) do
        {:noreply, assign(socket, pets: pets, meta: meta)}
      end
    end

    def handle_event("sort-pets", %{"order" => order}, socket) do
      flop = Flop.push_order(socket.assigns.meta.flop, order)

      with {:ok, {pets, meta}} <- Pets.list_pets(flop) do
        {:noreply, assign(socket, pets: pets, meta: meta)}
      end
    end

### Flop.Phoenix.build_path/3 (function)

Builds a path that includes query parameters for the given `Flop` struct
using the referenced Phoenix path helper function.

The first argument can be either one of:

- an MFA tuple (module, function name as atom, arguments)
- a 2-tuple (function, arguments)
- a URL string, usually produced with a verified route (e.g. `~p"/some/path"`)
- a function that takes the Flop parameters as a keyword list as an argument

Default values for `limit`, `page_size`, `order_by` and `order_directions` are
omitted from the query parameters. To pick up the default parameters from a
schema module deriving `Flop.Schema`, you need to pass the `:for` option. To
pick up the default parameters from the backend module, you need to pass the
`:backend` option. If you pass a `Flop.Meta` struct as the second argument,
these options are retrieved from the struct automatically.

> #### Date and Time Filters {: .info}
>
> When using filters on `Date`, `DateTime`, `NaiveDateTime` or `Time` fields,
> you may need to implement the `Phoenix.Param` protocol for these structs.
> See the documentation for `to_query/2`.

### Examples - Flop.Phoenix.build_path/3 (function)



### With a verified route - Flop.Phoenix.build_path/3 (function)

The examples below use plain URL strings without the p-sigil, so that the
doc tests work, but in your application, you can use verified routes or
anything else that produces a URL.

    iex> flop = %Flop{page: 2, page_size: 10}
    iex> path = build_path("/pets", flop)
    iex> %URI{path: parsed_path, query: parsed_query} = URI.parse(path)
    iex> {parsed_path, URI.decode_query(parsed_query)}
    {"/pets", %{"page" => "2", "page_size" => "10"}}

The Flop query parameters will be merged into existing query parameters.

    iex> flop = %Flop{page: 2, page_size: 10}
    iex> path = build_path("/pets?species=dogs", flop)
    iex> %URI{path: parsed_path, query: parsed_query} = URI.parse(path)
    iex> {parsed_path, URI.decode_query(parsed_query)}
    {"/pets", %{"page" => "2", "page_size" => "10", "species" => "dogs"}}

### With an MFA tuple - Flop.Phoenix.build_path/3 (function)

iex> flop = %Flop{page: 2, page_size: 10}
    iex> build_path(
    ...>   {Flop.PhoenixTest, :route_helper, [%Plug.Conn{}, :pets]},
    ...>   flop
    ...> )
    "/pets?page_size=10&page=2"

### With a function/arguments tuple - Flop.Phoenix.build_path/3 (function)

iex> pet_path = fn _conn, :index, query ->
    ...>   "/pets?" <> Plug.Conn.Query.encode(query)
    ...> end
    iex> flop = %Flop{page: 2, page_size: 10}
    iex> build_path({pet_path, [%Plug.Conn{}, :index]}, flop)
    "/pets?page_size=10&page=2"

We're defining fake path helpers for the scope of the doctests. In a real
Phoenix application, you would pass something like
`{Routes, :pet_path, args}` or `{&Routes.pet_path/3, args}` as the
first argument.

### Passing a `Flop.Meta` struct or a keyword list - Flop.Phoenix.build_path/3 (function)

You can also pass a `Flop.Meta` struct or a keyword list as the third
argument.

    iex> pet_path = fn _conn, :index, query ->
    ...>   "/pets?" <> Plug.Conn.Query.encode(query)
    ...> end
    iex> flop = %Flop{page: 2, page_size: 10}
    iex> meta = %Flop.Meta{flop: flop}
    iex> build_path({pet_path, [%Plug.Conn{}, :index]}, meta)
    "/pets?page_size=10&page=2"
    iex> query_params = to_query(flop)
    iex> build_path({pet_path, [%Plug.Conn{}, :index]}, query_params)
    "/pets?page_size=10&page=2"

### Additional path parameters - Flop.Phoenix.build_path/3 (function)

If the path helper takes additional path parameters, just add them to the
second argument.

    iex> user_pet_path = fn _conn, :index, id, query ->
    ...>   "/users/#{id}/pets?" <> Plug.Conn.Query.encode(query)
    ...> end
    iex> flop = %Flop{page: 2, page_size: 10}
    iex> build_path({user_pet_path, [%Plug.Conn{}, :index, 123]}, flop)
    "/users/123/pets?page_size=10&page=2"

### Additional query parameters - Flop.Phoenix.build_path/3 (function)

If the last path helper argument is a query parameter list, the Flop
parameters are merged into it.

    iex> pet_url = fn _conn, :index, query ->
    ...>   "https://pets.flop/pets?" <> Plug.Conn.Query.encode(query)
    ...> end
    iex> flop = %Flop{order_by: :name, order_directions: [:desc]}
    iex> build_path({pet_url, [%Plug.Conn{}, :index, [user_id: 123]]}, flop)
    "https://pets.flop/pets?user_id=123&order_directions[]=desc&order_by=name"
    iex> build_path(
    ...>   {pet_url,
    ...>    [%Plug.Conn{}, :index, [category: "small", user_id: 123]]},
    ...>   flop
    ...> )
    "https://pets.flop/pets?category=small&user_id=123&order_directions[]=desc&order_by=name"

### Set page as path parameter - Flop.Phoenix.build_path/3 (function)

Finally, you can also pass a function that takes the Flop parameters as
a keyword list as an argument. Default values will not be included in the
parameters passed to the function. You can use this if you need to set some
of the parameters as path parameters instead of query parameters.

    iex> flop = %Flop{page: 2, page_size: 10}
    iex> build_path(
    ...>   fn params ->
    ...>     {page, params} = Keyword.pop(params, :page)
    ...>     query = Plug.Conn.Query.encode(params)
    ...>     if page, do: "/pets/page/#{page}?#{query}", else: "/pets?#{query}"
    ...>   end,
    ...>   flop
    ...> )
    "/pets/page/2?page_size=10"

Note that in this example, the anonymous function just returns a string. With
Phoenix 1.7, you will be able to use verified routes.

    build_path(
      fn params ->
        {page, query} = Keyword.pop(params, :page)
        if page, do: ~p"/pets/page/#{page}?#{query}", else: ~p"/pets?#{query}"
      end,
      flop
    )

Note that the keyword list passed to the path builder function is built using
`Plug.Conn.Query.encode/2`, which means filters are formatted as map with
integer keys.

### Set filter value as path parameter - Flop.Phoenix.build_path/3 (function)

If you need to set a filter value as a path parameter, you can use
`Flop.Filter.pop/3`.

    iex> flop = %Flop{
    ...>   page: 5,
    ...>   order_by: [:published_at],
    ...>   filters: [
    ...>     %Flop.Filter{field: :category, op: :==, value: "announcements"}
    ...>   ]
    ...> }
    iex> build_path(
    ...>   fn params ->
    ...>     {page, params} = Keyword.pop(params, :page)
    ...>     filters = Keyword.get(params, :filters, [])
    ...>     {category, filters} = Flop.Filter.pop(filters, :category)
    ...>     params = Keyword.put(params, :filters, filters)
    ...>     query = Plug.Conn.Query.encode(params)
    ...>
    ...>     case {page, category} do
    ...>       {nil, nil} -> "/articles?#{query}"
    ...>       {page, nil} -> "/articles/page/#{page}?#{query}"
    ...>       {nil, %{value: category}} -> "/articles/category/#{category}?#{query}"
    ...>       {page, %{value: category}} -> "/articles/category/#{category}/page/#{page}?#{query}"
    ...>     end
    ...>   end,
    ...>   flop
    ...> )
    "/articles/category/announcements/page/5?order_by[]=published_at"

### Flop.Phoenix.cursor_pagination/1 (function)

Renders a cursor pagination element.

### Examples - Flop.Phoenix.cursor_pagination/1 (function)



### Handling parameters and JS commands - Flop.Phoenix.cursor_pagination/1 (function)

If you set the `path` assign, a link with query parameters is rendered.
In a LiveView, you need to handle the parameters in the
`c:Phoenix.LiveView.handle_params/3` callback.

    def handle_params(params, _, socket) do
      {pets, meta} = MyApp.list_pets(params)
      {:noreply, assign(socket, meta: meta, pets: pets)}
    end

If you use LiveView and set the `on_paginate` attribute, you need to update
the Flop parameters in the `handle_event/3` callback.

    def handle_event("paginate-users", %{"to" => to}, socket) do
      flop = Flop.set_cursor(socket.assigns.meta, to)
      {pets, meta} = MyApp.list_pets(flop)
      {:noreply, assign(socket, meta: meta, pets: pets)}
    end

### Getting the right parameters from Flop - Flop.Phoenix.cursor_pagination/1 (function)

This component requires the start and end cursors to be set in `Flop.Meta`. If
you pass a `Flop.Meta` struct with page or offset-based parameters, this will
result in an error. You can enforce cursor-based pagination in your query
function with the `default_pagination_type` and `pagination_types` options.

    def list_pets(params) do
      Flop.validate_and_run!(Pet, params,
        for: Pet,
        default_pagination_type: :first,
        pagination_types: [:first, :last]
      )
    end

`default_pagination_type` ensures that Flop defaults to the right pagination
type when it cannot determine the type from the parameters. `pagination_types`
ensures that parameters for other types are not accepted.

### Order fields - Flop.Phoenix.cursor_pagination/1 (function)

The pagination cursor is based on the `ORDER BY` fields of the query. It is
important that the combination of order fields is unique across the data set.
You can use:

- the field with the primary key
- a field with a unique index
- all fields of a composite primary key or unique index

If you want to order by fields that are not unique, you can add the primary
key as the last order field. For example, if you want to order by family name
and given name, you should set the `order_by` parameter to
`[:family_name, :given_name, :id]`.

### Attributes - Flop.Phoenix.cursor_pagination/1 (function)

* `meta` (`Flop.Meta`) (required) - The meta information of the query as returned by the `Flop` query functions.
* `path` (`:any`) - If set, the current view is patched with updated query parameters when a
  pagination link is clicked. In case the `on_paginate` attribute is set as
  well, the URL is patched _and_ the given JS command is executed.

  The value must be either a URI string (Phoenix verified route), an MFA or FA
  tuple (Phoenix route helper), or a 1-ary path builder function. See
  `Flop.Phoenix.build_path/3` for details.

  Defaults to `nil`.
* `on_paginate` (`Phoenix.LiveView.JS`) - A `Phoenix.LiveView.JS` command that is triggered when a pagination link is
  clicked.

  If used without the `path` attribute, you should include a `push` operation
  to handle the event with the `handle_event` callback.

      <.cursor_pagination
        meta={@meta}
        on_paginate={
          JS.dispatch("my_app:scroll_to", to: "#pet-table") |> JS.push("paginate")
        }
      />

  If used with the `path` attribute, the URL is patched _and_ the given JS
  command is executed.

      <.cursor_pagination
        meta={@meta}
        path={~"/pets"}
        on_paginate={JS.dispatch("my_app:scroll_to", to: "#pet-table")}
      />

  With the above attributes in place, you can add the following JavaScript to
  your application to scroll to the top of your table whenever a pagination
  link is clicked:

  ```js
  window.addEventListener("my_app:scroll_to", (e) => {
    e.target.scrollIntoView();
  });
  ```

  You can use CSS to scroll to the new position smoothly.

  ```css
  html {
    scroll-behavior: smooth;
  }
  ```

  Defaults to `nil`.
* `event` (`:string`) - If set, `Flop.Phoenix` will render links with a `phx-click` attribute.
  Alternatively, set `:path`, if you want the parameters to appear in the URL.
  Deprecated. Use `on_paginate` instead.

  Defaults to `nil`.
* `target` (`:string`) - Sets the `phx-target` attribute for the pagination links. Defaults to `nil`.
* `reverse` (`:boolean`) - By default, the `next` link moves forward with the `:after` parameter set to
  the end cursor, and the `previous` link moves backward with the `:before`
  parameter set to the start cursor. If `reverse` is set to `true`, the
  destinations of the links are switched.

  Defaults to `false`.
* `opts` (`:list`) - Options to customize the pagination. See
  `t:Flop.Phoenix.cursor_pagination_option/0`. Note that the options passed to
  the function are deep merged into the default options. Since these options
  will likely be the same for all the cursor pagination links in a project,
  it is recommended to define them once in a function or set them in a
  wrapper function as described in the `Customization` section of the module
  documentation.

  Defaults to `[]`.

### Flop.Phoenix.filter_fields/1 (function)

Renders all inputs for a filter form including the hidden inputs.

### Example - Flop.Phoenix.filter_fields/1 (function)

def filter_form(%{meta: meta} = assigns) do
      assigns = assign(assigns, :form, Phoenix.Component.to_form(meta))

      ~H"""
      <.form for={@form}>
        <.filter_fields :let={i} form={@form} fields={[:email, :name]}>
          <.input
            field={i.field}
            label={i.label}
            type={i.type}
            {i.rest}
          />
        </.filter_fields>
      </.form>
      """
    end

This assumes that you have defined an `input` component that renders a form
input including the label.

These options are passed to the inner block via `:let`:

- The `field` is a `Phoenix.HTML.FormField.t` struct.
- The `type` is the input type as a string, _not_ the name of the
  `Phoenix.HTML.Form` input function (e.g. `"text"`, not `:text_input`). The
  type is derived from the type of the field being filtered on, but it can
  be overridden in the field options.
- `rest` contains any additional field options passed.

### Field configuration - Flop.Phoenix.filter_fields/1 (function)

The fields can be passed as atoms or keywords with additional options.

    fields={[:name, :email]}

Or

    fields={[
      name: [label: gettext("Name")],
      email: [
        label: gettext("Email"),
        op: :ilike_and,
        type: "email"
      ],
      age: [
        label: gettext("Age"),
        type: "select",
        prompt: "",
        options: [
          {gettext("young"), :young},
          {gettext("old"), :old)}
        ]
      ]
    ]}

Available options:

- `label` - Defaults to the humanized field name.
- `op` - Defaults to `:==`.
- `type` - Defaults to an input type depending on the Ecto type of the filter
  field.

Any additional options will be passed to the input component (e.g. HTML
classes or a list of options).

### Attributes - Flop.Phoenix.filter_fields/1 (function)

* `form` (`Phoenix.HTML.Form`) (required)
* `fields` (`:list`) - The list of fields and field options. Note that inputs will not be rendered
  for fields that are not marked as filterable in the schema
  (see `Flop.Schema`).

  If `dynamic` is set to `false`, only fields in this list are rendered. If
  `dynamic` is set to `true`, only fields for filters present in the given
  `Flop.Meta` struct are rendered, and the fields are rendered even if they
  are not passed in the `fields` list. In the latter case, `fields` is
  optional, but you can still pass label and input configuration this way.

  Note that in a dynamic form, it is not possible to configure a single field
  multiple times.

  Defaults to `[]`.
* `dynamic` (`:boolean`) - If `true`, fields are only rendered for filters that are present in the
  `Flop.Meta` struct passed to the form. You can use this for rendering filter
  forms that allow the user to add and remove filters dynamically. The
  `fields` assign is only used for looking up the options in that case.

  Defaults to `false`.

### Slots - Flop.Phoenix.filter_fields/1 (function)

* `inner_block` - The necessary options for rendering a label and an input are passed to the
  inner block, which allows you to render the fields with your existing
  components.

      <.filter_fields :let={i} form={@form} fields={[:email, :name]}>
        <.input
          field={i.field}
          label={i.label}
          type={i.type}
          {i.rest}
        />
      </.filter_fields>

  The options passed to the inner block are:

  - `field` - A `Phoenix.HTML.FormField` struct.
  - `type` - The input type as a string.
  - `label` - The label text as a string.
  - `rest` - Any additional options passed in the field options.

### Flop.Phoenix.hidden_inputs_for_filter/1 (function)

Renders hidden inputs for the given form.

You can use this for convenience if you have a complex form layout that cannot
be accomplished with `Flop.Phoenix.filter_fields/1`. Put it as a direct child
of the `form` component to render the hidden inputs for pagination and order
parameters. Then use `PhoenixHTMLHelpers.Form.inputs_for/3` to render a single
filter field, and place this component within the anonymous function to render the
hidden inputs for the filter field and operator.

Since the filters are represented as an array in the params, make sure to
add the `offset` option so that the `Flop.Meta` can be properly mapped back to
your input fields. For every call to `inputs_for` always add the length of all
previous calls to `inputs_for` as offset.

    <.form :let={f} for={@meta}>
      <.hidden_inputs_for_filter form={@form} />

       
         
          <%= PhoenixHTMLHelpers.Form.inputs_for f, :filters, [fields: [:name]], fn ff -> %>
            <.hidden_inputs_for_filter form={ff} />
            <.input label="Name" type="text" field={{ff, :value}} />
          <% end %>
         
         
          <%= PhoenixHTMLHelpers.Form.inputs_for f, :filters, [fields: [{:email, op: :ilike}], offset: 1] fn ff -> %>
            <.hidden_inputs_for_filter form={ff} />
            <.input label="E-mail" type="email" field={{ff, :value}} />
          <% end %>
         
       
    </.form>

### Attributes - Flop.Phoenix.hidden_inputs_for_filter/1 (function)

* `form` (`Phoenix.HTML.Form`) (required)

### Flop.Phoenix.pagination/1 (function)

Generates a pagination element.

### Examples - Flop.Phoenix.pagination/1 (function)



### Page link options - Flop.Phoenix.pagination/1 (function)

By default, page links for all pages are shown. You can limit the number of
page links or disable them altogether by passing the `:page_links` option.

- `:all`: Show all page links (default).
- `:hide`: Don't show any page links. Only the previous/next links will be
  shown.
- `{:ellipsis, x}`: Limits the number of page links. The first and last page
  are always displayed. The `x` refers to the number of additional page links
  to show.

### Pagination link aria label - Flop.Phoenix.pagination/1 (function)

For the page links, there is the `:pagination_link_aria_label` option to set
the aria label. Since the page number is usually part of the aria label, you
need to pass a function that takes the page number as an integer and returns
the label as a string. The default is `&"Goto page #{&1}"`.

### Previous/next links - Flop.Phoenix.pagination/1 (function)

By default, the previous and next links contain the texts `Previous` and
`Next`. To change this, you can pass the `:previous_link_content` and
`:next_link_content` options.

### Attributes - Flop.Phoenix.pagination/1 (function)

* `meta` (`Flop.Meta`) (required) - The meta information of the query as returned by the `Flop` query functions.
* `path` (`:any`) - If set, the current view is patched with updated query parameters when a
  pagination link is clicked. In case the `on_paginate` attribute is set as
  well, the URL is patched _and_ the given command is executed.

  The value must be either a URI string (Phoenix verified route), an MFA or FA
  tuple (Phoenix route helper), or a 1-ary path builder function. See
  `Flop.Phoenix.build_path/3` for details.

  Defaults to `nil`.
* `on_paginate` (`Phoenix.LiveView.JS`) - A `Phoenix.LiveView.JS` command that is triggered when a pagination link is
  clicked.

  If used without the `path` attribute, you should include a `push` operation
  to handle the event with the `handle_event` callback.

      <.pagination
        meta={@meta}
        on_paginate={
          JS.dispatch("my_app:scroll_to", to: "#pet-table") |> JS.push("paginate")
        }
      />

  If used with the `path` attribute, the URL is patched _and_ the given
  JS command is executed.

      <.pagination
        meta={@meta}
        path={~"/pets"}
        on_paginate={JS.dispatch("my_app:scroll_to", to: "#pet-table")}
      />

  With the above attributes in place, you can add the following JavaScript to
  your application to scroll to the top of your table whenever a pagination
  link is clicked:

  ```js
  window.addEventListener("my_app:scroll_to", (e) => {
    e.target.scrollIntoView();
  });
  ```

  You can use CSS to scroll to the new position smoothly.

  ```css
  html {
    scroll-behavior: smooth;
  }
  ```

  Defaults to `nil`.
* `event` (`:string`) - If set, `Flop.Phoenix` will render links with a `phx-click` attribute.
  Alternatively, set `:path`, if you want the parameters to appear in the URL.
  Deprecated in favor of `on_paginate`.

  Defaults to `nil`.
* `target` (`:string`) - Sets the `phx-target` attribute for the pagination links. Defaults to `nil`.
* `opts` (`:list`) - Options to customize the pagination. See
  `t:Flop.Phoenix.pagination_option/0`. Note that the options passed to the
  function are deep merged into the default options. Since these options will
  likely be the same for all the tables in a project, it is recommended to
  define them once in a function or set them in a wrapper function as
  described in the `Customization` section of the module documentation.

  Defaults to `[]`.

### Flop.Phoenix.table/1 (function)

Generates a table with sortable columns.

### Example - Flop.Phoenix.table/1 (function)

```elixir
 
  <:col :let={pet} label="Name" field={:name}><%= pet.name %></:col>
  <:col :let={pet} label="Age" field={:age}><%= pet.age %></:col>
 
```

### Flop.Schema - Flop.Phoenix.table/1 (function)

If you pass the `for` option when making the query with Flop, Flop Phoenix can
determine which table columns are sortable. It also hides the `order` and
`page_size` parameters if they match the default values defined with
`Flop.Schema`.

### Attributes - Flop.Phoenix.table/1 (function)

* `id` (`:string`) - ID used on the table. If not set, an ID is chosen based on the schema
  module derived from the `Flop.Meta` struct.

  The ID is necessary in case the table is fed with a LiveView stream.

* `items` (`:list`) (required) - The list of items to be displayed in rows. This is the result list returned
  by the query.

* `meta` (`Flop.Meta`) (required) - The `Flop.Meta` struct returned by the query function.
* `path` (`:any`) - If set, the current view is patched with updated query parameters when a
  header link for sorting is clicked. In case the `on_sort` attribute is
  set as well, the URL is patched _and_ the given JS command is executed.

  The value must be either a URI string (Phoenix verified route), an MFA or FA
  tuple (Phoenix route helper), or a 1-ary path builder function. See
  `Flop.Phoenix.build_path/3` for details.

  Defaults to `nil`.
* `on_sort` (`Phoenix.LiveView.JS`) - A `Phoenix.LiveView.JS` command that is triggered when a header link for
  sorting is clicked.

  If used without the `path` attribute, you should include a `push` operation
  to handle the event with the `handle_event` callback.

      <.table
        items={@items}
        meta={@meta}
        on_sort={
          JS.dispatch("my_app:scroll_to", to: "#pet-table") |> JS.push("sort")
        }
      />

  If used with the `path` attribute, the URL is patched _and_ the given
  JS command is executed.

      <.table
        meta={@meta}
        path={~"/pets"}
        on_sort={JS.dispatch("my_app:scroll_to", to: "#pet-table")}
      />

  Defaults to `nil`.
* `event` (`:string`) - If set, `Flop.Phoenix` will render links with a `phx-click` attribute.
  Alternatively, set `:path`, if you want the parameters to appear in the URL.
  Deprecated in favor of `on_sort`.

  Defaults to `nil`.
* `target` (`:string`) - Sets the `phx-target` attribute for the header links. Defaults to `nil`.
* `caption` (`:string`) - Content for the ` ` element. Defaults to `nil`.
* `opts` (`:list`) - Keyword list with additional options (see `t:Flop.Phoenix.table_option/0`).
  Note that the options passed to the function are deep merged into the
  default options. Since these options will likely be the same for all the
  tables in a project, it is recommended to define them once in a function or
  set them in a wrapper function as described in the `Customization` section
  of the module documentation.

  Defaults to `[]`.
* `row_id` (`:any`) - Overrides the default function that retrieves the row ID from a stream item. Defaults to `nil`.
* `row_click` (`:any`) - Sets the `phx-click` function attribute for each row `td`. Expects to be a
  function that receives a row item as an argument. This does not add the
  `phx-click` attribute to the `action` slot.

  Example:

  ```elixir
  row_click={&JS.navigate(~p"/users/#{&1}")}
  ```

  Defaults to `nil`.
* `row_item` (`:any`) - This function is called on the row item before it is passed to the :col
  and :action slots.

  Defaults to `&Function.identity/1`.

### Slots - Flop.Phoenix.table/1 (function)

* `col` (required) - For each column to render, add one `<:col>` element.

  ```elixir
  <:col :let={pet} label="Name" field={:name} col_style="width: 20%;">
    <%= pet.name %>
  </:col>
  ```

  Any additional assigns will be added as attributes to the ` ` elements.

  Accepts attributes:

  * `label` (`:any`) - The content for the header column.
  * `field` (`:atom`) - The field name for sorting. If set and the field is configured as sortable
    in the schema, the column header will be clickable, allowing the user to
    sort by that column. If the field is not marked as sortable or if the
    `field` attribute is omitted or set to `nil` or `false`, the column header
    will not be clickable.

  * `directions` (`:any`) - An optional 2-element tuple used for custom ascending and descending sort
    behavior for the column, i.e. `{:asc_nulls_last, :desc_nulls_first}`

  * `show` (`:boolean`) - Boolean value to conditionally show the column. Defaults to `true`
    Deprecated. Use `:if` instead.

  * `hide` (`:boolean`) - Boolean value to conditionally hide the column. Defaults to `false`.
    Deprecated. Use `:if` instead.

  * `col_style` (`:string`) - If set, a ` ` element is rendered and the value of the
    `col_style` assign is set as `style` attribute for the ` ` element of
    the respective column. You can set the `width`, `background`, `border`,
    and `visibility` of a column this way.

  * `col_class` (`:string`) - If set, a ` ` element is rendered and the value of the
    `col_class` assign is set as `class` attribute for the ` ` element of
    the respective column. You can set the `width`, `background`, `border`,
    and `visibility` of a column this way.

  * `thead_th_attrs` (`:list`) - Additional attributes to pass to the ` ` element as a static keyword
    list. Note that these attributes will override any conflicting
    `thead_th_attrs` that are set at the table level.

  * `th_wrapper_attrs` (`:list`) - Additional attributes for the ` ` element that wraps the
    header link and the order direction symbol. Note that these attributes
    will override any conflicting `th_wrapper_attrs` that are set at the table
    level.

  * `tbody_td_attrs` (`:any`) - Additional attributes to pass to the ` ` element. May be provided as a
    static keyword list, or as a 1-arity function to dynamically generate the
    list using row data. Note that these attributes will override any
    conflicting `tbody_td_attrs` that are set at the table level.

* `action` - The slot for showing user actions in the last table column. These columns
  do not receive the `row_click` attribute.


  ```elixir
  <:action :let={user}>
    <.link navigate={~p"/users/#{user}"}>Show</.link>
  </:action>
  ```

  Accepts attributes:

  * `label` (`:string`) - The content for the header column.
  * `show` (`:boolean`) - Boolean value to conditionally show the column. Defaults to `true`.
  * `hide` (`:boolean`) - Boolean value to conditionally hide the column. Defaults to `false`.
  * `col_style` (`:string`) - If set, a ` ` element is rendered and the value of the
    `col_style` assign is set as `style` attribute for the ` ` element of
    the respective column. You can set the `width`, `background`, `border`,
    and `visibility` of a column this way.

  * `col_class` (`:string`) - If set, a ` ` element is rendered and the value of the
    `col_class` assign is set as `class` attribute for the ` ` element of
    the respective column. You can set the `width`, `background`, `border`,
    and `visibility` of a column this way.

  * `thead_th_attrs` (`:list`) - Any additional attributes to pass to the ` ` as a keyword list.
  * `tbody_td_attrs` (`:any`) - Any additional attributes to pass to the ` `. Can be a keyword list or
    a function that takes the current row item as an argument and returns a
    keyword list.

* `foot` - You can optionally add a `foot`. The inner block will be rendered inside
  a `tfoot` element.

       
        <:foot>
            Total:  <%= @total %>   
        </:foot>

### Flop.Phoenix.to_query/2 (function)

Converts a Flop struct into a keyword list that can be used as a query with
Phoenix verified routes or route helper functions.

### Default parameters - Flop.Phoenix.to_query/2 (function)

Default parameters for the limit and order parameters are omitted. The
defaults are determined by calling `Flop.get_option/3`.

- Pass the `:for` option to pick up the default values from a schema module
  deriving `Flop.Schema`.
- Pass the `:backend` option to pick up the default values from your backend
  configuration.
- If neither the schema module nor the backend module have default options
  set, the function will fall back to the application environment.

### Encoding queries - Flop.Phoenix.to_query/2 (function)

To encode the returned query as a string, you will need to use
`Plug.Conn.Query.encode/1`. `URI.encode_query/1` does not support bracket
notation for arrays and maps.

### Date and time filters - Flop.Phoenix.to_query/2 (function)

If you use the result of this function directly with
`Phoenix.VerifiedRoutes.sigil_p/2` for verified routes or in a route helper
function, all cast filter values need to be able to be converted to a string
using the `Phoenix.Param` protocol.

This protocol is implemented by default for integers, binaries, atoms, and
structs. For structs, Phoenix's default behavior is to fetch the id field.

If you have filters with `Date`, `DateTime`, `NaiveDateTime`,
`Time` values, or any other custom structs (e.g. structs that represent
composite types like a range column), you will need to implement the protocol
for these specific structs in your application.

    defimpl Phoenix.Param, for: Date do
      def to_param(%Date{} = d), do: to_string(d)
    end

    defimpl Phoenix.Param, for: DateTime do
      def to_param(%DateTime{} = dt), do: to_string(dt)
    end

    defimpl Phoenix.Param, for: NaiveDateTime do
      def to_param(%NaiveDateTime{} = dt), do: to_string(dt)
    end

    defimpl Phoenix.Param, for: Time do
      def to_param(%Time{} = t), do: to_string(t)
    end

It is important that the chosen string representation can be cast back into
the Ecto type.

### Examples - Flop.Phoenix.to_query/2 (function)

iex> to_query(%Flop{})
    []

    iex> f = %Flop{page: 5, page_size: 20}
    iex> to_query(f)
    [page_size: 20, page: 5]

    iex> f = %Flop{first: 20, after: "g3QAAAABZAAEbmFtZW0AAAAFQXBwbGU="}
    iex> to_query(f)
    [first: 20, after: "g3QAAAABZAAEbmFtZW0AAAAFQXBwbGU="]

    iex> f = %Flop{
    ...>   filters: [
    ...>     %Flop.Filter{field: :name, op: :=~, value: "Mag"},
    ...>     %Flop.Filter{field: :age, op: :>, value: 25}
    ...>   ]
    ...> }
    iex> to_query(f)
    [
      filters: %{
        0 => %{field: :name, op: :=~, value: "Mag"},
        1 => %{field: :age, op: :>, value: 25}
      }
    ]
    iex> to_query(f)
    [filters: %{0 => %{value: "Mag", op: :=~, field: :name}, 1 => %{value: 25, op: :>, field: :age}}]

    iex> f = %Flop{page: 5, page_size: 20}
    iex> to_query(f, default_limit: 20)
    [page: 5]

Encoding the query as a string:

    iex> f = %Flop{order_by: [:name, :age], order_directions: [:desc, :asc]}
    iex> to_query(f)
    [order_directions: [:desc, :asc], order_by: [:name, :age]]
    iex> f |> to_query |> Plug.Conn.Query.encode()
    "order_directions[]=desc&order_directions[]=asc&order_by[]=name&order_by[]=age"

### Flop.Phoenix.cursor_pagination_option/0 (type)

Defines the available options for `Flop.Phoenix.cursor_pagination/1`.

- `:disabled_class` - The class which is added to disabled links. Default:
  `"disabled"`.
- `:next_link_attrs` - The attributes for the link to the next page.
  Default: `[aria: [label: "Go to next page"], class: "pagination-next"]`.
- `:next_link_content` - The content for the link to the next page.
  Default: `"Next"`.
- `:previous_link_attrs` - The attributes for the link to the previous page.
  Default: `[aria: [label: "Go to previous page"], class: "pagination-previous"]`.
- `:previous_link_content` - The content for the link to the previous page.
  Default: `"Previous"`.
- `:wrapper_attrs` - The attributes for the ` ` element that wraps the
  pagination links.
  Default: `[class: "pagination", role: "navigation", aria: [label: "pagination"]]`.

### Flop.Phoenix.pagination_option/0 (type)

Defines the available options for `Flop.Phoenix.pagination/1`.

- `:current_link_attrs` - The attributes for the link to the current page.
  Default: `[class: "pagination-link is-current", aria: [current: "page"]]`.
- `:disabled_class` - The class which is added to disabled links. Default:
  `"disabled"`.
- `:ellipsis_attrs` - The attributes for the ` ` that wraps the
  ellipsis.
  Default: `[class: "pagination-ellipsis"]`.
- `:ellipsis_content` - The content for the ellipsis element.
  Default: `{:safe, "&hellip;"}`.
- `:next_link_attrs` - The attributes for the link to the next page.
  Default: `[aria: [label: "Go to next page"], class: "pagination-next"]`.
- `:next_link_content` - The content for the link to the next page.
  Default: `"Next"`.
- `:page_links` - Specifies how many page links should be rendered.
  Default: `:all`.
  - `:all` - Renders all page links.
  - `{:ellipsis, n}` - Renders `n` page links. Renders ellipsis elements if
    there are more pages than displayed.
  - `:hide` - Does not render any page links.
- `:pagination_link_aria_label` - 1-arity function that takes a page number
  and returns an aria label for the corresponding page link.
  Default: `&"Go to page #{&1}"`.
- `:pagination_link_attrs` - The attributes for the pagination links.
  Default: `[class: "pagination-link"]`.
- `:pagination_list_attrs` - The attributes for the pagination list.
  Default: `[class: "pagination-list"]`.
- `:pagination_list_item_attrs` - The attributes for the pagination list items.
  Default: `[]`.
- `:previous_link_attrs` - The attributes for the link to the previous page.
  Default: `[aria: [label: "Go to previous page"], class: "pagination-previous"]`.
- `:previous_link_content` - The content for the link to the previous page.
  Default: `"Previous"`.
- `:wrapper_attrs` - The attributes for the ` ` element that wraps the
  pagination links.
  Default: `[class: "pagination", role: "navigation", aria: [label: "pagination"]]`.

### Flop.Phoenix.table_option/0 (type)

Defines the available options for `Flop.Phoenix.table/1`.

- `:container` - Wraps the table in a ` ` if `true`.
  Default: `false`.
- `:container_attrs` - The attributes for the table container.
  Default: `[class: "table-container"]`.
- `:no_results_content` - Any content that should be rendered if there are no
  results. Default: ` No results. `.
- `:table_attrs` - The attributes for the ` ` element.
  Default: `[]`.
- `:th_wrapper_attrs` - The attributes for the ` ` element that wraps the
  header link and the order direction symbol.
  Default: `[]`.
- `:symbol_asc` - The symbol that is used to indicate that the column is
  sorted in ascending order.
  Default: `"▴"`.
- `:symbol_attrs` - The attributes for the ` ` element that wraps the
  order direction indicator in the header columns.
  Default: `[class: "order-direction"]`.
- `:symbol_desc` - The symbol that is used to indicate that the column is
  sorted in ascending order.
  Default: `"▾"`.
- `:symbol_unsorted` - The symbol that is used to indicate that the column is
  not sorted. Default: `nil`.
- `:tbody_attrs`: Attributes to be added to the ` ` tag within the
  ` `. Default: `[]`.
- `:tbody_td_attrs`: Attributes to be added to each ` ` tag within the
  ` `. Default: `[]`.
- `:thead_attrs`: Attributes to be added to the ` ` tag within the
  ` `. Default: `[]`.
- `:tbody_tr_attrs`: Attributes to be added to each ` ` tag within the
  ` `. A function with arity of 1 may be passed to dynamically generate
  the attrs based on row data.
  Default: `[]`.
- `:thead_th_attrs`: Attributes to be added to each ` ` tag within the
  ` `. Default: `[]`.
- `:thead_tr_attrs`: Attributes to be added to each ` ` tag within the
  ` `. Default: `[]`.

### Flop.Phoenix.IncorrectPaginationTypeError.message/1 (function)



### Flop.Phoenix.InvalidFilterFieldConfigError.message/1 (function)



### Flop.Phoenix.NoMetaFormError.message/1 (function)



### Flop.Phoenix.PathOrJSError.message/1 (function)



## Links

- [Online documentation](https://hexdocs.pm/flop_phoenix)