Crate ructe

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:

Many syntactical and logical errors in templates are caught compile-time, rather than in a running server.
No extra latency on the first request, since the templates are fully compiled before starting the program.
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>

§Getting started

The aim of ructe is to have your templates and static files accessible to your rust code as a module. Since this module will be generated code it will live outside of your src directory, so instead of just use templates, you will need to include it like this:

include!(concat!(env!("OUT_DIR"), "/templates.rs"));

For this to work, you need to tell cargo to build the code. First, specify a build script and ructe as a build dependency in Cargo.toml:

build = "src/build.rs"

[build-dependencies]
ructe = "0.6.0"

Then, in build.rs, compile all templates found in the templates directory and put the output where cargo tells it to:

use ructe::{Result, Ructe};

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

See the docs of the struct Ructe for details about e.g. adding static files.

Now, after putting templates in the templates directory, you should be able to render them. A template file named hello.rs.html becomes a function called hello_html in the templates module.

let mut buf = Vec::new();
templates::hello_html(&mut buf, "World").unwrap();
assert_eq!(buf, b"<h1>Hello World!</h1>\n");

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

§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.
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 dependency, 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 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§

RucteError: The build-time error type for Ructe.

Type Aliases§

Result: A result where the error type is a RucteError.