O que uma tag turbo stream realmente é

Um <turbo-frame> (curso anterior) espera ser chamado: um link ou formulário o mira, e o conteúdo dele é trocado. Um <turbo-stream> funciona ao contrário. É uma instrução pequena, que se descreve sozinha, chega e age por conta própria, tenha alguém clicado em algo na página ou não.

Sete verbos, um formato

A gem turbo-rails-2.0.23 instalada nesta aplicação lista o vocabulário de ações nos próprios comentários do código:

There are seven basic actions you can broadcast: after, append, before, prepend, remove, replace, and update.

Cada uma vira o mesmo formato de tag: uma ação, um id de alvo e (menos no remove, que só precisa do id) um template com HTML dentro:

<turbo-stream action="replace" target="clearance_5">
  <template>
    <div id="clearance_5">Other partial</div>
  </template>
</turbo-stream>

replace troca o elemento inteiro. update troca só o conteúdo dele. append e prepend acrescentam no fim ou no começo de um contêiner. before e after inserem um irmão. remove apaga o alvo. Os verbos mudam, mas o mecanismo é o mesmo: achar o elemento com esse id e aplicar nele uma operação de DOM. O Turbo 8.0.23, a versão que esta aplicação usa, tem ainda uma oitava ação, refresh, sem alvo e sem template. A aula 5 trata dela.

Onde a tag é montada

Quase nunca você escreve o <turbo-stream> cru à mão. A gem instalada traz o Turbo::Streams::TagBuilder, disponível em views e controllers como turbo_stream. O comentário de documentação dele mostra este formato:

def create
  @message = Message.create!(params.require(:message).permit(:content))
  respond_to do |format|
    format.turbo_stream
    format.html { redirect_to messages_url }
  end
end

<%# app/views/messages/create.turbo_stream.erb %>
<%= turbo_stream.append "messages", @message %>

<%= turbo_stream.replace "new_message" do %>
  <%= render partial: "new_message", locals: { room: @room } %>
<% end %>

format.turbo_stream no controller, junto de um template create.turbo_stream.erb, é o respond_to do Rails fazendo o que faz com format.html e format.json: escolher um template conforme o que o cliente pediu. O template desse formato chama turbo_stream.append, .replace e os demais, que montam o formato de tag da seção anterior em vez de um pedaço de HTML comum.

Não é uma troca de frame por requisição

A atualização de um turbo frame (curso anterior) está presa a uma navegação: um link ou formulário pede, e uma resposta restrita a esse frame responde. Uma tag de turbo stream leva o id do alvo com ela e não precisa vir de algo que a página atual pediu. Por isso ela tem o formato certo para a próxima aula: uma atualização que chega porque outra pessoa fez algo, e não porque você clicou.

Pontos-chave

• A gem do Turbo instalada nesta aplicação documenta sete ações básicas de broadcast: after, append, before, prepend, remove, replace e update. Cada uma vira o mesmo formato <turbo-stream action="..." target="...">.
• turbo_stream, um Turbo::Streams::TagBuilder, monta essas tags em Ruby com .replace, .append e os demais, sem escrever a marcação à mão.
• format.turbo_stream num controller, com um template .turbo_stream.erb, é o mesmo mecanismo de respond_to de format.html e format.json. Só responde com tags de stream em vez de uma página.
• Ao contrário de um turbo frame, uma tag de stream não está presa a responder uma requisição. Ela leva o próprio id de alvo e pode chegar tenha a página pedido algo ou não.