marten_turbo

This README is the one indexed from the repository at its latest ref, not from the tag for this version.

Marten Turbo adds Turbo Frames, Turbo Streams and Turbo-aware handlers to Marten applications.

It gives you three template tags (dom_id, turbo_frame, turbo_stream), a Crystal API to build Turbo Stream responses, and versions of Marten's generic record handlers that answer with a Turbo Stream when the browser asks for one.

This is the server side only. Turbo itself still needs to be installed and loaded in your frontend, for example through marten-importmap.

Compatibility

Marten Turbo	Marten	Crystal
0.4.x	0.6.x, 0.7.x	>= 1.19
0.3.x	0.6.x	>= 1.19

Installation

Add the shard to your shard.yml:

dependencies:
  marten_turbo:
    github: treagod/marten-turbo

Run shards install, then require it in src/project.cr:

require "marten_turbo"

The template tags are registered when the app is set up, so MartenTurbo::App has to be part of your installed_apps:

Marten.configure do |config|
  config.installed_apps = [
    MartenTurbo::App,
    # Other applications...
  ]
end

Skip that step and every template using dom_id, turbo_frame or turbo_stream fails with an unknown tag error.

Example

A handler that creates an article and answers Turbo requests with a stream:

class ArticleCreateHandler < MartenTurbo::Handlers::RecordCreate
  model Article
  schema ArticleSchema
  template_name "articles/create.html"
  turbo_stream_name "articles/create.turbo_stream.html"
  success_route_name "articles"
end

articles/create.turbo_stream.html gets the new record as record:

<turbo-stream action="append" target="articles">
  <div id="{% dom_id record %}">{{ record.title }}</div>
</turbo-stream>

Regular form submits still get the redirect to articles. Only requests that accept text/vnd.turbo-stream.html get the stream.

Documentation

The full documentation lives at treagod.github.io/marten-turbo, or under docs/ in this repository.

Contributing

Bug reports and pull requests are welcome on GitHub. Run crystal spec and crystal tool format before opening a PR.

License

MIT. See LICENSE.