maud/docs/content/elements-attributes.md
Chris Wong dc6c88fae3
Disallow slashes (/) in void elements ()
# Overview

The following syntax will no longer work:

```rust
html! {
    br /
    link rel="stylesheet" href="styles.css" /
}
```

This should be changed to the following:

```rust
html! {
    br;
    link rel="stylesheet" href="styles.css";
}
```

# Rationale

The `;` syntax was introduced in ; the rationale for it can be found there.

Removing support for the older `/` syntax will simplify the API surface, and allow for the space to be used for other things.
2021-11-07 23:17:15 +11:00

3.8 KiB
Raw Blame History

Elements and attributes

Elements with contents: p {}

Write an element using curly braces:

# let _ = maud::
html! {
    h1 { "Poem" }
    p {
        strong { "Rock," }
        " you are a rock."
    }
}
# ;

Void elements: br;

Terminate a void element using a semicolon:

# let _ = maud::
html! {
    link rel="stylesheet" href="poetry.css";
    p {
        "Rock, you are a rock."
        br;
        "Gray, you are gray,"
        br;
        "Like a rock, which you are."
        br;
        "Rock."
    }
}
# ;

The result will be rendered with HTML syntax <br> not <br />.

Custom elements and data attributes

Maud also supports elements and attributes with hyphens in them. This includes custom elements, data attributes, and ARIA annotations.

# let _ = maud::
html! {
    article data-index="12345" {
        h1 { "My blog" }
        tag-cloud { "pinkie pie pony cute" }
    }
}
# ;

Non-empty attributes: title="yay"

Add attributes using the syntax: attr="value". You can attach any number of attributes to an element. The values must be quoted: they are parsed as string literals.

# let _ = maud::
html! {
    ul {
        li {
            a href="about:blank" { "Apple Bloom" }
        }
        li class="lower-middle" {
            "Sweetie Belle"
        }
        li dir="rtl" {
            "Scootaloo "
            small { "(also a chicken)" }
        }
    }
}
# ;

Optional attributes: title=[Some("value")]

Add optional attributes to an element using attr=[value] syntax, with square brackets. These are only rendered if the value is Some<T>, and entirely omitted if the value is None.

# let _ = maud::
html! {
    p title=[Some("Good password")] { "Correct horse" }

    @let value = Some(42);
    input value=[value];

    @let title: Option<&str> = None;
    p title=[title] { "Battery staple" }
}
# ;

Empty attributes: checked

Declare an empty attribute by omitting the value.

# let _ = maud::
html! {
    form {
        input type="checkbox" name="cupcakes" checked;
        " "
        label for="cupcakes" { "Do you like cupcakes?" }
    }
}
# ;

Before version 0.22.2, Maud required a ? suffix on empty attributes: checked?. This is no longer necessary (#238), but still supported for backward compatibility.

Classes and IDs: .foo #bar

Add classes and IDs to an element using .foo and #bar syntax. You can chain multiple classes and IDs together, and mix and match them with other attributes:

# let _ = maud::
html! {
    input #cannon .big.scary.bright-red type="button" value="Launch Party Cannon";
}
# ;

In Rust 2021, the # symbol must be preceded by a space, to avoid conflicts with reserved syntax:

# let _ = maud::
html! {
    // Works on all Rust editions
    input #pinkie;

    // Works on Rust 2018 and older only
    input#pinkie;
}
# ;

The classes and IDs can be quoted. This is useful for names with numbers or symbols which otherwise wouldn't parse:

# let _ = maud::
html! {
    div."col-sm-2" { "Bootstrap column!" }
}
# ;

Implicit div elements

If the element name is omitted, but there is a class or ID, then it is assumed to be a div.

# let _ = maud::
html! {
    #main {
        "Main content!"
        .tip { "Storing food in a refrigerator can make it 20% cooler." }
    }
}
# ;