build_html

Crates.io	build_html
lib.rs	build_html
version	2.5.0
source	src
created_at	2021-01-24 20:02:18.741602
updated_at	2024-07-02 01:42:28.612357
description	Library for basic server-side rendering written in pure rust
homepage
repository	https://github.com/skubalj/build_html
max_upload_size
id	346142
size	113,623

Joseph Skubal (skubalj)

documentation

README

build_html: Rust HTML Generation

This crate allows HTML strings to be generated from within Rust code using the Builder pattern. Calls to add elements are repeatedly chained together to build up an HTML document. The struct is then flushed to a string which can be used elsewhere in your program.

The strings generated by this library are unformatted, but are not explicitly minimized. Whitespace passed into a string will generally be preserved. Note that escaping strings is also not automatic, although a function to do so is provided.

This crate is written in purely safe Rust with no production dependencies.

use build_html::{HtmlElement, HtmlTag, Html};

let element = HtmlElement::new(HtmlTag::Div)
    .with_child(
        HtmlElement::new(HtmlTag::ParagraphText)
            .with_child("Paragraph Text".into())
            .into()
    )
    .with_child(
        HtmlElement::new(HtmlTag::PreformattedText)
            .with_child("Preformatted Text".into())
            .into()
    )
    .to_html_string();

assert_eq!(element, "<div><p>Paragraph Text</p><pre>Preformatted Text</pre></div>");

The primary intention of this library is to provide an easy way to build dynamic elements that can be injected into an HTML page or framework that is written in its own file. The advantage to this is that it allows you to write the majority of your HTML with modern editor features such as linting and syntax highlighting. You can use the standard library's include_str! macro to "import" your html file and the format! macro to "inject" your new element.

However, if your page is very simple or the entire page is dynamic, you may want to create the entire thing from within your Rust code. To meet this use case, the library provides the HtmlPage struct. This struct implements the HtmlContainer interface, which can be used to easily add body content.

use build_html::{HtmlPage, Html, HtmlContainer};

let page = HtmlPage::new()
    .with_title("TITLE")
    .with_paragraph("PARAGRAPH")
    .to_html_string();

assert_eq!(page, concat!(
    "<!DOCTYPE html><html>",
    "<head><title>TITLE</title></head>",
    "<body><p>PARAGRAPH</p></body>",
    "</html>"
));

A More Complicated Example

use build_html::*;

let html: String = HtmlPage::new()
    .with_title("My Page")
    .with_header(1, "Main Content:")
    .with_html(
        HtmlElement::new(HtmlTag::Article)
            .with_attribute("id", "article1")
            .with_header_attr(2, "Hello, World", [("id", "article-head"), ("class", "header")])
            .with_paragraph("This is a simple HTML demo")
    )
    .to_html_string();

produces a string equivalent to:

<!DOCTYPE html>
<html>
    <head>
        <title>My Page</title>
    </head>
    <body>
        <h1>Main Content:</h1>
        <article id="article1">
            <h2 id="article-head" class="header">Hello World</h2>
            <p>This is a simple HTML demo</p>
        </article>
    </body>
</html>

If you are trying to create a more complicated document, you may find it easier to create a template from outside of Rust and build it into the binary with the include_str!() macro. Then, you can generate the parts that need to be dynamically created with build_html and insert them with the format!() macro.

Contributing

If you have an idea for making this library better, feel free to open an issue or pull request on GitHub! I try to respond within a reasonable amount of time, but please keep in mind that maintaining this library is not my full time job.

Acknowledgment

This project was made possible thanks to the following great projects:

Rust

License

This project is licensed under the MIT license.

Commit count: 81