From 0ab06117e2c0fd847b62ee480c3f7db6f9eaa5b5 Mon Sep 17 00:00:00 2001
From: Michaelyin <michaelyin@accordbox.com>
Date: Mon, 15 Jan 2024 16:44:23 +0800
Subject: [PATCH] add multi-format doc

---
 docs/source/index.rst       |  1 +
 docs/source/multi-format.md | 61 +++++++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+)
 create mode 100644 docs/source/multi-format.md

diff --git a/docs/source/index.rst b/docs/source/index.rst
index bbe3725..78de131 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -21,5 +21,6 @@ Topics
    turbo_frame.md
    turbo_stream.md
    real-time-updates.md
+   multi-format.md
    redirect.md
    test.md
diff --git a/docs/source/multi-format.md b/docs/source/multi-format.md
new file mode 100644
index 0000000..1b08798
--- /dev/null
+++ b/docs/source/multi-format.md
@@ -0,0 +1,61 @@
+# Multi-format Response
+
+In Ruby on Rails, `respond_to` is a method that allows you to define how your controller should respond to different types of requests.
+
+```ruby
+class PostsController < ApplicationController
+  def create
+    @post = Post.new(post_params)
+
+    respond_to do |format|
+      if @post.save
+        format.turbo_stream { render turbo_stream: turbo_stream.append(@post) }
+        format.json { render json: @post, status: :created }
+        format.html { redirect_to @post, notice: 'Post was successfully created.' }
+      else
+        format.turbo_stream { render turbo_stream: turbo_stream.replace('new_post', partial: 'posts/form', locals: { post: @post }) }
+        format.json { render json: @post.errors, status: :unprocessable_entity }
+        format.html { render :new }
+      end
+    end
+  end
+end
+```
+
+In the above code, developer can return different response format based on request `Accept` header.
+
+We can do similar approach with `turbo_helper`
+
+```python
+from turbo_helper import (
+  ResponseFormat,
+  response_format,
+)
+
+class TaskCreateView(LoginRequiredMixin, CreateView):
+  def form_valid(self, form):
+    response = super().form_valid(form)
+    request = self.request
+    messages.success(request, "Created successfully")
+
+    with response_format(request) as resp_format:
+      if resp_format == ResponseFormat.TurboStream:
+        return TurboStreamResponse(
+          render_to_string(
+            "demo_tasks/partial/task_create_success.turbo_stream.html",
+            context={
+              "form": TaskForm(),
+            },
+            request=self.request,
+          ),
+        )
+      else:
+        return response
+```
+
+Notes:
+
+1. If you are using Python 3.11+,
+2. If the client `Accept` turbo stream, we return turbo stream response.
+3. If not, we return normal HTML response as fallback solution.
+4. This is useful when we want to migrate our Django app from normal web page to turbo stream gradually.