rust_wasm_dodrio_templating

html templating for dodrio
version: 1.0.3 date: 2021-01-13 author: bestia.dev repository: GitHub

crates.io Documentation crev reviews RustActions latest doc Licence

Lines in Rust code Lines in Doc comments Lines in Comments Lines in examples Lines in tests

Html templating

In the past I wrote html inside Rust code with the macro html! from the crate typed-html
https://github.com/bodil/typed-html
It has also a macro dodrio ! created exclusively for the dodrio vdom.
I had two main problems with this approach:

  1. Any change to the html required a recompiling. And that is very slow in Rust.
  2. I could not add new html elements, that the macro don't recognize. I wanted to use SVG. There was not support for that.

I reinvented the wheel - "html templating".
First a graphical designer makes a html/css page that looks nice. No javascript, nothing is dynamic. It is just a graphical template.
Then I insert in it html comments and "data-" attributes that I can later replace in my code.
The html is not changed graphically because of it. So both the graphical designer and the programmer are still happy.
In my code I parse the html template as a microXml file. Basically they are the same with small effort. When I find a comment or "data-" attribute then the value of the next node is replaced.
I can replace attributes, strings and entire nodes. And I can insert event for behavior with "data-wt".
When developing, the html template is loaded and parsed and a dodrio node is created. That is not very fast. But I can change the html in real time and see it rendered without compiling the Rust code. This is super efficient for development.
I have in plans to add a Rust code generator, that creates the Rust code for the dodrio node before compile time. In that case nothing is parsed in runtime and I expect great speeds. But the flexibility of easily changing the html template is gone. For every change I must recompile the Rust code.

Used in projects

https://github.com/bestia-dev/unforgettable7_game/

How to use it

Inside a perfectly working static html insert special comments and attributes to replace the next node or attribute.

Replace the next text node

Insert a comment that starts with "wt_" (webbrowser text).
After that is the name of the enum to replace in the fn replace_with_string().

<p><!--wt_new_text>old_text</p>

Replace the next node with nodes

Insert a comment that starts with "wn_" (webbrowser nodes).
After that is the name of the enum to replace in the fn replace_with_nodes().
The computed nodes can be complicated with a lot of html. If needed, this fragments of html are saved inside the html template as sub_templates.

<p><!--wn_new_nodes><div id="old_node">...</div></p>

Replace the next attribute text value

Insert an attribute that starts with "data-wt-" (webbrowser text).
The attribute name finishes in the name of the next attribute.
The attribute value is the enum to use in the fn replace_with_string().

<input data-wt-value="wt_new_text" value="old text" />

Set the event handler

Insert an attribute that starts with "data-on-".
The attribute name finishes in the name of the event to handle.
The attribute value is the enum to use in the fn set_event_listener().
The enum name must start with "wl_" (Webbrowser listener).

<input data-on-keyup="wl_nickname_on_keyup" />

Sub_templates

When a part of the html template needs to be repeated, we use sub_templates. A sub_template is inside the html template in the node <template>.

<template name="sub_template_name">
        <div>some html</div>
</template>

The sub_template has a name attribute that is used for replacement in Rust code to return a vector of nodes for replace the "wn_" special comment.

pub fn div_grid_all_items<'a>(
    rrc: &RootRenderingComponent,
    cx: &mut RenderContext<'a>,
) -> Vec<Node<'a>> {
    let mut vec_grid_items: Vec<Node<'a>> = Vec::new();
    for x in 1..=10 {
        let html_template = rrc.web_data.get_sub_template("sub_template_name");

        let grid_item = rrc.render_template(
            cx,
            &html_template,
            rust_wasm_dodrio_templating::html_template_mod::HtmlOrSvg::Html
        ).unwrap();
        vec_grid_items.push(grid_item_bump);
    }

    // return
    vec_grid_items
}

cargo crev reviews and advisory

It is recommended to always use cargo-crev
to verify the trustworthiness of each of your dependencies.
Please, spread this info.
On the web use this url to read crate reviews. Example:
https://web.crev.dev/rust-reviews/crate/num-traits/