TurboRouter is a simple Rails plugin that smooths over some of the complexity and inconsistencies of using turbo-frames. For example, it can be a bit frustrating to understand or predict how turbo enabled links will behave, especially when you are just learning how to use them. This is because they can have several different attributes that can change their behavior, and their location in the context of the DOM can also change what they do.
To make things just a little easier, TurboRouter provides a handfull of straightforward view helpers that wrap the standard Rails
link_to helper and set the proper attributes on the links they generate so they will have a consistant and predictable behavior, regardless of where they are in the DOM and without the need to set different attributes. They also make it more straightforward to know when the browser's history will be advanced, and when it will not be.
Another aspect of turbo_frames that TurboRouter remedies is the fact that you need to wrap the HTML templates rendered back from your controllers with a turbo_frame matching the part of the DOM you wish to replace. Doing this may limit the reusability and flexibility of your templates, and it is extra boiler plate code that can easily be abstracted away. TurboRouter does this by rendering your templates with a layout with a dynamic id set to match the targeted turbo_frame of the request, so the partials always render with the proper turbo_frame wrapper. This behavior is, of course, opt-in for each controller action, so that you are not forced to use the dynamic template when you do not what to, but it is there when you need it.
TurboRouter establishes a baseline for turbo enabled links by wrapping the
<%= yield %> in your
application.html.erb with a turbo_frame (using a partial) with
id="turbo_router_content". By default, links generated by TurboRouter view helpers that don't target the entire page, will target this turbo_frame. Of course, you can set the
data-turbo-frame attribute on these links just as you would with
link_to to target a different turbo_frame instead.
TurboRouter also provides a method to your controllers for rendering a turbo_stream that targets the default turbo_frame, but can accept a different
id as well
In short, TurboRouter turns the following table:
The above tables may not look that different, and they are not. This plugin simply provides a slightly different API that is more imperative and requires setting fewer attributes yourself and less boiler plate code in your templates. It certainly isn't necessary, but it might be nice to have for those that find it useful.
Add this line to your application's Gemfile:
And then execute:
rails generate turbo_router
The above command will create the following files in your app:
The above command will also wrap the
yield call in
application.html.erb with the
layouts/turbo_router_content partial layout like so:
<%= render "layouts/turbo_router_content" do %><%= yield %><% end %>
The above layout ultimately wraps its contents with a turbo frame with
id="turbo_router_content" which will serve as the target for all TurboRouter navigations that do not target the full page.
Simply add this line to your
class ApplicationController < ActionController::Base include TurboRouter::Controller
For any actions you wish to render using the dynamic turbo_frame template, simply call
use_dynamic_layout and pass those actions to it like so:
use_dynamic_layout :index, :show
When an action is passed to
use_dynamic_layout and when requests are turbo_frame requests (
true), the layout rendered will wrap the template in a turbo_frame with the id matching
request.headers["Turbo-frame"]. This is always the same value that is set on the
data-turbo-frame attribute on the link that initiated the request (or the containing turbo_frame's id if not set). TurboRouter view helpers ensure that this value is always set to either
turbo_router_content if it isn't already set.
By default, if a request does not use the dynamic layout, the application layout will be used.
Because TurboRouter sets the controller's layout to use its dynamic layout for turbo_frame requests, it is incompatible with setting a different static/ global layout for a controller for other types of requests (turbo-rails also has this problem, but offers no solution). TurboRouter, however, allows you to set a layout for all requests that are not turbo_frame requests without interfering with the dynamic layout behavior using the
page_layout method, like so:
class ChaptersController < ApplicationController page_layout :other_layout
Of course, you are still able to set a layout more granularly with individual calls to render by passing a layout parameter, in which case the provided layout will override any layout that was determined by other means.
TurboRouter provides an additional method for controllers,
turbo_router_stream, which simply reduces the amount of boilerplat code you have to write to render a turbo_stream. It takes a template as it's first argument, and an optional id for the target element which defaults to
turbo_router_content if not provided, and any other options to be passed to as locals to the render call. Use it like so:
respond_to do |format| format.turbo_stream do turbo_router_stream "posts/show", "post_container", post: @post end end
The view helper TurboRouter provides are:
turbo_router_link_to both target the entire page, but the former performs a full page load without using TurboDrive, while the latter utilizes TurboDrive (under the hood it uses
data-turbo-frame="_top"). Both of these links will advance the browser's history.
turbo_router_route_to both target a turbo_frame (either the default turbo_frame with
id="turbo_router_content" or a different one specified with
data-turbo-frame), but the former does not advance the browser's history while the latter does.
All of the view helpers have take the same signature as
link_to so you may still pass any other attributes such as
class or other
data attributes as well (certain data attributes will be overridend to achieve the required behavior). This means they can directly replace any
link_to calls you have in your views and they will continue to work as expected in all other ways, but with the more imperatively determined behavior described above.
This plugin is currently in it's alpha stage and contributors are welcome!
Things that need to be done:
- Add helpers for button_to perhaps.
The gem is available as open source under the terms of the MIT License.