Kogia-sima
parent
faa8e661f7
commit
03413d1bcc
|
|
@ -40,9 +40,9 @@ Define the template struct to be rendered:
|
|||
```rust
|
||||
#[derive(TemplateOnce)] // automatically implement `TemplateOnce` trait
|
||||
#[template(path = "hello.stpl")] // specify the path to template
|
||||
struct HelloTemplate<'a> {
|
||||
struct HelloTemplate {
|
||||
// data to be passed to the template
|
||||
messages: &'a [String],
|
||||
messages: Vec<String>,
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -51,7 +51,7 @@ And render the data with `render_once()` method.
|
|||
```rust
|
||||
fn main() {
|
||||
let ctx = HelloTemplate {
|
||||
messages: &[String::from("foo"), String::from("bar")];
|
||||
messages: vec![String::from("foo"), String::from("bar")];
|
||||
}
|
||||
|
||||
// Now render templates with given data
|
||||
|
|
|
|||
|
|
@ -11,3 +11,6 @@ sailfish-macros = "0.1.1"
|
|||
`sailfish` crate contains runtime for rendering contents, and `sailfish-macros` serves you derive macros to compile and import the template files.
|
||||
|
||||
These crates are separated so that Rust compiler can compile them independently. This separation makes your compilation faster!
|
||||
|
||||
!!! Warning
|
||||
Make sure that the `sailfish-macros` version is larger than `sailfish`, otherwise the compilation may fail.
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ If a key is specified in both configuration file and derive options, then the va
|
|||
|
||||
### Configuration file format
|
||||
|
||||
Configuration files are written in the YAML 1.2 format. The default configuration is described below.
|
||||
Configuration files are written in the YAML 1.2 format. Here is the default configuration.
|
||||
|
||||
```
|
||||
template_dir: "templates"
|
||||
|
|
|
|||
|
|
@ -0,0 +1,48 @@
|
|||
# Includes
|
||||
|
||||
You can also include another template inside templates using `include!` macro.
|
||||
|
||||
Consider the following example.
|
||||
|
||||
- `templates/header.stpl`
|
||||
|
||||
```html
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<meta name="format-detection" content="telephone=no">
|
||||
<link rel="icon" type="image/x-icon" href="favicon.ico">
|
||||
```
|
||||
|
||||
- `templates/index.stpl`
|
||||
|
||||
```html
|
||||
<html>
|
||||
<head>
|
||||
<% include!("./header.stpl"); %>
|
||||
</head>
|
||||
<body>
|
||||
Main contents
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
Then you can see the `header.stpl` is embedded in the output.
|
||||
|
||||
```html
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<meta name="format-detection" content="telephone=no">
|
||||
<link rel="icon" type="image/x-icon" href="favicon.ico">
|
||||
</head>
|
||||
<body>
|
||||
Main contents
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
Like [`std::include!`](https://doc.rust-lang.org/std/macro.include.html) macro in Rust, the provided path is interpreted as a relative path to the current template file.
|
||||
|
||||
!!! Warning
|
||||
The path format is platform-specific. You must use `\` character as a separator on Windows.
|
||||
|
|
@ -0,0 +1,72 @@
|
|||
# Tags
|
||||
|
||||
## Code block
|
||||
|
||||
You can write Rust statement inside `<% %>` tag.
|
||||
|
||||
```ejs
|
||||
<% let mut total = 0; %>
|
||||
<% for elem in arr.iter().filter(|e| e.is_valid()) { %>
|
||||
<% total += elem.value() as u64; %>
|
||||
<% dbg!(total); %>
|
||||
<% if total > 100 { break; } %>
|
||||
Printed until the total value exceeds 100.
|
||||
<% } %>
|
||||
```
|
||||
|
||||
!!! Note
|
||||
Make sure that you cannot omit braces, parenthesis, and semicolons.
|
||||
|
||||
Sailfish is smart enough to figure out where the code block ends, so you can even include `%>` inside Rust comments or string literals.
|
||||
|
||||
```text
|
||||
<% /* Tag does not ends at %>! */ %>
|
||||
```
|
||||
|
||||
If you need to simply render `<%` character, you can escape it, or use evaluation block (described below).
|
||||
|
||||
```text
|
||||
<%% is converted into <%= "<%" %> character.
|
||||
```
|
||||
|
||||
Although almost all Rust statement is supported, the following statements inside templates may cause a strange compilation error.
|
||||
|
||||
- Function/Macro definition that render some contents
|
||||
- `impl` item
|
||||
- Macro call which defines some local variable.
|
||||
- Macro call which behaviour depends on the path to source file
|
||||
- Generator expression (yield)
|
||||
|
||||
## Evaluation block
|
||||
|
||||
Rust expression inside `<%= %>` tag is evaluated and the result will be rendered.
|
||||
|
||||
```ejs
|
||||
<%# The following code simple renders `3` %>
|
||||
<% let a = 1; %><%= a + 2 %>
|
||||
```
|
||||
|
||||
If the result contains `&"'<>` characters, sailfish replaces these characters with the equivalent html.
|
||||
|
||||
If you want to render the results without escaping, you can use `<%- %>` tag or [configure sailfish to not escape by default](../options.md). For example,
|
||||
|
||||
```ejs
|
||||
<div>
|
||||
<%- "<h1>Hello, World!</h1>" %>
|
||||
</div>
|
||||
```
|
||||
|
||||
This template results in the following output.
|
||||
|
||||
```ejs
|
||||
<div>
|
||||
<h1>Hello, World!</h1>
|
||||
</div>
|
||||
```
|
||||
|
||||
!!! Note
|
||||
Evaluation block does not return any value, so you cannot use the block to pass the render result to another code block. The following code is invalid.
|
||||
|
||||
```
|
||||
<% let result = %><%= 1 %><% ; %>
|
||||
```
|
||||
|
|
@ -27,6 +27,7 @@ theme:
|
|||
|
||||
# Extensions
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
- codehilite
|
||||
- footnotes
|
||||
|
||||
|
|
@ -47,3 +48,5 @@ nav:
|
|||
- 'Configuration': 'options.md'
|
||||
- 'Syntax':
|
||||
- 'Overview': 'syntax/overview.md'
|
||||
- 'Tags': 'syntax/tags.md'
|
||||
- 'Includes': 'syntax/includes.md'
|
||||
|
|
|
|||
Loading…
Reference in New Issue