#html #html-css #generate-html #macro #safe #expansion #rcss

rtml

(r)ust macros for h(tml) expansion => rtml. (r)ust type safe (css) => rcss

21 releases (breaking)

0.17.0 Feb 26, 2023
0.15.0 Feb 5, 2023
0.3.2 Dec 30, 2022

#928 in Rust patterns

Download history 55/week @ 2024-06-30 197/week @ 2024-07-28 145/week @ 2024-09-22

145 downloads per month

Custom license

130KB
3K SLoC

rtml

description

(r)ust macros for h(tml) expansion => rtml

(r)ust type safe (css) => rcss

usage

fn main() {
    use rtml::*;
    // Use the macros to generate some HTML
    let document = html! {
        .lang = "en",
            head!{
                title!{
                    "Title of the document"
                }
            },
            body!{
                    div!{
                        "text",
                        h1!{
                            "This is a heading"
                        },
                        p!{
                            "This is a paragraph"
                        }
                    }
            }
    }.render();

    println!("{}", document);
}

the output html will be in non pretty form. But equivalent to:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Page Title</title>
  </head>
<body>

<div>
  text
  <h1>This is a Heading</h1>
  <p>This is a paragraph.</p>
</div>

</body>
</html> 

When there are attributes, they go first, before adding any inner nested html.

div!{ .style="background-color: red;" }

call render() when the html needs to be built.

Getting Started

Install the latest version of the rtml crate into your project

use either specific tags you plan to use or reference all tags by adding this use statement.

  use rtml::p;  
  // or 
  use rtml::*;

CSS

Rtml also supports type safe css.

fn main() {
    use rtml::*;
    // Use the macros to generate some CSS
    let css = css! {
      p {
        background: "yellow",
        color: "red"
      }
    }.render();

    println!("{}", css);
}

The major difference between real inline css and rcss is that values are in strings. Another difference is that properties are split on commas , instead of semicolons ;

At-rules and Functions are not yet implemented.

Type Safe HTML Attributes

rtml allows an additional layer of type safety with tag use. For example,

a! { .href="/documents", My Documents }
<a href="/documents">My Documents</a>

Is the correct attribute allowed on the a tag. If you were not familiar, you might try to use the src attribute which is invalid. Most other website building projects would not prevent incompatible attribute use.

In rtml, there is a helpful error.

a! { .src="/documents", My Documents }
<a src="/documents">My Documents</a>
the trait bound `src: ACompat` is not satisified
the following other types implement the trait `ACompat`:
accesskey
class
contenteditable
dir
download
draggable
hidden
href
and 13 others

Breaking this error down,

the trait bound src: ACompat...

  • src : is the name of the attribute attempting to be used
  • ACompat : is the trait that would need to be implemented, every tag has their own version. Such as DivCompat and StyleCompat
  • accesskey class contenteditable : are a few of the attributes supported, Rust lists them in alphabetical order and therefore will not show all

Special Characters

rtml and rcss use structs and traits behind the scene, to ensure maximum type safety. Because of that, there are some special caveats due to rust having a few shared keywords between itself and rtml. The - character is not allowed in identifiers. So replace all - with an underscore _. Example: -webkit-line-clamp use _webkit_line_clamp

keyword rtml
as _as
type _type
kind _kind
for _for
loop _loop
where _where
async _async

Components

not implemented yet

Dependencies