Elemental.Feedback.Live.ToastGroup (elemental v0.3.0)

A live/stateful toast component, allows for more dynamic toasts granting consumers the ability to send server events to display or dismiss toasts based on events.

Renders a live/stateful Elemental.Feedback.Toast.toast_group/1 and attaches multiple handler to allow for dynamic handling of toast messages.

Usage

In your application where you want to add the toast sub-system simply add

<.live_component module={Elemental.Feedback.Live.ToastGroup} />

Additionally, the main Elemental.Feedback.Toast.toast_group/1 supports the live attribute allowing it to act as a pass through, this simplifies things to doing

<Elemental.Feedback.Toast.toast_group live />

The second form can further be simplified if you use Elemental to just

<.toast_group live />

To send a message you can use the send_message/2 function or you can send a list of messages by using the send_messages/2 function.

Those functions abstract away all the details needed and require you only optionally pass it an id option to the live toast group if you have many in your application.

defmodule MyPage do
  # your normal app setup

  use Elemental
  # or alias Elemental.Feedback.Live.ToastGroup

  # your normal page implementation

  def handle_event("some-event", params, socket) do
    # handle your event normally
    # now you can send the user a toast by calling
    ToastGroup.send_message("Some notice to the user")
    # remainder of your event handler
  end
end

Phoenix' flash system

You can also pass the flash attribute bound to Phoenix' flash system and would carry over the same behaviour as defined in the stateless variant, i.e. it should interoperate with it normally without any additional work form the consumer side.

Phoenix' flashes are rendered immediately after any messages passed/sent over via the Elemental.Feedback.Live.ToastGroup module.

Summary

Functions

Drop-in for Phoenix' Phoenix.LiveView.put_flash/3 that instead sends the message over via the handles of the live toast group.

Send a message to the associated live toast group.

Send a message to the associated live toast group.

Send a list of messages to the associated live toast group.

Types

level()

@type level() :: :info | :warning | :success | :error | String.t()

message()

@type message() ::
  String.t()
  | {level(), String.t()}
  | {level(), String.t(), String.t()}
  | {nil, String.t(), String.t()}

Functions

put_flash(socket, kind, message)

Drop-in for Phoenix' Phoenix.LiveView.put_flash/3 that instead sends the message over via the handles of the live toast group.

This captures the original behaviour and doesn't set the Phoenix flash related assigns instead passing it directly (and as is) to the main Elemental.Feedback.Toast.toast_group/1 component as a message.

send_message(message, opts \\ [])

@spec send_message(
  message(),
  keyword()
) :: :ok

Send a message to the associated live toast group.

Accepts a single message in the format accepted by Elemental.Feedback.Toast.toast_group/1.

See send_message/4 for details.

send_message(level, title, message, opts \\ [])

@spec send_message(level() | nil, String.t() | nil, String.t(), keyword()) :: :ok

Send a message to the associated live toast group.

Defaults to sending the message to a live component identified by the ID toast-group, if you're using a custom ID pass the :id option.

send_messages(messages, opts)

@spec send_messages(
  [message()],
  keyword()
) :: :ok

Send a list of messages to the associated live toast group.

Accepts a list of messages in the format accepted by Elemental.Feedback.Toast.toast_group/1.

See send_message/2 for details.