Aurora.Uix.Templates.Basic.Handlers.FormImpl behaviour (Aurora UIX v0.1.4-rc.5)

Copy Markdown

Behaviour and macro for implementing form live view component handlers in Aurora UIX LiveView templates.

Provides a set of callbacks and a __using__/1 macro to standardize the handling of mount, parameter changes, events, info messages, and action application. Designed for use with Phoenix LiveView and Aurora UIX conventions.

Key Features

  • Defines required callbacks for form live component lifecycle and event handling.
  • Supplies a macro to inject default implementations and imports for LiveView modules.
  • Integrates with Aurora UIX context and module generators for dynamic entity management.

Key Constraints

  • Expects the :auix assign to be present in the LiveView socket.
  • Designed for use with Phoenix LiveView and Aurora UIX context modules.
  • Assumes certain structure in the auix assign (e.g., modules.context, source_key, etc.).

Summary

Callbacks

auix_handle_event(event, params, socket)

Internally handles all LiveView events for the form component.

auix_update(assigns, socket)

Updates the form state and assigns for the LiveComponent.

save_entity(socket, entity_params)

Performs the creation or update of an entity.

Functions

auix_consume_uploads(socket, entity_params)

Consumes all uploaded entries for upload fields and merges the results into entity params.

auix_handle_event(event, params, socket)

Handles form-related events such as validation, saving, and section switching.

auix_update(assigns, socket)

Updates the form state and assigns for the LiveComponent.

conditional_route_back(socket, arg2, arg3)

Handles post-save navigation based on action and rendering context.

notify_parent(msg)

Sends a message to the parent LiveView with the operation result.

save_entity(socket, entity_params)

Saves or updates the entity using the given params.

Callbacks

auix_handle_event(event, params, socket)

@callback auix_handle_event(
  event :: binary(),
  params :: map(),
  socket :: Phoenix.LiveView.Socket.t()
) :: {:noreply, Phoenix.LiveView.Socket.t()}

Internally handles all LiveView events for the form component.

Parameters

  • event (binary()) - Event name.
  • params (map()) - Event parameters.
  • socket (Socket.t()) - LiveView socket.

Returns

{:noreply, Socket.t()} - Updated socket after event handling.

auix_update(assigns, socket)

@callback auix_update(assigns :: map(), socket :: Phoenix.LiveView.Socket.t()) ::
  {:ok, Phoenix.LiveView.Socket.t()}

Updates the form state and assigns for the LiveComponent.

Parameters

  • assigns (map()) - Assigns containing at least %{auix: %{entity: map(), routing_stack: Stack.t()}}.
  • socket (Socket.t()) - The current LiveView socket.

Returns

{:ok, Socket.t()} - The updated socket with form and routing stack assigned.

save_entity(socket, entity_params)

@callback save_entity(socket :: Phoenix.LiveView.Socket.t(), entity_params :: map()) ::
  {:ok, struct()} | {:error, Ecto.Changeset.t()}

Performs the creation or update of an entity.

Should perform the creation or update of an entity based on the current action in the socket assigns (:edit for updates, :new for creation).

Parameters

  • socket (Socket.t()) - Current socket with assigns containing action type.
  • entity_params (map()) - Parameters conforming to the entity schema for persistence.

Returns

{:ok, struct()} - If the entity was correctly saved. {:error, Ecto.Changeset.t()} - If any error occurred with changeset details.

Functions

auix_consume_uploads(socket, entity_params)

@spec auix_consume_uploads(Phoenix.LiveView.Socket.t(), map()) ::
  {:ok, map()} | {:error, term()}

Consumes all uploaded entries for upload fields and merges the results into entity params.

For each upload field, reads the uploaded binaries and calls the field's :consume callback. Returns {:ok, updated_params} on success, or {:error, reason} if any callback returns an error (aborting further processing).

When no file is selected for a field, the callback is not invoked and the field is left untouched in the params (:no_change short-circuit).

Parameters

  • socket (Socket.t()) - The current LiveView socket.
  • entity_params (map()) - The raw entity parameters from the form submission.

Returns

{:ok, map()} - Updated params with consumed upload values merged in. {:error, term()} - If a :consume callback returns {:error, reason}.

auix_handle_event(event, params, socket)

@spec auix_handle_event(binary(), map(), Phoenix.LiveView.Socket.t()) ::
  {:noreply, Phoenix.LiveView.Socket.t()}

Handles form-related events such as validation, saving, and section switching.

Parameters

  • event (binary()) - The event name (e.g., "validate", "save", "switch_section").
  • params (map()) - Parameters from the event.
  • socket (Socket.t()) - The current LiveView socket.

Returns

{:noreply, Socket.t()} - The updated socket after handling the event.

auix_update(assigns, socket)

@spec auix_update(map(), Phoenix.LiveView.Socket.t()) ::
  {:ok, Phoenix.LiveView.Socket.t()}

Updates the form state and assigns for the LiveComponent.

Parameters

  • assigns (map()) - Assigns containing at least %{auix: %{entity: map(), routing_stack: Stack.t()}}.
  • socket (Socket.t()) - The current LiveView socket.

Returns

{:ok, Socket.t()} - The updated socket with form and routing stack assigned.

conditional_route_back(socket, arg2, arg3)

@spec conditional_route_back(
  Phoenix.LiveView.Socket.t(),
  atom(),
  boolean()
) :: Phoenix.LiveView.Socket.t()

Handles post-save navigation based on action and rendering context.

For :new actions in one-to-many contexts, redirects to edit mode of the created entity. Otherwise, navigates back in the routing stack.

Parameters

  • socket (Socket.t()) - Current socket with auix assigns.
  • action (atom()) - Form action (:new or :edit).
  • one2many_rendered? (boolean()) - Whether this is a one-to-many form context.

Returns

Socket.t() - Updated socket after navigation.

notify_parent(msg)

@spec notify_parent(tuple()) :: :ok

Sends a message to the parent LiveView with the operation result.

Used to notify the parent component of successful operations.

Parameters

  • msg - Tuple message to send (e.g., {:saved, entity})

Returns

  • :ok

save_entity(socket, entity_params)

@spec save_entity(Phoenix.LiveView.Socket.t(), map()) ::
  {:ok, struct()} | {:error, Ecto.Changeset.t()}

Saves or updates the entity using the given params.

Based on the action type (:new or :edit), either creates a new entity or updates an existing one.

Parameters

  • socket (Socket.t()) - The current LiveView socket with action and auix assigns.
  • entity_params (map()) - UI entity changes to persist.

Returns

{:ok, struct()} - If the entity was correctly saved. {:error, Ecto.Changeset.t()} - If any error occurred with changeset details.