Crate ructe

source ·
Expand description

Rust Compiled Templates is a HTML template system for Rust.

Ructe works by converting your templates (and static files) to rust source code, which is then compiled with your project. This has the benefits that:

  1. Many syntactical and logical errors in templates are caught compile-time, rather than in a running server.
  2. No extra latency on the first request, since the templates are fully compiled before starting the program.
  3. The template files does not have to be distributed / installed. Templates (and static assets) are included in the compiled program, which can be a single binary.

The template syntax, which is inspired by Twirl, the Scala-based template engine in Play framework, is documented in the Template_syntax module. A sample template may look like this:

@use any::rust::Type;

@(name: &str, items: &[Type])

<html>
  <head><title>@name</title></head>
  <body>
    @if items.is_empty() {
      <p>There are no items.</p>
    } else {
      <p>There are @items.len() items.</p>
      <ul>
      @for item in items {
        <li>@item</li>
      }
      </ul>
    }
  <body>
</html>

There are some examples in the repository. There is also a separate example of using ructe with warp and diesel.

To be able to use this template in your rust code, you need a build.rs that transpiles the template to rust code. A minimal such build script looks like the following. See the Ructe struct documentation for details.

use ructe::{Result, Ructe};

fn main() -> Result<()> {
    Ructe::from_env()?.compile_templates("templates")
}

When calling a template, the arguments declared in the template will be prepended by a Write argument to write the output to. It can be a Vec<u8> as a buffer or for testing, or an actual output destination. The return value of a template is std::io::Result<()>, which should be Ok(()) unless writing to the destination fails.

#[test]
fn test_hello() {
    let mut buf = Vec::new();
    templates::hello_html(&mut buf, "World").unwrap();
    assert_eq!(buf, b"<h1>Hello World!</h1>\n");
}

§Optional features

Ructe has some options that can be enabled from Cargo.toml.

  • sass – Compile sass and include the compiled css as static assets.
  • mime03 – Static files know their mime types, compatible with version 0.3.x of the mime crate.
  • mime02 – Static files know their mime types, compatible with version 0.2.x of the mime crate.
  • warp03 – Provide an extension to Response::Builder of the warp framework (versions 0.3.x) to simplify template rendering.
  • http-types – Static files know their mime types, compatible with the http-types crate.
  • tide013, tide014, tide015, tide016 – Support for the tide framework version 0.13.x through 0.16.x. Implies the http-types feature (but does not require a direct http-types requirement, as that is reexported by tide). (these versions of tide is compatible enough that the features are actually just aliases for the first one, but a future tide version may require a modified feature.)

The mime02, mime03, and http-types features are mutually exclusive and requires a dependency on a matching version of mime or http-types. Any of them can be combined with the sass feature.

build = "src/build.rs"

[build-dependencies]
ructe = { version = "0.6.0", features = ["sass", "mime03"] }

[dependencies]
mime = "0.3.13"

Modules§

  • Template_syntax
    This module describes the template syntax used by ructe.
  • templates
    The module containing your generated template code will also contain everything from here.

Structs§

  • Ructe
    The main build-time interface of ructe.
  • StaticFiles
    Handler for static files.

Enums§

Type Aliases§