From e216140ef6defeeb89d914a70f96637a7a5556af Mon Sep 17 00:00:00 2001 From: jorgemanrubia Date: Wed, 21 Feb 2024 08:55:26 +0000 Subject: [PATCH] deploy: ad72fbdad9e8f79b51a4b81a77fd2071e3c514e1 --- handbook/introduction.html | 2 +- handbook/streams.html | 10 +++++----- reference/streams.html | 6 +++++- 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/handbook/introduction.html b/handbook/introduction.html index 0a9e7ee..d8de112 100644 --- a/handbook/introduction.html +++ b/handbook/introduction.html @@ -178,7 +178,7 @@

﹟ Turbo Streams: Deliver live page changes

Making partial page changes in response to asynchronous actions is how we make the application feel alive. While Turbo Frames give us such updates in response to direct interactions within a single frame, Turbo Streams let us change any part of the page in response to updates sent over a WebSocket connection, SSE or other transport. (Think an imbox that automatically updates when a new email arrives.)

-

Turbo Streams introduces a <turbo-stream> element with seven basic actions: append, prepend, replace, update, remove, before, and after. With these actions, along with the target attribute specifying the ID of the element you want to operate on, you can encode all the mutations needed to refresh the page. You can even combine several stream elements in a single stream message. Simply include the HTML you’re interested in inserting or replacing in a template tag and Turbo does the rest:

+

Turbo Streams introduces a <turbo-stream> element with eight basic actions: append, prepend, replace, update, remove, before, after, and refresh. With these actions, along with the target attribute specifying the ID of the element you want to operate on, you can encode all the mutations needed to refresh the page. You can even combine several stream elements in a single stream message. Simply include the HTML you’re interested in inserting or replacing in a template tag and Turbo does the rest:

<turbo-stream action="append" target="messages">
  <template>
    <div id="message_1">My new message!</div>
  </template>
</turbo-stream>

This stream element will take the div with the new message and append it to the container with the ID messages. It’s just as simple to replace an existing element:

<turbo-stream action="replace" target="message_1">
  <template>
    <div id="message_1">This changes the existing message!</div>
  </template>
</turbo-stream>
diff --git a/handbook/streams.html b/handbook/streams.html index b42092d..6747464 100644 --- a/handbook/streams.html +++ b/handbook/streams.html @@ -153,8 +153,8 @@

Come Alive with Turbo Streams

Turbo Streams deliver page changes as fragments of HTML wrapped in self-executing <turbo-stream> elements. Each stream element specifies an action together with a target ID to declare what should happen to the HTML inside it. These elements are delivered by the server over a WebSocket, SSE or other transport to bring the application alive with updates made by other users or processes. A new email arriving in your imbox is a great example.

﹟ Stream Messages and Actions

-

A Turbo Streams message is a fragment of HTML consisting of <turbo-stream> elements. The stream message below demonstrates the seven possible stream actions:

-
<turbo-stream action="append" target="messages">
  <template>
    <div id="message_1">
      This div will be appended to the element with the DOM ID "messages".
    </div>
  </template>
</turbo-stream>

<turbo-stream action="prepend" target="messages">
  <template>
    <div id="message_1">
      This div will be prepended to the element with the DOM ID "messages".
    </div>
  </template>
</turbo-stream>

<turbo-stream action="replace" target="message_1">
  <template>
    <div id="message_1">
      This div will replace the existing element with the DOM ID "message_1".
    </div>
  </template>
</turbo-stream>

<turbo-stream action="update" target="unread_count">
  <template>
    <!-- The contents of this template will replace the
    contents of the element with ID "unread_count" by
    setting innerHtml to "" and then switching in the
    template contents. Any handlers bound to the element
    "unread_count" would be retained. This is to be
    contrasted with the "replace" action above, where
    that action would necessitate the rebuilding of
    handlers. -->
    1
  </template>
</turbo-stream>

<turbo-stream action="remove" target="message_1">
  <!-- The element with DOM ID "message_1" will be removed.
  The contents of this stream element are ignored. -->
</turbo-stream>

<turbo-stream action="before" target="current_step">
  <template>
    <!-- The contents of this template will be added before the
    the element with ID "current_step". -->
    <li>New item</li>
  </template>
</turbo-stream>

<turbo-stream action="after" target="current_step">
  <template>
    <!-- The contents of this template will be added after the
    the element with ID "current_step". -->
    <li>New item</li>
  </template>
</turbo-stream>
+

A Turbo Streams message is a fragment of HTML consisting of <turbo-stream> elements. The stream message below demonstrates the eight possible stream actions:

+
<turbo-stream action="append" target="messages">
  <template>
    <div id="message_1">
      This div will be appended to the element with the DOM ID "messages".
    </div>
  </template>
</turbo-stream>

<turbo-stream action="prepend" target="messages">
  <template>
    <div id="message_1">
      This div will be prepended to the element with the DOM ID "messages".
    </div>
  </template>
</turbo-stream>

<turbo-stream action="replace" target="message_1">
  <template>
    <div id="message_1">
      This div will replace the existing element with the DOM ID "message_1".
    </div>
  </template>
</turbo-stream>

<turbo-stream action="update" target="unread_count">
  <template>
    <!-- The contents of this template will replace the
    contents of the element with ID "unread_count" by
    setting innerHtml to "" and then switching in the
    template contents. Any handlers bound to the element
    "unread_count" would be retained. This is to be
    contrasted with the "replace" action above, where
    that action would necessitate the rebuilding of
    handlers. -->
    1
  </template>
</turbo-stream>

<turbo-stream action="remove" target="message_1">
  <!-- The element with DOM ID "message_1" will be removed.
  The contents of this stream element are ignored. -->
</turbo-stream>

<turbo-stream action="before" target="current_step">
  <template>
    <!-- The contents of this template will be added before the
    the element with ID "current_step". -->
    <li>New item</li>
  </template>
</turbo-stream>

<turbo-stream action="after" target="current_step">
  <template>
    <!-- The contents of this template will be added after the
    the element with ID "current_step". -->
    <li>New item</li>
  </template>
</turbo-stream>

<turbo-stream action="refresh" request-id="abcd-1234"></turbo-stream>

Note that every <turbo-stream> element must wrap its included HTML inside a <template> element.

A Turbo Stream can integrate with any element in the document that can be resolved by an id attribute or CSS selector (with the exception of <template> element or <iframe> element content). It is not necessary to change targeted elements into <turbo-frame> elements. If your application utilizes <turbo-frame> elements for the sake of a <turbo-stream> element, change the <turbo-frame> into another built-in element.

@@ -179,11 +179,11 @@

﹟ But What About Running JavaScript?

-

Turbo Streams consciously restricts you to seven actions: append, prepend, (insert) before, (insert) after, replace, update, and remove. If you want to trigger additional behavior when these actions are carried out, you should attach behavior using Stimulus controllers. This restriction allows Turbo Streams to focus on the essential task of delivering HTML over the wire, leaving additional logic to live in dedicated JavaScript files.

+

Turbo Streams consciously restricts you to eight actions: append, prepend, (insert) before, (insert) after, replace, update, remove, and refresh. If you want to trigger additional behavior when these actions are carried out, you should attach behavior using Stimulus controllers. This restriction allows Turbo Streams to focus on the essential task of delivering HTML over the wire, leaving additional logic to live in dedicated JavaScript files.

Embracing these constraints will keep you from turning individual responses into a jumble of behaviors that cannot be reused and which make the app hard to follow. The key benefit from Turbo Streams is the ability to reuse templates for initial rendering of a page through all subsequent updates.

﹟ Custom Actions

-

By default, Turbo Streams support seven values for its action attribute. If your application needs to support other behaviors, you can override the event.detail.render function.

-

For example, if you’d like to expand upon the seven actions to support <turbo-stream> elements with [action="alert"] or [action="log"], you could declare a turbo:before-stream-render listener to provide custom behavior:

+

By default, Turbo Streams support eight values for its action attribute. If your application needs to support other behaviors, you can override the event.detail.render function.

+

For example, if you’d like to expand upon the eight actions to support <turbo-stream> elements with [action="alert"] or [action="log"], you could declare a turbo:before-stream-render listener to provide custom behavior:

addEventListener("turbo:before-stream-render", ((event) => {
  const fallbackToDefaultActions = event.detail.render

  event.detail.render = function (streamElement) {
    if (streamElement.action == "alert") {
      // ...
    } else if (streamElement.action == "log") {
      // ...
    } else {
      fallbackToDefaultActions(streamElement)
    }
  }
}))

In addition to listening for turbo:before-stream-render events, applications can also declare actions as properties directly on StreamActions:

diff --git a/reference/streams.html b/reference/streams.html index 7d9079d..b966799 100644 --- a/reference/streams.html +++ b/reference/streams.html @@ -151,7 +151,7 @@

Streams

-

﹟ The seven actions

+

﹟ The eight actions

﹟ Append

Appends the content within the template tag to the container designated by the target dom id.

<turbo-stream action="append" target="dom_id">
  <template>
    Content to append to container designated with the dom_id.
  </template>
</turbo-stream>
@@ -175,6 +175,10 @@

﹟ Before

﹟ After

Inserts the content within the template tag after the element designated by the target dom id.

<turbo-stream action="after" target="dom_id">
  <template>
    Content to place after the element designated with the dom_id.
  </template>
</turbo-stream>
+

﹟ Refresh

+

Initiates a Page Refresh to render new content with +morphing.

+
<!-- without `[request-id]` -->
<turbo-stream action="refresh"></turbo-stream>

<!-- debounced with `[request-id]` -->
<turbo-stream action="refresh" request-id="abcd-1234"></turbo-stream>

﹟ Targeting Multiple Elements

To target multiple elements with a single action, use the targets attribute with a CSS query selector instead of the target attribute.

<turbo-stream action="remove" targets=".elementsWithClass">
</turbo-stream>

<turbo-stream action="after" targets=".elementsWithClass">
  <template>
    Content to place after the elements designated with the css query.
  </template>
</turbo-stream>