HTML, written in Crystal.

A view is a Crystal class whose methods write HTML, and everything it writes is escaped unless you mark it as trusted.

Learning it for the first time? The recipe Create a resource generates a show view and a form view you can read. This page lists every element, attribute and rule.

Limits at a glance

A view is a class

Views live under app/views/. Each one is a Blueprint class that subclasses App::ApplicationView. That base is a Caramel::View with the application’s path helpers.

module App::Views::Books
  class Show < App::ApplicationView
    def initialize(@book : App::Book, @csrf_token : String)
    end

    private def blueprint
      h1 { @book.title }
      p { "by #{@book.author}" }
    end
  end
end

An action renders it as the page: page "Book", Views::Books::Show.new(book, csrf_token).

Element blocks write escaped text

Each HTML element is a method. For example, h1 { "<Dune>" } writes <h1>&lt;Dune&gt;</h1>.

p do
  plain "by "
  strong { @book.author || "Unknown" }
end

Attribute values are escaped

Attributes are keyword arguments.

div "hx-swap:inherited": "innerMorph" do
  input type: "checkbox", name: "done", checked: true, disabled: false
end

Only Safe values are written raw

Mount a third-party component →

Only HTML your application built itself belongs in Safe. Never wrap user input, stored text or a third-party response.

markup builds small escaped fragments

markup { … } builds a fragment in an action or a view without a view class.

morph "#count", with: markup { span { count.to_s } }

Forms carry the CSRF token

A form that posts carries the CSRF token in a hidden _csrf field, and a form for PATCH or DELETE names its method in _method. htmx requests need no hidden field: the layout’s hx-headers sends the token as X-CSRF-Token.

form action: book_path(@book.id), method: "post" do
  input type: "hidden", name: "_csrf", value: @csrf_token
  input type: "hidden", name: "_method", value: "DELETE"
  button(type: "submit") { "Delete" }
end

frappe make resource generates a complete form to start from. Its labelled helper writes a label, the control and the field’s errors. Its error summary is an alert listing each message.

private def labelled(name : String, text : String, &) : Nil
  id = "book_#{name}"
  label(for: id) { text }
  yield id
  div id: "#{id}_errors" do
    (@errors[name]? || [] of String).each { |error| p(class: "field-error") { error } }
  end
end

The layout wraps every page

The layout receives the rendered Caramel::Page and the CSRF token.

body "hx-boost:inherited": "true", "hx-target:inherited": "#content", "hx-swap:inherited": "innerMorph",
  "hx-headers:inherited": {"X-CSRF-Token" => @csrf_token}.to_json do
  main(id: "content") { raw @page.html }
end

frappe corretto spec/requests/books_spec.cr