erst 0.3.0

Embedded Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

# erst


[![Docs](https://docs.rs/erst/badge.svg)](https://docs.rs/crate/erst/)
[![Crates.io](https://img.shields.io/crates/v/erst.svg)](https://crates.io/crates/erst)

A small library for creating string templates, similar to [eRuby](https://ruby-doc.org/stdlib/libdoc/erb/rdoc/ERB.html)
and [JSP](https://en.wikipedia.org/wiki/JavaServer_Pages) (uses angle-bracket-percent tags: `<%= expr %>`).

Templates are precompiled for speed and safety, though partial dynamic rendering is provided when the `dynamic` flag is
enabled (some setup is required).

## Usage

```rust
use erst::Template;

#[derive(Template)]
#[template(path = "simple.erst", type = "html")]
pub struct Container<'a> {
    pub collection: Vec<&'a str>,
}

fn main() {
    println!("{}", Container { collection: vec!["Hello", "<>", "World"] });
}
```

Where `simple.erst` looks like:

```rust
<div>
    <p>Hello!</p>
    <%
        let desc = format!("Here is your list of {} items:", self.collection.len());
    -%>
    <p><%= desc %></p>
    <ul>
        <% for x in &self.collection { -%>
            <li><%= x %></li>
        <%- } %>
    </ul>
</div>
```

By default, the template's `path` will resolve to a file inside a `templates` directory in the current project context
(i.e., `CARGO_MANIFEST_DIR`). If you need to change this, you can set the `ERST_TEMPLATES_DIR` env variable to the
appropriate path. Note that this is only a concern when building; since the templates are compiled into your binary,
you don't need this structure/environment variables when running a compiled binary.

Note that, unlike `Askama` and many other template systems, you need to reference any members of your `Template` item
with `self` inside the template file. The template file is basically the body of a function that takes `&self`
(where `self` is the linked `Container` object).

Note that, like Askama and other precompiled template systems, you can reference any item (structs, functions, etc.)
available in your crate.

Currently, only the `html` type (or none) is supported, with very basic HTML escaping. To unescape HTML content in your
template file, wrap the content in [Raw](struct.Raw.html), e.g.:

```rust
erst::Raw("<p>Hello</p>")
```

## Dynamic

This library also provides a way to avoiding (re-)compiling the static/non-Rust parts of your template.

To enable this feature, add the following to your `Cargo.toml`:

```toml
[dependencies]
erst = { version = "0.2", features = ["dynamic"] }

[build-dependencies]
erst = { version = "0.2", features = ["dynamic"] }
```

You must also install a helper binary, [erst-prepare](https://crates.io/crates/erst-prepare):

```rust
cargo install erst-prepare
```

erst-prepare is a small binary that copies the code part of your templates to `$XDG_CACHE_HOME`
so that the build script can re-run on changes only to the code part of your templates.

Then run your project like:

```rust
erst-prepare && cargo run
```

If you have a unique setup, you may need to use the `--pkg-name` and `--templates-dir` flags to `erst-prepare`:

```rust
erst-prepare --pkg-name my-project --templates-dir /path/to/your/templates/dir
```

If you are using `dynamic` and do not run `erst-prepare` before building, it is possible that
your templates will not render correctly.

Current version: 0.3.0

License: MIT