` element."
attr :opts, :list,
default: [],
doc: """
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.
"""
attr :row_id, :any,
default: nil,
doc: """
Overrides the default function that retrieves the row ID from a stream item.
"""
attr :row_click, :any,
default: nil,
doc: """
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}")}
```
"""
attr :row_item, :any,
default: &Function.identity/1,
doc: """
This function is called on the row item before it is passed to the :col
and :action slots.
"""
slot :col,
required: true,
doc: """
For each column to render, add one `<:col>` element.
```elixir
<:col :let={pet} label="Name" field={:name} col_style="width: 20%;">
{pet.name}
```
Any additional assigns will be added as attributes to the `` elements.
""" do
attr :label, :any, doc: "The content for the header column."
attr :field, :atom,
doc: """
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.
"""
attr :directions, :any,
doc: """
An optional 2-element tuple used for custom ascending and descending sort
behavior for the column, i.e. `{:asc_nulls_last, :desc_nulls_first}`
"""
attr :col_style, :string,
doc: """
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.
"""
attr :col_class, :string,
doc: """
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.
"""
attr :thead_th_attrs, :list,
doc: """
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.
"""
attr :th_wrapper_attrs, :list,
doc: """
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.
"""
attr :tbody_td_attrs, :any,
doc: """
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.
"""
end
slot :action,
doc: """
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
```
""" do
attr :label, :string, doc: "The content for the header column."
attr :col_style, :string,
doc: """
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.
"""
attr :col_class, :string,
doc: """
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.
"""
attr :thead_th_attrs, :list,
doc: """
Any additional attributes to pass to the `| ` as a keyword list.
"""
attr :tbody_td_attrs, :any,
doc: """
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.
"""
end
slot :foot,
doc: """
You can optionally add a `foot`. The inner block will be rendered inside
a `tfoot` element.
```heex
<:foot>
| Total: {@total} |
```
"""
def table(%{path: nil, on_sort: nil}) do
raise Flop.Phoenix.PathOrJSError, component: :table
end
def table(%{meta: meta, opts: opts} = assigns) do
assigns =
assigns
|> assign(:opts, Table.merge_opts(opts))
|> assign_new(:id, fn -> table_id(meta.schema) end)
~H"""
<%= if @items == [] do %>
{@opts[:no_results_content]}
<% else %>
<%= if @opts[:container] do %>
"-container"} {@opts[:container_attrs]}>
<%= 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 %>
```
"""
@doc since: "0.16.0"
@doc section: :components
attr :form, Phoenix.HTML.Form, required: true
def hidden_inputs_for_filter(assigns) do
~H"""
<.hidden_inputs
:for={{field, value} <- @form.hidden}
form={@form}
field={field}
value={value}
/>
"""
end
attr :form, Phoenix.HTML.Form, required: true
attr :field, :atom, required: true
attr :value, :any, required: true
defp hidden_inputs(%{value: value} = assigns) when is_list(value) do
~H"""
"_#{index}"}
name={input_name(@form, @field) <> "[]"}
value={v}
hidden
/>
"""
end
defp hidden_inputs(assigns) do
~H"""
"""
end
@doc """
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
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
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
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
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"
"""
@doc since: "0.6.0"
@spec to_query(Flop.t()) :: keyword
def to_query(%Flop{filters: filters} = flop, opts \\ []) do
filter_map =
filters
|> Stream.with_index()
|> Enum.into(%{}, fn {filter, index} ->
{index, Map.from_struct(filter)}
end)
default_limit = Flop.get_option(:default_limit, opts)
default_order = Flop.get_option(:default_order, opts)
[]
|> Misc.maybe_put(:offset, flop.offset, 0)
|> Misc.maybe_put(:page, flop.page, 1)
|> Misc.maybe_put(:after, flop.after)
|> Misc.maybe_put(:before, flop.before)
|> Misc.maybe_put(:page_size, flop.page_size, default_limit)
|> Misc.maybe_put(:limit, flop.limit, default_limit)
|> Misc.maybe_put(:first, flop.first, default_limit)
|> Misc.maybe_put(:last, flop.last, default_limit)
|> Misc.maybe_put_order_params(flop, default_order)
|> Misc.maybe_put(:filters, filter_map)
end
@doc """
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
### With a verified route
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
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
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
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
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
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
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
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"
"""
@doc since: "0.6.0"
@spec build_path(
String.t()
| {module, atom, [any]}
| {function, [any]}
| (keyword -> String.t()),
Meta.t() | Flop.t() | keyword,
keyword
) :: String.t()
def build_path(path, meta_or_flop_or_params, opts \\ [])
def build_path(
path,
%Meta{backend: backend, flop: flop, schema: schema},
opts
) do
build_path(
path,
flop,
opts |> Keyword.put(:backend, backend) |> Keyword.put(:for, schema)
)
end
def build_path(path, %Flop{} = flop, opts) do
build_path(path, Flop.Phoenix.to_query(flop, opts))
end
def build_path({module, func, args}, flop_params, _opts)
when is_atom(module) and
is_atom(func) and
is_list(args) and
is_list(flop_params) do
final_args = build_final_args(args, flop_params)
apply(module, func, final_args)
end
def build_path({func, args}, flop_params, _opts)
when is_function(func) and
is_list(args) and
is_list(flop_params) do
final_args = build_final_args(args, flop_params)
apply(func, final_args)
end
def build_path(func, flop_params, _opts)
when is_function(func, 1) and is_list(flop_params) do
func.(flop_params)
end
def build_path(uri, flop_params, _opts)
when is_binary(uri) and is_list(flop_params) do
uri = URI.parse(uri)
query =
(uri.query || "")
|> Query.decode()
|> Map.merge(Map.new(flop_params))
query = if query != %{}, do: Query.encode(query), else: nil
uri
|> Map.put(:query, query)
|> URI.to_string()
end
defp build_final_args(args, flop_params) do
case Enum.reverse(args) do
[last_arg | rest] when is_list(last_arg) ->
query_arg = Keyword.merge(last_arg, flop_params)
Enum.reverse([query_arg | rest])
_ ->
args ++ [flop_params]
end
end
end
| | |