module Broadcastable

Turbo streams can be broadcast directly from models that include this module (this is automatically done for Active Records). This makes it convenient to execute both synchronous and asynchronous updates, and render directly from callbacks in models or from controllers or jobs that act on those models. Here’s an example:

class Clearance < ApplicationRecord belongs_to :petitioner, class_name: “Contact” belongs_to :examiner, class_name: “User”

after_create_commit :broadcast_later

private
  def broadcast_later
    broadcast_prepend_later_to examiner.identity, :clearances
  end

end

This is an example from HEY, and the clearance is the model that drives the screener, which gives users the power to deny first-time senders (petitioners) access to their attention (as the examiner). When a new clearance is created upon receipt of an email from a first-time sender, that’ll trigger the call to broadcast_later, which in turn invokes broadcast_prepend_later_to.

That method enqueues a Turbo::Streams::ActionBroadcastJob for the prepend, which will render the partial for clearance (it knows which by calling Clearance#to_partial_path, which in this case returns clearances/_clearance.html.erb), send that to all users that have subscribed to updates (using turbo_stream_from(examiner.identity, :clearances) in a view) using the Turbo::StreamsChannel under the stream name derived from [ examiner.identity, :clearances ], and finally prepend the result of that partial rendering to the target identified with the dom id “clearances” (which is derived by default from the plural model name of the model, but can be overwritten).

You can also choose to render html instead of a partial inside of a broadcast you do this by passing the html: option to any broadcast method that accepts the **rendering argument. Example:

class Message < ApplicationRecord belongs_to :user

after_create_commit :update_message_count

private
  def update_message_count
    broadcast_update_to(user, :messages, target: "message-count", html: "<p> #{user.messages.count} </p>")
  end

end

If you want to render a template instead of a partial, e.g. (‘messages/index’ or ‘messages/show’), you can use the template: option. Again, only to any broadcast method that accepts the **rendering argument. Example:

class Message < ApplicationRecord belongs_to :user

after_create_commit :update_message

private
  def update_message
    broadcast_replace_to(user, :message, target: "message", template: "messages/show", locals: { message: self })
  end

end

If you want to render a renderable object you can use the renderable: option.

class Message < ApplicationRecord belongs_to :user

after_create_commit :update_message

private
  def update_message
    broadcast_replace_to(user, :message, target: "message", renderable: MessageComponent.new)
  end

end

There are four basic actions you can broadcast: remove, replace, append, and prepend. As a rule, you should use the _later versions of everything except for remove when broadcasting within a real-time path, like a controller or model, since all those updates require a rendering step, which can slow down execution. You don’t need to do this for remove, since only the dom id for the model is used.

In addition to the four basic actions, you can also use broadcast_render, broadcast_render_to broadcast_render_later, and broadcast_render_later_to to render a turbo stream template with multiple actions.