Expand description
§smeltery-mold
Mold is the template engine of Smeltery. Templates are
resources/views/<name>.mold.html files with an @-directive syntax. In debug builds they are interpreted and
reloaded when a file changes; in release builds #[derive(Mold)] (from smeltery-mold-macros) compiles them to
Rust. Both modes produce the same bytes for the same data.
Apps use Mold through the smeltery crate (smeltery::mold, #[derive(Mold)]).
§Syntax
{{ post.title }} escaped output
{!! post.html !!} raw output
{{-- a comment --}} dropped
@{{ literal }} @@ a literal "{{" and "@"
@if(user.admin) … @elseif(user.editor) … @else … @endif
@unless(posts) … @endunless
@for(post in posts) {{ loop.index }}/{{ loop.count }} … @empty No posts. @endfor
@for(key, value in settings) … @endfor
@for post in posts (to the end of the line)
@extends("layouts/app") @section("content") … @endsection @section("title", post.title)
@yield("content") @yield("title", "Default")
@include("partials/nav") @include("partials/nav", { user: user, active: "home" })
<x-alert type="error" :count="errors | len">Body</x-alert> renders components/alert
<x-forms.input name="email" /> renders components/forms/input
@slot("title") … @endslot a named slot inside a component body
@csrf @method("PUT") @error("title") {{ message }} @enderror
@auth … @else … @endauth @guest … @endguest
@spark("counter", { start: 5 }) @sparksScriptsloophasindex(from 1),index0,first,lastandcount.- Inside a component only its props,
slot(the body, already-safe HTML) and the named slots exist. Attribute names with-become_(data-idisdata_id);:attrvalues are expressions, plain values are strings. - A line holding only a block directive (
@if,@else,@endfor,@section, …) is dropped with its line break. - An
@wordthat is not a Mold directive stays text, and an@right after an ASCII letter, digit or_never starts a directive, so CSS@mediaand e-mail addresses (me@auth.example) need no escaping. Writex @endif, notx@endif. Inside a block that takes it, a gluedx@else,x@elseif(…)orx@emptyfollowed by a space, a line break or(is an error (as text it would merge the block’s branches);x@@elsewrites the text.
Expressions: ||, &&, == != < <= > >=, + - * / %, !, unary -, a.b, a[i], literals (1, 1.5,
"text", 'text', true, false, null), parentheses, filters
upper lower trim title len default(x) join(sep) json url (name | upper, tags | join(", ")) and the functions old("field"), session("status"),
route("posts.show", { post: post.id }) and csrf_token().
{{ }} escapes & < > " ' for text and quoted attribute values. json writes a value as a JavaScript literal with
<, >, &, ', U+2028 and U+2029 escaped: {{ v | json }} in attributes that run JavaScript (x-data,
@click, onclick), {!! v | json !!} inside <script>. url keeps relative, http, https, mailto and
tel URLs and writes # for any other (javascript:) and for an &, byte-order mark or control character before
the first /, ? or #. {!! !!} never goes into an attribute (it writes " as it is).
Values: false, 0, 0.0, "", empty lists and maps, and None are falsy. Integer arithmetic stays integer
(overflow and division by zero are errors); a float operand makes a float; + joins two strings.
§Runtime engine
use smeltery_mold::{Engine, NoHost, to_value};
#[derive(serde::Serialize)]
struct Page {
title: String,
}
let engine = Engine::new("resources/views");
let data = to_value(&Page { title: "Hello".into() })?;
let html = engine.render("pages/home", &data, &NoHost)?;Errors name the file, line and column (resources/views/pages/home.mold.html:3:7: unknown variable titel``) and
carry a source excerpt; Error::to_html renders a development error page.
§License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Structs§
- Engine
- The runtime template engine: parses, resolves and caches templates from a views directory, and re-reads them
when a file they were built from changes (a
statper file per render, no watcher thread). - Error
- A Mold error: where it happened (
file:line:col), what went wrong and a source excerpt. - NoHost
- A
Hostwith no request: no token, nobody signed in, no errors, no old input. - Value
Error - Why a value could not be converted with
to_value.
Enums§
- Value
- A dynamic value: what template data becomes in runtime mode.
Traits§
- Host
- Request data a template can reach:
@csrf,@auth/@guest,@error,old(),route(),@spark,@sparksScripts,@alloy,@alloyHeadand@vite. - Template
- A template bound to its data, usually through
#[derive(Mold)].
Functions§
- set_
global_ views_ dir - Sets the views directory of
Engine::global. Returnsfalsewhen it was already set or the global engine is already in use. - to_
value - Converts any
T: Serializeinto aValue. - views_
dir - The app’s views directory: the one given to
set_global_views_dir, else$SMELTERY_ROOT/resources/views, else./resources/views.