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

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

Example

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 struct.
• The type is the input type as a string (e.g. "text", "number"). 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

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

• 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

• 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.

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. Note that the example below uses the old PhoenixHTMLHelpers.Form.inputs_for/4 function. Phoenix.Component.inputs_for/1 currently overrides the index set by Flop.Phoenix.FormData, which leads to duplicate DOM IDs.

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

  <div class="field-group">
    <div class="field">
      <%= 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 %>
    </div>
    <div class="field">
      <%= 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 %>
    </div>
  </div>
</.form>

Attributes

• form (Phoenix.HTML.Form) (required)

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

Renders pagination links for the given Flop.Meta struct.

This component can render both page-based or cursor-based pagination links. Which one is used depends on the pagination type that was used to make the Flop query.

Examples

With a verified route:

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

With a route helper:

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

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

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

• 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={~p"/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:

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

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

  html {
    scroll-behavior: smooth;
  }

  Defaults to nil.

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

• page_links (:any) - Defines how many page links to render.

  • :all - Renders all page links.
  • :none - Does not render any page links.
  • Integer - Renders up to the specified number of page links in addition to the first and last page.

  This attribute is only used for page-based pagination.

  Defaults to 5.

• 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.

  This attribute is only for for cursor-based pagination.

  Defaults to false.

• 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 pagination_for(map()) :: Phoenix.LiveView.Rendered.t()

This component is a pagination builder.

It does not render anything by itself. Instead, it prepares all the necessary information needed to render a pagination component and passes it to the inner block.

For an example implementation, see pagination/1.

Example

<.pagination_for
  :let={p}
  meta={@meta}
  page_links={4}
  path={~p"/birds"}
>
  <%!--
  The variable passed to the inner block via `:let` looks similar to:

  %{
    current_page: 6,
    ellipsis_start?: true,
    ellipsis_end?: true,
    next_page: 7,
    page_range_end: 8,
    path_fun: #Function<42.18682967/1 in :erl_eval.expr/6>,
    page_range_start: 5,
    pagination_type: :page,
    previous_page: 5,
    total_pages: 10
  }
  %>
</.pagination_for>

Attributes

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

• path (:any) - If set, a function that takes a page number and returns a link with pagination, filter, and sort parameters based on the given path is passed as path_fun to the inner block.

  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.

• page_links (:any) - Defines how many page links to render.

  • :all - Renders all page links.
  • :none - Does not render any page links.
  • Integer - Renders up to the specified number of page links in addition to the first and last page.

  A page_range_start and page_range_end attribute are passed to the inner block based on this option. If this attribute is set to :none, both of those values will be nil.

  Defaults to 5.

• 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.

Slots

• inner_block (required)

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

Generates a table with sortable columns.

Example

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

• 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={~p"/pets"}
    on_sort={JS.dispatch("my_app:scroll_to", to: "#pet-table")}
  />

  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_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:

  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

• 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 (: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}

  • 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, border, and visibility of a column this way.

  • col_class (:string) - If set, a <colgroup> element is rendered and the value of the col_class assign is set as class attribute for the <col> 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 <th> 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 <span> 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 <td> 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.

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

  Accepts attributes:

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

  • 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, border, and visibility of a column this way.

  • col_class (:string) - If set, a <colgroup> element is rendered and the value of the col_class assign is set as class attribute for the <col> 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 <th> as a keyword list.

  • tbody_td_attrs (:any) - Any additional attributes to pass to the <td>. 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.

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