Layouts

Layouts are the HTML shell that wraps your pages. They contain the common structure shared across pages: doctype, head, navigation, footer, and more.

What is a Layout?

A layout is a template that defines the outer structure of your pages. Instead of repeating the HTML boilerplate in every page, you define it once in a layout. Without layouts - every page repeats this:

<!DOCTYPE html>
<html>
<head>
    <title>Page Title</title>
    <link rel="stylesheet" href="/styles.css">
</head>
<body>
    <nav>...</nav>
    <!-- Page content here -->
    <footer>...</footer>
</body>
</html>

With layouts - define once, pages fill in the content:

<!DOCTYPE html>
<html>
<head>
    <title>{{.Data.Title}}</title>
    <link rel="stylesheet" href="/styles.css">
</head>
<body>
    <nav>...</nav>
    {{.Content}}
    <footer>...</footer>
</body>
</html>

Directory Structure

Layouts live in the layouts/ subdirectory:

views/
├── layouts/
│   ├── default.html    # Default layout
│   ├── admin.html      # Admin layout
│   └── minimal.html    # Minimal layout
└── pages/
    ├── home.html
    └── dashboard.html

Creating a Layout

Basic Layout

<!-- views/layouts/default.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{.Data.Title}}</title>
    <link rel="stylesheet" href="/css/main.css">
</head>
<body>
    <header>
        <nav>
            <a href="/">Home</a>
            <a href="/about">About</a>
            <a href="/contact">Contact</a>
        </nav>
    </header>

    <main>
        {{.Content}}
    </main>

    <footer>
        <p>&copy; 2024 My Company</p>
    </footer>

    <script src="/js/main.js"></script>
</body>
</html>

Key point: {{.Content}} is where the rendered page content is inserted.

Page Template

Pages simply provide content - no layout wrapper needed:

<!-- views/pages/home.html -->
<h1>Welcome, {{.Data.Name}}!</h1>
<p>This is the home page.</p>

How It Works

When you render a page:

view.Render(c, "home", view.Data{
    "Title": "Home",
    "Name":  "Alice",
})

The engine:

Renders pages/home.html with your data
Puts the result in .Content
Renders layouts/default.html with .Content set

Setting the Default Layout

Configure the default layout in your engine:

engine := view.New(view.Config{
    Dir:           "./views",
    DefaultLayout: "default",  // Uses layouts/default.html
})

Multiple Layouts

Create different layouts for different sections of your site.

Admin Layout

<!-- views/layouts/admin.html -->
<!DOCTYPE html>
<html>
<head>
    <title>Admin - {{.Data.Title}}</title>
    <link rel="stylesheet" href="/css/admin.css">
</head>
<body class="admin">
    <div class="admin-sidebar">
        <nav>
            <a href="/admin">Dashboard</a>
            <a href="/admin/users">Users</a>
            <a href="/admin/posts">Posts</a>
            <a href="/admin/settings">Settings</a>
        </nav>
    </div>
    <div class="admin-content">
        <header>
            <h1>{{.Data.PageTitle}}</h1>
        </header>
        <main>
            {{.Content}}
        </main>
    </div>
</body>
</html>

Using a Different Layout

Override the default layout when rendering:

func dashboardHandler(c *mizu.Ctx) error {
    return view.Render(c, "admin/dashboard", view.Data{
        "Title":     "Dashboard",
        "PageTitle": "Admin Dashboard",
        "Stats":     stats,
    }, view.Layout("admin"))
}

Minimal Layout

For simple pages that don’t need full navigation:

<!-- views/layouts/minimal.html -->
<!DOCTYPE html>
<html>
<head>
    <title>{{.Data.Title}}</title>
    <style>
        body {
            font-family: sans-serif;
            max-width: 600px;
            margin: 50px auto;
            padding: 20px;
        }
    </style>
</head>
<body>
    {{.Content}}
</body>
</html>

func loginHandler(c *mizu.Ctx) error {
    return view.Render(c, "login", view.Data{
        "Title": "Login",
    }, view.Layout("minimal"))
}

No Layout

For AJAX responses, partial HTML, or API endpoints that return HTML fragments:

// Returns just the page content, no layout
view.Render(c, "user-row", data, view.NoLayout())

This is useful for:

HTMX partial updates
AJAX content loading
Email templates (that define their own complete HTML)

Layout Data Access

Layouts have access to all the same data as pages:

Field	Description
`.Data`	Your data from the handler
`.Page.Name`	Page template name
`.Page.Layout`	Layout name
`.Content`	Rendered page content

view.Render(c, "home", view.Data{
    "Title":       "Home Page",
    "CurrentUser": user,
    "Year":        time.Now().Year(),
})

<!-- views/layouts/default.html -->
<!DOCTYPE html>
<html>
<head>
    <title>{{.Data.Title}}</title>
</head>
<body>
    <nav>
        {{if .Data.CurrentUser}}
            <span>Hello, {{.Data.CurrentUser.Name}}</span>
            <a href="/logout">Logout</a>
        {{else}}
            <a href="/login">Login</a>
        {{end}}
    </nav>

    <main>
        {{.Content}}
    </main>

    <footer>
        <p>&copy; {{.Data.Year}} My Company</p>
    </footer>
</body>
</html>

Common Patterns

Highlight the current page:

<!-- views/layouts/default.html -->
<nav>
    <a href="/" class="{{if eq .Page.Name "home"}}active{{end}}">Home</a>
    <a href="/about" class="{{if eq .Page.Name "about"}}active{{end}}">About</a>
    <a href="/contact" class="{{if eq .Page.Name "contact"}}active{{end}}">Contact</a>
</nav>

Or pass the current path:

view.Data{
    "CurrentPath": c.Path(),
}

<a href="/" class="{{if eq .Data.CurrentPath "/"}}active{{end}}">Home</a>

Flash Messages

Display flash messages from sessions:

{{if .Data.Flash}}
<div class="flash flash-{{.Data.Flash.Type}}">
    {{.Data.Flash.Message}}
</div>
{{end}}

Page-Specific Body Classes

<body class="{{.Data.BodyClass}}">

view.Data{
    "BodyClass": "page-home dark-mode",
}

Meta Tags

<head>
    <title>{{.Data.Title}}</title>
    <meta name="description" content="{{.Data.Description}}">
    {{if .Data.NoIndex}}<meta name="robots" content="noindex">{{end}}
</head>

Conditional Scripts

<body>
    {{.Content}}

    <script src="/js/main.js"></script>
    {{if .Data.NeedsChart}}
    <script src="/js/chart.js"></script>
    {{end}}
</body>

Best Practices

1. Keep Layouts Focused

Each layout should serve a clear purpose:

default.html - Main public pages
admin.html - Admin panel
auth.html - Login/signup pages
email.html - Email templates

2. Pass Common Data via Middleware

Instead of passing the same data in every handler, use middleware:

func commonDataMiddleware(next mizu.Handler) mizu.Handler {
    return func(c *mizu.Ctx) error {
        c.Locals("Year", time.Now().Year())
        c.Locals("CurrentPath", c.Path())
        return next(c)
    }
}

3. Use Meaningful Names

// Good: clear purpose
view.Layout("admin")
view.Layout("email")

// Avoid: unclear
view.Layout("layout2")
view.Layout("other")

4. Don’t Overcomplicate

Start simple. Most sites only need 2-3 layouts:

Main layout for public pages
Admin layout for backend
Minimal layout for auth pages

5. Test All Layouts

Make sure every layout works with your data:

func TestLayouts(t *testing.T) {
    engine := view.New(config)

    layouts := []string{"default", "admin", "minimal"}
    for _, layout := range layouts {
        var buf bytes.Buffer
        err := engine.Render(&buf, "test-page", testData, view.Layout(layout))
        if err != nil {
            t.Errorf("Layout %s failed: %v", layout, err)
        }
    }
}

View Engine

Live (Realtime)

Sync (State)

What is a Layout?

Directory Structure

Creating a Layout

Basic Layout

Page Template

How It Works

Setting the Default Layout

Multiple Layouts

Admin Layout

Using a Different Layout

Minimal Layout

No Layout

Layout Data Access

Common Patterns

Dynamic Navigation

Flash Messages

Page-Specific Body Classes

Meta Tags

Conditional Scripts

Best Practices

1. Keep Layouts Focused

2. Pass Common Data via Middleware

3. Use Meaningful Names

4. Don’t Overcomplicate

5. Test All Layouts

View Engine

Live (Realtime)

Sync (State)

​What is a Layout?

​Directory Structure

​Creating a Layout

​Basic Layout

​Page Template

​How It Works

​Setting the Default Layout

​Multiple Layouts

​Admin Layout

​Using a Different Layout

​Minimal Layout

​No Layout

​Layout Data Access

​Common Patterns

​Dynamic Navigation

​Flash Messages

​Page-Specific Body Classes

​Meta Tags

​Conditional Scripts

​Best Practices

​1. Keep Layouts Focused

​2. Pass Common Data via Middleware

​3. Use Meaningful Names

​4. Don’t Overcomplicate

​5. Test All Layouts

What is a Layout?

Directory Structure

Creating a Layout

Basic Layout

Page Template

How It Works

Setting the Default Layout

Multiple Layouts

Admin Layout

Using a Different Layout

Minimal Layout

No Layout

Layout Data Access

Common Patterns

Dynamic Navigation

Flash Messages

Page-Specific Body Classes

Meta Tags

Conditional Scripts

Best Practices

1. Keep Layouts Focused

2. Pass Common Data via Middleware

3. Use Meaningful Names

4. Don’t Overcomplicate

5. Test All Layouts