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
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
Askama
======
.. image:: https://travis-ci.org/djc/askama.svg?branch=master
:target: https://travis-ci.org/djc/askama
.. image:: https://codecov.io/gh/djc/askama/branch/master/graph/badge.svg
:target: https://codecov.io/gh/djc/askama
Askama implements a template rendering engine based on Jinja.
It generates Rust code from your templates at compile time
based on a user-defined ``struct`` to hold the template's context.
See below for an example, or read `the documentation`_.
Currently implemented features:
* Generates fully type-safe Rust code from your templates
* Template inheritance
* Basic loops and if/else if/else statements
* Whitespace suppressing with '-' markers
* Some built-in filters
Askama is in heavy development, so it currently has some limitations:
* Only a small number of built-in template filters have been implemented
* User-defined template filters are not supported yet
* Not a lot of documentation has been written
* Debugging template problems is not always straightforward
All feedback welcome. Feel free to file bugs, requests for documentation and
any other feedback to the `issue tracker`_ or `tweet me`_.
.. _the documentation: https://docs.rs/askama
.. _issue tracker: https://github.com/djc/askama/issues
.. _tweet me: https://twitter.com/djco/
How to get started
------------------
First, add the following to your crate's ``Cargo.toml``:
.. code-block:: toml
# in section [package]
build = "build.rs"
# in section [dependencies]
askama = "0.1"
askama_derive = "0.1"
# in section [build-dependencies]
askama = "0.1"
Custom derive macros can not be exported together with other items,
so you have to depend on a separate crate for it.
Because Askama will generate Rust code from your template files,
the crate will need to be recompiled when your templates change.
This is supported with a build script, ``build.rs``,
which needs askama as a build dependency:
.. code-block:: rust
extern crate askama;
fn main() {
askama::rerun_if_templates_changed();
}
Now create a directory called ``templates`` in your crate root.
In it, create a file called ``hello.html``, containing the following:
.. code-block:: jinja
Hello, {{ name }}!
In any Rust file inside your crate, add the following:
.. code-block:: rust
#[macro_use]
extern crate askama_derive; // for the custom derive implementation
extern crate askama; // for the Template trait
use askama::Template; // bring trait in scope
#[derive(Template)] // this will generate the code...
#[template(path = "hello.html")] // using the template in this path, relative
// to the templates dir in the crate root
struct HelloTemplate<'a> { // the name of the struct can be anything
name: &'a str, // the field name should match the variable name
// in your template
}
fn main() {
let hello = HelloTemplate { name: "world" }; // instantiate your struct
println!("{}", hello.render()); // then render it.
}
You should now be able to compile and run this code.
Review the `test cases`_ for more examples.
.. _test cases: https://github.com/djc/askama/tree/master/testing
Debugging and troubleshooting
-----------------------------
You can view the parse tree for a template as well as the generated code by
changing the ``template`` attribute item list for the template struct:
.. code-block:: rust
#[derive(Template)]
#[template(path = "hello.html", print = "all")]
struct HelloTemplate<'a> { ... }
The ``print`` key can take one of four values:
* ``none`` (the default value)
* ``ast`` (print the parse tree)
* ``code`` (print the generated code)
* ``all`` (print both parse tree and code)
The parse tree looks like this for the example template:
.. code-block::
[Lit("", "Hello,", " "), Expr(WS(false, false), Var("name")),
Lit("", "!", "\n")]
The generated code looks like this:
.. code-block:: rust
#[allow(dead_code, non_camel_case_types)]
type TemplateFromhello2ehtml<'a> = HelloTemplate<'a>;
impl<'a> askama::Template for HelloTemplate<'a> {
fn render_to(&self, writer: &mut std::fmt::Write) {
writer.write_str("Hello,").unwrap();
writer.write_str(" ").unwrap();
writer.write_fmt(format_args!("{}", self.name)).unwrap();
writer.write_str("!").unwrap();
writer.write_str("\n").unwrap();
}
}
|
