ticket

Controllers

A controller is a module of actions. Each action takes a Conn and returns a Response, names its own view, and lists its effects in its signature.

Actions

Every action has the same shape: action(conn: Conn) -> Response / {…}. The router calls it, and the type checker makes sure it fits.

module ArticlesController

uses
  Std.{Http, Map, Option}
  Layout
  Models.Article
  Paths
  Ticket.{Conn, Error, Params, Response}
  Views.Articles

functions
  index(conn: Conn) -> Response / {Mut} {
    Response.render(Layout.app("Articles", Articles.index(Article.all())))
  }

  show(conn: Conn) -> Response / {Mut, Throws<Halt>} {
    let article = find_or_halt(conn)

    Response.render(Layout.app(article.title, Articles.show(article)))
  }

  new(conn: Conn) -> Response {
    Response.render(Layout.app("New article", Articles.form("")))
  }

  create(conn: Conn) -> Response / {Mut} {
    let title = Option.with_default(Map.get(Params.nested(conn, "article"), "title"), "")

    if title == "" {
      Response.render_status(
        422,
        Layout.app("New article", Articles.form("Title can't be blank")),
      )
    } else {
      let article = Article.create(title)

      Response.redirect_to(conn, Paths.article_path(article.id))
    }
  }

exports
  create
  index
  new
  show

There's no implicit template lookup. The action calls its view and layout like any other function.

Building responses

Ticket.Response builds Std.Http.Response values. Actions return them, so they stay plain values you can test.

Function What it does
render(page) 200 with a full HTML document
render_status(status, page) The same with another status, like 422
redirect_to(conn, path) 302 after GET or HEAD, 303 after anything else, so a browser follows a form post with a GET
head(status) A status with no body
text(status, body), html(status, body) Plain text or an HTML string
view(status, page) An Html value as is, without the document wrapper
json(status, value) Any value with a Json impl
not_found() A plain-text 404
with_header(r, name, value) Replaces a header, ignoring case, or adds it
content_type(r, kind) Sets the content-type header

Linking with Paths

Use the generated Paths module for URLs, in controllers and views alike. It has every helper the routes zone generates.

JSON and uploads

An application/json object body is flattened into the same form map, so {"post":{"title":"x"}} reaches Params.record(conn, "post") like a form does. Malformed JSON is a 400 with a JSON error body. A JSON request skips the CSRF form token only when it carries an x-ticket-request header, which a cross-site form can't set.

Conn.format(conn) is HtmlFormat or JsonFormat, from a .json path extension (which wins) or the Accept header, and the extension is dropped before routing. Response.respond_to(conn, html, json) runs the matching branch and answers 406 when the Accept header allows neither.

A multipart/form-data upload is saved to a temp file by the launcher. Params.file(conn, "doc") gives Some({ name, content_type, size, path }), and text fields still reach Params. The temp file isn't kept, so the app copies it. [server] max_body (default "1MB") and max_upload (default "10MB") answer 413 before the body is read in full.

When an action fails

throw Halt(response) from anywhere under an action answers with that response. See Filters and Halting. Any other error that escapes is logged and answered with a 500. The body is internal server error, followed by the stack when options.env = "development".