@callback assign_uploads(field :: tuple(), socket :: Phoenix.LiveView.Socket.t()) ::
  Phoenix.LiveView.Socket.t()

This function will be called in the FormComponent and may be used to assign uploads.

@callback association?(field :: tuple()) :: boolean()

Determines whether the field is an association or not.

@callback before_changeset(
  changeset :: Phoenix.LiveView.Socket.t(),
  attrs :: map(),
  metadata :: keyword(),
  repo :: module(),
  field :: tuple(),
  assigns :: map()
) :: Ecto.Changeset.t()

This function is called before the changeset function is called. This allows fields to modify the changeset. The Backpex.Fields.HasMany uses this callback to put the linked associations into the changeset.

@callback consume_upload(
  field :: tuple(),
  socket :: Phoenix.LiveView.Socket.t(),
  item :: struct(),
  meta :: map(),
  entry :: Phoenix.LiveView.UploadEntry.t()
) :: {:ok, term()} | {:postpone, term()}

Consumes an uploaded entry after the item has been saved.

The form component calls it for every entry as the callback of Phoenix.LiveView.consume_uploaded_entries/3, with the saved item. See list_existing_files/2.

@callback display_field(field :: tuple()) :: atom()

The field to be displayed on index views. In most cases this is the name / key configured in the corresponding field definition. In fields with associations this value often differs from the name / key. The function will receive the field definition.

@callback index_assigns(field :: tuple(), items :: list(), assigns :: map()) :: map()

Returns assigns for the field on the index view, loaded once for all items of the page.

Backpex calls it whenever the items of the index view change (e.g. when loading a page, filtering or on item events) and merges the returned map into the assigns of the field in every row. It receives the field, the items of the page and the assigns of the index view. Use it to load data the field needs, such as the select options of render_index_form/1, with a constant number of queries instead of one query per row and render. Data that differs per row can be returned keyed by the item, e.g. by its primary value.

Also see the index edit guide.

@callback index_editable_change(field :: tuple(), value :: any(), assigns :: map()) ::
  map() | :error

Returns the change that saves the value of an inline edit on the index view, e.g. %{title: "New title"}.

The index view only saves inline edits of fields that implement this callback. It calls it when an index form rendered with Backpex.HTML.Form.index_form/1 changes. It receives the field, the value and the assigns of the index view. Validate or normalize the value here, as the index view saves the returned change with the update changeset of the LiveResource. Return :error to refuse the value, which the index view then marks as invalid.

@callback list_existing_files(field :: tuple(), item :: struct() | map()) :: [String.t()]

Returns the files of the item as a list of strings.

Upload fields (see upload_key/1) implement it, together with put_upload_change/7, consume_upload/5 and remove_uploads/4. The form component calls them on the module of the field and passes the field, so a custom upload field can implement them once and work out what it needs from the field, such as the column to read the files from, instead of taking a function per field as an option. Backpex.Fields.Upload implements them by calling the functions given in its options.

@callback put_upload_change(
  field :: tuple(),
  socket :: Phoenix.LiveView.Socket.t(),
  params :: map(),
  item :: struct() | map(),
  uploaded_entries :: {list(), list()},
  removed_entries :: [String.t()],
  action :: :validate | :insert
) :: map()

Puts the files of an upload field into the params that are passed to the changeset function.

The form component calls it on every change (action is :validate) and before saving (action is :insert). uploaded_entries is the tuple of completed and in progress entries from Phoenix.LiveView.uploaded_entries/2, removed_entries the files the user removed during an edit. See list_existing_files/2.

@callback remove_uploads(
  field :: tuple(),
  socket :: Phoenix.LiveView.Socket.t(),
  item :: struct(),
  removed_entries :: [String.t()]
) :: term()

Removes the files the user removed during an edit, after the item has been saved. See list_existing_files/2.

@callback render_form(assigns :: map()) :: %Phoenix.LiveView.Rendered{
  caller: term(),
  dynamic: term(),
  fingerprint: term(),
  root: term(),
  static: term()
}

Will be used on edit views to render a form for the value of the provided item. This has to be a heex template.

@callback render_index_form(assigns :: map()) :: %Phoenix.LiveView.Rendered{
  caller: term(),
  dynamic: term(),
  fingerprint: term(),
  root: term(),
  static: term()
}

Used to render form on index to support index editable.

@callback render_value(assigns :: map()) :: %Phoenix.LiveView.Rendered{
  caller: term(),
  dynamic: term(),
  fingerprint: term(),
  root: term(),
  static: term()
}

Will be used on index and show views to render a value from the provided item. This has to be a heex template.

@callback schema(field :: tuple(), schema :: atom()) :: atom()

The schema to be used in queries. In most cases this is the schema defined in the resource configuration. In fields with associations this is the schema of the corresponding relation. The function will receive the field definition and the schema defined in the resource configuration.

@callback search_condition(
  schema_name :: binary(),
  field_name :: binary(),
  search_string :: binary()
) ::
  Ecto.Query.dynamic_expr()

Defines the search condition. Defaults to an ilike condition with text comparison. The function has to return a query wrapped into a Ecto.Query.dynamic/2 which is then passed into a Ecto.Query.where/3.

Example

Imagine the underlying database type of the field is an integer. Before text comparison in an ilike condition you have to cast the integer to text.

The function could return the following query to make the field searchable.

dynamic(
  [{^schema_name, schema_name}],
  ilike(fragment("CAST(? AS TEXT)", schema_name |> field(^field_name)), ^search_string)
)