render_turbo_stream 2.1.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac522064ae87773819b4fdd059166e10a8bbb805de1dbbd020781f806ac6faeb
-  data.tar.gz: a78259d9e2468305da273618929296735f3217592ed0ac2f0311e14b9c913eaf
+  metadata.gz: 733ef3518b8c95cb2f5162d0abb6d6278e653219bf5a99b502159fa52e884be8
+  data.tar.gz: b526a407a00b9dee9e5e543a48d80d14c073d87bf2397ea9bf2c0027a3366527
 SHA512:
-  metadata.gz: b9e22fa2a8dbb9d7bb85d9fd19993ac6511c4cf9364c20da4b950b4bb368839c48f8c6ac93f31452592bc286f717d4c63107db7757731e339f1a37b871c7332a
-  data.tar.gz: 5c13d3c56d66450c20920403cef30c18c18e0101ba0c3de86516d9db26d57edcd5c3a37866dc6e2c9052e0f2be34c2751486b29361dd93a5b1f54f5255660dc6
+  metadata.gz: edf51ffaf2a192f7eb65f6147ba3d2b64cbb07d0c444a4bc00ec2d7a145cceaac943704ec1b50199e0ac1b4f42e3f524386679d682af728ca0f577b865dc72d9
+  data.tar.gz: '09e87e2f74275a48a459d47dac942c66787e2127d9cf61e08ff16a3e7dcf5cc63708d4c1b0d4d7fba89a429a0ff76f5e95a491906650ba167bf27bde82784afd'

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,17 @@ bundle install
 ApplicationController
 
 ```ruby
-include RenderTurboStream
+include RenderTurboStream::ControllerHelpers
+include RenderTurboStream::ControllerChannelHelpers
 ```
 
 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 +51,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_cable_for_turbo_stream_save = true
 ```
 
 The corresponding partials for flashes could look [like this](https://gitlab.com/sedl/renderturbostream/-/wikis/Flashes-example)
@@ -81,7 +82,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](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 +92,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 +121,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
 )
 ```
@@ -213,81 +214,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 +264,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,93 @@
+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