diff options
Diffstat (limited to 'guides/source/action_cable_overview.md')
-rw-r--r-- | guides/source/action_cable_overview.md | 34 |
1 files changed, 18 insertions, 16 deletions
diff --git a/guides/source/action_cable_overview.md b/guides/source/action_cable_overview.md index 16cfaf94e2..a4d9647057 100644 --- a/guides/source/action_cable_overview.md +++ b/guides/source/action_cable_overview.md @@ -39,7 +39,7 @@ client-server connection instance established per WebSocket connection. Connections form the foundation of the client-server relationship. For every WebSocket the cable server is accepting, a Connection object will be instantiated on the server side. -This instance becomes the parent of all the channel subscriptions that are created from there on. +This instance becomes the parent of all the channel subscriptions that are created from there on. The Connection itself does not deal with any specific application logic beyond authentication and authorization. The client of a WebSocket connection is called a consumer. An individual user will create one consumer-connection pair per browser tab, window, or device they have open. @@ -73,12 +73,12 @@ end ``` Here `identified_by` is a connection identifier that can be used to find the -specific connection later. Note that anything marked as an identifier will automatically +specific connection later. Note that anything marked as an identifier will automatically create a delegate by the same name on any channel instances created off the connection. This example relies on the fact that you will already have handled authentication of the user -somewhere else in your application, and that a successful authentication sets a signed -cookie with the `user_id`. +somewhere else in your application, and that a successful authentication sets a signed +cookie with the `user_id`. The cookie is then automatically sent to the connection instance when a new connection is attempted, and you use that to set the `current_user`. By identifying the connection @@ -89,8 +89,8 @@ or deauthorized). ### Channels A channel encapsulates a logical unit of work, similar to what a controller does in a -regular MVC setup. By default, Rails creates a parent `ApplicationCable::Channel` class -for encapsulating shared logic between your channels. +regular MVC setup. By default, Rails creates a parent `ApplicationCable::Channel` class +for encapsulating shared logic between your channels. #### Parent Channel Setup @@ -106,11 +106,11 @@ Then you would create your own channel classes. For example, you could have a **ChatChannel** and an **AppearanceChannel**: ```ruby -# app/channels/application_cable/chat_channel.rb +# app/channels/chat_channel.rb class ChatChannel < ApplicationCable::Channel end -# app/channels/application_cable/appearance_channel.rb +# app/channels/appearance_channel.rb class AppearanceChannel < ApplicationCable::Channel end ``` @@ -125,7 +125,7 @@ Incoming messages are then routed to these channel subscriptions based on an identifier sent by the cable consumer. ```ruby -# app/channels/application_cable/chat_channel.rb +# app/channels/chat_channel.rb class ChatChannel < ApplicationCable::Channel # Called when the consumer has successfully become a subscriber of this channel def subscribed @@ -150,7 +150,7 @@ established using the following Javascript, which is generated by default in Rai App.cable = ActionCable.createConsumer() ``` -This will ready a consumer that'll connect against /cable on your server by default. +This will ready a consumer that'll connect against /cable on your server by default. The connection won't be established until you've also specified at least one subscription you're interested in having. @@ -182,7 +182,7 @@ Streams provide the mechanism by which channels route published content (broadcasts) to its subscribers. ```ruby -# app/channels/application_cable/chat_channel.rb +# app/channels/chat_channel.rb class ChatChannel < ApplicationCable::Channel def subscribed stream_from "chat_#{params[:room]}" @@ -215,6 +215,7 @@ If a consumer is not streaming (subscribed to a given channel), they'll not get the broadcast should they connect later. Broadcasts are called elsewhere in your Rails application: + ```ruby WebNotificationsChannel.broadcast_to current_user, title: 'New things!', body: 'All the news fit to print' ``` @@ -417,7 +418,7 @@ App.cable.subscriptions.create "AppearanceChannel", 2. **Client** initiates a subscription to the `Appearance Channel` for their connection via `App.cable.subscriptions.create "AppearanceChannel"`. [*`appearance.coffee`*] 3. **Server** recognizes a new subscription has been initiated for `AppearanceChannel` channel performs the `subscribed` callback, which calls the `appear` method on the `current_user`. [*`appearance_channel.rb`*] 4. **Client** recognizes that a subscription has been established and calls `connected` [*`appearance.coffee`*] which in turn calls `@install` and `@appear`. `@appear` calls`AppearanceChannel#appear(data)` on the server, and supplies a data hash of `appearing_on: $("main").data("appearing-on")`. This is possible because the server-side channel instance will automatically expose the public methods declared on the class (minus the callbacks), so that these can be reached as remote procedure calls via a subscription's `perform` method. -5. **Server** receives the request for the `appear` action on the `AppearanceChannel` channel for the connection identified by `current_user`. [*`appearance_channel.rb`*] The server retrieves the data with the `appearing_on` key from the data hash, and sets it as the the value for the `on:` key being passed to `current_user.appear`. +5. **Server** receives the request for the `appear` action on the `AppearanceChannel` channel for the connection identified by `current_user`. [*`appearance_channel.rb`*] The server retrieves the data with the `appearing_on` key from the data hash and sets it as the value for the `on:` key being passed to `current_user.appear`. ### Example 2: Receiving new web notifications @@ -549,12 +550,13 @@ You can change that in `config/database.yml` through the `pool` attribute. ### In App Action Cable can run alongside your Rails application. For example, to -listen for WebSocket requests on `/websocket`, mount the server at that path: +listen for WebSocket requests on `/websocket`, specify that path to +`config.action_cable.mount_path`: ```ruby -# config/routes.rb -Example::Application.routes.draw do - mount ActionCable.server => '/cable' +# config/application.rb +class Application < Rails::Application + config.action_cable.mount_path = '/websocket' end ``` |