RustF View & Template Engine Layer
Overview
RustF provides a powerful view system with Total.js as the built-in template engine. The framework is optimized for Total.js templates, providing a familiar syntax for Total.js developers and direct integration with framework features.
Template Engine
Total.js (Built-in)
- No feature flag required - Always available
- Syntax: Uses
@{...}for expressions - Compatible with Total.js v4 - Familiar syntax for Total.js developers
- Optimized for RustF - Direct integration with framework features
- Powerful features - Conditionals, loops, layouts, sections, helpers
- Auto-escaping - HTML is escaped by default for security
Configuration
Configure your template engine in config.toml:
[views]
directory = "views" # Template directory
default_layout = "layouts/default" # Default layout template
cache_enabled = false # Template caching (dev: false, prod: true)
extension = "html" # File extension for templates
# engine is always "totaljs" - no other options available
storage = "filesystem" # Choose: "filesystem" or "embedded"
default_root = "" # Base URL path for deployment (e.g., "/app")
Basic Usage
In Controllers
#![allow(unused)]
fn main() {
use rustf::prelude::*;
pub fn install() -> Vec<Route> {
routes![
GET "/" => index,
GET "/about" => about,
GET "/standalone" => standalone,
]
}
async fn index(ctx: &mut Context) -> rustf::Result<()> {
// Page-level data (title, lists, flags) goes in the repository -> @{R.key}
ctx.repository_set("title", "Welcome");
ctx.repository_set("message", "Hello from RustF!");
ctx.repository_set("features", json!(["Fast", "Safe", "Productive"]));
// The model is ONE object (the page's subject); this page has none
ctx.view("home/index", json!({}))
}
async fn about(ctx: &mut Context) -> rustf::Result<()> {
// Render with custom layout
ctx.repository_set("title", "About Us");
ctx.layout("layouts/special");
ctx.view("about", json!({}))
}
async fn standalone(ctx: &mut Context) -> rustf::Result<()> {
// Render without layout
ctx.repository_set("content", "This page has no layout");
ctx.layout(""); // Empty string = no layout
ctx.view("standalone", json!({}))
}
}
Context Methods
#![allow(unused)]
fn main() {
// Basic template rendering
ctx.view("template_name", data)
// Set custom layout
ctx.layout("layouts/special")
.view("template", data)
// Render without layout
ctx.layout("") // Empty string = no layout
.view("template", data)
// Use default layout from config (no need to call layout())
ctx.view("template", data) // Uses config.views.default_layout
// Render HTML string directly
ctx.html("<h1>Direct HTML</h1>")
// JSON response
ctx.json(data)
// Text response
ctx.plain("Plain text response")
}
Total.js Template Syntax
Variables
<!-- Model/View data access -->
<h1>@{model.title}</h1>
<h1>@{M.title}</h1> <!-- Alias for model -->
<!-- Nested properties -->
<p>@{model.user.name}</p>
<p>@{M.user.name}</p> <!-- Alias -->
<!-- With default value -->
<!-- Default values using || operator -->
<p>@{model.description || 'No description'}</p>
<p>@{user.avatar || '/images/default-avatar.png'}</p>
<span>@{settings.theme || 'light'}</span>
Using || for Fallback Values:
The || (OR) operator provides default values when the left operand is falsy (null, undefined, empty string, 0, false, empty array/object):
<!-- String defaults -->
<p>Bio: @{user.bio || "No bio available"}</p>
<!-- Numeric defaults -->
<p>Items per page: @{settings.pageSize || 20}</p>
<!-- Chaining multiple fallbacks -->
<h1>@{custom_title || page.title || "Untitled Page"}</h1>
Conditionals
Basic If/Else
@{if model.logged_in}
<p>Welcome, @{model.username}!</p>
@{else}
<p>Please log in</p>
@{fi}
<!-- Inline conditional -->
<div class="@{if M.active}active@{else}inactive@{fi}">
Comparison Operators
<!-- Equality -->
@{if user.role == "admin"}
<p>Admin Dashboard</p>
@{fi}
@{if status != "deleted"}
<p>Active Item</p>
@{fi}
<!-- Strict equality (type-sensitive) -->
@{if count === 0}
<p>Exactly zero</p>
@{fi}
<!-- Numeric comparison -->
@{if age >= 18}
<p>Adult content</p>
@{fi}
@{if stock > 0}
<button>Add to Cart</button>
@{else}
<span>Out of Stock</span>
@{fi}
@{if price <= budget}
<span class="affordable">Within Budget</span>
@{fi}
Supported Comparison Operators:
==- Loose equality (type coercion)!=- Loose inequality===- Strict equality (no type coercion)!==- Strict inequality<- Less than>- Greater than<=- Less than or equal>=- Greater than or equal
Logical Operators
AND (&&) - Both conditions must be true:
@{if user.is_admin && user.is_active}
<a href="/admin">Admin Panel</a>
@{fi}
@{if age >= 18 && has_id}
<p>Access granted</p>
@{fi}
OR (||) - At least one condition must be true:
@{if user.is_admin || user.is_moderator}
<div class="staff-tools">Staff Area</div>
@{fi}
@{if is_weekend || is_holiday}
<span>π Special Hours</span>
@{fi}
Complex Conditions - Combine with parentheses:
@{if (age >= 18 && verified) || is_staff}
<p>Access granted</p>
@{fi}
@{if (is_member && points > 100) || is_vip}
<span class="badge">Premium</span>
@{fi}
Negation with !
<!-- NOT operator -->
@{if !user.is_banned}
<p>Welcome back!</p>
@{fi}
@{if !is_empty}
<ul>@{foreach item in items}...@{end}</ul>
@{fi}
<!-- Negating expressions -->
@{if !(status == "deleted" || status == "archived")}
<button>Edit</button>
@{fi}
Else-If Chains with @{elif}
@{if score > 90}
<span class="grade-a">A - Excellent!</span>
@{elif score > 80}
<span class="grade-b">B - Good Job</span>
@{elif score > 70}
<span class="grade-c">C - Fair</span>
@{elif score > 60}
<span class="grade-d">D - Needs Improvement</span>
@{else}
<span class="grade-f">F - Failed</span>
@{fi}
Multiple elif branches:
@{if role == "owner"}
<p>Full Access</p>
@{elif role == "admin"}
<p>Administrative Access</p>
@{elif role == "moderator"}
<p>Moderation Access</p>
@{elif role == "member"}
<p>Member Access</p>
@{else}
<p>Guest Access</p>
@{fi}
Truthy/Falsy Values
Values are evaluated as truthy or falsy in conditionals:
Falsy values:
falsenull0""(empty string)[](empty array){}(empty object)
Truthy values:
true- Any non-zero number
- Any non-empty string
- Any non-empty array
- Any non-empty object
<!-- Check if value exists and is truthy -->
@{if user.email}
<p>Email: @{user.email}</p>
@{fi}
<!-- Check if array has items -->
@{if products}
<p>@{products.length} products available</p>
@{fi}
Loops
<!-- Array iteration -->
@{foreach item in model.items}
<li>@{item.name} - @{item.price}</li>
@{end}
<!-- With index (using M alias) -->
@{foreach item, index in M.items}
<li>@{index}: @{item}</li>
@{end}
Escaping
<!-- Auto-escaped (safe by default) -->
<p>@{M.user_input}</p>
<!-- Raw HTML (unescaped) -->
<div>@{!M.html_content}</div>
Raw output @{!...} accepts a full expression, not just a bare variable β
e.g. @{!M.url || '/default.jpg'} renders the value-fallback unescaped.
Expressions & Operators
The Total.js template engine supports rich expressions with multiple operator types, allowing for complex logic directly in templates.
Operator Reference
| Category | Operators | Description | Example |
|---|---|---|---|
| Comparison | ==, != | Loose equality/inequality (with type coercion) | @{if age == "18"} |
===, !== | Strict equality/inequality (no type coercion) | @{if count === 0} | |
<, > | Less than, greater than | @{if price > 100} | |
<=, >= | Less/greater than or equal | @{if stock <= 5} | |
| Logical | && | AND - both must be true | @{if a && b} |
|| | OR - at least one must be true | @{if a || b} | |
| Unary | ! | NOT - negates boolean | @{if !is_deleted} |
- | Negation - negates number | @{-value} | |
| Arithmetic | + | Addition / String concatenation | @{price + tax} |
- | Subtraction | @{total - discount} | |
* | Multiplication | @{price * quantity} | |
/ | Division | @{total / count} | |
% | Modulo (remainder) | @{index % 2} |
Operator Precedence
Operators are evaluated in the following order (highest to lowest precedence):
- Parentheses
( )- Grouping (evaluated first) - Unary
!,-- NOT, negation - Multiplication/Division
*,/,%- Arithmetic - Addition/Subtraction
+,-- Arithmetic - Comparison
<,>,<=,>=- Relational - Equality
==,!=,===,!==- Equality checks - Logical AND
&&- Boolean AND - Logical OR
||- Boolean OR (evaluated last)
Examples:
<!-- Precedence without parentheses -->
@{if x + 5 > 10 && y < 20}
<!-- Evaluates as: ((x + 5) > 10) && (y < 20) -->
@{fi}
<!-- Using parentheses to control precedence -->
@{if (a || b) && c}
<!-- OR is evaluated before AND due to parentheses -->
@{fi}
Arithmetic Operations
<!-- Basic arithmetic -->
<p>Subtotal: $@{price * quantity}</p>
<p>Tax: $@{subtotal * 0.08}</p>
<p>Total: $@{subtotal + (subtotal * 0.08)}</p>
<!-- Complex calculations -->
<p>Price per unit: $@{total_price / item_count}</p>
<p>Discount: @{(original_price - sale_price) / original_price * 100}%</p>
<!-- Modulo for alternating styles -->
@{foreach item, index in items}
<tr class="@{if index % 2 == 0}even@{else}odd@{fi}">
<td>@{item.name}</td>
</tr>
@{end}
String Concatenation
<!-- Concatenate strings with + -->
<p>@{first_name + " " + last_name}</p>
<p>@{"Hello, " + user.name + "!"}</p>
<!-- Build URLs -->
<a href="@{"/products/" + product.id}">View Product</a>
<!-- Combine with variables -->
<p>@{greeting + " " + M.username}</p>
Default Values with ||
The || operator provides fallback values when the left side is falsy:
<!-- Simple default -->
<p>@{user.bio || "No bio provided"}</p>
<!-- Nested properties with default -->
<p>@{user.profile.avatar || "/images/default-avatar.png"}</p>
<!-- Numeric defaults -->
<p>Items per page: @{settings.page_size || 20}</p>
<!-- Chain multiple defaults -->
<p>@{custom_title || default_title || "Untitled"}</p>
Complex Expressions
<!-- Nested conditionals in expressions -->
<p class="@{if score >= 90}excellent@{elif score >= 70}good@{else}poor@{fi}">
Score: @{score}
</p>
<!-- Mathematical expressions in conditionals -->
@{if (price * quantity) > budget}
<span class="warning">Over budget!</span>
@{fi}
<!-- Combining multiple operators -->
@{if ((total - discount) * tax_rate) < 100 && is_member}
<span>Free shipping!</span>
@{fi}
<!-- Expression in attribute values -->
<div data-score="@{points * 10}"
class="level-@{if points > 100}high@{else}low@{fi}">
</div>
Grouping with Parentheses
Use parentheses to control evaluation order and clarify complex expressions:
<!-- Without parentheses (may be unclear) -->
@{if a && b || c && d} <!-- Evaluates as: (a && b) || (c && d) -->
<!-- With parentheses (explicit) -->
@{if (a && b) || (c && d)} <!-- Same result, but clearer intent -->
<!-- Change evaluation order -->
@{if a && (b || c) && d} <!-- OR evaluated before outer ANDs -->
<!-- Arithmetic grouping -->
<p>@{(price + shipping) * (1 + tax_rate)}</p>
Practical Examples
Important: The Total.js engine does not support template-level variable assignment (
@{var x = ...}and reassignment do not work) and there is noMath.*object. Inline arithmetic and boolean expressions are supported (e.g.@{price * quantity},@{a && b}), but any value that needs to be computed once and reused β a subtotal, a page count, an access-control flag β should be calculated in the handler and passed in via the repository.
Shopping Cart Total:
Compute the per-item and subtotal values in the handler, then pass them in. Inline arithmetic is fine for purely derived display values:
#![allow(unused)]
fn main() {
// In the handler
async fn cart(ctx: &mut Context) -> rustf::Result<()> {
// ... build `items` (each with a pre-computed `total`) and `subtotal` ...
ctx.repository_set("items", json!(items));
ctx.repository_set("subtotal", json!(subtotal));
ctx.repository_set("tax_rate", json!(0.2));
ctx.repository_set("grand_total", json!(subtotal * 1.2));
ctx.view("cart/index", json!({}))
}
}
@{foreach item in items}
<tr>
<td>@{item.name}</td>
<td>@{item.quantity} Γ $@{item.price}</td>
<td>$@{item.total}</td>
</tr>
@{end}
<tr class="total">
<td colspan="2">Subtotal:</td>
<td>$@{subtotal}</td>
</tr>
<tr>
<td colspan="2">Tax (@{tax_rate * 100}%):</td>
<td>$@{subtotal * tax_rate}</td>
</tr>
<tr class="grand-total">
<td colspan="2">Total:</td>
<td>$@{grand_total}</td>
</tr>
Pagination Logic:
Compute total_pages, has_prev, and has_next in the handler (no Math.ceil
in templates), then read them in the view:
#![allow(unused)]
fn main() {
let total_pages = (total_items + items_per_page - 1) / items_per_page; // ceil
ctx.repository_set("current_page", json!(current_page));
ctx.repository_set("total_pages", json!(total_pages));
ctx.repository_set("has_prev", json!(current_page > 1));
ctx.repository_set("has_next", json!(current_page < total_pages));
}
<div class="pagination">
@{if has_prev}
<a href="?page=@{current_page - 1}">Previous</a>
@{fi}
<span>Page @{current_page} of @{total_pages}</span>
@{if has_next}
<a href="?page=@{current_page + 1}">Next</a>
@{fi}
</div>
Access Control:
Resolve permission flags in the handler and pass them through the repository:
#![allow(unused)]
fn main() {
let can_edit = user.id == post.author_id || user.is_admin;
ctx.repository_set("can_edit", json!(can_edit));
ctx.repository_set("can_delete", json!(user.is_admin || (user.is_moderator && post.flagged)));
ctx.repository_set("can_publish", json!((user.role == "editor" || user.role == "admin") && !post.published));
}
@{if can_edit}
<button onclick="editPost()">Edit</button>
@{fi}
@{if can_delete}
<button onclick="deletePost()" class="danger">Delete</button>
@{fi}
@{if can_publish}
<button onclick="publishPost()" class="primary">Publish</button>
@{fi}
Data Access in Templates
Global Constants
These are directly accessible without any prefix:
@{url} <!-- Current request URL -->
@{hostname} <!-- Server hostname -->
@{root} <!-- Application root path (from config.default_root) -->
@{index} <!-- Current loop index (inside foreach) -->
@{csrf_token} <!-- CSRF token for forms -->
Data Source Objects
These objects can be accessed entirely or via dot notation for properties:
<!-- Configuration (entire object or properties) -->
@{CONF} <!-- Entire config object -->
@{CONF.app_name} <!-- Specific config value -->
@{CONF.default_root} <!-- Deployment root path -->
<!-- Session (entire object or properties) -->
@{session} <!-- Entire session object -->
@{session.user_id} <!-- Specific session value -->
@{session.cart} <!-- Session cart data -->
<!-- Flash Messages (stored in session, aliased for convenience) -->
@{flash} <!-- All flash messages -->
@{flash.error} <!-- Error flash message -->
@{flash.success} <!-- Success flash message -->
@{flash.info} <!-- Info flash message -->
@{flash.custom_key} <!-- Custom flash message -->
<!-- Query parameters (entire object or properties) -->
@{query} <!-- All query parameters -->
@{query.page} <!-- Specific query parameter -->
@{query.search} <!-- Search query parameter -->
<!-- User (entire object or properties) -->
@{user} <!-- Entire user object -->
@{user.name} <!-- User's name -->
@{user.email} <!-- User's email -->
<!-- Context Repository (per-handler) -->
@{repository} <!-- Entire repository object -->
@{repository.key} <!-- Specific repository value -->
@{R.key} <!-- Shorthand for repository.key -->
<!-- Global Repository (application-wide) -->
@{APP.key} <!-- Global repository value -->
@{MAIN.key} <!-- Alias for APP.key -->
<!-- Model/View Data (from ctx.view()) -->
@{model} <!-- Entire model object -->
@{model.key} <!-- Specific model value -->
@{M} <!-- Alias for entire model -->
@{M.key} <!-- Alias for model.key -->
Loop Variables
Within @{foreach} loops, the iterator variable is directly accessible:
@{foreach product in model.products}
<!-- 'product' is directly accessible here -->
<h3>@{product.name}</h3>
<p>Price: @{product.price}</p>
<p>Index: @{index}</p> <!-- Loop index is available -->
@{end}
<!-- foreach binds a SINGLE loop variable. Two-variable key/value object
iteration (e.g. `foreach key, value in obj`) is NOT supported. -->
@{foreach tag in post.tags}
<span class="tag">@{tag}</span>
@{end}
Built-in Functions
<!-- Asset / URL helpers -->
@{url('/path')} <!-- Resolve a URL -->
@{css('/static/app.css')} <!-- CSS link tag -->
@{js('/static/app.js')} <!-- Script tag. Never pass request data: any https:// URL loads and runs -->
@{image('/logo.png')} <!-- Image tag -->
<!-- Data formatting -->
@{json(data)} <!-- JSON, HTML-escaped: safe in text and attributes -->
@{!json(data)} <!-- JSON for a <script> block (still escapes < > &) -->
<!-- String case (HTML is auto-escaped; use @{!expr} to bypass) -->
@{upper(text)} <!-- Uppercase (alias: toUpperCase) -->
@{lower(text)} <!-- Lowercase (alias: toLowerCase) -->
<!-- Iteration helpers -->
@{range(10)} <!-- Generate array [0,1,2,3,4,5,6,7,8,9] -->
@{range(1, 11)} <!-- Generate array [1,2,3,4,5,6,7,8,9,10] -->
@{range(0, 10, 2)} <!-- Generate array [0,2,4,6,8] with step -->
Range Function Examples
The range() function generates numeric sequences for loops:
<!-- Simple range: 0 to N-1 -->
@{foreach num in range(5)}
<p>Item @{num}</p> <!-- Outputs: 0, 1, 2, 3, 4 -->
@{end}
<!-- Range with start and stop -->
@{foreach page in range(1, 6)}
<a href="/page/@{page}">Page @{page}</a> <!-- Pages 1-5 -->
@{end}
<!-- Range with custom step -->
@{foreach year in range(2020, 2030, 2)}
<option value="@{year}">@{year}</option> <!-- 2020, 2022, 2024, 2026, 2028 -->
@{end}
<!-- Practical example: pagination -->
@{foreach page in range(1, model.totalPages + 1)}
@{if page == model.currentPage}
<span class="active">@{page}</span>
@{else}
<a href="?page=@{page}">@{page}</a>
@{fi}
@{end}
Form Helpers
Form helpers render an HTML form element and auto-bind its value from the model field named by the first argument. An optional object literal supplies HTML attributes:
@{text('email', { class: 'form', placeholder: 'you@example.com', required: true })}
<!-- with model { email: "a@b.com" }: -->
<!-- <input type="text" name="email" value="a@b.com" class="form" placeholder="you@example.com" required /> -->
Attribute object rules: key: 'str' / key: 30 β key="..."; flag: true β
a bare boolean attribute (required); flag: false β omitted. Values and
attributes are HTML-escaped; a missing model field renders an empty value.
| Helper | Renders |
|---|---|
@{text('field', { ...attrs })} | <input type="text" name="field" value="{model.field}" ... /> |
@{password('field', { ...attrs })} | <input type="password" ... /> |
@{hidden('field', { ...attrs })} | <input type="hidden" ... /> |
@{textarea('field', { ...attrs })} | <textarea name="field" ...>{model.field}</textarea> |
@{checkbox('field', [label])} | <input type="checkbox" name="field"[ checked] />, checked when the model field is truthy |
@{radio('field', 'value', [label])} | <input type="radio" name="field" value="value"[ checked] />, checked when the model field == value |
checkbox and radio take an optional label that wraps the input in a
<label>. For radio, the third argument is either a label string or an
object whose label key is the wrap text and whose other keys are attributes:
@{checkbox('agree', 'I accept the terms')}
<!-- <label><input type="checkbox" name="agree" checked /> I accept the terms</label> -->
@{radio('gender', 'male', 'Male')}
@{radio('gender', 'female', { label: 'Female', class: 'opt' })}
Meta Helpers (title & description)
@{title('...')} and @{description('...')} are setters β they store the
value in meta data (carried from the view into its layout) and render nothing
inline. The layout reads them back with @{title} / @{description}:
<!-- view: auth/login.html -->
@{title('Sign in')}
@{description('Access your account')}
<!-- layouts/default.html -->
<head>
<title>@{title} Β· @{MAIN.site_name}</title>
<meta name="description" content="@{description}">
</head>
@{meta('Title', 'Description', 'Keywords')} is the all-in-one variant that
emits the <title> and <meta> tags directly at its position.
Request Properties
Read-only values available in any template:
| Property | Description |
|---|---|
@{url} | the requestβs relative URL |
@{hostname} | the request host |
@{mobile} | boolean β true for mobile-device User-Agents (@{if mobile}β¦@{fi}) |
@{root} | configured views.default_root with the trailing / stripped β for apps served under a sub-path |
Inside a @{foreach} loop, @{break} and @{continue} work both directly and
inside @{if} / @{elif} blocks:
@{foreach item in M.items}
@{if item.sold_out}@{continue}@{fi}
<li>@{item.name}</li>
@{if index >= 9}@{break}@{fi}
@{end}
Template Partials and Includes
Total.js templates support including other templates (partials) using the @{view()} function:
<!-- Include a partial template -->
@{view('partials/header')}
<!-- Include with specific model data -->
@{view('partials/user-card', model.currentUser)}
<!-- Include in loops -->
@{foreach user in model.users}
@{view('partials/user-card', user)}
@{end}
<!-- Nested partials (partials can include other partials) -->
<!-- In partials/sidebar.html: -->
@{view('partials/user-info', model.user)}
@{view('partials/menu', model.menuItems)}
Partial Template Example
Create reusable components in views/partials/:
<!-- views/partials/user-card.html -->
<div class="user-card">
<img src="@{model.avatar}" alt="@{model.name}">
<h3>@{model.name}</h3>
<p>@{model.email}</p>
@{if model.isAdmin}
<span class="badge">Admin</span>
@{fi}
</div>
Use it in your main templates:
<!-- views/users/list.html -->
<div class="users-grid">
@{foreach user in model.users}
@{view('partials/user-card', user)}
@{end}
</div>
Important Notes
- Partials have access to all global data (repository, session, etc.)
- When passing model data, the partial receives only that data as its model
- Partials are loaded relative to the views directory
- Nested partials are supported (partials can include other partials)
- Currently, array indexing in expressions (e.g.,
model.users[0]) is not supported in the view() function
Layouts
Layout System Overview
RustF follows the Total.js pattern for layouts:
- Default layout: Configured in
config.tomlasviews.default_layout(default:"layouts/default") - Custom layout: Use
ctx.layout("path/to/layout")in controller - No layout: Use
ctx.layout("")with empty string - Layout inheritance: Templates can specify their own layout with
@{layout('path')}
Controller-Side Layout Control
#![allow(unused)]
fn main() {
use rustf::prelude::*;
pub fn install() -> Vec<Route> {
routes![
GET "/" => index,
GET "/admin" => admin,
GET "/api-doc" => api_doc,
]
}
// Uses default layout from config
async fn index(ctx: &mut Context) -> rustf::Result<()> {
ctx.repository_set("title", "Home");
ctx.view("home/index", json!({}))
}
// Custom layout
async fn admin(ctx: &mut Context) -> rustf::Result<()> {
ctx.layout("layouts/admin"); // Set custom layout
ctx.view("admin/dashboard", json!({"user": "Admin"}))
}
// No layout (standalone page)
async fn api_doc(ctx: &mut Context) -> rustf::Result<()> {
ctx.layout(""); // Empty string = no layout
ctx.view("docs/api", json!({"version": "1.0"}))
}
}
Total.js Layouts
Define a layout (views/layouts/default.html):
<!DOCTYPE html>
<html>
<head>
<title>@{if R.title}@{R.title} - @{fi}My App</title>
@{css('/static/css/main.css')}
</head>
<body>
<nav>
<a href="@{root}/">Home</a>
<a href="@{root}/about">About</a>
</nav>
<main>
@{body} <!-- Child template content renders here -->
</main>
@{js('/static/js/app.js')}
</body>
</html>
Use in child template (views/home/index.html):
<h1>@{model.title}</h1>
<p>@{M.message}</p>
@{foreach feature in model.features}
<div>@{feature}</div>
@{end}
Note:
@{layout('...')}is not a template directive in RustF. The layout is chosen by the handler withctx.layout("layouts/default")(or falls back to theviews.default_layoutvalue inconfig.toml). Set it before callingctx.view(...).
Sections
Section System Overview
Sections allow child templates to define content blocks that parent layouts can render in specific locations. This is the standard pattern for customizing different areas of a layout (head content, sidebar, footer, etc.) from child views.
Key Concepts:
- Child defines sections: Use
@{section name}...@{end}in child templates - Parent renders sections: Use
@{section('name')}in layout templates - Optional sections: Missing sections render as empty (no errors)
- Multiple sections: Child can define multiple sections for different layout areas
Basic Section Usage
Layout with Section Placeholders (views/layouts/main.html):
<!DOCTYPE html>
<html>
<head>
<title>@{M.title}</title>
<!-- Child can inject custom styles here -->
@{section('styles')}
<!-- Child can add meta tags, scripts, etc. -->
@{section('head')}
</head>
<body>
<header>
<!-- Child can customize header -->
@{section('header')}
</header>
<main>
@{body} <!-- Main content -->
</main>
<aside>
<!-- Child can provide sidebar content -->
@{section('sidebar')}
</aside>
<footer>
<!-- Child can customize footer -->
@{section('footer')}
</footer>
<!-- Child can inject page-specific scripts -->
@{section('scripts')}
</body>
</html>
Child Template Defining Sections (views/products/detail.html):
@{section styles}
<link rel="stylesheet" href="/css/products.css">
<style>
.product-gallery { display: grid; }
</style>
@{end}
@{section head}
<meta property="og:title" content="@{M.product.name}">
<meta property="og:image" content="@{M.product.image}">
@{end}
@{section header}
<h1>@{M.product.name}</h1>
<nav class="breadcrumb">
<a href="@{root}/">Home</a> >
<a href="@{root}/products">Products</a> >
@{M.product.category}
</nav>
@{end}
<!-- Main content (rendered in @{body}) -->
<div class="product-detail">
<img src="@{M.product.image}" alt="@{M.product.name}">
<div class="product-info">
<p class="price">$@{M.product.price}</p>
<p>@{M.product.description}</p>
</div>
</div>
@{section sidebar}
<h3>Related Products</h3>
@{foreach item in M.related}
<div class="related-item">
<a href="/products/@{item.id}">@{item.name}</a>
</div>
@{end}
@{end}
@{section scripts}
<script src="/js/product-gallery.js"></script>
<script>
initProductGallery('@{M.product.id}');
</script>
@{end}
Section Features
1. Optional Sections - No errors if section not defined:
<!-- Layout -->
<div class="notifications">
@{section('alerts')} <!-- Empty if child doesn't define it -->
</div>
<!-- Child - can choose to define or skip -->
@{section alerts}
<div class="alert">Special offer!</div>
@{end}
2. Conditional Sections:
<!-- Child template -->
@{if M.show_newsletter}
@{section footer}
<div class="newsletter-signup">
<form>...</form>
</div>
@{end}
@{fi}
3. Sections with Dynamic Content:
<!-- Child template -->
@{section sidebar}
<h3>Categories</h3>
@{foreach cat in M.categories}
<a href="/category/@{cat.slug}">@{cat.name}</a>
@{end}
<h3>Tags</h3>
@{foreach tag in M.tags}
<span class="tag">@{tag}</span>
@{end}
@{end}
4. Multiple Sections in One Template:
<!-- A single child view can define many sections -->
@{section meta}...@{end}
@{section styles}...@{end}
@{section header}...@{end}
<!-- Main content here -->
@{section sidebar}...@{end}
@{section footer}...@{end}
@{section scripts}...@{end}
Common Section Patterns
Meta Tags & SEO:
<!-- Layout head -->
@{section('meta')}
<!-- Child defines SEO metadata -->
@{section meta}
<meta name="description" content="@{M.description}">
<meta name="keywords" content="@{M.keywords}">
<link rel="canonical" href="@{M.canonical_url}">
@{end}
Page-Specific Styles:
<!-- Layout head -->
@{section('page_styles')}
<!-- Child adds custom CSS -->
@{section page_styles}
<link rel="stylesheet" href="/css/dashboard.css">
<style>
.dashboard-widget { margin: 1rem; }
</style>
@{end}
JavaScript Initialization:
<!-- Layout before </body> -->
@{section('page_scripts')}
<!-- Child adds page logic -->
@{section page_scripts}
<script src="/js/chart.min.js"></script>
<script>
initCharts(@{!json(M.chart_data)}); // raw form inside <script>
</script>
@{end}
Breadcrumbs:
<!-- Layout -->
<nav class="breadcrumbs">
<a href="/">Home</a>
@{section('breadcrumbs')}
</nav>
<!-- Child extends breadcrumb trail -->
@{section breadcrumbs}
> <a href="/products">Products</a>
> @{M.category}
@{end}
Section vs @{head} Special Placeholder
RustF provides a special @{head} placeholder that automatically renders content from a section named βheadβ:
<!-- These are equivalent: -->
@{section('head')}
@{head}
The @{head} placeholder is a convenience feature inherited from Total.js for adding content to the HTML <head> section. For all other sections, use the explicit @{section('name')} syntax.
Best Practices
-
Name sections clearly: Use descriptive names like
page_styles,sidebar_menu,footer_links -
Document expected sections: Comment layout templates to show which sections are available:
<!-- Available sections: - styles: Custom CSS for this page - header: Page-specific header content - sidebar: Sidebar widgets - scripts: Page-specific JavaScript --> -
Keep sections focused: Each section should have a single, clear purpose
-
Make sections optional: Donβt require every child to define every section
-
Use consistent naming: Establish naming conventions across your app:
page_styles/page_scriptsfor page-specific assetsmetafor SEO metadataheader/footer/sidebarfor layout areas
Example: Complete Blog Post Template
Layout (views/layouts/blog.html):
<!DOCTYPE html>
<html>
<head>
<title>@{M.title} - My Blog</title>
<meta charset="UTF-8">
@{section('meta')}
@{css('/css/blog.css')}
@{section('styles')}
</head>
<body>
<header class="site-header">
<h1>My Blog</h1>
@{section('breadcrumbs')}
</header>
<div class="content-wrapper">
<article>
@{section('article_header')}
@{body}
</article>
<aside class="sidebar">
@{section('sidebar')}
</aside>
</div>
<footer>
@{section('comments')}
<p>© 2025 My Blog</p>
</footer>
@{js('/js/blog.js')}
@{section('scripts')}
</body>
</html>
Blog Post (views/blog/post.html):
@{section meta}
<meta name="description" content="@{M.excerpt}">
<meta name="author" content="@{M.author}">
<meta property="og:image" content="@{M.featured_image}">
@{end}
@{section breadcrumbs}
<a href="/blog">Blog</a> >
<a href="/blog/@{M.category}">@{M.category_name}</a>
@{end}
@{section article_header}
<h1>@{M.title}</h1>
<div class="meta">
By @{M.author} on @{M.published_date}
</div>
<img src="@{M.featured_image}" alt="@{M.title}">
@{end}
<!-- Main article content -->
<div class="article-body">
@{M.content}
</div>
@{section sidebar}
<h3>About the Author</h3>
<p>@{M.author_bio}</p>
<h3>Related Posts</h3>
@{foreach post in M.related_posts}
<a href="/blog/@{post.slug}">@{post.title}</a>
@{end}
@{end}
@{section comments}
<div class="comments">
<h3>Comments (@{M.comment_count})</h3>
@{foreach comment in M.comments}
<div class="comment">
<strong>@{comment.author}</strong>
<p>@{comment.text}</p>
</div>
@{end}
</div>
@{end}
@{section scripts}
<script src="/js/syntax-highlighter.js"></script>
<script>highlightCode();</script>
@{end}
Storage Options
Filesystem (Development)
- Templates loaded from disk at runtime
- Supports hot-reloading
- Easy to modify during development
- Configure with:
storage = "filesystem"
Embedded (Production)
- Templates compiled into binary
- Faster startup, no file I/O
- Requires
embedded-viewsfeature - Configure with:
storage = "embedded"
Advanced Features
Custom Template Functions
Custom functions usable in templates (@{my_helper(...)}) are registered as
helpers through the Definitions system β there is no public
engine.register_function(...) method. Register the helper inside a definitions
moduleβs install function:
#![allow(unused)]
fn main() {
use rustf::definitions::Definitions;
pub fn install(defs: &mut Definitions) {
// `defs.helpers` is the public HelperRegistry; `register_fn` takes a
// name, description, and a closure `Fn(&[Value], _) -> Result<Value>`.
defs.helpers.register_fn(
"format_price",
"Format a number as a price",
|args, _| {
let amount = args.first().and_then(|v| v.as_f64()).unwrap_or(0.0);
Ok(serde_json::Value::String(format!("${:.2}", amount)))
},
);
}
// Use in template
// @{format_price(19.99)} => "$19.99"
}
See the Definitions guide for the full helper API
(register_helper, register_fn) and how definitions modules are auto-discovered.
CSRF Protection
Automatic CSRF token injection:
#![allow(unused)]
fn main() {
// In controller - generate token and render view.
// generate_csrf takes an Option<&str> token id; pass None for the default.
ctx.generate_csrf(None)?;
ctx.view("form", data)
}
<!-- In template - Total.js -->
<form method="POST">
@{csrf} <!-- Renders hidden input with the default token -->
<!-- or manually -->
<input type="hidden" name="_token" value="@{csrf_token}">
</form>
Repository System
RustF provides two repository systems for sharing data between controllers and views:
Context Repository (Per-Request)
The context repository is request-scoped data that controllers can set to share with templates. Itβs useful for page-specific settings, user permissions, or any data thatβs specific to the current request.
Setting in Controllers:
#![allow(unused)]
fn main() {
async fn dashboard(ctx: &mut Context) -> rustf::Result<()> {
// Set various types of repository data
ctx.repository_set("current_section", "analytics")
.repository_set("sidebar_expanded", true)
.repository_set("user_role", "admin")
.repository_set("available_actions", json!(["view", "edit", "delete"]))
.repository_set("theme", json!({
"primary_color": "#007bff",
"mode": "dark"
}));
ctx.repository_set("title", "Dashboard");
// Repository data is automatically available in templates.
// The model is the page's single subject: here, the stats object.
let stats = get_stats().await?;
ctx.view("dashboard/index", json!(stats))
}
}
Accessing in Templates:
<!-- Using R. prefix (recommended, shorter) -->
@{if R.user_role == 'admin'}
<div class="admin-panel">
@{foreach action in R.available_actions}
<button>@{action}</button>
@{end}
</div>
@{fi}
<!-- Using repository. prefix (alternative) -->
<div class="sidebar @{if repository.sidebar_expanded}expanded@{fi}">
Current Section: @{repository.current_section}
</div>
<!-- Accessing nested data -->
<style>
:root {
--primary-color: @{R.theme.primary_color};
}
body.@{R.theme.mode} {
/* Dark mode styles */
}
</style>
Global Repository (APP/MAIN)
The global repository is application-wide data shared across all requests. Itβs typically set during application initialization and contains site-wide settings, application metadata, or shared constants.
Setting During Application Setup:
Use the APP global repository. It accepts dotted paths, so nested values are
set directly:
#![allow(unused)]
fn main() {
// In your main.rs or app initialization
use rustf::APP;
APP::set("site_name", "My Application")?;
APP::set("version", "2.1.0")?;
APP::set("copyright", "Β© 2024 MyCompany")?;
APP::set("contact_email", "support@example.com")?;
APP::set("features.comments", true)?;
APP::set("features.notifications", true)?;
APP::set("features.api_v2", false)?;
APP::set("social_links.twitter", "https://twitter.com/myapp")?;
APP::set("social_links.github", "https://github.com/myapp")?;
}
Deprecated:
TotalJsEngine::set_global_repository(...)is marked#[deprecated]β useAPP::set()as shown above instead.
Accessing in Templates:
<!-- Using APP. prefix -->
<footer>
<p>@{APP.copyright}</p>
<p>Contact: <a href="mailto:@{APP.contact_email}">@{APP.contact_email}</a></p>
<p>Version @{APP.version}</p>
</footer>
<!-- Using MAIN. prefix (alias for APP) -->
<title>@{title} - @{MAIN.site_name}</title>
<!-- Checking features -->
@{if APP.features.comments}
<div class="comments-section">
<!-- Comments enabled -->
</div>
@{fi}
<!-- Social links -->
<div class="social">
@{if APP.social_links.twitter}
<a href="@{APP.social_links.twitter}">Twitter</a>
@{fi}
@{if APP.social_links.github}
<a href="@{APP.social_links.github}">GitHub</a>
@{fi}
</div>
Repository vs Data: Whatβs the Difference?
Repository Data (R. or repository.)
- Available to all views called within the same handler function
- Set using
ctx.repository_set()before calling views - Ideal for shared UI elements, user info, theme settings
- Lives for the duration of the handler function execution
View Data (Model)
- Specific to each individual view call
- Passed via
ctx.view(template, data) - Accessed via
@{model.key}or@{M.key}prefix - For page-specific content
- Only available in that specific view call
- Preferabily used for data flowing from db to form or vis versa
Example showing both:
#![allow(unused)]
fn main() {
async fn product_page(ctx: &mut Context) -> rustf::Result<()> {
let id = ctx.param_as::<i64>("id")?;
// Repository: page-level data, collections and flags -> @{R.key}
ctx.repository_set("nav_items", get_navigation())
.repository_set("user", get_current_user())
.repository_set("cart_count", get_cart_count())
.repository_set("reviews", get_reviews(id))
.repository_set("related", get_related_products(id));
// Model: ONE object, the product this page is about -> @{M.field}
ctx.view("products/show", get_product(id))
}
}
<!-- Repository data accessible in the template -->
<nav>
@{foreach item in R.nav_items}
<a href="@{item.url}">@{item.title}</a>
@{end}
<span class="cart">Cart (@{R.cart_count})</span>
</nav>
<!-- View data (Model): the product itself -->
<h1>@{model.name}</h1>
<p>@{M.description}</p>
@{foreach review in R.reviews}
<div class="review">@{review.text}</div>
@{end}
Repository Best Practices
-
Use Context Repository for:
- Data needed by multiple views within the same handler
- User information for the current request
- UI state for the current handler (theme, layout settings)
- Temporary computed values used across view calls
- Avoiding data duplication when rendering multiple views
-
Use Global Repository (APP/MAIN) for:
- Application metadata (name, version, copyright)
- Site-wide configuration (features, limits)
- Constants needed across the entire application
- External service URLs and API keys (non-sensitive)
- Data accessible throughout the application, not just in views
-
Naming Conventions:
#![allow(unused)] fn main() { // β Good: Clear, semantic names ctx.repository_set("user_permissions", permissions); ctx.repository_set("page_metadata", metadata); // β Bad: Generic or unclear names ctx.repository_set("data", something); ctx.repository_set("x", value); } -
Performance Considerations:
- Context repository exists only during handler execution (keep it reasonable)
- Global repository is shared application-wide (can hold more persistent data)
- Context repository is cleared when handler returns
- Global repository persists for the applicationβs lifetime
-
Common Patterns:
#![allow(unused)] fn main() { // Pattern 1: Set common data at the start of a handler async fn my_handler(ctx: &mut Context) -> rustf::Result<()> { // Set repository data first ctx.repository_set("user", get_current_user(&ctx)?); ctx.repository_set("notifications", get_notifications(&ctx)?); // Then render view(s) that need this data ctx.view("my_template", specific_data) } // Pattern 2: Use repository for feature flags ctx.repository_set("features", json!({ "new_editor": is_feature_enabled("new_editor"), "beta_api": is_feature_enabled("beta_api") })); // Pattern 3: Breadcrumb builder ctx.repository_set("breadcrumbs", json!([ {"label": "Home", "url": "/"}, {"label": "Products", "url": "/products"}, {"label": product.name, "url": null} // Current page ])); }
Flash Messages
Flash messages are one-time messages that survive redirects but are automatically cleared when a view is rendered. They provide a clean way to show user feedback across page redirections.
Setting Flash Messages in Controllers
#![allow(unused)]
fn main() {
// Standard convenience methods
ctx.flash_success("User created successfully!");
ctx.flash_error("Invalid credentials");
ctx.flash_info("Please check your email");
// Generic flash setter for any key and serializable value
ctx.flash("warning_msg", "This is a warning")?;
ctx.flash("user_level", 42)?;
ctx.flash("notification", json!({
"text": "You have new messages",
"count": 5
}))?;
ctx.flash("recent_actions", vec!["Logged in", "Updated profile"])?;
// Manual flash management
ctx.flash_clear(); // Clear all flash messages
ctx.flash_clear_key("error_msg"); // Clear specific flash message
// Typical usage pattern
if validation_failed {
ctx.flash_error("Please correct the errors below");
return ctx.redirect("/form");
}
ctx.flash_success("Form submitted successfully!");
ctx.redirect("/dashboard")
}
Accessing Flash Messages in Templates
Flash messages are stored in the session but are aliased for convenience, so you can access them directly using @{flash.xxx} instead of @{session.flash.xxx}:
<!-- Standard flash messages - Total.js -->
@{if flash.success}
<div class="alert alert-success">@{flash.success}</div>
@{fi}
@{if flash.error}
<div class="alert alert-error">@{flash.error}</div>
@{fi}
@{if flash.info}
<div class="alert alert-info">@{flash.info}</div>
@{fi}
<!-- Custom flash messages -->
@{if flash.warning}
<div class="alert alert-warning">@{flash.warning}</div>
@{fi}
<!-- Complex flash data -->
@{if flash.notification}
<div class="notification">
@{flash.notification.text}
@{if flash.notification.count}
<span class="badge">@{flash.notification.count}</span>
@{fi}
</div>
@{fi}
<!-- Array flash data -->
@{if flash.recent_actions}
<div class="recent-actions">
<h4>Recent Actions:</h4>
<ul>
@{foreach action in flash.recent_actions}
<li>@{action}</li>
@{end}
</ul>
</div>
@{fi}
<!-- Number flash data -->
@{if flash.user_level}
<div class="user-level">Level: @{flash.user_level}</div>
@{fi}
Flash Message Lifecycle
- Set in controller: Flash messages are stored in the session
- Survive redirects: Messages persist through HTTP redirects
- Auto-cleared on view render: Messages are automatically removed when any view is rendered
- Manual clearing: Use
flash_clear()orflash_clear_key()for explicit control
Best Practices
#![allow(unused)]
fn main() {
// β
Good: Use specific flash keys for different message types
ctx.flash("validation_error", "Email is required")?;
ctx.flash("success", "Account created")?;
ctx.flash("warning", "Trial period expires soon")?;
// β
Good: Clear flash before setting new messages in error scenarios
if let Err(e) = process_data() {
ctx.flash_clear(); // Clear any existing flash
ctx.flash_error(&format!("Processing failed: {}", e));
return ctx.redirect("/retry");
}
// β
Good: Use structured data for complex notifications
ctx.flash("notification", json!({
"type": "info",
"title": "System Update",
"message": "Maintenance scheduled for tonight",
"actions": [{"text": "Learn More", "url": "/maintenance"}]
}))?;
// β
Good: Selective clearing for fine-grained control
ctx.flash_clear_key("error_msg"); // Keep other flash messages
ctx.flash_success("Operation completed!");
}
Static Asset Helpers
<!-- Total.js built-in helpers -->
@{css('/static/css/app.css')}
<!-- Renders: <link rel="stylesheet" href="/static/css/app.css"> -->
@{js('/static/js/app.js')}
<!-- Renders: <script src="/static/js/app.js"></script> -->
<!-- With root path -->
@{css(root + '/static/css/app.css')}
<!-- Renders: <link rel="stylesheet" href="/myapp/static/css/app.css"> -->
Translation & Internationalization (i18n)
RustF provides a Total.js-style translation system using resource files with automatic key generation and view-scoped translations.
Template Syntax
<!-- Direct text translation (key generated from text) -->
<h1>@(Welcome to our application)</h1>
<p>@(Please enter your credentials)</p>
<!-- Translation by custom key -->
<footer>@(#app.copyright)</footer>
<nav>@(#nav.home)</nav>
Resource File Format
Translation files use the .res extension and are stored in the resources/ directory:
# resources/default.res
[global]
# Common translations used across multiple views
save : "Save"
cancel : "Cancel"
loading : "Loading..."
[views/home/index]
# View-specific translations
welcome_to_our_application : "Welcome to our application"
please_enter_your_credentials : "Please enter your credentials"
[views/layouts/main]
# Layout translations
app.copyright : "Β© 2024 My Company"
nav.home : "Home"
Setting Up Translations
Loading translations in your application:
#![allow(unused)]
fn main() {
use rustf::prelude::*;
use rustf::views::TotalJsEngine;
// During app initialization
let engine = TotalJsEngine::new("views");
// Load translations from resources directory
engine.load_translations(Path::new("resources"))?;
// Or manually with resource translation system
use rustf::views::totaljs::resource_translation::ResourceTranslationSystem;
let mut translator = ResourceTranslationSystem::new();
translator.load_resources_dir(Path::new("resources"))?;
translator.set_language("fr"); // Switch to French
engine.set_resource_translator(translator);
}
Managing Translations with CLI
# Scan views and generate default.res with all discovered translations
rustf-cli translations scan
# Output:
# π Scanning views for translations...
# β
Generated resources/default.res with 45 translations
# Update existing language files with new keys
rustf-cli translations update --lang fr
# Output:
# π Regenerating default.res...
# π Updating fr.res...
# π Update Report for fr.res:
# β Existing translations preserved: 42
# β οΈ New keys needing translation: 3
# - welcome_message
# - user_greeting
# - logout_confirm
# Check for missing translations
rustf-cli translations check --lang es
# Show translation statistics
rustf-cli translations stats
Translation Workflow
- Write views with translatable text:
<!-- views/home/index.html -->
<h1>@(Welcome to RustF)</h1>
<p>@(Build fast web applications)</p>
<div>@(#custom.message)</div>
- Generate translation keys:
rustf-cli translations scan
- Translate to other languages:
# Copy default to create language file
cp resources/default.res resources/fr.res
# Edit fr.res and translate the values
vim resources/fr.res
- View generated fr.res:
# resources/fr.res
[global]
save : "Enregistrer"
cancel : "Annuler"
loading : "Chargement..."
[views/home/index]
welcome_to_rustf : "Bienvenue Γ RustF"
build_fast_web_applications : "Construire des applications web rapides"
custom.message : "" # TODO: needs translation
Key Generation
- Text in
@(text)is converted to a readable slug key (max 30 chars) - Spaces become underscores, special characters removed
- Common translations (appearing in 3+ views) are automatically moved to
[global] - Custom keys using
@(#key)are preserved as-is
Best Practices
-
Use descriptive custom keys for important text:
@(#app.title) <!-- Good: Clear purpose --> @(#msg1) <!-- Bad: Unclear --> -
Keep translations organized by view:
- Each view gets its own section in the .res file
- Layouts have their own sections
- Common text automatically extracted to global
-
Language switching in controllers:
#![allow(unused)] fn main() { // Set language based on user preference if let Some(lang) = ctx.session_get("language") { engine.resource_translator.set_language(&lang); } } -
Fallback language support:
#![allow(unused)] fn main() { translator.set_fallback("en"); // English as fallback }
Global VIEW API
RustF provides a global VIEW API for rendering templates from anywhere in your application without needing a Context instance. This is particularly useful for:
- Email generation in background workers
- PDF/report generation
- Dynamic content rendering in services
- Template rendering in middleware or utilities
Basic Usage
#![allow(unused)]
fn main() {
use rustf::prelude::*;
use serde_json::json;
// Render an inline template string
let html = VIEW::render_string(
"Hello @{M.name}!",
json!({"name": "Alice"}),
None
)?;
// Output: "Hello Alice!"
// Render a template file
let html = VIEW::render(
"emails/welcome",
json!({"user": "Alice"}),
None,
Some("layouts/email")
)?;
}
Method Signatures
VIEW::render_string()
Render an inline template string with model and optional repository data.
#![allow(unused)]
fn main() {
pub fn render_string(
template_string: &str,
model: Value,
repository: Option<Value>
) -> Result<String>
}
Parameters:
template_string: Template content as stringmodel: Main template data (accessible as@{M.key})repository: Optional context data (accessible as@{R.key})
Example:
#![allow(unused)]
fn main() {
let template = "Welcome @{M.user}, your role is @{R.role}";
let model = json!({"user": "Alice"});
let repository = json!({"role": "Admin"});
let html = VIEW::render_string(template, model, Some(repository))?;
// Output: "Welcome Alice, your role is Admin"
}
VIEW::render()
Render a template file with model, repository, and optional layout.
#![allow(unused)]
fn main() {
pub fn render(
template_path: &str,
model: Value,
repository: Option<Value>,
layout: Option<&str>
) -> Result<String>
}
Parameters:
template_path: Path to template (relative to views directory, without extension)model: Main template data (accessible as@{M.key})repository: Optional context data (accessible as@{R.key})layout: Optional layout template name
Example:
#![allow(unused)]
fn main() {
let html = VIEW::render(
"reports/sales",
json!({"month": "January", "total": 50000}),
Some(json!({"company": "ACME Corp", "year": 2025})),
Some("layouts/pdf")
)?;
}
Model vs Repository Data
The VIEW API maintains the same model/repository separation as controller rendering:
- Model (
@{M.key}): Primary template data - the main content - Repository (
@{R.key}): Context/metadata - site config, user info, etc.
#![allow(unused)]
fn main() {
let model = json!({
"product": "Widget",
"price": 29.99,
"quantity": 5
});
let repository = json!({
"site_name": "My Store",
"currency": "USD",
"tax_rate": 0.08
});
let template = r#"
<h1>@{R.site_name}</h1>
<p>Product: @{M.product}</p>
<p>Price: @{R.currency} @{M.price}</p>
"#;
let html = VIEW::render_string(template, model, Some(repository))?;
}
Use Cases
Email Generation in Workers
#![allow(unused)]
fn main() {
use rustf::prelude::*;
pub async fn send_welcome_email(ctx: WorkerContext) -> rustf::Result<()> {
let email_template = r#"
<html>
<body>
<h1>Welcome to @{R.app_name}!</h1>
<p>Hello @{M.name},</p>
<p>Thanks for signing up. Your username is: @{M.username}</p>
<footer>© @{R.year} @{R.company}</footer>
</body>
</html>
"#;
let model = json!({
"name": ctx.data["name"],
"username": ctx.data["username"]
});
let repository = json!({
"app_name": "My App",
"year": 2025,
"company": "My Company Inc."
});
let html = VIEW::render_string(email_template, model, Some(repository))?;
// Send email with html content
send_email(&ctx.data["email"].as_str().unwrap(), &html).await?;
Ok(())
}
}
Report Generation
#![allow(unused)]
fn main() {
use rustf::prelude::*;
pub fn generate_sales_report(sales_data: Vec<SaleRecord>) -> rustf::Result<String> {
let template = r#"
<h1>Sales Report - @{M.period}</h1>
<table>
<tr><th>Product</th><th>Units</th><th>Revenue</th></tr>
@{foreach item in M.items}
<tr>
<td>@{item}</td>
<td>@{item}</td>
<td>$@{item}</td>
</tr>
@{end}
</table>
<p>Generated: @{R.generated_date}</p>
"#;
let model = json!({
"period": "Q1 2025",
"items": sales_data
});
let repository = json!({
"generated_date": chrono::Utc::now().to_rfc3339()
});
VIEW::render_string(template, model, Some(repository))
}
}
Dynamic Content in Middleware
#![allow(unused)]
fn main() {
use rustf::prelude::*;
pub async fn render_error_page(status: u16, message: &str) -> rustf::Result<String> {
let template = r#"
<!DOCTYPE html>
<html>
<head><title>Error @{M.status}</title></head>
<body>
<h1>@{M.status} - @{M.title}</h1>
<p>@{M.message}</p>
<footer>@{R.app_name}</footer>
</body>
</html>
"#;
let model = json!({
"status": status,
"title": if status == 404 { "Not Found" } else { "Error" },
"message": message
});
let repository = json!({
"app_name": "My Application"
});
VIEW::render_string(template, model, Some(repository))
}
}
Template File Rendering
#![allow(unused)]
fn main() {
// views/emails/order_confirmation.html
// <h1>Order Confirmation</h1>
// <p>Thank you @{M.customer_name}!</p>
// <p>Order #@{M.order_id} has been confirmed.</p>
use rustf::prelude::*;
pub async fn send_order_confirmation(order: Order) -> rustf::Result<()> {
let html = VIEW::render(
"emails/order_confirmation",
json!({
"customer_name": order.customer_name,
"order_id": order.id,
"total": order.total
}),
Some(json!({
"site_name": "My Shop",
"support_email": "support@myshop.com"
})),
Some("layouts/email") // Use email layout
)?;
send_email(&order.customer_email, &html).await?;
Ok(())
}
}
Limitations
- No Session Data: Global VIEW API doesnβt have access to session data (use
ctx.view()in controllers for session access) - Initialization Required: VIEW must be initialized during app startup (automatic with
auto_load()) - Template Features: All Total.js features work (conditionals, loops, variables, etc.)
Best Practices
- Use Model/Repository Separation: Keep template data (
M) separate from context (R) - Validate Before Rendering: Ensure data is complete before calling VIEW
- Handle Errors: Always handle
Resultfrom VIEW methods - Cache Templates: Use file-based templates for better caching in production
- Test Rendering: Unit test your templates with VIEW::render_string()
Performance Tips
Development
[views]
cache_enabled = false # Hot-reload templates
Production
[views]
cache_enabled = true # Cache compiled templates
storage = "embedded" # Embed templates in binary
Template Caching
Templates are automatically cached when cache_enabled = true:
- First request compiles the template
- Subsequent requests use cached version
- No manual cache management needed
Directory Structure
views/
βββ layouts/
β βββ application.html # Main layout
βββ home/
β βββ index.html # Homepage
β βββ about.html # About page
βββ auth/
β βββ login.html # Login form
β βββ register.html # Registration
βββ components/
βββ navbar.html # Reusable navbar
βββ footer.html # Reusable footer
Error Handling
Template Not Found
#![allow(unused)]
fn main() {
// Graceful fallback
match ctx.view("missing-template", data) {
Ok(response) => Ok(response),
Err(_) => ctx.view("errors/404", json!({"message": "Page not found"}))
}
}
Syntax Errors
- Total.js: Errors shown with line numbers during development
Note: Total.js is the only supported template engine in RustF. Tera and other engines are not supported.
Migration Guide
Coming From Tera (Syntax Cheat Sheet)
If youβre used to Tera, hereβs how the equivalent Total.js syntax looks. (RustF itself does not run Tera β this table is only to ease the transition.)
| Tera (other engine) | Total.js (RustF) |
|---|---|
{{ variable }} | @{variable} |
{% if condition %} | @{if condition} |
{% endif %} | @{fi} |
{% for item in items %} | @{foreach item in items} |
{% endfor %} | @{end} |
{{ var | escape }} | @{var} (auto-escaped) |
{{ var | safe }} | @{!var} |
Best Practices
- Use layouts - Define common structure once
- Escape user input - Use auto-escaping by default
- Cache in production - Enable template caching
- Organize templates - Group by feature/module
- Keep logic minimal - Complex logic belongs in controllers
- Use components - Create reusable template parts
- Validate data - Donβt trust template input
- Handle errors - Provide fallback templates
Troubleshooting
Templates Not Loading
- Check
views.directoryin config.toml - Verify file extensions match
views.extension - Ensure template names donβt include extension in controller
Variables Not Rendering
- Check variable names match exactly
- Verify data is passed to
ctx.view() - Use
@{json(variable)}to debug data structure
Layout Issues
- Verify layout path is correct
- Check
@{content}placeholder exists in layout - Ensure child template specifies layout
Performance Issues
- Enable
cache_enabledin production - Use
embeddedstorage for deployment - Minimize template complexity
- Move heavy logic to controllers
Examples
Complete Controller with Views and Repositories
#![allow(unused)]
fn main() {
use rustf::prelude::*;
pub fn install() -> Vec<Route> {
routes![
GET "/products" => index,
GET "/products/{id}" => show,
POST "/products/{id}/buy" => purchase,
]
}
async fn index(ctx: &mut Context) -> rustf::Result<()> {
let products = vec![
json!({"id": 1, "name": "Widget", "price": 19.99}),
json!({"id": 2, "name": "Gadget", "price": 29.99}),
];
// Set context repository for this page
ctx.repository_set("view_mode", "grid")
.repository_set("filters_available", json!(["price", "category", "brand"]))
.repository_set("user_preferences", json!({
"currency": "USD",
"show_tax": true
}));
ctx.repository_set("title", "Our Products")
.repository_set("products", json!(products))
.repository_set("featured", true);
// A list page has no single subject: empty model
ctx.view("products/index", json!({}))
}
async fn show(ctx: &mut Context) -> rustf::Result<()> {
let id = ctx.param_str("id")?;
// Fetch product from database
let product = json!({
"id": id,
"name": "Premium Widget",
"price": 49.99,
"description": "High-quality widget"
});
// Set repository data for product page
ctx.repository_set("breadcrumbs", json!([
{"name": "Home", "url": "/"},
{"name": "Products", "url": "/products"},
{"name": "Premium Widget", "url": null}
]))
.repository_set("show_reviews", true)
.repository_set("related_products_count", 5);
ctx.view("products/show", product)
}
async fn purchase(ctx: &mut Context) -> rustf::Result<()> {
let id = ctx.param_str("id")?;
// Process purchase...
ctx.flash_success("Purchase completed!")?;
ctx.redirect(&format!("/products/{}", id))
}
}
Template with All Features Including Repositories
<!-- Page specific CSS -->
@{css('/static/css/products.css')}
<!-- Breadcrumbs from repository -->
@{if R.breadcrumbs}
<nav class="breadcrumbs">
@{foreach crumb in R.breadcrumbs}
@{if crumb.url}
<a href="@{crumb.url}">@{crumb.name}</a> /
@{else}
<span>@{crumb.name}</span>
@{fi}
@{end}
</nav>
@{fi}
<div class="products-page view-@{R.view_mode}">
<h1>@{R.title}</h1>
<!-- Filters from repository -->
@{if R.filters_available}
<div class="filters">
@{foreach filter in R.filters_available}
<button class="filter-btn">Filter by @{filter}</button>
@{end}
</div>
@{fi}
<!-- User preferences from repository -->
<div class="preferences">
Currency: @{R.user_preferences.currency}
@{if R.user_preferences.show_tax}
<small>(Prices include tax)</small>
@{fi}
</div>
<!-- Conditional rendering -->
@{if R.featured}
<div class="featured-banner">
<p>Check out our featured products!</p>
</div>
@{fi}
<!-- Loop through products -->
<div class="product-grid">
@{foreach product in R.products}
<div class="product-card">
<h3>@{product.name}</h3>
<p class="price">@{format_price(product.price)}</p>
<a href="@{root}/products/@{product.id}" class="btn">
View Details
</a>
</div>
@{end}
</div>
<!-- Reviews section if enabled -->
@{if R.show_reviews}
<div class="reviews-section">
<h2>Customer Reviews</h2>
<!-- Reviews content -->
</div>
@{fi}
<!-- Related products -->
@{if R.related_products_count > 0}
<div class="related">
<p>See @{R.related_products_count} related products</p>
</div>
@{fi}
<!-- Raw HTML inclusion -->
@{if marketing_content}
@{!marketing_content}
@{fi}
</div>
<!-- Footer with global repository data -->
<footer>
<p>@{APP.site_name} v@{APP.version}</p>
<p>@{MAIN.copyright}</p>
<p>Contact: @{APP.contact_email}</p>
</footer>
<!-- Page specific JS -->
@{js('/static/js/products.js')}
This documentation provides a complete guide to using the RustF view system with practical examples and best practices for the Total.js template engine (the only supported engine).