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".