Answer every client.

How an action turns a valid contract into a page, a fragment, a redirect, a stream or JSON in Caramel 0.15.0.

Learning it for the first time? The recipe Read and write JSON shows one action answering a browser and a JSON client. This page lists every response and limit.

Limits at a glance

An action answers one request

An action is a struct that answers one request. It subclasses your application’s App::ApplicationAction, which subclasses Caramel::Action. contract do … end declares the request’s typed fields. handle(contract : Contract) runs only when the contract is valid.

module App::Books
  struct Show < App::ApplicationAction
    contract do
      field id : Int64, min: 1
    end

    def handle(contract : Contract)
      record = App::Book.query.find(contract.id)
      return not_found("Book not found") unless record
      {record: record}
    end

    def render(result)
      page "Book", Views::Books::Show.new(result[:record], csrf_token)
    end
  end
end

def handle(contract : Contract)
  changes = App::Book.create(title: contract.title)
  return render_errors(changes.errors) unless changes.saved?
  self.status = 201
  {record: changes.record}
end

def render(result)
  redirect_to(book_path(result[:record].id))
end

A JSON client gets 201 and the record. A browser gets a 303 to the new book.

Declare routes and contracts →

Accept and HX-Request choose the client

Caramel weighs only application/json and text/html in Accept.

Read and write JSON →

Pages render inside the layout

page(title, body, status) takes a String, a view, or markup { … }.

def handle(contract : Contract)
  page "Shelf", markup { h1 { "Shelf" } }
end

Caramel::Action has a minimal default layout with an escaped title. The generated base action replaces it with your layout view and suffixes every title.

module App
  abstract struct ApplicationAction < Caramel::Action
    include App::Paths

    def layout(page : Caramel::Page) : String
      Views::Layouts::Application.new(page, csrf_token).to_s
    end

    def title_for(page : Caramel::Page) : String
      "#{page.title} · #{App::TITLE}"
    end
  end
end

morph and partials update regions

morph(target, with: html, swap: "innerMorph") replaces one target’s content. partials sends several Caramel::Partial records in one response. Each becomes an <hx-partial> element that htmx 4 swaps into its own target.

def handle(contract : Contract)
  count = 3
  morph "#count", with: markup { span { count.to_s } }
end

def handle(contract : Contract)
  members = ["Ann", contract.name]
  partials([
    Caramel::Partial.new("#roster", markup { ul { members.each { |m| li { m } } } }.to_s),
    Caramel::Partial.new("#roster-count", members.size.to_s, "innerHTML"),
  ])
end

Write the HTML →

Redirects check their target

def handle(contract : Contract)
  redirect_external("https://example.com/docs", 301)
end

A stream writes its body from a block

stream(content_type, status) writes the body from its block.

Caramel::SSE.write(io, data, event) writes one server-sent event and flushes it.

def handle(contract : Contract)
  stream "text/event-stream" do |io|
    3.times { |tick| Caramel::SSE.write(io, event: "Tick", data: tick.to_s) }
  end
end

Publish updates with Cold Brew →

Invalid input answers 422

An invalid contract never reaches handle.

ERR CONTRACT_INVALID:422 at POST /items
FIELD seats: must be at least 1
FIELD _base: Unknown field: extra

What each client gets for a refusal is in the SweetTalk guide: Call the domain from actions →. A generated resource with a form re-renders it with the submitted values and every error:

def contract_failure_page(contract : Caramel::RequestContract) : Caramel::Response
  render_form(contract.values, contract.errors, contract.values["id"]?.try(&.to_i64?), 422)
end

JSON answers may carry a version

json(value, status = 200) answers a value as JSON. self.etag = version in handle adds the version to the answer, and if_match?(version) reads the request’s If-Match header against it.

A versioned update that answers 409 and 412 is application code; the SugarORM reference shows one.

The session is a signed cookie

def handle(contract : Contract)
  session["user_id"] = contract.user_id
  redirect_to("/")
end

Security defaults lists the cookie, its signature, its lifetime, the limit and the csrf: false case.

Review the security defaults →Receive a signed webhook →

frappe check
frappe corretto spec/requests/books_spec.cr