turbo-rails 1.5.0 → 2.0.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +126 -16
- data/app/assets/javascripts/turbo.js +2226 -953
- data/app/assets/javascripts/turbo.min.js +9 -5
- data/app/assets/javascripts/turbo.min.js.map +1 -1
- data/app/channels/turbo/streams/broadcasts.rb +47 -10
- data/app/channels/turbo/streams_channel.rb +15 -15
- data/app/controllers/concerns/turbo/request_id_tracking.rb +12 -0
- data/app/controllers/turbo/frames/frame_request.rb +2 -2
- data/app/controllers/turbo/native/navigation.rb +17 -11
- data/app/helpers/turbo/drive_helper.rb +72 -14
- data/app/helpers/turbo/frames_helper.rb +8 -8
- data/app/helpers/turbo/streams/action_helper.rb +12 -4
- data/app/helpers/turbo/streams_helper.rb +5 -0
- data/app/javascript/turbo/cable_stream_source_element.js +10 -0
- data/app/javascript/turbo/index.js +2 -0
- data/app/jobs/turbo/streams/action_broadcast_job.rb +2 -2
- data/app/jobs/turbo/streams/broadcast_job.rb +1 -1
- data/app/jobs/turbo/streams/broadcast_stream_job.rb +7 -0
- data/app/models/concerns/turbo/broadcastable.rb +201 -42
- data/app/models/turbo/debouncer.rb +24 -0
- data/app/models/turbo/streams/tag_builder.rb +50 -12
- data/app/models/turbo/thread_debouncer.rb +28 -0
- data/config/routes.rb +3 -4
- data/lib/install/turbo_with_importmap.rb +1 -1
- data/lib/tasks/turbo_tasks.rake +0 -22
- data/lib/turbo/broadcastable/test_helper.rb +5 -5
- data/lib/turbo/engine.rb +80 -9
- data/lib/turbo/system_test_helper.rb +128 -0
- data/lib/turbo/test_assertions/integration_test_assertions.rb +2 -2
- data/lib/turbo/test_assertions.rb +2 -2
- data/lib/turbo/version.rb +1 -1
- data/lib/turbo-rails.rb +10 -0
- metadata +10 -19
- data/lib/install/turbo_needs_redis.rb +0 -20
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: caaac3cb2273385e8f6ce553077cda24dfe79dec5b67c01aa2895b9c0053ea55
|
|
4
|
+
data.tar.gz: 95760946d353827c09cd57d9f88a678ea56f21f3365a78df5b996ee654bffbd6
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 50d447ead41f0524f3177e4d25a4b7085bc282de2b66234f4a01cf515b00600959172c23bf9d0640929e460246b511d08e55f262b5e2901aadc2bc8add5ade9c
|
|
7
|
+
data.tar.gz: e822ce8f0ada6d357a4ba28787d8d62dcbfa29001d84239abd026ee6808cf8adfdb4be9b054a3f60b6091b21bff00980ebcb3847dc34fe7932100d6366990278
|
data/README.md
CHANGED
|
@@ -6,12 +6,11 @@ On top of accelerating web applications, Turbo was built from the ground-up to f
|
|
|
6
6
|
|
|
7
7
|
Turbo is a language-agnostic framework written in JavaScript, but this gem builds on top of those basics to make the integration with Rails as smooth as possible. You can deliver turbo updates via model callbacks over Action Cable, respond to controller actions with native navigation or standard redirects, and render turbo frames with helpers and layout-free responses.
|
|
8
8
|
|
|
9
|
-
|
|
10
9
|
## Navigate with Turbo Drive
|
|
11
10
|
|
|
12
11
|
Turbo is a continuation of the ideas from the previous [Turbolinks](https://github.com/turbolinks/turbolinks) framework, and the heart of that past approach lives on as Turbo Drive. When installed, Turbo automatically intercepts all clicks on `<a href>` links to the same domain. When you click an eligible link, Turbo prevents the browser from following it. Instead, Turbo changes the browser’s URL using the History API, requests the new page using `fetch`, and then renders the HTML response.
|
|
13
12
|
|
|
14
|
-
During rendering, Turbo replaces the current `<body>` element outright and merges the contents of the `<head>` element. The JavaScript window and document objects, and the
|
|
13
|
+
During rendering, Turbo replaces the current `<body>` element outright and merges the contents of the `<head>` element. The JavaScript window and document objects, and the `<html>` element, persist from one rendering to the next.
|
|
15
14
|
|
|
16
15
|
Whereas Turbolinks previously just dealt with links, Turbo can now also process form submissions and responses. This means the entire flow in the web application is wrapped into Turbo, making all the parts fast. No more need for `data-remote=true`.
|
|
17
16
|
|
|
@@ -51,13 +50,13 @@ For instance:
|
|
|
51
50
|
<% end %>
|
|
52
51
|
```
|
|
53
52
|
|
|
54
|
-
When the user
|
|
53
|
+
When the user clicks on the `Edit this todo` link, as a direct response to this user interaction, the turbo frame will be automatically replaced with the one in the `edit.html.erb` page.
|
|
55
54
|
|
|
56
55
|
[See documentation](https://turbo.hotwired.dev/handbook/frames).
|
|
57
56
|
|
|
58
57
|
### A note on custom layouts
|
|
59
58
|
|
|
60
|
-
In order to render turbo frame requests without the application layout, Turbo registers a custom [layout method](https://api.rubyonrails.org/classes/ActionView/Layouts/ClassMethods.html#method-i-layout).
|
|
59
|
+
In order to render turbo frame requests without the application layout, Turbo registers a custom [layout method](https://api.rubyonrails.org/classes/ActionView/Layouts/ClassMethods.html#method-i-layout).
|
|
61
60
|
If your application uses custom layout resolution, you have to make sure to return `"turbo_rails/frame"` (or `false` for TurboRails < 1.4.0) for turbo frame requests:
|
|
62
61
|
|
|
63
62
|
```ruby
|
|
@@ -65,7 +64,7 @@ layout :custom_layout
|
|
|
65
64
|
|
|
66
65
|
def custom_layout
|
|
67
66
|
return "turbo_rails/frame" if turbo_frame_request?
|
|
68
|
-
|
|
67
|
+
|
|
69
68
|
# ... your custom layout logic
|
|
70
69
|
```
|
|
71
70
|
|
|
@@ -75,14 +74,14 @@ If you are using a custom, but "static" layout,
|
|
|
75
74
|
layout "some_static_layout"
|
|
76
75
|
```
|
|
77
76
|
|
|
78
|
-
you **have** to change it to a layout method in order to conditionally return `
|
|
77
|
+
you **have** to change it to a layout method in order to conditionally return `"turbo_rails/frame"` for turbo frame requests:
|
|
79
78
|
|
|
80
79
|
```ruby
|
|
81
80
|
layout :custom_layout
|
|
82
81
|
|
|
83
82
|
def custom_layout
|
|
84
83
|
return "turbo_rails/frame" if turbo_frame_request?
|
|
85
|
-
|
|
84
|
+
|
|
86
85
|
"some_static_layout"
|
|
87
86
|
```
|
|
88
87
|
|
|
@@ -101,6 +100,64 @@ This gem provides a `turbo_stream_from` helper to create a turbo stream.
|
|
|
101
100
|
<%# Rest of show here %>
|
|
102
101
|
```
|
|
103
102
|
|
|
103
|
+
### Testing Turbo Stream Broadcasts
|
|
104
|
+
|
|
105
|
+
Receiving server-generated Turbo Broadcasts requires a connected Web Socket.
|
|
106
|
+
Views that render `<turbo-cable-stream-source>` elements with the
|
|
107
|
+
`#turbo_stream_from` view helper incur a slight delay before they're ready to
|
|
108
|
+
receive broadcasts. In System Tests, that delay can disrupt Capybara's built-in
|
|
109
|
+
synchronization mechanisms that wait for or assert on content that's broadcast
|
|
110
|
+
over Web Sockets. For example, consider a test that navigates to a page and then
|
|
111
|
+
immediately asserts that broadcast content is present:
|
|
112
|
+
|
|
113
|
+
```ruby
|
|
114
|
+
test "renders broadcasted Messages" do
|
|
115
|
+
message = Message.new content: "Hello, from Action Cable"
|
|
116
|
+
|
|
117
|
+
visit "/"
|
|
118
|
+
click_link "All Messages"
|
|
119
|
+
message.save! # execute server-side code to broadcast a Message
|
|
120
|
+
|
|
121
|
+
assert_text message.content
|
|
122
|
+
end
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
If the call to `Message#save!` executes quickly enough, it might beat-out any
|
|
126
|
+
`<turbo-cable-stream-source>` elements rendered by the call to `click_link "All
|
|
127
|
+
Messages"`.
|
|
128
|
+
|
|
129
|
+
To wait for any disconnected `<turbo-cable-stream-source>` elements to connect,
|
|
130
|
+
call [`#connect_turbo_cable_stream_sources`](https://github.com/hotwired/turbo-rails/blob/main/lib/turbo/system_test_helper.rb):
|
|
131
|
+
|
|
132
|
+
```diff
|
|
133
|
+
test "renders broadcasted Messages" do
|
|
134
|
+
message = Message.new content: "Hello, from Action Cable"
|
|
135
|
+
|
|
136
|
+
visit "/"
|
|
137
|
+
click_link "All Messages"
|
|
138
|
+
+ connect_turbo_cable_stream_sources
|
|
139
|
+
message.save! # execute server-side code to broadcast a Message
|
|
140
|
+
|
|
141
|
+
assert_text message.content
|
|
142
|
+
end
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
By default, calls to [`#visit`](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Session:visit) will wait for all `<turbo-cable-stream-source>` elements to connect. You can control this by modifying the `config.turbo.test_connect_after_actions`. For example, to wait after calls to [`#click_link`](https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Actions:click_link), add the following to `config/environments/test.rb`:
|
|
146
|
+
|
|
147
|
+
```ruby
|
|
148
|
+
# config/environments/test.rb
|
|
149
|
+
|
|
150
|
+
config.turbo.test_connect_after_actions << :click_link
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
To disable automatic connecting, set the configuration to `[]`:
|
|
154
|
+
|
|
155
|
+
```ruby
|
|
156
|
+
# config/environments/test.rb
|
|
157
|
+
|
|
158
|
+
config.turbo.test_connect_after_actions = []
|
|
159
|
+
```
|
|
160
|
+
|
|
104
161
|
[See documentation](https://turbo.hotwired.dev/handbook/streams).
|
|
105
162
|
|
|
106
163
|
## Installation
|
|
@@ -110,9 +167,8 @@ This gem is automatically configured for applications made with Rails 7+ (unless
|
|
|
110
167
|
1. Add the `turbo-rails` gem to your Gemfile: `gem 'turbo-rails'`
|
|
111
168
|
2. Run `./bin/bundle install`
|
|
112
169
|
3. Run `./bin/rails turbo:install`
|
|
113
|
-
4. Run `./bin/rails turbo:install:redis` to change the development Action Cable adapter from Async (the default one) to Redis. The Async adapter does not support Turbo Stream broadcasting.
|
|
114
170
|
|
|
115
|
-
Running `turbo:install` will install through NPM if
|
|
171
|
+
Running `turbo:install` will install through NPM or Bun if a JavaScript runtime is used in the application. Otherwise the asset pipeline version is used. To use the asset pipeline version, you must have `importmap-rails` installed first and listed higher in the Gemfile.
|
|
116
172
|
|
|
117
173
|
If you're using node and need to use the cable consumer, you can import [`cable`](https://github.com/hotwired/turbo-rails/blob/main/app/javascript/turbo/cable.js) (`import { cable } from "@hotwired/turbo-rails"`), but ensure that your application actually *uses* the members it `import`s when using this style (see [turbo-rails#48](https://github.com/hotwired/turbo-rails/issues/48)).
|
|
118
174
|
|
|
@@ -122,17 +178,27 @@ The `Turbo` instance is automatically assigned to `window.Turbo` upon import:
|
|
|
122
178
|
import "@hotwired/turbo-rails"
|
|
123
179
|
```
|
|
124
180
|
|
|
125
|
-
|
|
126
181
|
## Usage
|
|
127
182
|
|
|
128
183
|
You can watch [the video introduction to Hotwire](https://hotwired.dev/#screencast), which focuses extensively on demonstrating Turbo in a Rails demo. Then you should familiarize yourself with [Turbo handbook](https://turbo.hotwired.dev/handbook/introduction) to understand Drive, Frames, and Streams in-depth. Finally, dive into the code documentation by starting with [`Turbo::FramesHelper`](https://github.com/hotwired/turbo-rails/blob/main/app/helpers/turbo/frames_helper.rb), [`Turbo::StreamsHelper`](https://github.com/hotwired/turbo-rails/blob/main/app/helpers/turbo/streams_helper.rb), [`Turbo::Streams::TagBuilder`](https://github.com/hotwired/turbo-rails/blob/main/app/models/turbo/streams/tag_builder.rb), and [`Turbo::Broadcastable`](https://github.com/hotwired/turbo-rails/blob/main/app/models/concerns/turbo/broadcastable.rb).
|
|
129
184
|
|
|
185
|
+
Note that in development, the default Action Cable adapter is the single-process `async` adapter. This means that turbo updates are only broadcast within that same process. So you can't start `bin/rails console` and trigger Turbo broadcasts and expect them to show up in a browser connected to a server running in a separate `bin/dev` or `bin/rails server` process. Instead, you should use the web-console when needing to manaually trigger Turbo broadcasts inside the same process. Add "console" to any action or "<%= console %>" in any view to make the web console appear.
|
|
186
|
+
|
|
130
187
|
### RubyDoc Documentation
|
|
131
188
|
|
|
132
|
-
For the API documentation covering this gem's classes and packages, [visit the
|
|
133
|
-
|
|
189
|
+
For the API documentation covering this gem's classes and packages, [visit the RubyDoc page](https://rubydoc.info/github/hotwired/turbo-rails/main).
|
|
190
|
+
Note that this documentation is updated automatically from the main branch, so it may contain features that are not released yet.
|
|
134
191
|
|
|
135
|
-
[
|
|
192
|
+
- [Turbo Drive Helpers](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/DriveHelper)
|
|
193
|
+
- [Turbo Frames Helpers](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/FramesHelper)
|
|
194
|
+
- [Turbo Streams View Helpers](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/StreamsHelper)
|
|
195
|
+
- [Turbo Streams Broadcast Methods](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/Broadcastable)
|
|
196
|
+
- [Turbo Streams Channel](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/StreamsChannel)
|
|
197
|
+
- [Turbo Native Navigation](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/Native/Navigation)
|
|
198
|
+
- [Turbo Test Assertions](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/TestAssertions)
|
|
199
|
+
- [Turbo Integration Test Assertions](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/TestAssertions/IntegrationTestAssertions)
|
|
200
|
+
- [Turbo Broadcastable Test Helper](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/Broadcastable/TestHelper)
|
|
201
|
+
- [Turbo System Test Helper](https://rubydoc.info/github/hotwired/turbo-rails/main/Turbo/SystemTestHelper)
|
|
136
202
|
|
|
137
203
|
## Compatibility with Rails UJS
|
|
138
204
|
|
|
@@ -140,17 +206,61 @@ Turbo can coexist with Rails UJS, but you need to take a series of upgrade steps
|
|
|
140
206
|
|
|
141
207
|
## Testing
|
|
142
208
|
|
|
143
|
-
|
|
144
|
-
The [`Turbo::TestAssertions`](./lib/turbo/test_assertions.rb) concern provides Turbo Stream test helpers that assert the presence or absence of `<turbo-stream>` elements in a rendered fragment of HTML. `Turbo::TestAssertions` are automatically included in [`ActiveSupport::TestCase`](https://edgeapi.rubyonrails.org/classes/ActiveSupport/TestCase.html) and depend on the presence of [`rails-dom-testing`](https://github.com/rails/rails-dom-testing/) assertions.
|
|
209
|
+
The [`Turbo::TestAssertions`](./lib/turbo/test_assertions.rb) concern provides Turbo Stream test helpers that assert the presence or absence ofs s `<turbo-stream>` elements in a rendered fragment of HTML. `Turbo::TestAssertions` are automatically included in [`ActiveSupport::TestCase`](https://edgeapi.rubyonrails.org/classes/ActiveSupport/TestCase.html) and depend on the presence of [`rails-dom-testing`](https://github.com/rails/rails-dom-testing/) assertions.
|
|
145
210
|
|
|
146
211
|
The [`Turbo::TestAssertions::IntegrationTestAssertions`](./lib/turbo/test_assertions/integration_test_assertions.rb) are built on top of `Turbo::TestAssertions`, and add support for passing a `status:` keyword. They are automatically included in [`ActionDispatch::IntegrationTest`](https://edgeguides.rubyonrails.org/testing.html#integration-testing).
|
|
147
212
|
|
|
148
|
-
The [`Turbo::Broadcastable::TestHelper`](./lib/turbo/broadcastable/test_helper.rb) concern provides Action Cable-aware test helpers that assert that `<turbo-stream>` elements were or were not broadcast over Action Cable.
|
|
213
|
+
The [`Turbo::Broadcastable::TestHelper`](./lib/turbo/broadcastable/test_helper.rb) concern provides Action Cable-aware test helpers that assert that `<turbo-stream>` elements were or were not broadcast over Action Cable. `Turbo::Broadcastable::TestHelper` is automatically included in [`ActiveSupport::TestCase`](https://edgeapi.rubyonrails.org/classes/ActiveSupport/TestCase.html).
|
|
214
|
+
|
|
215
|
+
### Rendering Outside of a Request
|
|
216
|
+
|
|
217
|
+
Turbo utilizes [ActionController::Renderer][] to render templates and partials
|
|
218
|
+
outside the context of the request-response cycle. If you need to render a
|
|
219
|
+
Turbo-aware template, partial, or component, use [ActionController::Renderer][]:
|
|
220
|
+
|
|
221
|
+
```ruby
|
|
222
|
+
ApplicationController.renderer.render template: "posts/show", assigns: { post: Post.first } # => "<html>…"
|
|
223
|
+
PostsController.renderer.render :show, assigns: { post: Post.first } # => "<html>…"
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
As a shortcut, you can also call render directly on the controller class itself:
|
|
227
|
+
|
|
228
|
+
```ruby
|
|
229
|
+
ApplicationController.render template: "posts/show", assigns: { post: Post.first } # => "<html>…"
|
|
230
|
+
PostsController.render :show, assigns: { post: Post.first } # => "<html>…"
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
[ActionController::Renderer]: https://api.rubyonrails.org/classes/ActionController/Renderer.html
|
|
149
234
|
|
|
150
235
|
## Development
|
|
151
236
|
|
|
152
237
|
Run the tests with `./bin/test`.
|
|
153
238
|
|
|
239
|
+
### Using local Turbo version
|
|
240
|
+
|
|
241
|
+
Often you might want to test changes made locally to [Turbo lib](https://github.com/hotwired/turbo) itself. To package your local development version of Turbo you can use [yarn link](https://classic.yarnpkg.com/lang/en/docs/cli/link/) feature:
|
|
242
|
+
|
|
243
|
+
```sh
|
|
244
|
+
cd <local-turbo-dir>
|
|
245
|
+
yarn link
|
|
246
|
+
|
|
247
|
+
cd <local-turbo-rails-dir>
|
|
248
|
+
yarn link @hotwired/turbo
|
|
249
|
+
|
|
250
|
+
# Build the JS distribution files...
|
|
251
|
+
yarn build
|
|
252
|
+
# ...and commit the changes
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
Now you can reference your version of turbo-rails in your Rails projects packaged with your local version of Turbo.
|
|
256
|
+
|
|
257
|
+
## Contributing
|
|
258
|
+
|
|
259
|
+
Having a way to reproduce your issue will help people confirm, investigate, and ultimately fix your issue. You can do this by providing an executable test case. To make this process easier, we have prepared an [executable bug report Rails application](./bug_report_template.rb) for you to use as a starting point.
|
|
260
|
+
|
|
261
|
+
This template includes the boilerplate code to set up a System Test case. Copy the content of the template into a `.rb` file and make the necessary changes to demonstrate the issue. You can execute it by running `ruby the_file.rb` in your terminal. If all goes well, you should see your test case failing.
|
|
262
|
+
|
|
263
|
+
You can then share your executable test case as a gist or paste the content into the issue description.
|
|
154
264
|
|
|
155
265
|
## License
|
|
156
266
|
|