> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Layouts
> Create consistent page structures with 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:**
```html theme={null}
Page Title
```
**With layouts - define once, pages fill in the content:**
```html theme={null}
{{.Data.Title}}
{{.Content}}
```
## 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
```html theme={null}
{{.Data.Title}}
{{.Content}}
```
**Key point:** `{{.Content}}` is where the rendered page content is inserted.
### Page Template
Pages simply provide content - no layout wrapper needed:
```html theme={null}
Welcome, {{.Data.Name}}!
This is the home page.
```
## How It Works
When you render a page:
```go theme={null}
view.Render(c, "home", view.Data{
"Title": "Home",
"Name": "Alice",
})
```
The engine:
1. Renders `pages/home.html` with your data
2. Puts the result in `.Content`
3. Renders `layouts/default.html` with `.Content` set
## Setting the Default Layout
Configure the default layout in your engine:
```go theme={null}
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
```html theme={null}
Admin - {{.Data.Title}}
{{.Data.PageTitle}}
{{.Content}}
```
### Using a Different Layout
Override the default layout when rendering:
```go theme={null}
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:
```html theme={null}
{{.Data.Title}}
{{.Content}}
```
```go theme={null}
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:
```go theme={null}
// 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 |
```go theme={null}
view.Render(c, "home", view.Data{
"Title": "Home Page",
"CurrentUser": user,
"Year": time.Now().Year(),
})
```
```html theme={null}
{{.Data.Title}}
{{.Content}}
```
## Common Patterns
### Dynamic Navigation
Highlight the current page:
```html theme={null}
```
Or pass the current path:
```go theme={null}
view.Data{
"CurrentPath": c.Path(),
}
```
```html theme={null}
Home
```
### Flash Messages
Display flash messages from sessions:
```html theme={null}
{{if .Data.Flash}}
{{.Data.Flash.Message}}
{{end}}
```
### Page-Specific Body Classes
```html theme={null}
```
```go theme={null}
view.Data{
"BodyClass": "page-home dark-mode",
}
```
### Meta Tags
```html theme={null}
{{.Data.Title}}
{{if .Data.NoIndex}}{{end}}
```
### Conditional Scripts
```html theme={null}
{{.Content}}
{{if .Data.NeedsChart}}
{{end}}
```
## 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:
```go theme={null}
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
```go theme={null}
// 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:
```go theme={null}
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)
}
}
}
```