RsHtml

https://rshtml.github.io
Admin
RsHtml is a compile-time, type-safe template engine for Rust that seamlessly integrates Rust code...
Tokens:6,310
Snippets:72
Trust Score:8.3
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install RsHtml Language Server via Cargo

Source: https://rshtml.github.io/index

Installs the RsHtml language server using the Cargo package manager. This is necessary for editor integration and provides features like autocompletion and error checking. Ensure you have Rust and Cargo installed.

```bash
cargo install --git https://github.com/rshtml/rshtml-analyzer.git --tag v0.1.5
```

--------------------------------

### RsHtml Component Definition Example

Source: https://rshtml.github.io/index

Provides an example of a reusable RsHtml component (`Card.rs.html`) that accepts a 'title' prop and renders child content. It encapsulates markup and logic for a card UI element.

```html
@* This component expects a 'title' parameter. *@
<div class="card">
    <div class="card-header">
        @title @* title prop rendered here. *@
    </div>
    <div class="card-body">
        @* Any content passed to the component will be rendered here. *@
        @child_content 
    </div>
</div>

```

--------------------------------

### RsHtml Simple Expressions

Source: https://rshtml.github.io/index

Demonstrates the usage of simple expressions in RsHtml, which start with the `@` symbol. These are evaluated at render time and can include variable access, function calls, or field lookups. Rust's ownership rules apply.

```html
<h1>Welcome, @self.username</h1>
<p>You have @self.items.len() items.</p>

```

--------------------------------

### Configure RsHtml Language Support in Helix

Source: https://rshtml.github.io/index

Sets up RsHtml language support in the Helix editor by configuring the `languages.toml` file. This includes specifying file types, language servers, and grammar sources. Requires `rshtml-analyzer` and `vscode-html-language-server` to be installed.

```toml
[[language]]
name = "rshtml"
file-types = [{ glob = "*.rs.html" }]
scope = "source.rshtml"
language-servers = [
  "rshtml-analyzer",
  "vscode-html-language-server",
  "superhtml",
]
grammar = "rshtml"
roots = ["Cargo.lock", "Cargo.toml"]
block-comment-tokens = { start = "@*", end = "*@" }
indent = { tab-width = 2, unit = "  " }

[language-server.rshtml-analyzer]
command = "rshtml-analyzer"
args = ["--stdio"]

[[grammar]]
name = "rshtml"
source = { git = "https://github.com/rshtml/tree-sitter-rshtml", rev = "8379a7d67c67fca21d5a45c4329eb2f61743417e" }
```

--------------------------------

### Using RsHtml Components

Source: https://rshtml.github.io/index

Demonstrates how to use RsHtml components, including self-closing tags and components with child content. Component names must follow PascalCase. Components are included using the @use directive.

```RsHtml
@use "components/Alert.rs.html"

@* A self-closing component with a 'message' attribute *@
<Alert message="This is a warning."/>

@* A component with nested child content *@
<Alert message="Operation successful!">
    <p>Your data was saved correctly.</p>
    <a href="/home">Go back</a>
</Alert>
```

--------------------------------

### Import RsHtml Components with Aliases

Source: https://rshtml.github.io/index

Demonstrates how to import RsHtml components using the @use directive. It shows importing with a custom alias (`as ComponentName`) and using the default file name as the alias. The `.rs.html` extension is optional.

```html
@* Import with a custom alias *@
@use "components/Card.rs.html" as Card

@* Import using the default name (will be available as 'Alert') *@
@use "components/Alert.rs.html"

@* It can also be used without the rs.html extension and the extension is added automatically. *@
@use "components/Alert"
@use "components/Alert" as Alert

```

--------------------------------

### Track Template Changes with build.rs

Source: https://rshtml.github.io/index

Set up a `build.rs` file to automatically recompile your project when template files are modified. This ensures changes are reflected without requiring a full `cargo clean`.

```rust
use rshtml::track_views_folder;

fn main() {
    // This function tells cargo to re-run the build script if
    // any file inside the configured views directory changes.
    track_views_folder();
}
```

--------------------------------

### Render RsHtml Template

Source: https://rshtml.github.io/index

Render an RsHtml template by creating an instance of your struct and calling the `.render()` method. This method returns a `Result<String, std::fmt::Error>` containing the generated HTML.

```rust
fn main() {
    let page = HomePage {
        title: "RsHtml".to_string(),
        items: vec!["Item 1".to_string(), "Item 2".to_string()],
    };

    let html_output = page.render().unwrap();
    println!("{}", html_output);
}
```

--------------------------------

### Importing RsHtml Functions in Rust

Source: https://rshtml.github.io/index

Demonstrates how to import the necessary RsHtml functions and traits into your Rust code to use them within templates.

```rust
use rshtml::{RsHtml, functions::*, traits::RsHtml};
```

--------------------------------

### Formatting Dates with RsHtml time() Helper

Source: https://rshtml.github.io/index

Shows how to use the `time()` helper function in RsHtml to convert date/time values into a `RsDateTime` object for formatting. Includes default formatting, `.pretty()` for human-readable output, and `.format()` for custom specifications.

```RsHtml
<p>Published on: @time(&self.post_created_at)</p>

<p>Published on: @time(&self.post_created_at).pretty()</p>

<p>Published on: @time(&self.post_created_at).format("%A, %B %e, %Y")</p>
```

--------------------------------

### RsHtml Layout Inheritance with @extends

Source: https://rshtml.github.io/index

Explains the @extends directive for applying layouts to RsHtml templates. It can be used to specify a particular layout file or to use the project's default layout, and must be the first statement in the template.

```rshtml
@extends("layout.rs.html")

```

--------------------------------

### Enabling RsHtml Functions Feature

Source: https://rshtml.github.io/index

Shows how to enable the 'functions' feature for RsHtml in Cargo.toml, which provides access to built-in helper functions.

```toml
rshtml = { version = "*", features = ["functions"] }
```

--------------------------------

### RsHtml Template Inclusion with @include

Source: https://rshtml.github.io/index

Demonstrates the @include directive for organizing templates by inserting the content of one RsHtml file into another. This facilitates code reuse and modular template design.

```rshtml
<div>
    <p>this is home page, @self.value</p>

    @include("header.rs.html")
</div>

```

--------------------------------

### Render Named Sections and Default Body in RsHtml

Source: https://rshtml.github.io/index

Demonstrates using @render('section_name') to inject specific content blocks and @render_body to include the default content within a layout template. This allows for flexible content placement and structure.

```html
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>@render("title") - My Website</title>
</head>
<body>
    <div class="container">
        <main>
            @render_body
        </main>
        <aside>
            @render("sidebar")
        </aside>
    </div>
</body>
</html>

```

```html
@render_body
@render_body() @* Parentheses are also allowed *@

```

--------------------------------

### RsHtml Pattern Matching with @match

Source: https://rshtml.github.io/index

Demonstrates the flexibility of @match expressions in RsHtml for handling single-line content, block content, and multiple match arms. It allows for direct Rust values, HTML snippets, or complex template blocks.

```rshtml
@match self.value {
    0 => {<p>this is zero: @self.value</p>},
    1 => <p>this is one</p>,
    2 => self.value,
    3 | 4 => (i * 3),
    _ => <p>this is bigger than four</p>,
}

```

--------------------------------

### Creating JavaScript let Variables with JSON in RsHtml

Source: https://rshtml.github.io/index

Illustrates the `json_let()` helper function in RsHtml, which serializes a Rust value to JSON and directly wraps it in a JavaScript `let` variable declaration.

```RsHtml
<script>
    @#json_let("user", &self.current_user);
    console.log("Username:", user.username);
</script>
```

--------------------------------

### RsHtml While Loops

Source: https://rshtml.github.io/index

Shows how to implement @while loops in RsHtml, mirroring Rust's while loop syntax. The loop continues as long as the condition is true. Use RsHtml expressions within the loop body.

```html
@while self.count < 10 {
    <p> Counter is: @self.count </p>
    @self.increment()
}

```

--------------------------------

### Embedding Rust Code Blocks in RsHtml with @{...}

Source: https://rshtml.github.io/index

Shows how to embed larger Rust code snippets within RsHtml templates using @{ ... } blocks. This allows for variable declarations, function definitions, loops, and other complex logic that can influence the template rendering.

```rshtml
@{ 
    let s = "hello";

     fn inline_function() -> String {
        "inline function".to_string() 
     }

     for i in 0..10 {
        println!("Item {}", i);
     }

     let message = "I Love RsHtml!";
}

<p>@message</p>

```

--------------------------------

### Add RsHtml Dependency to Cargo.toml

Source: https://rshtml.github.io/index

Include RsHtml as a dependency in your project's Cargo.toml file to use its templating capabilities.

```toml
[dependencies]
rshtml = "0.3.0"
```

--------------------------------

### Configure RsHtml in Cargo.toml

Source: https://rshtml.github.io/index

Customize RsHtml view settings in Cargo.toml. Specifies the path for views and layout files, and controls whether to extract generated code to a file in debug mode.

```toml
[package.metadata.rshtml]
views = { path = "views", layout = "layout.rs.html", extract_file_on_debug = false }
```

--------------------------------

### Serializing Rust Data to JSON in RsHtml

Source: https://rshtml.github.io/index

Explains and demonstrates the `json()` helper function in RsHtml for serializing Rust values into JSON strings, useful for embedding data in JavaScript.

```RsHtml
<script>
    const userData = @#json(&self.current_user);
    console.log("User ID:", userData.id);
</script>
```

--------------------------------

### RsHtml For Loops

Source: https://rshtml.github.io/index

Demonstrates using the @for directive in RsHtml for iterating over collections, similar to Rust's native for loops. The loop body can contain HTML and RsHtml expressions. Use `continue` and `break` for control flow.

```html
<ul>
    @for item in &self.items {
        <li>@item</li>
    }

    <table>
        @for (index, user) in self.users.iter().enumerate() {
            <tr>
                <td>@(index + 1)</td>
                <td>@user.name</td>
            </tr>
        }
    </table>
</ul>

```

```html
@for i in 0..10 {
    @if i == 3 {
        @continue
    }

    @if i == 8 {
        @break
    }

    <p>it is @i</p>
}

```

--------------------------------

### RsHtml Safe vs. Raw Rendering with @# and @@

Source: https://rshtml.github.io/index

Details RsHtml's default HTML escaping for security and how to bypass it using the @# prefix for raw, unescaped rendering. It also covers escaping the literal '@' character with '@@'.

```rshtml
@* --- Default, Safe Rendering --- *@
@* The HTML tags will be visible as plain text. *@
<div>@self.my_var</div>

@* --- Raw, Unescaped Rendering --- *@
@* The string is rendered as actual HTML. *@
<div>@#self.my_var</div>

```

```rshtml
<p>Follow us on: @@rshtml_engine</p>

```

--------------------------------

### Passing Data to RsHtml Components

Source: https://rshtml.github.io/index

Illustrates how to pass data to RsHtml components using attributes, supporting various data types including string literals, numbers, booleans, Rust expressions, and template blocks. Components can be aliased using 'as'.

```RsHtml
@use "components/ComplexCard.rs.html" as Card

<Card
    title="Dynamic Card"
    is_published=true
    view_count=@self.page_views
    header={
        <div class="custom-header">
            Rendered from a template block! @self.data
        </div>
    }
/>
```

--------------------------------

### Display Current Layout Name in RsHtml

Source: https://rshtml.github.io/index

Illustrates how to access and display the name of the currently applied layout using the `layout` constant. This is useful for debugging or informational purposes within templates.

```html
Layout name: @layout

```

--------------------------------

### Check Section Existence in RsHtml

Source: https://rshtml.github.io/index

Shows how to use the has_section() function to conditionally render content based on whether a specific named section exists within the template. This provides dynamic control over page elements.

```html
@if has_section("section_name") {
    <p>The section "section_name" exists.</p>
}

```

--------------------------------

### Define Struct for RsHtml Template

Source: https://rshtml.github.io/index

Use the `RsHtml` derive macro to automatically implement the `RsHtml trait` for your structs. The macro infers the template file path based on the struct name or allows an explicit path override.

```rust
use rshtml::{RsHtml, traits::RsHtml};

#[derive(RsHtml)]
struct HomePage {
    username: String,
    items: Vec<String>,
}
```

--------------------------------

### RsHtml Server-Side Comments with @*

Source: https://rshtml.github.io/index

Illustrates how to add server-side comments in RsHtml templates using the @* ... *@ syntax. These comments are processed during compilation and do not appear in the final HTML output.

```rshtml
@* this is server side comment, it will not appear in the html output *@

```

--------------------------------

### RsHtml Conditional Statements (if/else)

Source: https://rshtml.github.io/index

Illustrates conditional rendering in RsHtml using @if, @else if, and @else directives. These follow standard Rust expression syntax within curly braces. Remember to escape literal closing braces with `@@}`.

```html
@if self.items.is_empty() {
    <p>You have no items.</p>
} else {
    <p>Here are your items.</p>
}

```

```html
@if self.count == 0 {
    <p>You have no items.</p>
} else if self.count == 1 {
    <p>You have one item.</p>
} else {
    <p>Here are your items.</p>
}

```

--------------------------------

### RsHtml Raw Output Block with @raw {...}

Source: https://rshtml.github.io/index

Explains the usage of the @raw { ... } block in RsHtml to render content verbatim without any processing by the RsHtml engine. This is useful for including HTML or other directives that should be treated as literal text.

```rshtml
@raw {
    <p>this is raw block @self.value</p>
    @self.my_func()

    <h2></h2>
    <p>Count value: 8</p>
}

```

--------------------------------

### RsHtml Section Definition with @section

Source: https://rshtml.github.io/index

Illustrates the inline @section directive for defining simple, single-line sections within RsHtml templates. It accepts a section name and either a string literal or a Rust expression as its value.

```rshtml
@section("section_name", "A string value")
@section("section_name", @self.rust_variable)

```

--------------------------------

### Default Content Handling in RsHtml

Source: https://rshtml.github.io/index

Illustrates how content outside of named @section blocks is treated as default content. This content is automatically captured and can be rendered in a layout using the @render_body directive. It requires extending a layout template.

```html
@extends("layout.rs.html")

@* This is the default content because it's not in a @section block. *@
<h1>A Simple Page</h1>
<p>No need to wrap this in a section block.</p>

```

--------------------------------

### RsHtml Parenthesized Expressions

Source: https://rshtml.github.io/index

Shows how to use parenthesized expressions in RsHtml for clarity or when dealing with more complex logic. Expressions within parentheses are evaluated as a single unit. This helps resolve ambiguity in parsing.

```html
<p>Final price: @(item.cost + item.tax)</p>
<p>@((self.value * 10).pow(2))</p>

```

--------------------------------

### Render Child Content within RsHtml Components

Source: https://rshtml.github.io/index

Explains the @child_content directive, used within a component's template to specify where any nested content passed from a parent template should be rendered. Parentheses are optional.

```html
@child_content
@child_content() @* Parentheses are also allowed *@

```

--------------------------------

### Define Section Block in RsHtml

Source: https://rshtml.github.io/index

Defines a named multi-line content block using the @section directive. Content within curly braces is captured and can be injected elsewhere using @render. This is the primary method for organizing larger content chunks.

```html
@section menu {
    <p>this is section menu content @self.data</p>
}
```
Tokens:
Raw