Hooks DSL
v0.0.7
The hooks section of a resource's table and form blocks holds lifecycle callbacks. A table also has per-action hooks keyed by action name. A hook function runs inside a LiveComponent, so self() is the parent LiveView process.
Table hooks
Global lifecycle hooks and built-in transition flags of a table. It sits at mishka_gervaz.table.hooks.
| Option | Type or signature | Default | Description |
|---|---|---|---|
on_load | fn query, state -> {:cont, query} | none | Runs before the data loads. Return {:cont, query} to use a changed query. Any other return, a bare query included, leaves the query as it was. |
before_delete | fn record, state -> {:ok, state} | {:halt, {:error, msg}} | none | Before delete. |
after_delete | fn record, state -> any | none | After delete (side effects only). |
on_realtime | fn notification, socket -> socket | {:cont, socket} | {:halt, socket} | none | PubSub received. Return {:halt, socket} to skip the table's own update; a hook that adds or removes rows itself pipes its socket through MishkaGervaz.Table.Web.DataLoader.refresh_total/1. |
on_expand | fn record_id, socket -> socket | {:cont, socket} | {:halt, socket} | none | Row expanded. Return {:halt, socket} to skip the {:expand_row, id} message the table sends to its parent LiveView. |
on_filter | fn filter_values, socket -> socket | {:cont, socket} | none | Filter changed. Do not return {:halt, socket}: Gervaz does not unwrap it for this hook. |
on_event | fn event_name, params, socket -> socket | {:cont, socket} | {:halt, socket} | none | Runs for an event the table does not handle itself: a row action event with no matching action or override_row_action, a custom_event, or an unknown event name. Return {:halt, socket} to skip the message the table then sends to its parent LiveView, {:row_action, event_name, params} or {:table_event, event_name, params}. |
on_select | fn selected_ids, socket -> socket | {:cont, socket} | none | Selection changed. Do not return {:halt, socket}: Gervaz does not unwrap it for this hook. |
on_sort | fn {field, direction}, socket -> socket | {:cont, socket} | none | Sort changed. Do not return {:halt, socket}: Gervaz does not unwrap it for this hook. |
switch_to_active_on_empty_archive | boolean | false | Switches to the active list after an unarchive or a permanent destroy leaves the archive list empty. |
switch_to_archive_on_empty_active | boolean | false | Switches to the archive list after a destroy leaves the active list empty. |
clear_selection_after_bulk | boolean | true | Clears the selection after a successful bulk action. |
reset_page_on_empty_current_page | boolean | false | After a load, reloads page 1 when the current page is past the first and the total is zero. |
redirect_on_empty | String.t | (any -> any) | none | A path, or fn state -> path, to redirect to when the total count is zero after a load. |
Per-action hooks
These entities take an action name, or a list of names, and a function. before_* hooks refuse by returning {:halt, {:error, message}}. on_*_success and on_*_error hooks accept arity 2 or 3, and arity 3 gets the socket. See the guide for the flash rules.
| Entity | Call | Runs |
|---|---|---|
before_row_action | before_row_action names, run | Before the built-in row action handler. It can refuse. |
after_row_action | after_row_action names, run | After the handler, for side effects. |
on_row_action_success | on_row_action_success names, run | After a row action succeeds. |
on_row_action_error | on_row_action_error names, run | After a row action fails. |
before_bulk_action | before_bulk_action names, run | Before the bulk handler. It can refuse. |
after_bulk_action | after_bulk_action names, run | After the bulk handler, for side effects. |
on_bulk_action_success | on_bulk_action_success names, run | After a bulk action succeeds. |
on_bulk_action_error | on_bulk_action_error names, run | After a bulk action fails. |
override_row_action | override_row_action names, run | Replaces the built-in row action handler. |
override_bulk_action | override_bulk_action names, run | Replaces the built-in bulk action handler. |
Both arguments are required. names is an atom or a list of atoms, and run is a function of arity 2. Only the on_*_success and on_*_error hooks also accept arity 3.
Form hooks
Server-side lifecycle callbacks of a form. It sits at mishka_gervaz.form.hooks.
| Option | Type or signature | Default | Description |
|---|---|---|---|
on_init | fn form, state -> form | none | After form initialization. |
before_save | fn params, state -> params | {:cont, params} | {:halt, reason} | none | Runs before the save. params are the save event's params, with the form's values under "form". The params it returns, bare or in {:cont, params}, are saved. {:halt, reason} cancels the save with no message. |
after_save | fn record, state -> any | none | Runs after a successful save, with the saved record, for side effects. What it returns is not read. The js hook of the same name runs too, and the parent receives {:form_saved, mode, record}. |
on_error | fn form, state -> state | none | Runs after a failed save, with the form the save left. The state it returns is the one the form shows, and anything else keeps the form's own state. The js hook of the same name runs too. |
on_cancel | fn state -> state | none | When form is cancelled. |
on_validate | fn params, state -> params | {params, errors} | none | Runs on each validation event. Return the params, or {params, errors} with a map of errors to force. Picking a record in a relation field runs it too, with the picks in the form's params and "_target" naming the first picked field, so a value made from a picked record follows the pick. |
on_change | fn field, value, state -> {:halt, state} | none | Runs on a field change. {:halt, state} replaces the form state and skips the default handling. Any other return lets the default run. |
js
Client-side JS commands. Each function returns a %Phoenix.LiveView.JS{}. on_init runs as phx-mounted on the form container, on_cancel runs when the reader clicks Cancel, and Gervaz pushes after_save and on_error to the browser as a "gervaz:exec-js" event. The page needs a listener for that event. It sits at mishka_gervaz.form.hooks.js.
| Option | Type or signature | Default | Description |
|---|---|---|---|
on_init | fn -> %JS{} | none | JS commands for phx-mounted on form container. |
after_save | fn record_id -> %JS{} | none | JS commands after successful save. Receives saved record ID. |
on_cancel | fn record_id -> %JS{} | none | JS commands when form is cancelled. Receives record ID or nil (create). |
on_error | fn record_id -> %JS{} | none | JS commands on save error. Receives record ID or nil (create). |