Crate stpl [−] [src]
stpl - Super template library for Rust
stpl
is plain-Rust template library.
Main idea
In stpl
there are no magic macros or DSLs, and no clunky
text-files with weird syntax. Everything is just normal, easy
to understand Rust code.
Let's take a look at a real-life example from the pilot project:
pub fn base<C: Render + 'static>(data: &Data, content: C) -> impl Render { ( doctype("html"), html(( head(( meta.charset("utf-8"), meta.name("viewport").content("width=device-width, initial-scale=1, shrink-to-fit=no"), meta.name("description").content(""), meta.name("author").content("Dawid Ciężarkiewicz"), title(data.title.clone()), ( link.rel("icon").href("/static/favicon.ico"), link.rel("stylesheet").href("/static/theme/flatly/bootstrap.min.css"), link.rel("stylesheet").href("/static/theme/starter-template.css"), ) )), body(( navbar(data), main .id("main") .role("main") .class("container mb-5")( content, ), ( script.src("https://code.jquery.com/jquery-3.2.1.min.js").crossorigin("anonymous"), script.src("https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.3/umd/popper.min.js") .integrity("sha384-vFJXuSJphROIrBnz7yo7oB41mKfc8JzQZiCq4NCceLEaO4IHwicKwpJf9c9IpFgh") .crossorigin("anonymous"), script.src("https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-beta.2/js/bootstrap.min.js") .integrity("sha384-alpBpkh1PFOepccYVYDB4do5UnbKysX5WZXm3XxPqe5iKTfUKjNkCk9SaVuEZflJ") .crossorigin("anonymous"), script.type_("text/javascript")( raw(include_str!("white-icon.js")) ), ) )) )) ) }
The above is an HTML base-template. It contains base HTML skeleton of a Bootstrap-based UI.
It is just a function. There is no magic, no macros, no textfiles involved.
The whole template was formatted with rustfmt
just like a normal Rust code.
The function accepts arguments:
data: Data
containing information how to "fill the blanks", andcontent: Render
- sub-template value that will be used as main page content.
The function returns Render
value that can be rendered as a string or bytes, or
composed with other templates. The value is basically a one big tuple
nesting many other Render
values. Render
is implemented for many standard types,
can be implemented for new types or can be generated using functions/closures.
Users are free to use any Rust language primitives to generate their templates and structure relationship between them in any way that does suits them.
Dynamic rendering
While stpl
generates Rust code and does not invole "runtime parsing",
it supports doing the actual rendering in a
separate process, thus hot-swapping the templates at runtime. This is very
useful for speeding up development.
The basic mechanism is:
- serialize the template data, and send it to a child process
- read the rendered template back from the child
In the child process:
- identify the template to use,
- read the serialized data from the stdio and deserialize it
- render the template and output it to stdout
In this scheme the binary for parent and child processes can be the same
(see render_dynamic_self
) or different (see `render_dynamic).
Using the same binary is more convenient. Using separate binaries requires structuring the project in a certain way, but can greatly improve iteration time.
The following is an exerpt from Cargo.toml
to support dynamic
rendering in a separate binary:
[[bin]]
name = "template"
path = "src/main_template.rs"
[[bin]]
name = "webapp"
path = "src/main.rs"
These two programs share many modules (eg. templates and data structures),
but main_template
does not have to include any heavy-duty libraries like
rocket
, diesel
and similar, thus compiles much faster.
In our tests it takes 11.4 secs to build the main webapp in debug mode, while recompiling all templates is much faster:
$ cargo build --bin template Compiling communityaudit v0.1.0 (file:///home/dpc/lab/rust/hackeraudit/web) Finished dev [unoptimized + debuginfo] target(s) in 1.04 secs
Drawbacks
This library relies on some nightly
-only unstable features
Where to start
You are most probably interested in reading html
module documentation
Help
Please see ./playground
subdirectory for example usage.
Modules
html |
HTML rendering |
Structs
Fn |
Use to wrap closures with |
HandleDynamic |
|
RawRenderer |
A |
Enums
DynamicError |
Constants
EXIT_CODE_FAILED |
Exit code used by the dynamic template binary on failure |
EXIT_CODE_NOT_FOUND |
Exit code used by the deyamic template binary when template key was not found |
EXIT_CODE_SUCCESS |
Exit code used by the dynamic template binary on success |
Traits
Render |
A value that can be rendered - part or a whole template |
Renderer |
Rendering logic responsible for string escaping and such. |
Template |
A whole template that knows how to render itself |
TemplateExt |
Convinience methods for |
Functions
handle_dynamic | |
render_dynamic |
Call a template dynamically (with ability to update at runtime) |
render_dynamic_self |
Call current binary file to handle the template |