Hooks DSL
v0.0.1
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 -> {:cont, params} | {:halt, state} | none | Runs before the save. {:cont, params} saves with those params. {:halt, _} cancels the save with no message. Any other return, a bare params map included, saves the original params. |
after_save | fn result, state -> state | none | After successful save. Gervaz never calls it as a server hook. The js hook of the same name runs, and the parent receives {:form_saved, mode, record}. |
on_error | fn form, state -> state | none | On save error. Gervaz never calls it as a server hook. The js hook of the same name runs. |
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. |
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. |
transform_params | fn params -> params | none | Transform params before action. Gervaz does not call it. Use before_save, or override transform_params/2 on the submit handler. |
transform_errors | fn changeset, errors -> errors | none | Transform error messages. Gervaz does not call it. |
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). |