Module: Turbo::Broadcastable
- Extended by:
- ActiveSupport::Concern
- Defined in:
- app/models/concerns/turbo/broadcastable.rb
Overview
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](hey.com), and the clearance is the model that drives [the screener](hey.com/features/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
class Message < ApplicationRecord
belongs_to :user
after_create_commit :update_message_count
private
def
broadcast_update_to(user, :messages, target: "message-count", html: "<p> #{user..count} </p>")
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.
Defined Under Namespace
Modules: ClassMethods
Instance Method Summary collapse
-
#broadcast_action(action, target: broadcast_target_default, **rendering) ⇒ Object
Same as
#broadcast_action_to
, but the designated stream is automatically set to the current model. -
#broadcast_action_later(action:, target: broadcast_target_default, **rendering) ⇒ Object
Same as
#broadcast_action_later_to
, but the designated stream is automatically set to the current model. -
#broadcast_action_later_to(*streamables, action:, target: broadcast_target_default, **rendering) ⇒ Object
Same as
broadcast_action_to
but run asynchronously via aTurbo::Streams::BroadcastJob
. -
#broadcast_action_to(*streamables, action:, target: broadcast_target_default, **rendering) ⇒ Object
Broadcast a named
action
, allowing for dynamic dispatch, instead of using the concrete action methods. -
#broadcast_after_to(*streamables, target:, **rendering) ⇒ Object
Insert a rendering of this broadcastable model after the target identified by it’s dom id passed as
target
for subscribers of the stream name identified by the passedstreamables
. -
#broadcast_append(target: broadcast_target_default, **rendering) ⇒ Object
Same as
#broadcast_append_to
, but the designated stream is automatically set to the current model. -
#broadcast_append_later(target: broadcast_target_default, **rendering) ⇒ Object
Same as
#broadcast_append_later_to
, but the designated stream is automatically set to the current model. -
#broadcast_append_later_to(*streamables, target: broadcast_target_default, **rendering) ⇒ Object
Same as
broadcast_append_to
but run asynchronously via aTurbo::Streams::BroadcastJob
. -
#broadcast_append_to(*streamables, target: broadcast_target_default, **rendering) ⇒ Object
Append a rendering of this broadcastable model to the target identified by it’s dom id passed as
target
for subscribers of the stream name identified by the passedstreamables
. -
#broadcast_before_to(*streamables, target:, **rendering) ⇒ Object
Insert a rendering of this broadcastable model before the target identified by it’s dom id passed as
target
for subscribers of the stream name identified by the passedstreamables
. -
#broadcast_prepend(target: broadcast_target_default, **rendering) ⇒ Object
Same as
#broadcast_prepend_to
, but the designated stream is automatically set to the current model. -
#broadcast_prepend_later(target: broadcast_target_default, **rendering) ⇒ Object
Same as
#broadcast_prepend_later_to
, but the designated stream is automatically set to the current model. -
#broadcast_prepend_later_to(*streamables, target: broadcast_target_default, **rendering) ⇒ Object
Same as
broadcast_prepend_to
but run asynchronously via aTurbo::Streams::BroadcastJob
. -
#broadcast_prepend_to(*streamables, target: broadcast_target_default, **rendering) ⇒ Object
Prepend a rendering of this broadcastable model to the target identified by it’s dom id passed as
target
for subscribers of the stream name identified by the passedstreamables
. -
#broadcast_remove ⇒ Object
Same as
#broadcast_remove_to
, but the designated stream is automatically set to the current model. -
#broadcast_remove_to(*streamables, target: self) ⇒ Object
Remove this broadcastable model from the dom for subscribers of the stream name identified by the passed streamables.
-
#broadcast_render(**rendering) ⇒ Object
Render a turbo stream template with this broadcastable model passed as the local variable.
-
#broadcast_render_later(**rendering) ⇒ Object
Same as
broadcast_action_to
but run asynchronously via aTurbo::Streams::BroadcastJob
. -
#broadcast_render_later_to(*streamables, **rendering) ⇒ Object
Same as
broadcast_render_later
but run with the added option of naming the stream using the passedstreamables
. -
#broadcast_render_to(*streamables, **rendering) ⇒ Object
Same as
broadcast_render
but run with the added option of naming the stream using the passedstreamables
. -
#broadcast_replace(**rendering) ⇒ Object
Same as
#broadcast_replace_to
, but the designated stream is automatically set to the current model. -
#broadcast_replace_later(**rendering) ⇒ Object
Same as
#broadcast_replace_later_to
, but the designated stream is automatically set to the current model. -
#broadcast_replace_later_to(*streamables, **rendering) ⇒ Object
Same as
broadcast_replace_to
but run asynchronously via aTurbo::Streams::BroadcastJob
. -
#broadcast_replace_to(*streamables, **rendering) ⇒ Object
Replace this broadcastable model in the dom for subscribers of the stream name identified by the passed
streamables
. -
#broadcast_update(**rendering) ⇒ Object
Same as
#broadcast_update_to
, but the designated stream is automatically set to the current model. -
#broadcast_update_later(**rendering) ⇒ Object
Same as
#broadcast_update_later_to
, but the designated stream is automatically set to the current model. -
#broadcast_update_later_to(*streamables, **rendering) ⇒ Object
Same as
broadcast_update_to
but run asynchronously via aTurbo::Streams::BroadcastJob
. -
#broadcast_update_to(*streamables, **rendering) ⇒ Object
Update this broadcastable model in the dom for subscribers of the stream name identified by the passed
streamables
.
Instance Method Details
#broadcast_action(action, target: broadcast_target_default, **rendering) ⇒ Object
Same as #broadcast_action_to
, but the designated stream is automatically set to the current model.
224 225 226 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 224 def broadcast_action(action, target: broadcast_target_default, **rendering) broadcast_action_to self, action: action, target: target, **rendering end |
#broadcast_action_later(action:, target: broadcast_target_default, **rendering) ⇒ Object
Same as #broadcast_action_later_to
, but the designated stream is automatically set to the current model.
275 276 277 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 275 def broadcast_action_later(action:, target: broadcast_target_default, **rendering) broadcast_action_later_to self, action: action, target: target, **rendering end |
#broadcast_action_later_to(*streamables, action:, target: broadcast_target_default, **rendering) ⇒ Object
Same as broadcast_action_to
but run asynchronously via a Turbo::Streams::BroadcastJob
.
270 271 272 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 270 def broadcast_action_later_to(*streamables, action:, target: broadcast_target_default, **rendering) Turbo::StreamsChannel.broadcast_action_later_to(*streamables, action: action, target: target, **broadcast_rendering_with_defaults(rendering)) end |
#broadcast_action_to(*streamables, action:, target: broadcast_target_default, **rendering) ⇒ Object
Broadcast a named action
, allowing for dynamic dispatch, instead of using the concrete action methods. Examples:
# Sends <turbo-stream action="prepend" target="clearances"><template><div id="clearance_5">My Clearance</div></template></turbo-stream>
# to the stream named "identity:2:clearances"
clearance.broadcast_action_to examiner.identity, :clearances, action: :prepend, target: "clearances"
219 220 221 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 219 def broadcast_action_to(*streamables, action:, target: broadcast_target_default, **rendering) Turbo::StreamsChannel.broadcast_action_to(*streamables, action: action, target: target, **broadcast_rendering_with_defaults(rendering)) end |
#broadcast_after_to(*streamables, target:, **rendering) ⇒ Object
Insert a rendering of this broadcastable model after the target identified by it’s dom id passed as target
for subscribers of the stream name identified by the passed streamables
. The rendering parameters can be set by appending named arguments to the call. Examples:
# Sends <turbo-stream action="after" target="clearance_5"><template><div id="clearance_6">My Clearance</div></template></turbo-stream>
# to the stream named "identity:2:clearances"
clearance.broadcast_after_to examiner.identity, :clearances, target: "clearance_5"
# Sends <turbo-stream action="after" target="clearance_5"><template><div id="clearance_6">Other partial</div></template></turbo-stream>
# to the stream named "identity:2:clearances"
clearance.broadcast_after_to examiner.identity, :clearances, target: "clearance_5",
partial: "clearances/other_partial", locals: { a: 1 }
168 169 170 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 168 def broadcast_after_to(*streamables, target:, **rendering) Turbo::StreamsChannel.broadcast_after_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering)) end |
#broadcast_append(target: broadcast_target_default, **rendering) ⇒ Object
Same as #broadcast_append_to
, but the designated stream is automatically set to the current model.
189 190 191 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 189 def broadcast_append(target: broadcast_target_default, **rendering) broadcast_append_to self, target: target, **rendering end |
#broadcast_append_later(target: broadcast_target_default, **rendering) ⇒ Object
Same as #broadcast_append_later_to
, but the designated stream is automatically set to the current model.
255 256 257 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 255 def broadcast_append_later(target: broadcast_target_default, **rendering) broadcast_append_later_to self, target: target, **rendering end |
#broadcast_append_later_to(*streamables, target: broadcast_target_default, **rendering) ⇒ Object
Same as broadcast_append_to
but run asynchronously via a Turbo::Streams::BroadcastJob
.
250 251 252 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 250 def broadcast_append_later_to(*streamables, target: broadcast_target_default, **rendering) Turbo::StreamsChannel.broadcast_append_later_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering)) end |
#broadcast_append_to(*streamables, target: broadcast_target_default, **rendering) ⇒ Object
Append a rendering of this broadcastable model to the target identified by it’s dom id passed as target
for subscribers of the stream name identified by the passed streamables
. The rendering parameters can be set by appending named arguments to the call. Examples:
# Sends <turbo-stream action="append" target="clearances"><template><div id="clearance_5">My Clearance</div></template></turbo-stream>
# to the stream named "identity:2:clearances"
clearance.broadcast_append_to examiner.identity, :clearances, target: "clearances"
# Sends <turbo-stream action="append" target="clearances"><template><div id="clearance_5">Other partial</div></template></turbo-stream>
# to the stream named "identity:2:clearances"
clearance.broadcast_append_to examiner.identity, :clearances, target: "clearances",
partial: "clearances/other_partial", locals: { a: 1 }
184 185 186 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 184 def broadcast_append_to(*streamables, target: broadcast_target_default, **rendering) Turbo::StreamsChannel.broadcast_append_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering)) end |
#broadcast_before_to(*streamables, target:, **rendering) ⇒ Object
Insert a rendering of this broadcastable model before the target identified by it’s dom id passed as target
for subscribers of the stream name identified by the passed streamables
. The rendering parameters can be set by appending named arguments to the call. Examples:
# Sends <turbo-stream action="before" target="clearance_5"><template><div id="clearance_4">My Clearance</div></template></turbo-stream>
# to the stream named "identity:2:clearances"
clearance.broadcast_before_to examiner.identity, :clearances, target: "clearance_5"
# Sends <turbo-stream action="before" target="clearance_5"><template><div id="clearance_4">Other partial</div></template></turbo-stream>
# to the stream named "identity:2:clearances"
clearance.broadcast_before_to examiner.identity, :clearances, target: "clearance_5",
partial: "clearances/other_partial", locals: { a: 1 }
152 153 154 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 152 def broadcast_before_to(*streamables, target:, **rendering) Turbo::StreamsChannel.broadcast_before_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering)) end |
#broadcast_prepend(target: broadcast_target_default, **rendering) ⇒ Object
Same as #broadcast_prepend_to
, but the designated stream is automatically set to the current model.
210 211 212 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 210 def broadcast_prepend(target: broadcast_target_default, **rendering) broadcast_prepend_to self, target: target, **rendering end |
#broadcast_prepend_later(target: broadcast_target_default, **rendering) ⇒ Object
Same as #broadcast_prepend_later_to
, but the designated stream is automatically set to the current model.
265 266 267 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 265 def broadcast_prepend_later(target: broadcast_target_default, **rendering) broadcast_prepend_later_to self, target: target, **rendering end |
#broadcast_prepend_later_to(*streamables, target: broadcast_target_default, **rendering) ⇒ Object
Same as broadcast_prepend_to
but run asynchronously via a Turbo::Streams::BroadcastJob
.
260 261 262 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 260 def broadcast_prepend_later_to(*streamables, target: broadcast_target_default, **rendering) Turbo::StreamsChannel.broadcast_prepend_later_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering)) end |
#broadcast_prepend_to(*streamables, target: broadcast_target_default, **rendering) ⇒ Object
Prepend a rendering of this broadcastable model to the target identified by it’s dom id passed as target
for subscribers of the stream name identified by the passed streamables
. The rendering parameters can be set by appending named arguments to the call. Examples:
# Sends <turbo-stream action="prepend" target="clearances"><template><div id="clearance_5">My Clearance</div></template></turbo-stream>
# to the stream named "identity:2:clearances"
clearance.broadcast_prepend_to examiner.identity, :clearances, target: "clearances"
# Sends <turbo-stream action="prepend" target="clearances"><template><div id="clearance_5">Other partial</div></template></turbo-stream>
# to the stream named "identity:2:clearances"
clearance.broadcast_prepend_to examiner.identity, :clearances, target: "clearances",
partial: "clearances/other_partial", locals: { a: 1 }
205 206 207 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 205 def broadcast_prepend_to(*streamables, target: broadcast_target_default, **rendering) Turbo::StreamsChannel.broadcast_prepend_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering)) end |
#broadcast_remove ⇒ Object
Same as #broadcast_remove_to
, but the designated stream is automatically set to the current model.
98 99 100 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 98 def broadcast_remove broadcast_remove_to self end |
#broadcast_remove_to(*streamables, target: self) ⇒ Object
Remove this broadcastable model from the dom for subscribers of the stream name identified by the passed streamables. Example:
# Sends <turbo-stream action="remove" target="clearance_5"></turbo-stream> to the stream named "identity:2:clearances"
clearance.broadcast_remove_to examiner.identity, :clearances
93 94 95 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 93 def broadcast_remove_to(*streamables, target: self) Turbo::StreamsChannel.broadcast_remove_to(*streamables, target: target) end |
#broadcast_render(**rendering) ⇒ Object
Render a turbo stream template with this broadcastable model passed as the local variable. Example:
# Template: entries/_entry.turbo_stream.erb
<%= turbo_stream.remove entry %>
<%= turbo_stream.append "entries", entry if entry.active? %>
Sends:
<turbo-stream action="remove" target="entry_5"></turbo-stream>
<turbo-stream action="append" target="entries"><template><div id="entry_5">My Entry</div></template></turbo-stream>
…to the stream named “entry:5”.
Note that rendering inline via this method will cause template rendering to happen synchronously. That is usually not desireable for model callbacks, certainly not if those callbacks are inside of a transaction. Most of the time you should be using ‘broadcast_render_later`, unless you specifically know why synchronous rendering is needed.
296 297 298 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 296 def broadcast_render(**rendering) broadcast_render_to self, **rendering end |
#broadcast_render_later(**rendering) ⇒ Object
Same as broadcast_action_to
but run asynchronously via a Turbo::Streams::BroadcastJob
.
311 312 313 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 311 def broadcast_render_later(**rendering) broadcast_render_later_to self, **rendering end |
#broadcast_render_later_to(*streamables, **rendering) ⇒ Object
Same as broadcast_render_later
but run with the added option of naming the stream using the passed streamables
.
317 318 319 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 317 def broadcast_render_later_to(*streamables, **rendering) Turbo::StreamsChannel.broadcast_render_later_to(*streamables, **broadcast_rendering_with_defaults(rendering)) end |
#broadcast_render_to(*streamables, **rendering) ⇒ Object
Same as broadcast_render
but run with the added option of naming the stream using the passed streamables
.
Note that rendering inline via this method will cause template rendering to happen synchronously. That is usually not desireable for model callbacks, certainly not if those callbacks are inside of a transaction. Most of the time you should be using ‘broadcast_render_later_to`, unless you specifically know why synchronous rendering is needed.
306 307 308 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 306 def broadcast_render_to(*streamables, **rendering) Turbo::StreamsChannel.broadcast_render_to(*streamables, **broadcast_rendering_with_defaults(rendering)) end |
#broadcast_replace(**rendering) ⇒ Object
Same as #broadcast_replace_to
, but the designated stream is automatically set to the current model.
117 118 119 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 117 def broadcast_replace(**rendering) broadcast_replace_to self, **rendering end |
#broadcast_replace_later(**rendering) ⇒ Object
Same as #broadcast_replace_later_to
, but the designated stream is automatically set to the current model.
235 236 237 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 235 def broadcast_replace_later(**rendering) broadcast_replace_later_to self, **rendering end |
#broadcast_replace_later_to(*streamables, **rendering) ⇒ Object
Same as broadcast_replace_to
but run asynchronously via a Turbo::Streams::BroadcastJob
.
230 231 232 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 230 def broadcast_replace_later_to(*streamables, **rendering) Turbo::StreamsChannel.broadcast_replace_later_to(*streamables, target: self, **broadcast_rendering_with_defaults(rendering)) end |
#broadcast_replace_to(*streamables, **rendering) ⇒ Object
Replace this broadcastable model in the dom for subscribers of the stream name identified by the passed streamables
. The rendering parameters can be set by appending named arguments to the call. Examples:
# Sends <turbo-stream action="replace" target="clearance_5"><template><div id="clearance_5">My Clearance</div></template></turbo-stream>
# to the stream named "identity:2:clearances"
clearance.broadcast_replace_to examiner.identity, :clearances
# Sends <turbo-stream action="replace" target="clearance_5"><template><div id="clearance_5">Other partial</div></template></turbo-stream>
# to the stream named "identity:2:clearances"
clearance.broadcast_replace_to examiner.identity, :clearances, partial: "clearances/other_partial", locals: { a: 1 }
112 113 114 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 112 def broadcast_replace_to(*streamables, **rendering) Turbo::StreamsChannel.broadcast_replace_to(*streamables, target: self, **broadcast_rendering_with_defaults(rendering)) end |
#broadcast_update(**rendering) ⇒ Object
Same as #broadcast_update_to
, but the designated stream is automatically set to the current model.
136 137 138 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 136 def broadcast_update(**rendering) broadcast_update_to self, **rendering end |
#broadcast_update_later(**rendering) ⇒ Object
Same as #broadcast_update_later_to
, but the designated stream is automatically set to the current model.
245 246 247 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 245 def broadcast_update_later(**rendering) broadcast_update_later_to self, **rendering end |
#broadcast_update_later_to(*streamables, **rendering) ⇒ Object
Same as broadcast_update_to
but run asynchronously via a Turbo::Streams::BroadcastJob
.
240 241 242 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 240 def broadcast_update_later_to(*streamables, **rendering) Turbo::StreamsChannel.broadcast_update_later_to(*streamables, target: self, **broadcast_rendering_with_defaults(rendering)) end |
#broadcast_update_to(*streamables, **rendering) ⇒ Object
Update this broadcastable model in the dom for subscribers of the stream name identified by the passed streamables
. The rendering parameters can be set by appending named arguments to the call. Examples:
# Sends <turbo-stream action="update" target="clearance_5"><template><div id="clearance_5">My Clearance</div></template></turbo-stream>
# to the stream named "identity:2:clearances"
clearance.broadcast_update_to examiner.identity, :clearances
# Sends <turbo-stream action="update" target="clearance_5"><template><div id="clearance_5">Other partial</div></template></turbo-stream>
# to the stream named "identity:2:clearances"
clearance.broadcast_update_to examiner.identity, :clearances, partial: "clearances/other_partial", locals: { a: 1 }
131 132 133 |
# File 'app/models/concerns/turbo/broadcastable.rb', line 131 def broadcast_update_to(*streamables, **rendering) Turbo::StreamsChannel.broadcast_update_to(*streamables, target: self, **broadcast_rendering_with_defaults(rendering)) end |