[][src]Crate ructe

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(&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.
  • mime02 -- Static files know their mime types, compatible with version 0.2.x of the mime crate.
  • mime03 -- Static files know their mime types, compatible with version 0.3.x of the mime crate.
  • warp -- Provide an extension to Response::Builder to simplify template rendering in the warp framework.

The mime02 and mime03 features are mutually exclusive and requires a dependency on a matching version of mime. 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

RucteError

The build-time error type for Ructe.

Type Definitions

Result

A result where the error type is a RucteError.