Basic Command

Let's create a basic Command that inrements and decrements a number. It's simple and contrived but will demonstrate some high level concepts.

Be sure to open the browser's network tab and watch HTTP activity as you increment and decrement the number.

With Turbo Frame

This demo was built in about 50 lines of code spread over 8 files... including the model, view, controller, and commands. 🤯

Pretty impressive when you consider it's a full-stack solution that persists "state" changes to the backend database and executes within 50-100ms (including repaint). and most of the latency is actually network I/O.

Look at all the things we aren't doing!

No JavaScript (including Stimulus)
No additional routes
No additional controllers
No additional actions

files

├── app
│   ├── commands
│   │   ├── decrement_count_command.rb
│   │   ├── increment_count_command.rb
│   │   └── reset_count_command.rb
│   │
│   ├── controllers
│   │   └── basic_commands_controller.rb
│   │
│   ├── models
│   │   └── user.rb
│   │
│   ├── views
│   │   └── basic_commands
│   │       ├── _demo.html.erb
│   │       ├── show.html.erb
│   │       └── show.turbo_stream.erb

Commands send the Accept: text/vnd.turbo-boost.html, text/html, application/xhtml+xml HTTP request header.

If a Command is triggered inside a Turbo Frame or with a Turbo Method, the request will also include the turbo_stream format in the URL.

Rails determines request format by looking at both the URL and the request headers and then locates the view template based on the format. This means that Commands look for view templates in the following order.

Request format specified in the URL - i.e. /resource.turbo_stream
HTTP accept header in linear order, left to right - i.e. Accept: text/vnd.turbo-boost.html, text/html, application/xhtml+xml

For example, this specific demo will look for view templates in the following order.

*.turbo_stream.erb
*.turbo_boost.erb
*.html.erb

This demo uses the *.turbo_stream.erb template because it's updating multiple places in the DOM; however, simply re-rendering the *.html.erb template is often sufficient for many use cases.

You can also hijack normal response mechanics from within the Command by calling prevent_controller_action

View Templates

app/views/basic_commands/show.html.erb

<!-- content... -->

<%= turbo_frame_tag "basic_command-turbo-frame", src: basic_command_path(format: :turbo_stream) %>

<!-- content... -->

View on GitHub app/views/basic_commands/show.turbo_stream.erb

<%= turbo_stream.update "basic_command-turbo-frame" do %>
  <%= render "basic_commands/demo" %>
<% end %>

<!-- also update the no-frame demo to keep the counts in sync -->
<%= turbo_stream.update "basic_command-no-frame" do %>
  <%= render "basic_commands/demo" %>
<% end %>

View on GitHub app/views/basic_commands/_demo.html.erb

<h3>Counter</h3>

<p>
  In this demo, the counter value or "state" is managed by the User model.
  It is persisted to the database and used when rendering the page.
</p>

<code role="counter"><%= padded_number Current.user.count %></code>

<% cache do %>
  <div>
    <button data-turbo-command="IncrementCountCommand">
      <%= render "icons/heroicons/plus", solid: true %> Increment
    </button>

    <button data-turbo-command="DecrementCountCommand">
      <%= render "icons/heroicons/minus", solid: true %> Decrement
    </button>

    <button data-turbo-command="ResetCountCommand" data-turbo-confirm="Are you sure?">
      <%= render "icons/heroicons/arrow_path", solid: true %> Reset
    </button>
  </div>
<% end %>

View on GitHub

TurboBoost Commands

app/commands/increment_count_command.rb

# frozen_string_literal: true

class IncrementCountCommand < TurboBoost::Commands::Command
  def perform
    Current.user.increment! :count
  end
end

View on GitHub app/commands/decrement_count_command.rb

# frozen_string_literal: true

class DecrementCountCommand < TurboBoost::Commands::Command
  def perform
    Current.user.decrement! :count
  end
end

View on GitHub app/commands/reset_count_command.rb

# frozen_string_literal: true

class ResetCountCommand < TurboBoost::Commands::Command
  def perform
    Current.user.update count: 0
  end
end

View on GitHub

Controller

app/controllers/basic_commands_controller.rb

# frozen_string_literal: true

class BasicCommandsController < ApplicationController
  # GET /basic_command
  def show
  end
end

View on GitHub

Model

app/models/user.rb

# frozen_string_literal: true

class User < ApplicationRecord
  # extends ..................................................................................................

  # includes .................................................................................................

  # constants ................................................................................................

  # class methods ............................................................................................
  class << self
  end

  # relationships ............................................................................................

  # validations ..............................................................................................
  validates :session_id, presence: true
  validates :count, numericality: true

  # callbacks (caution: side effects) ........................................................................

  # scopes (composable queries) ..............................................................................

  # additional config (accepts_nested_attribute_for, etc.) ...................................................

  # public instance methods ..................................................................................

  # protected instance methods ...............................................................................

  # private instance methods .................................................................................
end

View on GitHub

Without Turbo Frame

Counter

In this demo, the counter value or "state" is managed by the User model. It is persisted to the database and used when rendering the page.

0000

This demo was built in about 50 lines of code spread over 8 files... including the model, view, controller, and commands. 🤯

Pretty impressive when you consider it's a full-stack solution that persists "state" changes to the backend database and executes within 30-75ms (including repaint). and most of the latency is actually network I/O.

Look at all the things we aren't doing!

No JavaScript (including Stimulus)
No Turbo Frames
No additional routes
No additional controllers
No additional actions

files

├── app
│   ├── commands
│   │   ├── decrement_count_command.rb
│   │   ├── increment_count_command.rb
│   │   └── reset_count_command.rb
│   │
│   ├── controllers
│   │   └── basic_commands_controller.rb
│   │
│   ├── models
│   │   └── user.rb
│   │
│   ├── views
│   │   └── basic_commands
│   │       ├── _demo.html.erb
│   │       ├── show.html.erb
│   │       └── show.turbo_boost.erb

Commands send the Accept: text/vnd.turbo-boost.html, text/html, application/xhtml+xml HTTP request header.

If a Command is triggered inside a Turbo Frame or with a Turbo Method, the request will also include the turbo_stream format in the URL.

Request format specified in the URL - i.e. /resource.turbo_stream
HTTP accept header in linear order, left to right - i.e. Accept: text/vnd.turbo-boost.html, text/html, application/xhtml+xml

For example, this specific demo will look for view templates in the following order.

*.turbo_boost.erb
*.html.erb

This demo uses the *.turbo_boost.erb template because it's updating multiple places in the DOM; however, simply re-rendering the *.html.erb template is often sufficient for many use cases.

You can also hijack normal response mechanics from within the Command by calling prevent_controller_action

View Templates

app/views/basic_commands/show.html.erb

<!-- content... -->

<div id="basic_command-no-frame">
  <%= render "basic_commands/demo" %>
</div>

<!-- content... -->

View on GitHub app/views/basic_commands/show.turbo_boost.erb

<%= turbo_stream.update "basic_command-no-frame" do %>
  <%= render "basic_commands/demo" %>
<% end %>

<!-- also update the turbo-frame demo to keep the counts in sync -->
<%= turbo_stream.update "basic_command-turbo-frame" do %>
  <%= render "basic_commands/demo" %>
<% end %>

View on GitHub app/views/basic_commands/_demo.html.erb

<h3>Counter</h3>

<p>
  In this demo, the counter value or "state" is managed by the User model.
  It is persisted to the database and used when rendering the page.
</p>

<code role="counter"><%= padded_number Current.user.count %></code>

<% cache do %>
  <div>
    <button data-turbo-command="IncrementCountCommand">
      <%= render "icons/heroicons/plus", solid: true %> Increment
    </button>

    <button data-turbo-command="DecrementCountCommand">
      <%= render "icons/heroicons/minus", solid: true %> Decrement
    </button>

    <button data-turbo-command="ResetCountCommand" data-turbo-confirm="Are you sure?">
      <%= render "icons/heroicons/arrow_path", solid: true %> Reset
    </button>
  </div>
<% end %>

View on GitHub

TurboBoost Commands

app/commands/increment_count_command.rb

# frozen_string_literal: true

class IncrementCountCommand < TurboBoost::Commands::Command
  def perform
    Current.user.increment! :count
  end
end

View on GitHub app/commands/decrement_count_command.rb

# frozen_string_literal: true

class DecrementCountCommand < TurboBoost::Commands::Command
  def perform
    Current.user.decrement! :count
  end
end

View on GitHub app/commands/reset_count_command.rb

# frozen_string_literal: true

class ResetCountCommand < TurboBoost::Commands::Command
  def perform
    Current.user.update count: 0
  end
end

View on GitHub

Controller

app/controllers/basic_commands_controller.rb

# frozen_string_literal: true

class BasicCommandsController < ApplicationController
  # GET /basic_command
  def show
  end
end

View on GitHub

Model

app/models/user.rb

# frozen_string_literal: true

class User < ApplicationRecord
  # extends ..................................................................................................

  # includes .................................................................................................

  # constants ................................................................................................

  # class methods ............................................................................................
  class << self
  end

  # relationships ............................................................................................

  # validations ..............................................................................................
  validates :session_id, presence: true
  validates :count, numericality: true

  # callbacks (caution: side effects) ........................................................................

  # scopes (composable queries) ..............................................................................

  # additional config (accepts_nested_attribute_for, etc.) ...................................................

  # public instance methods ..................................................................................

  # protected instance methods ...............................................................................

  # private instance methods .................................................................................
end

View on GitHub

Was this helpful?

I hope TurboBoost helps you get better at Hotwire while teaching you some cool new tricks... because this stuff is fun and addictive. Check out the test/dummy app on GitHub to see how this site was made, and please consider supporting my efforts.

Sponsor TurboBoost

Basic Command

With Turbo Frame

Highlights

How it's Built

View Templates

TurboBoost Commands

Controller

Model

How it Works

Without Turbo Frame

Counter

Highlights

How it's Built

View Templates

TurboBoost Commands

Controller

Model

How it Works

Was this helpful?