turbo-fetch（涡轮提取）

Turbo Fetch Skill

This skill documents the turbo fetch pattern for dynamically updating form fields based on user input using Turbo Streams and Stimulus.

When to Use

Use turbo fetch when you need to:

• Update form options based on another field's selection
• Show/hide conditional fields dynamically
• Refresh parts of a form without reloading the entire page
• Implement cascading dropdowns or dependent fields

Pattern Overview

The turbo fetch pattern consists of four components:

1. Routes - A routing concern that adds the turbo_fetch endpoint
2. Controller Action - A backend action that prepares data and renders turbo streams
3. Stimulus Controller - Frontend controller that triggers PATCH requests
4. Turbo Stream View - Template that updates specific DOM elements

Implementation Steps

1. Add Routing Concern (if not already present)

In config/routes.rb, ensure the turbo_fetch concern exists:

concern :turbo_fetch do
  patch :turbo_fetch, on: :collection
end

Then apply it to your resource:

resources :materials, concerns: %i[turbo_fetch]

This creates a route: PATCH /materials/turbo_fetch

2. Implement Controller Action

Add a turbo_fetch action to your controller:

class MaterialsController < ApplicationController
  def turbo_fetch
    @material = authorize Material.new(material_params)
    # The view will handle the turbo stream responses
  end

  private

  def material_params
    params.require(:material).permit(:type, :substance, ...)
  end
end

Key points:

• Creates a new instance with submitted params (doesn't save to database)
• Runs authorization if needed
• The instance will be used in the turbo stream view to determine updated options

3. Create Turbo Stream View

Create app/views/[resource]/turbo_fetch.turbo_stream.slim:

= simple_form_for @material do |f|
  = turbo_stream.update 'substance-field' do
    = f.input :substance, collection: @material.substances
  = turbo_stream.replace 'material_details', partial: dimension_fields_partial_path, locals: { f: }

Available turbo stream actions:

• turbo_stream.update - Replace the content inside an element
• turbo_stream.replace - Replace the entire element
• turbo_stream.append - Add content at the end
• turbo_stream.prepend - Add content at the beginning
• turbo_stream.remove - Remove an element

4. Setup Form with Stimulus Controller

Add the Stimulus controller to your form:

= simple_form_for resource, data: { controller: 'turbo-fetch', turbo_fetch_url_value: turbo_fetch_materials_url } do |f|
  .form-row
    = f.input :type, input_html: { data: { action: "turbo-fetch#perform" } }

  #substance-field.flexible
    = f.input :substance, collection: f.object.substances

  #material_details
    = render dimension_fields_partial_path, f: f

Key attributes:

• data-controller="turbo-fetch" - Activates the Stimulus controller
• data-turbo-fetch-url-value - The URL to PATCH (defaults to form action + /turbo_fetch)
• data-action="turbo-fetch#perform" - Triggers the fetch on field change

5. Verify Stimulus Controller Exists

The turbo_fetch_controller.js should exist at app/javascript/controllers/turbo_fetch_controller.js:

import { Controller } from '@hotwired/stimulus'
import { patch } from '@rails/request.js'

export default class extends Controller {
  static values = { url: String, count: Number }

  async perform({ params: { url: urlParam, query: queryParams } }) {
    const body = new FormData(this.element)

    if (queryParams) Object.keys(queryParams).forEach(key => body.append(key, queryParams[key]))

    const response = await patch(urlParam || this.urlValue, { body, responseKind: 'turbo-stream' })
    if (response.ok) this.countValue += 1
  }
}

Examples from Codebase

Materials Example

Route:

resources :materials, concerns: %i[duplication turbo_fetch]

Controller:

def turbo_fetch
  @material = authorize Material.new(material_params)
end

View (turbo_fetch.turbo_stream.slim):

= simple_form_for @material do |f|
  = turbo_stream.update 'substance-field' do
    = f.input :substance, collection: @material.substances, as: :tom_select, allow_create: true
  = turbo_stream.replace 'material_details', partial: dimension_fields_partial_path, locals: { f: }

Form:

= simple_form_for resource, data: { controller: 'turbo-fetch', turbo_fetch_url_value: turbo_fetch_materials_url } do |f|
  = f.input :type, input_html: { data: { action: "turbo-fetch#perform" } }

  #substance-field.flexible
    = f.input :substance, collection: f.object.substances

  #material_details
    = render dimension_fields_partial_path, f: f

Common Patterns

Pattern 1: Dependent Dropdown

When selecting a type, update available options in another field:

• Trigger field has data-action="turbo-fetch#perform"
• Target field has unique ID (e.g., #substance-field)
• Turbo stream updates the target with new collection

Pattern 2: Conditional Field Sections

Show/hide entire form sections based on selection:

• Use turbo_stream.replace to swap out entire sections
• Render different partials based on the selected value

Pattern 3: Member vs Collection Routes

Most turbo_fetch routes are on :collection, but for nested resources with IDs:

resources :custom_parts, concerns: %i[turbo_fetch] do
  patch :turbo_fetch, on: :member # For child items with IDs
end

Tips

1. Target IDs: Ensure target elements have unique, stable IDs
2. Form Context: The turbo stream view wraps form builder in simple_form_for to maintain form context
3. Authorization: Apply same authorization as create/update actions
4. Don't Save: The turbo_fetch action creates instances but never saves them
5. Multiple Updates: You can include multiple turbo_stream updates in one response

Troubleshooting

Updates not appearing:

• Check that target element ID matches the turbo_stream selector
• Verify the Stimulus action is firing (check browser console)
• Ensure turbo_fetch route exists (run rails routes | grep turbo_fetch)

Wrong data in fields:

• Verify params are being permitted in material_params (or equivalent)
• Check that the model's computed properties return correct values

Authorization errors:

• Ensure turbo_fetch action runs same authorization as new/create