View Source Backpex.Field behaviour (Backpex v0.9.1)

Behaviour implemented by all fields.

A field defines how a column is rendered on index, show and edit views. In the resource configuration file you can configure a list of fields. You may create your own field by implementing this behaviour. A field has to be a LiveComponent.

Options

These are general field options which can be used on every field. Check the field modules for field-specific options.

  • :module (atom/0) - Required. The field module.

  • :label (String.t/0) - Required. The field label.

  • :default (function of arity 1) - A function to assign default values to fields. Also see the field defaults guide.

  • :render (function of arity 1) - A function to overwrite the template used . It should take assigns and return a HEEX template.

  • :render_form (function of arity 1) - A function to overwrite the template used in forms. It should take assigns and return a HEEX template.

  • :custom_alias (atom/0) - A custom alias for the field.

  • :align - Align the fields of a resource in the index view.

  • :align_label - Align the labels of the fields in the edit view.

  • :searchable (boolean/0) - Define wether this field should be searchable on the index view.

  • :orderable (boolean/0) - Define wether this field should be orderable on the index view.

  • :visible (function of arity 1) - Function to change the visibility of a field for all views except index. Receives the assigns and has to return a boolean.

  • :can? (function of arity 1) - Function to change the visibility of a field for all views. Receives the assigns and has to return a boolean.

  • :panel (atom/0) - Group field into panel. Also see the panels guide.

  • :index_editable - Define wether this field should be editable on the index view. Also see the index edit guide.

  • :index_column_class - Add additional class(es) to the index column. In case of a function it takes the assigns and should return a string.

  • :select (struct of type Ecto.Query.DynamicExpr) - Define a dynamic select query expression for this field.

    Example 

    full_name: %{
  module: Backpex.Fields.Text,
  label: "Full Name",
  select: dynamic([user: u], fragment("concat(?, ' ', ?)", u.first_name, u.last_name)),
}

  • :only - Define the only views where this field should be visible.

  • :except - Define the views where this field should not be visible.

  • :translate_error (function of arity 1) - Function to customize error messages for a field. The function receives the error tuple and must return a tuple with the message and metadata.

Example 

def fields do
  [
    rating: %{
      module: Backpex.Fields.Text,
      label: "Rating"
    }
  ]
end

Summary

Callbacks

assign_uploads(field, socket)

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

association?(field)

Determines whether the field is an association or not.

before_changeset(changeset, attrs, metadata, repo, field, assigns)

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.

display_field(field)

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.

render_form(assigns)

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

render_form_readonly(assigns)

Used to render the readonly version of the field.

render_index_form(assigns)

Used to render form on index to support index editable.

render_value(assigns)

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

schema(field, schema)

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.

search_condition(schema_name, field_name, search_string)

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.

Functions

__using__(opts)

Defines Backpex.Field behaviour and provides default implementations.

align_label(field_options, assigns, default \\ :center)

Gets alignment option for label.

changeset_types(fields)

Returns a map of types from a list of fields used for the Ecto changeset.

debounce(arg1, assigns)

Defines debounce timeout value.

default_config_schema()

Returns the default config schema.

handle_index_editable(socket, value, change)

Handles index editable.

index_editable_enabled?(field_options, assigns, default \\ false)

Checks whether index editable is enabled or not.

placeholder(arg1, assigns)

Defines placeholder value.

readonly?(arg1, assigns)

Determines whether the field should be rendered as readonly version.

throttle(arg1, assigns)

Defines throttle timeout value.

translate_error_fun(arg1, assigns)

Callbacks

assign_uploads(field, socket)

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

association?(field)

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

Determines whether the field is an association or not.

before_changeset(changeset, attrs, metadata, repo, field, assigns)

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

display_field(field)

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

render_form(assigns)

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

render_form_readonly(assigns)

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

Used to render the readonly version of the field.

render_index_form(assigns)

(optional) 
@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.

render_value(assigns)

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

schema(field, schema)

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

search_condition(schema_name, field_name, search_string)

@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)
)

Functions

__using__(opts)

(macro)

Defines Backpex.Field behaviour and provides default implementations.

align_label(field_options, assigns, default \\ :center)

Gets alignment option for label.

changeset_types(fields)

Returns a map of types from a list of fields used for the Ecto changeset.

debounce(arg1, assigns)

Defines debounce timeout value.

default_config_schema()

Returns the default config schema.

handle_index_editable(socket, value, change)

Handles index editable.

index_editable_enabled?(field_options, assigns, default \\ false)

Checks whether index editable is enabled or not.

placeholder(arg1, assigns)

Defines placeholder value.

readonly?(arg1, assigns)

Determines whether the field should be rendered as readonly version.

throttle(arg1, assigns)

Defines throttle timeout value.

translate_error_fun(arg1, assigns)