update doc

docs/source/install.md

@@ -3,7 +3,7 @@
 ```{note}
 This package does not include any Javascript library, you may wish to add these yourself using your preferred Javascript build tool, or use a CDN.
 
-Please check <a href="https://turbo.hotwired.dev/handbook/installing" target="_blank">Hotwire Doc</a>
+Please check <a href="https://turbo.hotwired.dev/handbook/installing" target="_blank">Hotwire Doc</a> for more details
 ```
 
 ## Requirements
@@ -13,7 +13,7 @@ This library requires Python 3.8+ and Django 3.2+.
 ## Getting Started
 
 ```shell
-pip install django-turbo-helper
+$ pip install django-turbo-helper
 ```
 
 Next update **INSTALLED_APPS**:
@@ -27,21 +27,37 @@ INSTALLED_APPS = [
 
 ## Middleware
 
-You can optionally install `turbo_helper.middleware.TurboMiddleware`. This adds the attribute `turbo` to your `request`.
+Add `turbo_helper.middleware.TurboMiddleware` to the `MIDDLEWARE` in Django settings file.
 
 ```python
 MIDDLEWARE = [
     ...
-    "turbo_helper.middleware.TurboMiddleware",
-    "django.middleware.common.CommonMiddleware",
+    "turbo_helper.middleware.TurboMiddleware",   # new
     ...
 ]
 ```
 
+With the `TurboMiddleware` we have `request.turbo` object which we can access in Django view or template.
+
 If the request originates from a turbo-frame, we can get the value from the `request.turbo.frame`
 
 ```django
-{% turbo_frame request.turbo.frame %}
-  {% include 'template.html' %}
-{% endturbo_frame %}
+{% load turbo_helper %}
+
+{% if request.turbo.frame %}
+
+  {% turbo_frame request.turbo.frame %}
+    {% include 'template.html' %}
+  {% endturbo_frame %}
+
+{% endif %}
+```
+
+Or we can use `request.turbo.accept_turbo_stream` to check if the request accepts turbo stream response.
+
+```python
+if request.turbo.accept_turbo_stream:
+  # return turbo stream response
+else:
+  # return normal HTTP response
 ```

docs/source/multi-format.md

@@ -55,12 +55,10 @@ class TaskCreateView(LoginRequiredMixin, CreateView):
 
 Notes:
 
-1. If the browser accepts HTML, we return HTML response.
-2. If the browser accepts turbo stream, we return turbo stream response.
-3. This is useful when we want to migrate our Django app from normal web page to turbo stream gradually.
+1. If the browser accepts turbo stream, we return turbo stream response.
+2. If the browser accepts HTML, we return HTML response.
+3. This is useful when we want to **migrate our Django app from normal web page to turbo stream gradually**.
 
 ```{note}
-Most browsers send Accept: `*/*` by default, so this would return True for all content types.
-
-To avoid problem, it is recommned to put resp_format.html logic at the top since the order matters.
+Please **put the non html response before html response**, and use html response as the fallback response.
 ```

docs/source/real-time-updates.md

@@ -1,4 +1,4 @@
-# Update Page in Real Time via Websocket
+# Real Time Updates via Websocket
 
 Use Websocket and Turbo Stream to update the web page in real time, without writing Javascript.
 
@@ -16,7 +16,7 @@ To import `turbo-cable-stream-source` element to the frontend, there are two way
 
 Or you can [Jump start frontend project bundled by Webpack](https://github.com/AccordBox/python-webpack-boilerplate#jump-start-frontend-project-bundled-by-webpack) and install it via `npm install`
 
-After frontend work is done, to support Actioncable on the server, please install [django-actioncable](https://github.com/AccordBox/django-actioncable).
+After frontend is setup, to support Actioncable protocol on the server side, please install [django-actioncable](https://github.com/AccordBox/django-actioncable).
 
 In `routing.py`, register `TurboStreamCableChannel`
 
@@ -27,7 +27,7 @@ from turbo_helper.channels.streams_channel import TurboStreamCableChannel
 cable_channel_register(TurboStreamCableChannel)
 ```
 
-In Django template, we can subscribe to stream source like this:
+In Django template, we can subscribe to stream source like this, it has nearly the same syntax as Rails `turbo_stream_from`:
 
 ```html
 {% load turbo_helper %}
@@ -57,3 +57,43 @@ broadcast_render_to(
 2. `keyword arguments` `template` and `context` are used to render the template.
 
 The web page can be updated in real time, through Turbo Stream over Websocket.
+
+## Broadcasts
+
+### broadcast_action_to
+
+Under `turbo_helper.channels.broadcasts`, there are some other helper functions to broadcast Turbo Stream to the stream source, just like Rails:
+
+```python
+def broadcast_action_to(*streamables, action, target=None, targets=None, **kwargs):
+```
+
+The `broadcast_action_to` function is inspired by Rails and is designed to facilitate broadcasting actions to multiple streamable objects. It accepts a variable number of streamables as arguments, which represent the objects that will receive the broadcasted actions.
+
+The function requires an `action` parameter, which specifies the type of action to be performed.
+
+Example:
+
+```python
+broadcast_action_to(
+    "chat",
+    instance.chat_id,
+    action="append",
+    template="message_content.html",
+    context={
+        "instance": instance,
+    },
+    target=dom_id(instance.chat_id, "message_list"),
+)
+```
+
+### broadcast_refresh_to
+
+This is for Rails 8 refresh action, and it would broadcast something like this via the websocket to trigger the page refresh:
+
+```html
+<turbo-stream
+  request-id="ca519ab9-1138-4625-abc2-6049317321a9"
+  action="refresh">
+</turbo-stream>
+```

docs/source/turbo_stream.md

@@ -20,7 +20,12 @@ turbo_stream.append(
 )
 ```
 
-Turbo Stream built-in actions are supported in syntax `turbo_stream.xxx`:
+Notes:
+
+1. `request`, `context` are optional
+2. If `content` is not set, then `template` is required to render the `content`.
+
+Turbo Stream built-in actions are all supported in syntax `turbo_stream.xxx`:
 
 - append
 - prepend