`)
- `data-{entity}-id` for JS identification
- `data-status`, `data-category` store raw enum values
- Display names (`categoryDisplayName`) for visible text
- `LocalizableDate` property (`createdAt`) renders automatically
---
## Template 4: Row Fragment
**Location:** `Sources/{WebAppTarget}/Resources/Views/{Feature}/{Entity}RowView.leaf`
**Renders:** `{Entity}RowViewModel`
```html
|
#(row.initial)
#(row.name)
|
#(row.statusDisplayName)
|
#(row.createdAt)
|
|
```
---
## Template 5: Column/Container Fragment
**Location:** `Sources/{WebAppTarget}/Resources/Views/{Feature}/{Entity}ColumnView.leaf`
**Renders:** `{Entity}ColumnViewModel`
```html
#(column.displayName)
#(column.count)
#for(card in column.cards):
#extend("{Feature}/{Entity}CardView")
#endfor
#if(column.cards.count == 0):
#(column.emptyMessage)
#endif
```
---
## Template 6: Modal Fragment
**Location:** `Sources/{WebAppTarget}/Resources/Views/{Feature}/{Action}ModalView.leaf`
**Renders:** `{Action}ModalViewModel`
```html
```
---
## WebApp Route Examples
### Rendering a Full Page
```swift
// GET /{feature}
app.get("{feature}") { req async throws -> View in
let serverRequest = {Feature}ViewModelRequest()
guard let response = try await serverRequest.processRequest(baseURL: app.serverBaseURL) else {
throw Abort(.internalServerError)
}
return try await req.view.render(
"{Feature}/{Feature}View",
["viewModel": response]
)
}
```
### Rendering a Fragment (HTML-over-the-wire)
```swift
// POST /move-{entity}
app.post("move-{entity}") { req async throws -> Response in
let body = try req.content.decode(Move{Entity}Request.RequestBody.self)
let serverRequest = Move{Entity}Request(requestBody: body)
guard let response = try await serverRequest.processRequest(baseURL: app.serverBaseURL) else {
throw Abort(.internalServerError)
}
// Return HTML fragment, not full page
return try await req.view.render(
"{Feature}/{Entity}CardView",
["card": response.viewModel]
).encodeResponse(for: req)
}
```
---
## Localizable+Leaf Integration
FOSMVVM provides `LeafDataRepresentable` conformance for all Localizable types.
**Location:** `FOSUtilities/Sources/FOSMVVMVapor/Extensions/Localizable+Leaf.swift`
```swift
import FOSMVVM
import LeafKit
extension LocalizableString: LeafDataRepresentable {
public var leafData: LeafData {
.string((try? localizedString) ?? "")
}
}
extension LocalizableDate: LeafDataRepresentable {
public var leafData: LeafData {
.string((try? localizedString) ?? "")
}
}
// Also: LocalizableInt, LocalizableArray, LocalizableCompoundValue, LocalizableSubstitutions
```
**Why this matters:**
- `LocalizableString` encodes as plain string → works by default
- `LocalizableDate` encodes as keyed container → needs explicit LeafData conversion
- Without this, dates render as `[ds: "2", ls: "Dec 27, 2025", v: "..."]`
---
## Data Attribute Reference
| Purpose | Pattern | JS Access |
|---------|---------|-----------|
| Entity ID | `data-{entity}-id` | `element.dataset.{entity}Id` |
| Status | `data-status` | `element.dataset.status` |
| Category | `data-{category}` | `element.dataset.{category}` |
| Action | `data-action` | `element.dataset.action` |
**HTML (kebab-case):**
```html
```
**JS (camelCase):**
```javascript
const userId = element.dataset.userId;
const status = element.dataset.status;
```
---
## Conditional Rendering Patterns
### Optional Properties
```html
#if(card.assignee):
#(card.assignee.name)
#else:
#(card.unassignedLabel)
#endif
```
### Boolean Flags
```html
#if(card.isHighPriority):
#(card.priorityLabel)
#endif
```
### Empty States
```html
#if(items.count == 0):
#(viewModel.emptyMessage)
#else:
#for(item in items):
#extend("{Feature}/{Entity}CardView")
#endfor
#endif
```
---
## Troubleshooting
### Dates Show Debug Description
**Symptom:** `[ds: "2", ls: "Dec 27, 2025", v: "1766598117.309064"]`
**Fix:**
1. Verify `Localizable+Leaf.swift` exists in FOSMVVMVapor
2. Verify `LeafKit` is a dependency
3. Run `swift package clean && swift build`
### Data Attributes Missing in JS
**Symptom:** `element.dataset.entityId` is `undefined`
**Fix:**
1. HTML uses `data-entity-id` (kebab-case)
2. JS reads as `dataset.entityId` (camelCase)
3. Verify template variable: `#(card.id)` is not empty
### Localized String Shows Key Path
**Symptom:** Shows `{Entity}CardViewModel.statusDisplayName` instead of "Active"
**Fix:**
1. YAML file exists: `{Entity}CardViewModel.yml`
2. YAML has the key: `statusDisplayName: "Active"`
3. ViewModel uses `@LocalizedString`
---
## Checklist
### Full-Page Template
- [ ] Extends base layout: `#extend("base"):`
- [ ] Exports title: `#export("title"):...#endexport`
- [ ] Exports content: `#export("content"):...#endexport`
- [ ] Filename matches ViewModel: `{Feature}View.leaf` → `{Feature}ViewModel`
### Fragment Template
- [ ] NO `#extend("base")` - just the component
- [ ] Single root element
- [ ] `data-{entity}-id` for JS identification
- [ ] Raw enum values in data attributes
- [ ] Display names from ViewModel properties
- [ ] Filename matches ViewModel: `{Entity}CardView.leaf` → `{Entity}CardViewModel`
### ViewModel Properties
- [ ] `id: ModelIdType` for data-{entity}-id
- [ ] Raw enum for data-{field} attributes
- [ ] `@LocalizedString` for display names
- [ ] `@LocalizedDate` for dates