_Hatmil_ is an HTML builder for Rust. It can be used to create or modify web
pages dynamically, including [inline SVG].
With a [Tree], there are two "root" methods:
- [html] for a full document, including `DOCTYPE` declaration
- [root] for a snippet, starting from any root [element] (HTML or [SVG])
In either case, an element struct is returned which borrows from the `Tree`.
Each element has methods for setting valid attributes, such as `id`. There
are also methods for adding permitted child elements.
```rust
use hatmil::Tree;
let mut tree = Tree::new();
let mut html = tree.html();
let mut body = html.body();
body.p().id("para").cdata("Graph");
assert_eq!(
String::from(tree),
"<!DOCTYPE html><html><body><p id=\"para\">Graph</p></body></html>"
);
```
Text content (_character data_) can be added using the `cdata` or `cdata_len`
methods on an [element]. Special HTML characters will automatically be
replaced by [character reference]s, as needed (for content which has already
been escaped, use the [raw] method). The [close] method can be used to close
the final open element.
After creating the tree, use `String::from(tree)` to get the resulting HTML.
Any open tags will be closed automatically. [Display] is also implemented,
enabling the use of [format] or `to_string()`.
```rust
use hatmil::{Tree, html::Div};
let mut tree = Tree::new();
let mut div = tree.root::<Div>();
div.button().class("rounded").cdata("Press Me!");
assert_eq!(
String::from(tree),
"<div><button class=\"rounded\">Press Me!</button></div>"
);
```
## Method Names
In most cases, element methods match the HTML tag exactly. But due to clashes
with attribute names, some methods for creating child elements have an `_el`
suffix:
- `abbr_el` on [Th], clash with `abbr` attribute
- `cite_el` on [BlockQuote] and [Q], clash with `cite` attribute
- `form_el` on [FieldSet], clash with `form` attribute
- `slot_el` on many [element]s, clash with `slot` global attribute
- `style_el` on [Head], [NoScript] and [SVG] elements, clash with `style`
global attribute
- `title_el` on [Head] and [SVG Style], clash with `title` global attribute
Some HTML names clash with Rust keywords. In these cases, [raw identifiers]
must be used to call those methods:
- `r#as` on [Link]
- `r#async` on [Script]
- `r#for` on [Label] and [Output]
- `r#in` on multiple SVG filter elements
- `r#loop` on [Audio] and [Video]
- `r#type` on multiple HTML and [SVG] elements
- `r#use` (SVG element)
[Audio]: https://docs.rs/hatmil/latest/hatmil/html/struct.Audio.html
[BlockQuote]: https://docs.rs/hatmil/latest/hatmil/html/struct.BlockQuote.html
[cdata]: https://docs.rs/hatmil/latest/hatmil/struct.Tree.html#method.cdata
[cdata_len]: https://docs.rs/hatmil/latest/hatmil/struct.Tree.html#method.cdata_len
[character reference]: https://developer.mozilla.org/en-US/docs/Glossary/Character_reference
[close]: https://docs.rs/hatmil/latest/hatmil/struct.Tree.html#method.close
[Display]: https://doc.rust-lang.org/std/fmt/trait.Display.html
[element]: https://docs.rs/hatmil/latest/hatmil/html/
[FieldSet]: https://docs.rs/hatmil/latest/hatmil/html/struct.FieldSet.html
[format]: https://doc.rust-lang.org/std/macro.format.html
[root]: https://docs.rs/hatmil/latest/hatmil/struct.Tree.html#method.root
[Head]: https://docs.rs/hatmil/latest/hatmil/html/struct.Head.html
[html]: https://docs.rs/hatmil/latest/hatmil/struct.Tree.html#method.html
[inline SVG]: https://developer.mozilla.org/en-US/docs/Web/SVG/Guides/SVG_in_HTML
[Label]: https://docs.rs/hatmil/latest/hatmil/html/struct.Label.html
[Link]: https://docs.rs/hatmil/latest/hatmil/html/struct.Link.html
[NoScript]: https://docs.rs/hatmil/latest/hatmil/html/struct.NoScript.html
[Output]: https://docs.rs/hatmil/latest/hatmil/html/struct.Output.html
[tree]: https://docs.rs/hatmil/latest/hatmil/struct.Tree.html
[Q]: https://docs.rs/hatmil/latest/hatmil/html/struct.Q.html
[raw]: https://docs.rs/hatmil/latest/hatmil/struct.Tree.html#method.raw
[raw identifiers]: https://doc.rust-lang.org/rust-by-example/compatibility/raw_identifiers.html
[Script]: https://docs.rs/hatmil/latest/hatmil/html/struct.Script.html
[SVG]: https://docs.rs/hatmil/latest/hatmil/svg/
[SVG Style]: https://docs.rs/hatmil/latest/hatmil/svg/struct.Style.html
[Th]: https://docs.rs/hatmil/latest/hatmil/html/struct.Th.html
[Video]: https://docs.rs/hatmil/latest/hatmil/html/struct.Video.html