MishkaGervaz.Table.Web.Events behaviour (MishkaGervaz v0.0.6)

Copy Markdown View Source

Handles all table events for MishkaGervaz.

This module centralizes event handling for:

  • Sorting
  • Filtering
  • Row actions (delete, edit, custom events)
  • Bulk actions
  • Row expansion
  • Archive status changes
  • Pagination, Load more and Load earlier
  • Reloading, the error state's Retry ("reload")

Sub-builders

Events functionality is split into specialized sub-builders:

  • SanitizationHandler - Input sanitization
  • RecordHandler - Record CRUD operations
  • SelectionHandler - Selection state management
  • BulkActionHandler - Bulk action execution
  • HookRunner - Hook execution
  • RelationFilterHandler - Relation filter search/select events

Customization

You can override individual sub-builders via DSL:

mishka_gervaz do
  table do
    events do
      sanitization MyApp.CustomSanitizationHandler
      record MyApp.CustomRecordHandler
      selection MyApp.CustomSelectionHandler
      bulk_action MyApp.CustomBulkActionHandler
      hooks MyApp.CustomHookRunner
      relation_filter MyApp.CustomRelationFilterHandler
    end
  end
end

Or override the entire Events module:

mishka_gervaz do
  table do
    events MyApp.CustomEvents
  end
end

See MishkaGervaz.Table.Web.Events.SanitizationHandler, MishkaGervaz.Table.Web.Events.RecordHandler, MishkaGervaz.Table.Web.Events.SelectionHandler, MishkaGervaz.Table.Web.Events.BulkActionHandler, MishkaGervaz.Table.Web.Events.HookRunner, MishkaGervaz.Table.Web.Events.RelationFilterHandler, MishkaGervaz.Table.Web.State, MishkaGervaz.Table.Web.DataLoader, MishkaGervaz.Table.Web.Live.

Summary

Types

socket()
state()

Callbacks

handle(event, params, socket)

Main event handler dispatcher.

Functions

do_delete(state, record, socket, params \\ %{})

Deletes one record, runs the :delete action hooks and the after_delete hook, then drops the row from the stream and the header count.

drop_shown_row(state, id, arg3)

Takes the row id out of what the view shows, so the next Load more reads after the rows still shown.

handle(event, params, socket)

Main event handler dispatcher.

report_row_error(state, action_name, reason, error, socket)

Runs a failed row action's on_row_action_error hook, then puts the error flash. A hook answering {:halt, socket} puts no flash.

row_action_label(state, params, type)

The label of the row action a failed row event ran, for its error flash, or nil when the action declares none.

Types

socket()

@type socket() :: Phoenix.LiveView.Socket.t()

state()

@type state() :: MishkaGervaz.Table.Web.State.t()

Callbacks

handle(event, params, socket)

@callback handle(event :: String.t(), params :: map(), socket :: socket()) ::
  {:noreply, socket()}

Main event handler dispatcher.

Called from LiveComponent's handle_event callback.

Functions

do_delete(state, record, socket, params \\ %{})

@spec do_delete(
  MishkaGervaz.Table.Web.State.t(),
  map(),
  Phoenix.LiveView.Socket.t(),
  map()
) ::
  {:noreply, Phoenix.LiveView.Socket.t()}

Deletes one record, runs the :delete action hooks and the after_delete hook, then drops the row from the stream and the header count.

params are the "delete" event's params; their "action" names the row action a failed delete's flash is labelled with (see row_action_label/3).

Public so a RecordHandler override can defer the destroy itself to the default behaviour rather than re-implementing the surrounding bookkeeping.

drop_shown_row(state, id, arg3)

@spec drop_shown_row(MishkaGervaz.Table.Web.State.t(), term(), :self | :realtime) ::
  MishkaGervaz.Table.Web.State.t()

Takes the row id out of what the view shows, so the next Load more reads after the rows still shown.

A table with keep_loaded_records true drops it from loaded_records. Any other table moves next_offset back by one, the offset Load more reads from when its read action has no keyset pagination; a Load more by keyset reads after the last row's keyset and does not use it. A row the view removes itself (:self) is held by its id in removed_ids until its own realtime removal (:realtime) arrives, which then moves nothing, so the row is counted once whether realtime is on or off.

handle(event, params, socket)

@spec handle(String.t(), map(), socket()) :: {:noreply, socket()}

Main event handler dispatcher.

Called from LiveComponent's handle_event callback.

report_row_error(state, action_name, reason, error, socket)

@spec report_row_error(
  MishkaGervaz.Table.Web.State.t(),
  atom(),
  any(),
  any(),
  Phoenix.LiveView.Socket.t()
) :: Phoenix.LiveView.Socket.t()

Runs a failed row action's on_row_action_error hook, then puts the error flash. A hook answering {:halt, socket} puts no flash.

row_action_label(state, params, type)

@spec row_action_label(MishkaGervaz.Table.Web.State.t(), map(), atom()) ::
  String.t() | nil

The label of the row action a failed row event ran, for its error flash, or nil when the action declares none.

params are the event's params. The action is the row action of type named by "action", else the one "event" names, else the first row action of type, dropdown items included.