Crate el

Crate el 

Source
Expand description

§el

Write, modify, and safely render HTML elements as simple data structures.

This library is inspired by hiccup and named after a small helper function I once wrote in JS.

§Library overview

The basic data structure is the Element, which can be rendered to a String using the Render trait. Custom elements can be constructed using Element::normal or Element::new. Once constructed, elements can be modified by accessing their fields or using the Element::add or Element::with methods, though this is usually not necessary.

Constructor functions for all (non-deprecated) HTML tags can be found in the html module, SVG tags in svg and MathML tags in mathml. These three modules are designed to be wildcard-included for more concise code, either on a per-function or per-file basis.

Element construction uses the ElementComponent trait, which represents not only element contents but also attributes. Tuples, arrays, Vec, Option, and Result can be used to combine components. The order of content components is preserved. To set attributes, include Attr values as components.

If you want to render an entire web page, wrap an html::html element in a Document. When rendered, documents include the <!DOCTYPE html> annotation required by the standard.

§Usage example

use el::{Render, html::*};

let page: String = html((
    head((
        meta((
            attr::name("viewport"),
            attr::content("width=device-width, initial-scale=1"),
        )),
        title("Example page"),
    )),
    body((
        h1((attr::id("heading"), "Example page")),
        p(("This is an example for a ", em("simple"), " web page.")),
    )),
))
.into_document()
.render_to_string()
.unwrap();

§Axum support

The axum crate is supported via the optional axum feature flag. When it is enabled, Document implements axum’s IntoResponse trait and can be returned directly from handlers. In order to prevent accidentally returning incomplete HTML documents, Element does not implement IntoResponse.

[dependencies]
el = { version = "...", features = ["axum"] }

§But what about that small helper function?

See the readme for more details.

Modules§

html
Definitions for HTML elements and attributes (MDN).
mathml
Definitions for all non-deprecated MathML elements (MDN).
svg
Definitions for all non-deprecated SVG elements (MDN).

Structs§

Attr
An element attribute, used during Element construction.
Document
A full HTML document including doctype.
Element
An HTML element.
Error
An error that can occur during element rendering.

Enums§

Content
A single bit of Element content.
ElementKind
The kind of an element.
ErrorCause
The cause of an Error.

Traits§

ElementComponent
A component can add itself to an Element by modifying it.
Render
Render an Element or a Document to a fmt::Write; usually a String.

Type Aliases§

Result
A wrapper around std::result::Result with the error Error.