Views and Responses
Relevant source files
The following files were used as context for generating this wiki page:
Loco provides a robust system for generating HTTP responses, allowing developers to return various content types such as JSON, HTML, YAML, and plain text. The framework leverages Axum for performance and extensibility, offering a format module that simplifies response creation through a fluent API and pre-defined utility functions.
The system is designed to be "content-aware," enabling controllers to match on incoming request formats and respond with the appropriate content type, such as server-rendered templates using the Tera engine or strongly typed JSON backed by serde.
Sources: src/controller/format.rs:1-15, docs-site/config.toml:116-135, docs-site/content/casts/001-dynamic-responses-and-content-types.md:1-15
The Response System Architecture
The response system is built around the format module, which wraps Axum's response builders to provide a more ergonomic interface for Loco applications. It supports both immediate helper functions for common tasks and a RenderBuilder for complex responses involving custom headers, status codes, and cookies.
The diagram shows how controller actions interface with either simple utility functions or the RenderBuilder to generate an Axum-compatible response.
Sources: src/controller/format.rs:43-160
Key Response Utilities
Loco provides several high-level functions in the format module to generate standard responses quickly.
| Function | Output Content-Type | Description |
|---|---|---|
json<T>(data) | application/json | Serializes a struct into a JSON response. |
html(content) | text/html | Returns an HTML string. |
text(t) | text/plain | Returns raw text. |
yaml(content) | application/yaml | Returns a YAML formatted response. |
redirect(to) | N/A | Returns a 303 See Other redirect. |
empty() | N/A | Returns an empty response with 200 OK. |
Sources: src/controller/format.rs:43-138
RenderBuilder Fluent API
For responses requiring specific configurations like status codes, cookies, or ETags, the render() function initializes a RenderBuilder. This builder follows the builder pattern, allowing chained calls to configure the response before finalization.
Builder Methods
status(code): Sets the HTTP status code (e.g.,StatusCode::CREATED).header(key, value): Adds a custom HTTP header.etag(value): Specifically adds anETAGheader.cookies(cookies): Attaches a slice ofaxum_extra::extract::cookie::Cookieto the response.
Sources: src/controller/format.rs:179-237
The sequence illustrates the lifecycle of a complex response being built fluently.
Sources: src/controller/format.rs:163-300
Template Views and Engines
Loco supports server-side rendering through a view engine abstraction. The primary engine used is Tera, a powerful template engine for Rust.
View Rendering Logic
Rendering can be performed using templates stored in the file system or directly from strings. The ViewRenderer trait defines the interface for different engines to implement rendering logic.
format::view(renderer, key, data): Renders a template file located by itskey(path) using the provided data.format::template(string, data): Renders a template directly from a raw string.
Sources: src/controller/format.rs:146-160, src/controller/views/engine.rs:8-15
The class diagram shows the relationship between the view rendering trait and the Tera implementation used by the format module.
Sources: src/controller/views/mod.rs:1-10, src/tera.rs:10-30
Tera Integration
The TeraView implementation handles the loading of templates from the file system (typically a templates/ directory) and provides built-in functions for template logic. It supports features like template inheritance, filters, and global functions.
Sources: src/tera.rs:1-50, docs-site/config.toml:127-130
Conclusion
The Views and Responses system in Loco provides a unified and type-safe way to handle outgoing data. By combining simple utility functions for common formats like JSON and HTML with a powerful RenderBuilder for custom headers and the Tera engine for server-side templates, Loco ensures that developers can handle diverse client requirements with minimal boilerplate while maintaining the performance benefits of the Axum ecosystem.
Sources: src/controller/format.rs:1-20, docs-site/config.toml:116-125