@spec cursor_pagination(map()) :: Phoenix.LiveView.Rendered.t()

Renders a cursor pagination element.

example

Example

<Flop.Phoenix.cursor_pagination
  meta={@meta}
  path={{Routes, :pet_path, [@socket, :index]}}
/>

handling-parameters-and-events

Handling parameters and events

If you set the path assign, a link with query parameters is rendered. In a LiveView, you need to handle the parameters in the 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 event assign, 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

Getting the right parameters from Flop

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

Order fields

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

Attributes

• meta (Flop.Meta) (required) - The meta information of the query as returned by the Flop query functions.

• path (:any) - 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. If set, links will be rendered with Phoenix.Components.link/1 with the patch attribute. In a LiveView, the parameters will have to be handled in the handle_params/3 callback of the LiveView module. Alternatively, set :event, if you don't want the parameters to appear in the URL.

  Defaults to nil.

• path_helper (:any) - Deprecated. Use :path instead. 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.

  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 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 [].

@spec filter_fields(map()) :: Phoenix.LiveView.Rendered.t()

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

example

Example

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

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

Most options passed to the inner block should be self-explaining.

• 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.
• The field is a Phoenix.HTML.Form.t / field name tuple (e.g. {f, :name}).
• rest contains any additional field options passed.

field-configuration

Field configuration

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_input"
  ],
  age: [
    label: gettext("Age"),
    type: "select",
    prompt: "",
    options: [
      {gettext("young"), :young},
      {gettext("old"), :old)}
    ]
  ]
]}

Available options:

• label
• op
• type

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

attributes

Attributes

• 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

Slots

• 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={f} fields={[:email, :name]}>
    <.label for={i.id}><%= i.label %></.label>
    <.input
      id={i.id}
      name={i.name}
      label={i.label}
      type={i.type}
      value={i.value}
      field={{i.form, i.field}}
      {i.rest}
    />
  </.filter_fields>

  The options passed to the inner block are:
  • id - The input ID.
  • name - The input name.
  • label - The label text as a string.
  • type - The input type as a string. This is not the value returned by Phoenix.HTML.Form.input_type/2.
  • value - The input value.
  • form - The %Phoenix.HTML.Form{} struct.
  • field - The field name as an atom.
  • rest - Any additional options passed in the field options.

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 Phoenix.HTML.Form.inputs_for/3 to render a single filter field, and place this component within the do block to render the hidden inputs for the filter field and operator.

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

  <div class="field-group">
    <div class="field">
      <%= for ff <- Phoenix.HTML.Form.inputs_for(f, :filters, fields: [:name]) do %>
        <.hidden_inputs_for_filter form={ff} />
        <.input label="Name" type="text" field={{ff, :value}} />
      <% end %>
    </div>
    <div class="field">
      <%= for ff <- Phoenix.HTML.Form.inputs_for(f, :filters, fields: [:email]) do %>
        <.hidden_inputs_for_filter form={ff} />
        <.input label="E-mail" type="email" field={{ff, :value}} />
      <% end %>
    </div>
  </div>
</.form>

attributes

Attributes

• form (Phoenix.HTML.Form) (required)
• id (:string) - Defaults to nil.

@spec pagination(map()) :: Phoenix.LiveView.Rendered.t()

Generates a pagination element.

examples

Examples

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

<Flop.Phoenix.pagination
  meta={@meta}
  path={{Routes, :pet_path, [@socket, :index]}}
/>

page-link-options

Page link options

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

Pagination link aria label

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

Previous/next links

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

Attributes

• meta (Flop.Meta) (required) - The meta information of the query as returned by the Flop query functions.

• path (:any) - 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. If set, links will be rendered with Phoenix.Components.link/1 with the patch attribute. In a LiveView, the parameters will have to be handled in the handle_params/3 callback of the LiveView module. Alternatively, set :event, if you don't want the parameters to appear in the URL.

  Defaults to nil.

• path_helper (:any) - Deprecated. Use :path instead. 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.

  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 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 [].

@spec table(map()) :: Phoenix.LiveView.Rendered.t()

Generates a table with sortable columns.

example

Example

<Flop.Phoenix.table
  items={@pets}
  meta={@meta}
  path={{Routes, :pet_path, [@socket, :index]}}
>
  <:col :let={pet} label="Name" field={:name}><%= pet.name %></:col>
  <:col :let={pet} label="Age" field={:age}><%= pet.age %></:col>
</Flop.Phoenix.table>

flop-schema

Flop.Schema

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

Attributes

• 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) - 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. If set, links will be rendered with Phoenix.Components.link/1 with the patch attribute. In a LiveView, the parameters will have to be handled in the handle_params/3 callback of the LiveView module. Alternatively, set :event, if you don't want the parameters to appear in the URL.

  Defaults to nil.

• path_helper (:any) - Deprecated. Use :path instead. 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.

  Defaults to nil.

• target (:string) - Sets the phx-target attribute for the header links. Defaults to nil.

• caption (:string) - Content for the <caption> element. Defaults to nil.

• opts (:list) - Keyword list with additional options (see 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_click (Phoenix.LiveView.JS) - 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 apply add the phx-click attribute to the action slot.

  For example:

  row_click={&JS.navigate(Routes.show_user_path(@socket, user, &1))}

  Results in:

  <tr>
    <td phx-click={"/user/1/show"}>...</td>
    <td phx-click={"/user/1/show"}>...</td>
  </tr>

  Defaults to nil.

slots

Slots

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

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

  Any additional assigns will be added as attributes to the <td> elements.

  Accepts attributes:

  • label (:string) - The content for the header column.

  • field (:atom) - The field name for sorting.

  • 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 <colgroup> element is rendered and the value of the col_style assign is set as style attribute for the <col> element of the respective column. You can set the width, background and border of a column this way.

  • attrs (:list) - Any additional attributes to pass to the <td>.

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

  <:action :let={user}>
    <.link navigate={Routes.user_path(@socket, :show, 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 <colgroup> element is rendered and the value of the col_style assign is set as style attribute for the <col> element of the respective column. You can set the width, background and border of a column this way.

  • attrs (:list) - Any additional attributes to pass to the <td>.

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

  <Flop.Phoenix.table>
    <:foot>
      <tr><td>Total: <span class="total"><%= @total %></span></td></tr>
    </:foot>
  </Flop.Phoenix.table>