Specs

build_path(function(), [any()], Flop.Meta.t() | Flop.t() | keyword(), keyword()) ::
  String.t()

Takes a Phoenix path helper function and a list of path helper arguments and builds a path that includes query parameters for the given Flop struct.

Default values for limit, page_size, order_by and order_directions are omit from the query parameters. To pick up the default parameters from a schema module deriving Flop.Schema, you need to pass the :for option.

Examples

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/3 as the first argument.

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"

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"

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"