render_turbo_stream 2.1.2 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92144d161ab6a0eee72442b7b848a140b9f439cbda17a3e41ad4a28aa5f0a8cb
-  data.tar.gz: 3b290864b96789968ab8ad704b1127cb37ab6c00985c11c1cd87c28a2cb87695
+  metadata.gz: ef24460b794e7db6757f2ad199e94f9ce7df38615b9ed64bcdcfc0af978cf573
+  data.tar.gz: 1c14768ff0ee5277befcb9d039c37b7df5e549cf3f23910672583099ab387590
 SHA512:
-  metadata.gz: ea284231a3dd9343643a868bde136c954e32d0347354c5127f83b64e297e81309372214490df90580f32143c9a0f1422fe8f6abb2e2e1b9f7096726fb1454896
-  data.tar.gz: c8719357d38e4ced162e9bc2b94401ee3e7096f6097e1402b9ac9670c3b124326da0a9ac858b9ff5a434458efd010fb50d3b8104a6da6c8902cf0697cb748973
+  metadata.gz: 805e49cacca8b70246a6549c52a7e4bde532989ab80dcd375e0c238ed880aedf55a6f51ebc1275b030ad81daf6dae81753ffdb3590af14ba309383a7aa9473da
+  data.tar.gz: 5d7f808aaf2fa1b77338fbf8f4f236ec41bcf1c4b89113e9d55608a56ac349416a8a91e3fb951b387383b937cdd125c2c19816fad78191bfc0285245e41ef854

data/README.md

@@ -1,21 +1,19 @@
 # RenderTurboStream
 
-Defining templates like `(create|update).turbo_stream.haml` annoyed me. 
+DHH made a milestone in web development with [Rails 7, "Fulfilling a Vision"](https://rubyonrails.org/2021/12/15/Rails-7-fulfilling-a-vision). This gem is my contribution to that bold new step. The goal is to have a complete rails like workflow.
 
-Working consistently with turbo_stream or Turbo Streams Channel means shooting a lot of partials from the backend to the frontend. This always requires the same attributes: the path to the partial, the html id that turbo_stream points to, and maybe some locals, and maybe generate a translated flash message for update or create actions. All this can be done in one step directly from the controller.
+Defining templates like `(create|update).turbo_stream.haml` annoyed me. Because it is a heavy mix of logic and view. Working consistently with turbo_stream or Turbo Streams Channel means shooting a lot of partials from the backend to the frontend. There are many ways and tedious details to handle redirects since Turbo! There is a lot that can be streamlined.
 
-There are many ways and tedious details to handle redirects since Turbo! Below described are options.
+Execute [turbo_power](https://github.com/marcoroth/turbo_power) commands such as adding a css class to an html element, pushing a state to the browser history, or running custom javascript actions through Turbo Stream can be written in pure ruby code. No need for embeds like `.html.erb`.
 
-Turbo has seamlessly integrated Action Cable. The intention here is to bring it all together in a unified workflow with a sufficient testing strategy.
+Logic to ruby, view to views and the area between for the gem! And with specific testings for the Ruby side.
 
-Execute [turbo_power](https://github.com/marcoroth/turbo_power) commands, such as adding a css class to an html element, pushing a state to the browser history, or running custom javascript actions through Turbo Stream (cable not yet integrated here) can be written in pure ruby code. No need for embeds like `.html.erb`.
-
-This plugin is in a early state.
+This gem is in a early state.
 
 An overview of how we design a rails-7 application with turbo
 is [published on dev.to](https://dev.to/chmich/rails-7-vite-wrapping-up-1pia).
 
-A quick and dirty application with all the features, including tests, built in is [here](https://gitlab.com/sedl/renderturbostream_railsapp).
+A quick and dirty application with all the features, including built in tests is [here](https://gitlab.com/sedl/renderturbostream_railsapp).
 
 Hope it can help you.
 
@@ -34,15 +32,16 @@ bundle install
 ApplicationController
 
 ```ruby
-include RenderTurboStream
+include RenderTurboStream::ControllerHelpers
 ```
 
 spec/rails_helper.rb
 
 ```ruby
 RSpec.configure do |config|
-  config.include RenderTurboStream::Test::RequestHelpers, type: :request
-  config.include RenderTurboStream::Test::RspecRequestHelpers, type: :request #=> if you are on rspec
+  ...
+  config.include RenderTurboStream::Test::Request::Helpers, type: :request
+  config.include RenderTurboStream::Test::Request::ChannelHelpers, type: :request
 end
 ```
 
@@ -51,9 +50,10 @@ end
 Required Configurations for Flash Partial
 
 ```ruby
-config.x.render_turbo_stream.flash_partial = 'layouts/flash'
-config.x.render_turbo_stream.flash_id = 'flash-box'
-config.x.render_turbo_stream.flash_action = 'prepend'
+    config.x.render_turbo_stream.flash_partial = 'layouts/flash'
+    config.x.render_turbo_stream.flash_id = 'flash-box'
+    config.x.render_turbo_stream.flash_action = 'prepend'
+    config.x.render_turbo_stream.use_channel_for_turbo_stream_save = true
 ```
 
 The corresponding partials for flashes could look [like this](https://gitlab.com/sedl/renderturbostream/-/wikis/Flashes-example)
@@ -81,7 +81,8 @@ A comprehensive tutorial on turbo and how to check that it is working properly c
 
 **Turbo::StreamsChannel**
 
-The Rails team has seamlessly integrated `ActionCable` as `Turbo::StreamsChannel` into `Turbo Rails`. For installation along with this gem, see the [README](https://gitlab.com/sedl/renderturbostream/-/blob/main/README-cable.md).
+The Rails team has integrated `ActionCable` as `Turbo::StreamsChannel` into `Turbo Rails`. For installation along with this gem, see the [README-channels](https://gitlab.com/sedl/renderturbostream/-/blob/main/README-channels.md).
+
 # Usage
 
 `turbo_stream_save` is a special method for streamlining `update` or `create` functions with `turbo_stream`. A controller action for update might look like this:
@@ -90,10 +91,9 @@ The Rails team has seamlessly integrated `ActionCable` as `Turbo::StreamsChannel
 
 def update
   turbo_stream_save(
-    @customer.update(customer_params),
-    turbo_redirect_on_success_to: edit_customer_path(@customer),
-    id: 'customer-form',
-    partial: 'form'
+    @article.update(article_params),
+    turbo_redirect_on_success_to: (params['no_redirection'] == 'true' ? nil : articles_path),
+    id: 'form'
   )
 end
 ```
@@ -120,9 +120,9 @@ The `stream_partial` method is for rendering a partial alone.
 
 ```ruby
 stream_partial(
-  id,
+  'flash-box',
   partial: nil, #=> default: id.gsub('-','_')
-  locals: {},
+  locals: { title: 'my title' },
   action: nil #=> default: :replace
 )
 ```
@@ -158,7 +158,7 @@ Suppose you have a CRUD controller that should do all its actions inside a turbo
 There are two workarounds:
 
 ```ruby
-config.x.render_turbo_stream.use_cable_for_turbo_stream_save = true
+config.x.render_turbo_stream.use_channel_for_turbo_stream_save = true
 ```
 
 With this config, the `turbo_stream_save` method will send flash messages through `Turbo::StreamsChannel` (if installed as described above) to a channel to the currently logged in user in parallel with the redirect.
@@ -213,81 +213,48 @@ def update
     flashes_on_error: [] #=> array of strings
 
 
-# Testing Scenarios
+# Testing
 
 For system testing there is Capybara. Its the only way to check if frontend and backend work together. But its a good practice to break tests into smaller pieces. The much larger number of tests we will write on the much faster request tests, examples here in rspec.
 
+**request tests cannot test javascript. they only test the ruby side: check if the right content is sent to turbo**.
+
 If the request format is not `turbo_stream`, which is the case on request specs, the method responds in a special html
 that contains the medadata that is interesting for our tests and is parsed by included test helpers. 
 
-There is a helper for writing the test: In the debugger, within the test, check the output of `streams_log`.
+There is a helper for writing the test: In the debugger, within the test, check the output of `all_turbo_responses`.
 
 Test scenarios are:
 
 **The fastest**
 
-If you want to check if a controller action succeeded, just check for `response.status`. The `turbo_stream_save` method returns three statuses: `200` if `save_action` is true, otherwise `422` and `302` for redirect. If one of the declared partials does not exist or breaks, the server will respond with exception anyway. 
-
-**rspec**
-
-For rspec there is a special helper, for a successful save action:
-
-```ruby
-it 'update failed' do
-  patch article_path(article, params: valid_params)
-  expect_successful_saved('customer-form', 'flash-box')
-  # expects response.status 200
-  # Make sure that the responses point to exactly these 2 IDs ('form' and 'flash-box').
-  # Make sure that to each ID is responded to exactly once.
-end
-```
+If you want to check if a controller action succeeded, just check for `response.status`. The `turbo_stream_save` method returns three statuses: `200` if `save_action` is true, otherwise `422` and `302` for redirect. If one of the declared partials does not exist or breaks, the server will respond with exception anyway.
 
 **Redirection**
 ```ruby
   it 'update success' do
-    patch article_path(article, params: valid_params)
-    expect(turbo_redirect_to).to eq(articles_path)
-  end
+  patch article_path(article, params: valid_params)
+  expect(turbo_redirect_to).to eq(articles_path)
+end
 ```
 
-**Easier check what the partials have done**
+**Test turbo stream response**
 
-For checking a little more inside the partial responses, but with a simple syntax that checks for a one-time response from a specific partial and may be sufficient for most cases:
 ```ruby
-expect(stream_targets_count).to eq(2)
+expect(turbo_targets.length).to eq(2)
 # Check the total number of targeted html-ids, in most cases it will be one form and one flash.
- 
-expect(stream_response('customer-form')).to eq(true)
-# Make sure that the id «customer-form» is targeted exactly once.
 
-expect(stream_response('customer-form', css: '.field_with_errors', include_string: 'Title')).to eq(true)
-# Verify that the response targeted to "customer-form" contains the specified html.
+assert_stream_response('form'){|e|e.css('.field_with_errors').inner_html.include?('title')}
+# make sure that there is one response to the target '#form' and it checks the rendered content
+# if cero or more responses are expected, add a attribute like 'count: 0'
 ```
-
-**More detailed**
-
-Consider a controller action that should respond in 2 flashes:
+Possible matchers can be found at [Nokogiri](https://nokogiri.org/tutorials/searching_a_xml_html_document.html).
 
 ```ruby
-expect(stream_targets_count).to eq(1)
-
-expect(
-  stream_target_response_count('flash-box', total: 2) do |p|
-    p.css('.callout.success').inner_html.include?('All perfect')
-  end
-).to eq(1)
-
-expect(
-  stream_target_response_count('flash-box', total: 2) do |p|
-    p.css('.callout.alert').inner_html.include?('Something went wrong')
-  end
-).to eq(1)
+# check actions from turbo_power gem
+assert_stream_response('colored-element', action: 'remove_css_class') {|args| args.last == 'background-red' }
+# block (all within {}) is optional
 ```
-`stream_target_response_count` returns the number of matched responses.
-
-Possible matchers can be found at [Nokogiri](https://nokogiri.org/tutorials/searching_a_xml_html_document.html). 
-
-For more detailed testing of partials, there are view tests.
 
 **P.S.:**
 
@@ -296,7 +263,7 @@ includes the plugin and has tests done by rspec/request and capybara.
 
 # More Configs
 
-On test helpers, the marker for a turbo-stream target is in most cases the id of the target element. This is true for the standard turbo-stream functions. On `turbo_power` it is the same in most cases. `RenderTurboStream::Libs.first_arg_is_html_id()` checks for which methods this is true. You can override this:
+On test helpers, the marker for a turbo-stream target is in most cases the id of the target element. This is true for the standard turbo-stream functions. On `turbo_power` it is the same in most cases. `RenderTurboStream::Test::Request::Libs.first_arg_is_html_id()` checks for which methods this is true. You can override this:
 
 ```ruby
 config.x.render_turbo_stream.first_argument_is_html_id = %[replace append prepend turbo_frame_set_src]

data/app/views/render_turbo_stream_command.html.erb

@@ -0,0 +1 @@
+<%= turbo_stream.send(command, *arguments) %>

data/app/views/{render_turbo_stream.html.erb → render_turbo_stream_request_test.html.erb}

@@ -4,9 +4,9 @@
 <% streams.each do |s| %>
 
   <% if s.is_a?(Array) %>
-    <% attr_id = RenderTurboStream::Libs.first_arg_is_html_id(s.first) %>
-    <% h = { attributes: s, type: 'command' } %>
-    <% h[:target] = "##{s.second}" if attr_id %>
+    <% attr_id = RenderTurboStream::Test::Request::Libs.first_arg_is_html_id(s.first) %>
+    <% h = { array: s, type: 'stream-command', action: s.first } %>
+    <% h[:target] = "##{s.second[0]=='#' ? s.second[1..-1] : s.second}" if attr_id %>
     <% rendered_partials.push(h) %>
   <% else %>
     <% html = (render s[:partial], locals: s[:locals]&.symbolize_keys, formats: [:html]) %>

data/lib/render_turbo_stream/channel_libs.rb

@@ -0,0 +1,94 @@
+module RenderTurboStream
+  class ChannelLibs
+
+    def self.render_to_channel(response, channel, target_id, action, partial: nil, template: nil, locals: nil)
+
+      locals = {} unless locals # prevent error missing keys for nil
+
+      # add headers for test
+      if Rails.env.test?
+        html = RenderTurboStreamRenderController.render(partial: partial, locals: locals) if partial
+        html = RenderTurboStreamRenderController.render(template: template, locals: locals) if template
+        props = {
+          target: "##{target_id}",
+          action: action,
+          type: 'channel-partial',
+          locals: locals,
+          channel: channel,
+          html_response: html.to_s
+        }
+
+        props[:partial] = partial if partial
+        props[:template] = template if template
+        h = response.headers.to_h
+        i = 1
+        loop do
+          k = "test-turbo-channel-#{i}"
+          unless h.keys.include?(k)
+            response.headers[k] = props.to_json
+            break
+          end
+          i += 1
+        end
+      end
+
+      # send
+
+      if partial
+        Turbo::StreamsChannel.send(
+          "broadcast_#{action}_to",
+          channel.to_s,
+          target: target_id,
+          partial: partial,
+          locals: locals&.symbolize_keys,
+          layout: false
+        )
+      elsif template
+        Turbo::StreamsChannel.send(
+          "broadcast_#{action}_to",
+          channel.to_s,
+          target: target_id,
+          template: template,
+          locals: locals&.symbolize_keys,
+          layout: false
+        )
+      end
+    end
+
+    def self.action_to_channel(response, channel, command, arguments)
+
+      if Rails.env.test?
+
+        props = {
+          action: command,
+          type: 'channel-command',
+          channel: channel,
+          array: [command] + arguments,
+        }
+        if RenderTurboStream::Test::Request::Libs.first_arg_is_html_id(command)
+          target_id = (arguments.first[0..0] == '#' ? arguments.first[1..-1] : arguments.first)
+          props[:target] = "##{target_id}"
+        end
+        
+        h = response.headers.to_h
+        i = 1
+        loop do
+          k = "test-turbo-channel-#{i}"
+          unless h.keys.include?(k)
+            response.headers[k] = props.to_json
+            break
+          end
+          i += 1
+        end
+      end
+
+      content = RenderTurboStreamRenderController.render(template: 'render_turbo_stream_command', layout: false, locals: { command: command, arguments: arguments })
+
+      Turbo::StreamsChannel.broadcast_stream_to(
+        channel,
+        content: content
+      )
+    end
+
+  end
+end

data/lib/render_turbo_stream/channel_view_helpers.rb

@@ -0,0 +1,36 @@
+module RenderTurboStream
+  module ChannelViewHelpers
+
+    def channel_from_me
+      if current_user
+        turbo_stream_from "authenticated-user-#{current_user.id}"
+      else
+        Rails.logger.debug("  • SKIP channel_from_me because not authenticated")
+        nil
+      end
+    end
+
+    def channel_from_authenticated_group(group)
+      if current_user
+        turbo_stream_from "authenticated-group-#{group}"
+      else
+        Rails.logger.debug("  • SKIP channel_from_authenticated_group because not authenticated")
+        nil
+      end
+    end
+
+    def channel_from_all
+      turbo_stream_from "all"
+    end
+
+    def channel_from_group(group)
+      if group.present?
+        turbo_stream_from group
+      else
+        Rails.logger.debug("  • SKIP channel_from_group because no group given")
+        nil
+      end
+    end
+
+  end
+end

data/lib/render_turbo_stream/controller_channel_helpers.rb

@@ -0,0 +1,121 @@
+module RenderTurboStream
+  module ControllerChannelHelpers
+
+    def render_to_all(target_id, action = :replace, partial: nil, template: nil, locals: nil)
+      render_to_channel(
+        'all',
+        target_id,
+        action,
+        partial: partial,
+        template: template,
+        locals: locals
+      )
+    end
+
+    def render_to_me(target_id, action = :replace, partial: nil, locals: nil)
+      begin
+        u_id = helpers.current_user&.id
+        unless u_id.present?
+          Rails.logger.debug('  • SKIP RenderTurboStream.render_to_me because current_user is nil')
+          return
+        end
+      rescue
+        Rails.logger.debug('  • ERROR RenderTurboStream.render_to_me because current_user is not available')
+        return
+      end
+
+      render_to_channel(
+        "authenticated-user-#{helpers.current_user.id}",
+        target_id,
+        action,
+        partial: partial,
+        locals: locals
+      )
+    end
+
+    def render_to_authenticated_group(group, target_id, action = :replace, partial: nil, locals: nil)
+      begin
+        u_id = helpers.current_user&.id
+        unless u_id.present?
+          Rails.logger.debug('  • SKIP RenderTurboStream.render_to_authenticated_group because current_user is nil')
+          return
+        end
+      rescue
+        Rails.logger.debug('  • ERROR RenderTurboStream.render_to_authenticated_group because current_user method is not available')
+        return
+      end
+
+      render_to_channel(
+        "authenticated-group-#{group}",
+        target_id,
+        action,
+        partial: partial,
+        locals: locals
+      )
+    end
+
+    def render_to_channel(channel, target_id, action, partial: nil, template: nil, locals: nil)
+
+      disable_default = false
+      if partial
+        template = nil
+      elsif template.present? && !template.to_s.include?('/')
+        template = [controller_path, template].join('/')
+        disable_default = true
+      else
+        template = [controller_path, action_name].join('/')
+        disable_default = true
+      end
+
+      if disable_default && !@render_cable_template_was_called
+        # make sure default render action returns nil
+        render template: 'render_turbo_stream_empty_template', layout: false unless @render_cable_template_was_called
+        @render_cable_template_was_called = true
+      end
+
+      RenderTurboStream::ChannelLibs.render_to_channel(response, channel, target_id, action, template: template, partial: partial, locals: locals)
+
+    end
+
+    def action_to_all(action, *arguments)
+      action_to_channel('all', action, arguments)
+    end
+
+    def action_to_me(action, *arguments)
+
+      begin
+        u_id = helpers.current_user&.id
+        unless u_id.present?
+          Rails.logger.debug('  • SKIP RenderTurboStream.action_to_me because current_user is nil')
+          return
+        end
+      rescue
+        Rails.logger.debug('  • ERROR RenderTurboStream.action_to_me because current_user is not available')
+        return
+      end
+
+      action_to_channel("authenticated-user-#{helpers.current_user.id}", action, arguments)
+    end
+
+    def action_to_authenticated_group(group, action, *arguments)
+
+      begin
+        u_id = helpers.current_user&.id
+        unless u_id.present?
+          Rails.logger.debug('  • SKIP RenderTurboStream.action_to_authenticated_group because current_user is nil')
+          return
+        end
+      rescue
+        Rails.logger.debug('  • ERROR RenderTurboStream.action_to_authenticated_group because current_user method is not available')
+        return
+      end
+
+      action_to_channel("authenticated-group-#{group}", action, arguments)
+    end
+
+    def action_to_channel(channel, command, arguments)
+      RenderTurboStream::ChannelLibs.action_to_channel(response, channel, command, arguments)
+    end
+
+  end
+end