svelte-on-rails 5.0.0 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 702cfaf256c84b2e8f17356ed333b63e14d4d1252f7e1e2dabd1698d350a4461
-  data.tar.gz: d7b63bfce50f3aba78c2bfd5f646bba5e02e0ae351d6cf4cc6129b8ba4ce26f4
+  metadata.gz: 0e2782073f696f72736004ae21d57a71e4429fb878f915954e36628e16904de9
+  data.tar.gz: 2d041a60e7908ce20ab64f490ccebe3d3c673882986c83a64981aaf1e9931768
 SHA512:
-  metadata.gz: f86aafc1b3e91cbe2eff633fc40325dc048f00d5d668d52f7ea03c130f9171ecea1101a63c871883ac8ec173dfbaaa5932cb37e1de83a49fea5e3c09993463ef
-  data.tar.gz: 197a951604f5dcdf6c64bf7ccfcfe0fd65cd91e2ae8cb6d55c53de3bcd0b0821292856ba2cfdffb56f72a3b3d6e93b76a4e63ea08c8eb16548a03b4166cdcf10
+  metadata.gz: 5d1fef990a79dfa782b0101f33ed64f3631d126ea6ef16dfde8d21d240653d8d938a87689955af288b862362216fbb760db61e79d709c512b242d0f86ad823d1
+  data.tar.gz: 430b9cf7ab45fb7e0ab629b4de95bd262e8b02bd68a58793dcd614832dfd2bb04d63f52d20ddc6639dc951d8ae132188dee755dadab1042f98a0268dcf4bab63

data/README.md

@@ -346,45 +346,133 @@ on the svelte-on-rails config file or pass the `expires_in` as argument to the v
 
 Pass `debug: true` to the helper and you will see on the logs how your configuration works.
 
-# Turbo::StreamsChannel.send!
+## ActionCable / TurboStream
+
+There are two ways that the server can talk to the client over Websocket:
+
+- ActionCable transmits directly to the frontends javascript
+- TurboStreams is a wrapper around ActionCable
+  - You always need a html part for communication
+
+**Configs**
+
+Check the regarding keys and their commends on the [config file](https://gitlab.com/sedl/svelte-on-rails/-/blob/main/templates/config_base/config/svelte_on_rails.yml?ref_type=heads).
+From there, you just need:
+
+```yaml
+turbo_stream:
+  target_html_id: 'svelte-on-rails-stream-actions-box'
+  channel: 'public'
+```
+
+## ActionCable!
+
+ActionCable is the more basic library behind `TurboStream` and it is a second Option to call Javascript Actions from the server.
+
+**Setup**
+
+Add `app/channels/svelte_on_rails_channel.rb`
+
+```ruby
+class SvelteOnRailsChannel < ApplicationCable::Channel
+  def subscribed
+    stream_from "svelte_on_rails_channel"
+  end
+
+  def unsubscribed
+    # Any cleanup needed when channel is unsubscribed
+  end
+end
+```
+
+run
+
+```shell
+npm i @rails/actioncable
+```
+
+Add to `application.js`
+
+```javascript
+import { createConsumer } from "@rails/actioncable"
+import {dispatchSvelteStreamEvent, actionCableDebugLog} from '@csedl/svelte-on-rails'
+
+const consumer = createConsumer()
+
+consumer.subscriptions.create("SvelteOnRailsChannel", {
+    connected() {
+        actionCableDebugLog("Connected to SvelteOnRailsChannel")
+    },
+    disconnected() {
+        actionCableDebugLog("Disconnected from SvelteOnRailsChannel")
+    },
+    received(data) {
+        actionCableDebugLog("Received:", data)
+        dispatchSvelteStreamEvent(data)
+    }
+})
+```
+
+By setting `debug = true` [node package](https://www.npmjs.com/package/@csedl/svelte-on-rails) you see what it is doing.
+
+**WhatdispatchSvelteStreamEvent does**
+
+- Without the attribute `component` given,
+  it searches for all elements with the class `svelte-component` and fires the event `channel-action`
+    - When `selector` is given, it searches for all matching elements within each component.
+    - The event can be overriden by the argument `event`
+
+**Usage**
 
-There are some methods that making it easier to let the server speak to the Components on the front.
+Now you can dispatch events on the component by:
 
-Theese are independent class methods that can be executed from every place on the app.
+```ruby
+ActionCable.server.broadcast("svelte_on_rails_channel",
+                           {
+                             eventDetail: { message: "Sent by ActionCable: äöü🤣🌴🌍漢字" },
+                             component: '/javascript/components/ReceiveFromChannel',
+                           }
+)
+```
+
+# Turbo::StreamsChannel.send!
 
 Few setup is needed for that:
 
 **Setup**
 
-Please setup the `turbo-rails` gem and follow the chapter [Come alive with Turbo Streams](https://github.com/hotwired/turbo-rails?tab=readme-ov-file#come-alive-with-turbo-streams)
+Please setup the `turbo-rails` gem and follow the chapter [Come alive with Turbo Streams](https://github.com/hotwired/turbo-rails?tab=readme-ov-file#come-alive-with-turbo-streams), which mainly is:
+
+```shell
+bundle add turbo-rails
+rails turbo:install
+```
+
+make sure that `import "@hotwired/turbo-rails"` is on your application.js and set the view helper
+`<%= turbo_stream_from 'public' %>` to your view.
 
-If a channel - let's call us it `public` is working and you have a html-tag on the front
-with a ID - let's call us it `svelte-on-rails-stream-actions-box` (This can be any element,
-you could just give the body-tag a ID // it is just the way hotwired works)
-and a code Block like
+If a channel (e.g.: `public`) is active and you have an HTML element with a HTML-ID (e.g.: `svelte-on-rails-stream-actions-box`),
+you can test it by:
 
 ```ruby
      Turbo::StreamsChannel.send(
         "broadcast_append_to",
         'public',
         target: 'svelte-on-rails-stream-actions-box',
-        content: "<div>Hello World</div>"
+        content: "<div>Turbo-Streams are working!</div>"
       )
 ```
 
-is exposing a «Hello World» on the front then you are good to go. 
-Please check the regarding keys and theyr commends on the [config file](https://gitlab.com/sedl/svelte-on-rails/-/blob/main/templates/config_base/config/svelte_on_rails.yml?ref_type=heads).
-
-**Usage Example: Component Event**
+When this works you are good to go.
 
-The easiest way on the svelte component is: 
+**Minimal Usage Example**
 
 ```sveltehtml
 <script>
   import {addComponentStreamListener} from '@csedl/svelte-on-rails/src/componentStreamListener'
 
-  function handleCableEvent(event) {
-      console.log(event.detail.message)
+  function handleCableEvent() {
+      console.log('Event received by Turbo Stream')
   }
 </script>
 <!--on any element:-->
@@ -394,44 +482,45 @@ The easiest way on the svelte component is:
 And call this by:
 
 ```ruby
-    SvelteOnRails::TurboStream.new.dispatch_event(
-        event_detail: { message: "Special Chars from the server: äöü🤣🌴🌍漢字" }
-      )
+    SvelteOnRails::TurboStream.new.dispatch_event
 ```
+**What it does**
 
-**What is this doing?**
-
-- The `addComponentStreamListener` adds a `eventListener` on the Element, that wraps each
-component that is rendered by the view helper `svelte_component`, found by `currentElement.closest('.svelte-component')`
-- A Stimulus controller is pushed to all subscribers of the configured channel. 
-  - You can override this by passing `stream_name` to the method.
-- Without the attribute `component` given, 
-it searches for all elements with the class `svelte-component` and fires the event `channel-action`
-  - When `selector` is given, it searches for all matching elements within each component.
-  - The event can be overriden by the argument `event`
-
-By setting `debug = true` [node package](https://www.npmjs.com/package/@csedl/svelte-on-rails) you see what it is doing.
+- The `addComponentStreamListener` adds the eventListener `stream-action` on the wrapping Element
+    - The «wrapping Element» is the Element from the view helper `svelte_component` with the class `svelte-component`.
+- A Stimulus controller is pushed to all subscribers of the configured channel.
+    - You can override the channel name by passing `channel` to the method.
 
-**Usage Example: Event on components element**
+**Usage Example, more detailed**
 
 If you want to fire a event on a specific element within the component, you do not need `addComponentStreamListener`. 
-Just do something like
+Just do something like:
 
 ```sveltehtml
-<button class="counter-button" onclick="{increaseCounter}">increase {counter}</button>
+<script>
+    function logStreamMessage(event) {
+        console.log(event.detail.message)
+    }
+</script>
+<button class="counter-button" onclick="{logStreamMessage}">Show Contents</button>
 ```
 
-within the svelte component and call it by
+within the svelte component.
+
+Then, call it by:
 
 ```ruby
       SvelteOnRails::TurboStream.new.dispatch_event(
-        event: 'click',
+        channel: 'my-custom-stream',
+        component: '/javascript/components/TurboStreamsChannel',
         selector: '.counter-button',
-        component: '/javascript/components/TurboStreamsChannel'
+        event: 'click',
+        event_detail: { message: "Greetings from Server: äöü🤣🌴🌍漢字" }
       )
 ```
 
 
+
 ## More rake tasks
 
 This tasks are more for testing/playground purposes

data/lib/svelte-on-rails.rb

@@ -1,6 +1,7 @@
 require "svelte_on_rails/configuration"
 require "svelte_on_rails/view_helpers"
 require "svelte_on_rails/turbo_stream"
+require "svelte_on_rails/action_cable"
 require "svelte_on_rails/railtie" if defined?(Rails)
 
 require "svelte_on_rails/renderer/renderer"

data/lib/svelte_on_rails/action_cable.rb

@@ -0,0 +1,42 @@
+module SvelteOnRails
+  class ActionCable
+    def dispatch_event(event: 'stream-action', event_detail: nil, selector: nil, component: nil, channel: "svelte_on_rails_channel")
+
+      if event != 'stream-action' && !selector
+        raise "Another event name than the default one is only possible together with a selector"
+      end
+
+      args = {
+        eventDetail: event_detail,
+        component: component,
+        event: event,
+        selector: selector
+      }
+
+      #args_enc = Base64.strict_encode64(args.to_json)
+
+      ActionCable.server.broadcast(channel, args)
+
+    end
+
+    private
+
+    def configs
+      @configs ||= begin
+
+                     conf = SvelteOnRails::Configuration.instance
+                     unless conf.configs[:turbo_stream]
+                       raise '[svelte-on-rails] missing configuration: :turbo_stream'
+                     end
+                     unless conf.configs[:turbo_stream]['target_html_id']
+                       raise '[svelte-on-rails] missing configuration: turbo_stream/target_html_id'
+                     end
+                     unless conf.configs[:turbo_stream]['channel']
+                       raise '[svelte-on-rails] missing configuration: turbo_stream/channel'
+                     end
+
+                     conf.configs[:turbo_stream]
+                   end
+    end
+  end
+end

data/lib/svelte_on_rails/turbo_stream.rb

@@ -1,6 +1,10 @@
 module SvelteOnRails
   class TurboStream
-    def dispatch_event(event: 'stream-action', event_detail: nil, selector: nil, component: nil, stream_name: nil)
+    def dispatch_event(event: 'stream-action', event_detail: nil, selector: nil, component: nil, channel: nil)
+
+      if event != 'stream-action' && !selector
+        raise "Another event name than the default one is only possible together with a selector"
+      end
 
       args = {
         eventDetail: event_detail,
@@ -13,7 +17,7 @@ module SvelteOnRails
 
       Turbo::StreamsChannel.send(
         "broadcast_append_to",
-        stream_name || configs['stream_name'],
+        channel || configs['channel'],
         target: configs['target_html_id'],
         content: "<div style=\"display: none;\" data-controller=\"svelte-on-rails-turbo-stream\" data-args=\"#{args_enc}\"></div>"
       )
@@ -32,8 +36,8 @@ module SvelteOnRails
                      unless conf.configs[:turbo_stream]['target_html_id']
                        raise '[svelte-on-rails] missing configuration: turbo_stream/target_html_id'
                      end
-                     unless conf.configs[:turbo_stream]['stream_name']
-                       raise '[svelte-on-rails] missing configuration: turbo_stream/stream_name'
+                     unless conf.configs[:turbo_stream]['channel']
+                       raise '[svelte-on-rails] missing configuration: turbo_stream/channel'
                      end
 
                      conf.configs[:turbo_stream]

data/templates/config_base/config/svelte_on_rails.yml

@@ -25,7 +25,7 @@ turbo_stream:
   # this part you need when you want to be able to trigger javascript actions on svelte-components from the backend
   target_html_id: 'svelte-on-rails-stream-actions-box'
   # html-id of any element that must exist for being able to receive actions (turbo streams can only work this way)
-  stream_name: 'public'
+  channel: 'public'
 
 development:
   watch_changes: true

data/templates/rails_vite_hello_world/app/channels/svelte_on_rails_channel.rb

@@ -0,0 +1,9 @@
+class SvelteOnRailsChannel < ApplicationCable::Channel
+  def subscribed
+    stream_from "svelte_on_rails_channel"
+  end
+
+  def unsubscribed
+    # Any cleanup needed when channel is unsubscribed
+  end
+end

data/templates/rails_vite_hello_world/app/controllers/svelte_on_rails_hello_world_controller.rb

@@ -9,17 +9,27 @@ class SvelteOnRailsHelloWorldController < ApplicationController
       SvelteOnRails::TurboStream.new.dispatch_event(
         event: 'click',
         selector: '.counter-button',
-        component: '/javascript/components/TurboStreamsChannel'
+        component: '/javascript/components/ReceiveFromChannel'
       )
       render plain: 'increase-action streamed'
+    elsif params['action_cable']
+
+      ActionCable.server.broadcast("svelte_on_rails_channel",
+                                   {
+                                     eventDetail: { message: "Sent by ActionCable: äöü🤣🌴🌍漢字" },
+                                     component: '/javascript/components/ReceiveFromChannel',
+                                   }
+      )
+      #SvelteOnRails::ActionCable.new.dispatch_event(channel: "svelte_on_rails_channel", event_detail: { message: "Hello from SvelteChannel!" })
+
+      render plain: 'ActionCable streaming'
     else
       SvelteOnRails::TurboStream.new.dispatch_event(
-        event_detail: { message: "Special Chars from the server: äöü🤣🌴🌍漢字", user: "Müller" }
+        event_detail: { message: "Sent by TurboStream: äöü🤣🌴🌍漢字", user: "Müller" }
       )
       render plain: 'component-action streamed'
     end
 
-    head :ok
   end
 
 end

data/templates/rails_vite_hello_world/app/frontend/javascript/components/{TurboStreamsChannel.svelte → ReceiveFromChannel.svelte}

@@ -7,7 +7,6 @@
     let results = $state([])
     let incrBtn
 
-
     onMount(() => {
         incrBtn.addEventListener('click', increaseCounter)
     });
@@ -31,7 +30,7 @@
     const handleCableEvent = (ev) => {
         results.push(
             {
-                text: `Message received from TurboStream: ${JSON.stringify(ev.detail.message)}`,
+                text: `Message received from Server: ${JSON.stringify(ev.detail.message)}`,
                 class: 'stream-action-received'
             }
         )
@@ -49,6 +48,8 @@
 
 <button class="call-channel-action" onclick="{callChannelAction}">Action</button>
 
+<button onclick="{() => callChannelAction('action_cable=true')}">Call ActionCable Action</button>
+
 <ul class="results">
     {#each results as result}
         <li class="{result.class}">{result.text}</li>

data/templates/rails_vite_hello_world/app/views/svelte_on_rails_hello_world/turbo_streams_channel.html.erb

@@ -6,7 +6,7 @@
 <%= render 'nav' %>
 
 
-<%= svelte_component "TurboStreamsChannel" %>
+<%= svelte_component "ReceiveFromChannel" %>
 
 <%= content_tag :div, id: 'svelte-on-rails-stream-actions-box' do %>
 <% end %>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: svelte-on-rails
 version: !ruby/object:Gem::Version
-  version: 5.0.0
+  version: 5.1.0
 platform: ruby
 authors:
 - Christian Sedlmair
@@ -31,6 +31,7 @@ files:
 - README.md
 - lib/generators/svelte_on_rails/install/install_generator.rb
 - lib/svelte-on-rails.rb
+- lib/svelte_on_rails/action_cable.rb
 - lib/svelte_on_rails/configuration.rb
 - lib/svelte_on_rails/installer/gem_utils.rb
 - lib/svelte_on_rails/installer/haml.rb
@@ -53,6 +54,7 @@ files:
 - templates/config_base/app/frontend/ssr/ssr.js
 - templates/config_base/config/svelte_on_rails.yml
 - templates/config_base/vite-ssr.config.ts
+- templates/rails_vite_hello_world/app/channels/svelte_on_rails_channel.rb
 - templates/rails_vite_hello_world/app/controllers/svelte_on_rails_hello_world_controller.rb
 - templates/rails_vite_hello_world/app/frontend/images/svelte-on-rails-hello-world-england.png
 - templates/rails_vite_hello_world/app/frontend/images/svelte-on-rails-hello-world-face-smile-wink.svg
@@ -61,9 +63,9 @@ files:
 - templates/rails_vite_hello_world/app/frontend/javascript/components/JpgImport.svelte
 - templates/rails_vite_hello_world/app/frontend/javascript/components/ParentWithChild.svelte
 - templates/rails_vite_hello_world/app/frontend/javascript/components/PngImport.svelte
+- templates/rails_vite_hello_world/app/frontend/javascript/components/ReceiveFromChannel.svelte
 - templates/rails_vite_hello_world/app/frontend/javascript/components/SvelteOnRailsHelloWorld.svelte
 - templates/rails_vite_hello_world/app/frontend/javascript/components/SvgRawImport.svelte
-- templates/rails_vite_hello_world/app/frontend/javascript/components/TurboStreamsChannel.svelte
 - templates/rails_vite_hello_world/app/frontend/javascript/components/sub/NestedComponent.svelte
 - templates/rails_vite_hello_world/app/frontend/javascript/nestedJavascript.js
 - templates/rails_vite_hello_world/app/frontend/javascript/nestedJavascriptToggled.js