Skip to main content

Crate smeltery_mold

Crate smeltery_mold 

Source
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 })   @sparksScripts
  • loop has index (from 1), index0, first, last and count.
  • Inside a component only its props, slot (the body, already-safe HTML) and the named slots exist. Attribute names with - become _ (data-id is data_id); :attr values are expressions, plain values are strings.
  • A line holding only a block directive (@if, @else, @endfor, @section, …) is dropped with its line break.
  • An @word that is not a Mold directive stays text, and an @ right after an ASCII letter, digit or _ never starts a directive, so CSS @media and e-mail addresses (me@auth.example) need no escaping. Write x @endif, not x@endif. Inside a block that takes it, a glued x@else, x@elseif(…) or x@empty followed by a space, a line break or ( is an error (as text it would merge the block’s branches); x@@else writes 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 stat per 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 Host with no request: no token, nobody signed in, no errors, no old input.
ValueError
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, @alloyHead and @vite.
Template
A template bound to its data, usually through #[derive(Mold)].

Functions§

set_global_views_dir
Sets the views directory of Engine::global. Returns false when it was already set or the global engine is already in use.
to_value
Converts any T: Serialize into a Value.
views_dir
The app’s views directory: the one given to set_global_views_dir, else $SMELTERY_ROOT/resources/views, else ./resources/views.