docs(07): research admin forms/lists domain
Phase 7: Admin Forms & Lists - Standard stack identified: circe-yaml, ScalaTags, HTMX - Architecture patterns documented: YAML ADT parsing, widget registry, form generation - Pitfalls catalogued: YAML anchors, trigger conditions, repeater state, relation modals
This commit is contained in:
Jakub Zych
602
.planning/phases/07-admin-forms-lists/07-RESEARCH.md
Normal file
602
.planning/phases/07-admin-forms-lists/07-RESEARCH.md
Normal file
@@ -0,0 +1,602 @@
|
|||||||
|
# Phase 7: Admin Forms & Lists - Research
|
||||||
|
|
||||||
|
**Researched:** 2026-02-05
|
||||||
|
**Domain:** YAML-driven form and list generation for admin backend
|
||||||
|
**Confidence:** HIGH (based on WinterCMS reference + official library documentation)
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
This research covers the implementation of YAML-driven form and list generation for SummerCMS admin backend. The WinterCMS reference implementation provides a comprehensive blueprint with `fields.yaml` for forms and `columns.yaml` for lists, supported by a widget system for field rendering.
|
||||||
|
|
||||||
|
The standard approach involves:
|
||||||
|
1. YAML parsing into typed Scala case classes representing form fields and list columns
|
||||||
|
2. A widget registry system for mapping field types to rendering implementations
|
||||||
|
3. ScalaTags-based HTML generation with HTMX for interactivity
|
||||||
|
4. Type-safe validation defined in Scala models (not YAML)
|
||||||
|
|
||||||
|
**Primary recommendation:** Use circe-yaml for YAML parsing into strongly-typed ADTs, ScalaTags for HTML generation, and HTMX for AJAX-like form submission and partial updates.
|
||||||
|
|
||||||
|
## Standard Stack
|
||||||
|
|
||||||
|
### Core
|
||||||
|
| Library | Version | Purpose | Why Standard |
|
||||||
|
|---------|---------|---------|--------------|
|
||||||
|
| circe-yaml | 1.x | YAML parsing | Bridges YAML to Circe JSON AST with type-safe ADT marshalling |
|
||||||
|
| circe | 0.14.x | JSON/YAML codec derivation | Compile-time derivation of encoders/decoders |
|
||||||
|
| ScalaTags | 0.13.x | HTML generation | Type-safe, composable HTML fragments |
|
||||||
|
| HTMX | 2.x | Frontend interactivity | Declarative AJAX, form submission, partial updates |
|
||||||
|
|
||||||
|
### Supporting
|
||||||
|
| Library | Version | Purpose | When to Use |
|
||||||
|
|---------|---------|---------|-------------|
|
||||||
|
| zio-config-yaml | 4.x | ZIO-native YAML config | Alternative if deeper ZIO integration needed |
|
||||||
|
| Sortable.js | 1.15.x | Drag-and-drop reordering | Repeater item reorder, list row reorder |
|
||||||
|
| Flatpickr | 4.6.x | Date/time picker | DatePicker widget implementation |
|
||||||
|
|
||||||
|
### Alternatives Considered
|
||||||
|
| Instead of | Could Use | Tradeoff |
|
||||||
|
|------------|-----------|----------|
|
||||||
|
| circe-yaml | zio-config-yaml | Better ZIO integration but less flexible for ad-hoc YAML |
|
||||||
|
| ScalaTags | Pebble templates | Pebble already in stack; ScalaTags better for programmatic generation |
|
||||||
|
| HTMX | Full SPA (React) | HTMX simpler, server-rendered, aligns with WinterCMS approach |
|
||||||
|
|
||||||
|
**Mill dependencies:**
|
||||||
|
```scala
|
||||||
|
ivy"io.circe::circe-yaml:1.0.0",
|
||||||
|
ivy"io.circe::circe-generic:0.14.9",
|
||||||
|
ivy"com.lihaoyi::scalatags:0.13.1"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Architecture Patterns
|
||||||
|
|
||||||
|
### Recommended Project Structure
|
||||||
|
```
|
||||||
|
summercms/
|
||||||
|
├── admin/
|
||||||
|
│ ├── forms/
|
||||||
|
│ │ ├── Form.scala # Form widget container
|
||||||
|
│ │ ├── FormField.scala # Field definition ADT
|
||||||
|
│ │ ├── FormTabs.scala # Tab grouping
|
||||||
|
│ │ ├── widgets/ # Widget implementations
|
||||||
|
│ │ │ ├── TextWidget.scala
|
||||||
|
│ │ │ ├── TextareaWidget.scala
|
||||||
|
│ │ │ ├── DropdownWidget.scala
|
||||||
|
│ │ │ ├── CheckboxWidget.scala
|
||||||
|
│ │ │ ├── DatePickerWidget.scala
|
||||||
|
│ │ │ ├── RepeaterWidget.scala
|
||||||
|
│ │ │ └── RelationWidget.scala
|
||||||
|
│ │ └── WidgetRegistry.scala # Widget type -> renderer mapping
|
||||||
|
│ ├── lists/
|
||||||
|
│ │ ├── ListView.scala # List widget container
|
||||||
|
│ │ ├── ListColumn.scala # Column definition ADT
|
||||||
|
│ │ ├── columns/ # Column type implementations
|
||||||
|
│ │ │ ├── TextColumn.scala
|
||||||
|
│ │ │ ├── DateColumn.scala
|
||||||
|
│ │ │ ├── RelationColumn.scala
|
||||||
|
│ │ │ └── SwitchColumn.scala
|
||||||
|
│ │ ├── Filter.scala # Filter scopes
|
||||||
|
│ │ └── Pagination.scala # Pagination handling
|
||||||
|
│ └── yaml/
|
||||||
|
│ ├── FieldsYamlParser.scala # fields.yaml parser
|
||||||
|
│ ├── ColumnsYamlParser.scala # columns.yaml parser
|
||||||
|
│ └── YamlSchema.scala # Shared YAML structures
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pattern 1: YAML to ADT Parsing
|
||||||
|
**What:** Parse YAML configuration into strongly-typed Scala ADTs using circe-yaml
|
||||||
|
**When to use:** Loading fields.yaml and columns.yaml definitions
|
||||||
|
**Example:**
|
||||||
|
```scala
|
||||||
|
// Source: Circe-YAML documentation
|
||||||
|
import io.circe.yaml.parser
|
||||||
|
import io.circe.generic.auto._
|
||||||
|
|
||||||
|
sealed trait FieldType
|
||||||
|
case object Text extends FieldType
|
||||||
|
case object Textarea extends FieldType
|
||||||
|
case object Dropdown extends FieldType
|
||||||
|
case object Checkbox extends FieldType
|
||||||
|
case object DatePicker extends FieldType
|
||||||
|
case object Repeater extends FieldType
|
||||||
|
case object Relation extends FieldType
|
||||||
|
|
||||||
|
case class TriggerConfig(
|
||||||
|
action: String, // "show", "hide", "enable", "disable"
|
||||||
|
field: String, // field name to watch
|
||||||
|
condition: String // "checked", "unchecked", "value[x]"
|
||||||
|
)
|
||||||
|
|
||||||
|
case class FormField(
|
||||||
|
`type`: Option[String] = Some("text"),
|
||||||
|
label: Option[String] = None,
|
||||||
|
span: Option[String] = Some("full"), // "left", "right", "full", "auto"
|
||||||
|
tab: Option[String] = None,
|
||||||
|
placeholder: Option[String] = None,
|
||||||
|
comment: Option[String] = None,
|
||||||
|
commentAbove: Option[String] = None,
|
||||||
|
default: Option[String] = None,
|
||||||
|
required: Option[Boolean] = None,
|
||||||
|
disabled: Option[Boolean] = None,
|
||||||
|
hidden: Option[Boolean] = None,
|
||||||
|
context: Option[List[String]] = None, // ["create", "update"]
|
||||||
|
trigger: Option[TriggerConfig] = None,
|
||||||
|
options: Option[Map[String, String]] = None,
|
||||||
|
cssClass: Option[String] = None,
|
||||||
|
// Repeater-specific
|
||||||
|
form: Option[FormDefinition] = None,
|
||||||
|
minItems: Option[Int] = None,
|
||||||
|
maxItems: Option[Int] = None,
|
||||||
|
// Relation-specific
|
||||||
|
select: Option[String] = None,
|
||||||
|
nameFrom: Option[String] = None,
|
||||||
|
emptyOption: Option[String] = None
|
||||||
|
)
|
||||||
|
|
||||||
|
case class FormDefinition(
|
||||||
|
fields: Map[String, FormField],
|
||||||
|
tabs: Option[TabsConfig] = None,
|
||||||
|
secondaryTabs: Option[TabsConfig] = None
|
||||||
|
)
|
||||||
|
|
||||||
|
// Parsing
|
||||||
|
val yaml = """
|
||||||
|
fields:
|
||||||
|
title:
|
||||||
|
label: Title
|
||||||
|
span: left
|
||||||
|
content:
|
||||||
|
type: textarea
|
||||||
|
tab: Content
|
||||||
|
"""
|
||||||
|
|
||||||
|
parser.parse(yaml).flatMap(_.as[FormDefinition])
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pattern 2: Widget Registry Pattern
|
||||||
|
**What:** Map field type strings to widget rendering implementations
|
||||||
|
**When to use:** Dynamically rendering form fields based on YAML type
|
||||||
|
**Example:**
|
||||||
|
```scala
|
||||||
|
trait FormWidget {
|
||||||
|
def render(field: FormField, value: Any, context: FormContext): Frag
|
||||||
|
def getSaveValue(field: FormField, postData: Map[String, Any]): Any
|
||||||
|
}
|
||||||
|
|
||||||
|
class WidgetRegistry {
|
||||||
|
private val widgets = mutable.Map[String, FormWidget]()
|
||||||
|
|
||||||
|
def register(typeName: String, widget: FormWidget): Unit =
|
||||||
|
widgets(typeName) = widget
|
||||||
|
|
||||||
|
def resolve(typeName: String): Option[FormWidget] =
|
||||||
|
widgets.get(typeName)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Registration (in plugin boot)
|
||||||
|
registry.register("text", TextWidget)
|
||||||
|
registry.register("textarea", TextareaWidget)
|
||||||
|
registry.register("dropdown", DropdownWidget)
|
||||||
|
registry.register("checkbox", CheckboxWidget)
|
||||||
|
registry.register("datepicker", DatePickerWidget)
|
||||||
|
registry.register("repeater", RepeaterWidget)
|
||||||
|
registry.register("relation", RelationWidget)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pattern 3: ScalaTags Form Generation
|
||||||
|
**What:** Generate HTML forms from parsed YAML using ScalaTags
|
||||||
|
**When to use:** Rendering forms and lists in admin controllers
|
||||||
|
**Example:**
|
||||||
|
```scala
|
||||||
|
// Source: ScalaTags documentation
|
||||||
|
import scalatags.Text.all._
|
||||||
|
|
||||||
|
def renderFormField(field: FormField, name: String, value: Any): Frag = {
|
||||||
|
val fieldType = field.`type`.getOrElse("text")
|
||||||
|
val widget = widgetRegistry.resolve(fieldType)
|
||||||
|
|
||||||
|
div(cls := s"form-group span-${field.span.getOrElse("full")}",
|
||||||
|
field.trigger.map(t => Seq(
|
||||||
|
data.trigger := s"[name='${t.field}']",
|
||||||
|
data.triggerAction := t.action,
|
||||||
|
data.triggerCondition := t.condition
|
||||||
|
)).getOrElse(Nil),
|
||||||
|
|
||||||
|
field.label.map(l =>
|
||||||
|
label(cls := "form-label",
|
||||||
|
l,
|
||||||
|
field.required.filter(identity).map(_ => span(cls := "required", "*"))
|
||||||
|
)
|
||||||
|
),
|
||||||
|
|
||||||
|
field.commentAbove.map(c => p(cls := "help-block before-field", c)),
|
||||||
|
|
||||||
|
widget.map(_.render(field, value, context)).getOrElse(
|
||||||
|
input(cls := "form-control", `type` := "text", attr("name") := name)
|
||||||
|
),
|
||||||
|
|
||||||
|
field.comment.map(c => p(cls := "help-block", c))
|
||||||
|
)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pattern 4: HTMX Form Submission with Validation Display
|
||||||
|
**What:** Handle form submission and validation error display via HTMX
|
||||||
|
**When to use:** Save forms with server-side validation, display inline errors
|
||||||
|
**Example:**
|
||||||
|
```scala
|
||||||
|
// Form with HTMX attributes
|
||||||
|
form(
|
||||||
|
attr("hx-post") := "/admin/posts/update",
|
||||||
|
attr("hx-target") := "#form-container",
|
||||||
|
attr("hx-swap") := "innerHTML",
|
||||||
|
|
||||||
|
// Fields rendered here...
|
||||||
|
|
||||||
|
div(cls := "form-buttons",
|
||||||
|
button(`type` := "submit", cls := "btn btn-primary",
|
||||||
|
attr("hx-include") := "[name]",
|
||||||
|
"Save"
|
||||||
|
),
|
||||||
|
button(`type` := "submit", cls := "btn btn-primary",
|
||||||
|
attr("hx-post") := "/admin/posts/update?close=true",
|
||||||
|
"Save and Close"
|
||||||
|
)
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
// Server response on validation error (422 status)
|
||||||
|
def renderFieldWithError(field: FormField, name: String, value: Any, error: String): Frag = {
|
||||||
|
div(cls := "form-group has-error",
|
||||||
|
// ... field rendering ...
|
||||||
|
p(cls := "error-message", error)
|
||||||
|
)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pattern 5: List Column Rendering
|
||||||
|
**What:** Render table columns with type-specific formatting
|
||||||
|
**When to use:** Admin list views with searchable, sortable columns
|
||||||
|
**Example:**
|
||||||
|
```scala
|
||||||
|
case class ListColumn(
|
||||||
|
label: String,
|
||||||
|
`type`: Option[String] = Some("text"),
|
||||||
|
searchable: Option[Boolean] = None,
|
||||||
|
sortable: Option[Boolean] = Some(true),
|
||||||
|
invisible: Option[Boolean] = None,
|
||||||
|
width: Option[String] = None,
|
||||||
|
relation: Option[String] = None,
|
||||||
|
select: Option[String] = None,
|
||||||
|
format: Option[String] = None // for dates, numbers
|
||||||
|
)
|
||||||
|
|
||||||
|
def renderColumnValue(column: ListColumn, record: Model): Frag = {
|
||||||
|
val value = column.relation match {
|
||||||
|
case Some(rel) => record.getRelation(rel).map(_.getAttribute(column.select.getOrElse("name")))
|
||||||
|
case None => record.getAttribute(column.columnName)
|
||||||
|
}
|
||||||
|
|
||||||
|
column.`type`.getOrElse("text") match {
|
||||||
|
case "date" => formatDate(value, column.format)
|
||||||
|
case "timetense" => formatTimeTense(value) // "2 hours ago"
|
||||||
|
case "switch" => renderSwitch(value)
|
||||||
|
case "partial" => renderPartial(column.path, record)
|
||||||
|
case _ => span(value.toString)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Anti-Patterns to Avoid
|
||||||
|
- **YAML in YAML strings:** Don't nest raw YAML strings; use proper nested structures
|
||||||
|
- **Validation in YAML:** Keep validation rules in Scala models, not YAML definitions
|
||||||
|
- **Widget type guessing:** Always require explicit `type` or use clear defaults
|
||||||
|
- **Inline JavaScript:** Use HTMX data attributes, not inline event handlers
|
||||||
|
- **Direct DOM manipulation:** Let HTMX handle DOM updates from server responses
|
||||||
|
|
||||||
|
## Don't Hand-Roll
|
||||||
|
|
||||||
|
Problems that look simple but have existing solutions:
|
||||||
|
|
||||||
|
| Problem | Don't Build | Use Instead | Why |
|
||||||
|
|---------|-------------|-------------|-----|
|
||||||
|
| YAML parsing | Custom parser | circe-yaml | Edge cases: anchors, aliases, multi-doc, escaping |
|
||||||
|
| Date/time picker | Custom calendar | Flatpickr | i18n, timezones, range selection |
|
||||||
|
| Drag-and-drop | Custom DnD | Sortable.js | Touch support, animations, nested lists |
|
||||||
|
| Form validation display | Custom error handling | HTMX + 422 status | Standard pattern, proper error semantics |
|
||||||
|
| Rich text editing | Custom editor | Existing RichEditor | Toolbar, formatting, sanitization |
|
||||||
|
| Color picker | Custom picker | Existing ColorPicker | Presets, formats, accessibility |
|
||||||
|
|
||||||
|
**Key insight:** Form widgets are deceptively complex. Each widget has edge cases (empty states, validation, disabled mode, preview mode, nested forms). Reuse WinterCMS widget patterns rather than reinventing.
|
||||||
|
|
||||||
|
## Common Pitfalls
|
||||||
|
|
||||||
|
### Pitfall 1: YAML Anchor/Alias Complexity
|
||||||
|
**What goes wrong:** YAML anchors (&) and aliases (*) create unexpected merge behavior
|
||||||
|
**Why it happens:** Users expect intuitive override behavior but YAML merge has specific semantics
|
||||||
|
**How to avoid:** Document merge behavior clearly; test anchor resolution; provide clear error messages for circular references
|
||||||
|
**Warning signs:** Fields appearing with unexpected values; missing overrides
|
||||||
|
|
||||||
|
### Pitfall 2: Trigger Condition Evaluation
|
||||||
|
**What goes wrong:** Conditional field visibility (`trigger`) doesn't work as expected
|
||||||
|
**Why it happens:** Complex condition expressions, field name resolution in nested forms, timing of evaluation
|
||||||
|
**How to avoid:**
|
||||||
|
- Use simple condition types: `checked`, `unchecked`, `value[x]`, `empty`, `filled`
|
||||||
|
- Resolve field names relative to form context (handle repeaters specially)
|
||||||
|
- Trigger on client-side with JavaScript, not server round-trips
|
||||||
|
**Warning signs:** Fields that don't show/hide correctly; triggers that work in forms but not in repeaters
|
||||||
|
|
||||||
|
### Pitfall 3: Repeater State Management
|
||||||
|
**What goes wrong:** Repeater items lose state, duplicate incorrectly, or save wrong data
|
||||||
|
**Why it happens:** Index-based naming collisions; AJAX add/remove doesn't sync with form state
|
||||||
|
**How to avoid:**
|
||||||
|
- Use unique item keys (UUIDs) not sequential indexes
|
||||||
|
- Send full repeater state on form submit, not diffs
|
||||||
|
- Re-render entire repeater on add/remove via HTMX partial
|
||||||
|
**Warning signs:** "Add item" duplicates existing item's data; deleted items reappear
|
||||||
|
|
||||||
|
### Pitfall 4: Relation Widget Complexity
|
||||||
|
**What goes wrong:** RelationController-style modals don't load, save, or dismiss correctly
|
||||||
|
**Why it happens:** Modal forms need separate form context, deferred bindings, session keys
|
||||||
|
**How to avoid:**
|
||||||
|
- Each modal gets its own form session key
|
||||||
|
- Use deferred bindings for unsaved parent models
|
||||||
|
- Clear modal content on close to prevent stale data
|
||||||
|
**Warning signs:** Related records not saving; modal data persisting across opens
|
||||||
|
|
||||||
|
### Pitfall 5: List Column Type Coercion
|
||||||
|
**What goes wrong:** Column values display incorrectly (dates as timestamps, booleans as 0/1)
|
||||||
|
**Why it happens:** No type coercion from database values to display values
|
||||||
|
**How to avoid:**
|
||||||
|
- Always apply column type formatting before display
|
||||||
|
- Handle null values explicitly for each column type
|
||||||
|
- Test with actual database values, not mocked data
|
||||||
|
**Warning signs:** Raw database values appearing in list; "null" or "None" displayed
|
||||||
|
|
||||||
|
## Code Examples
|
||||||
|
|
||||||
|
### Complete fields.yaml Parsing
|
||||||
|
```scala
|
||||||
|
// Source: WinterCMS fields.yaml structure analysis
|
||||||
|
import io.circe._
|
||||||
|
import io.circe.yaml.parser
|
||||||
|
import io.circe.generic.semiauto._
|
||||||
|
|
||||||
|
case class PresetConfig(field: String, `type`: String)
|
||||||
|
|
||||||
|
case class TriggerConfig(
|
||||||
|
action: String,
|
||||||
|
field: String,
|
||||||
|
condition: String
|
||||||
|
)
|
||||||
|
|
||||||
|
case class FormFieldConfig(
|
||||||
|
`type`: Option[String] = None,
|
||||||
|
label: Option[String] = None,
|
||||||
|
span: Option[String] = None,
|
||||||
|
size: Option[String] = None,
|
||||||
|
tab: Option[String] = None,
|
||||||
|
placeholder: Option[String] = None,
|
||||||
|
comment: Option[String] = None,
|
||||||
|
commentAbove: Option[String] = None,
|
||||||
|
default: Option[Json] = None,
|
||||||
|
required: Option[Boolean] = None,
|
||||||
|
disabled: Option[Boolean] = None,
|
||||||
|
hidden: Option[Boolean] = None,
|
||||||
|
readOnly: Option[Boolean] = None,
|
||||||
|
context: Option[Json] = None, // String or List[String]
|
||||||
|
trigger: Option[TriggerConfig] = None,
|
||||||
|
preset: Option[PresetConfig] = None,
|
||||||
|
dependsOn: Option[List[String]] = None,
|
||||||
|
options: Option[Json] = None, // Map or method name string
|
||||||
|
cssClass: Option[String] = None,
|
||||||
|
attributes: Option[Map[String, String]] = None,
|
||||||
|
// Widget-specific
|
||||||
|
form: Option[NestedFormConfig] = None,
|
||||||
|
path: Option[String] = None,
|
||||||
|
mode: Option[String] = None,
|
||||||
|
// Repeater
|
||||||
|
prompt: Option[String] = None,
|
||||||
|
titleFrom: Option[String] = None,
|
||||||
|
minItems: Option[Int] = None,
|
||||||
|
maxItems: Option[Int] = None,
|
||||||
|
sortable: Option[Boolean] = None,
|
||||||
|
// Relation
|
||||||
|
select: Option[String] = None,
|
||||||
|
nameFrom: Option[String] = None,
|
||||||
|
emptyOption: Option[String] = None,
|
||||||
|
// FileUpload
|
||||||
|
imageWidth: Option[Int] = None,
|
||||||
|
imageHeight: Option[Int] = None
|
||||||
|
)
|
||||||
|
|
||||||
|
case class TabsConfig(
|
||||||
|
fields: Map[String, FormFieldConfig],
|
||||||
|
stretch: Option[Boolean] = None,
|
||||||
|
cssClass: Option[String] = None,
|
||||||
|
paneCssClass: Option[Map[String, String]] = None,
|
||||||
|
`lazy`: Option[List[String]] = None,
|
||||||
|
icons: Option[Map[String, String]] = None
|
||||||
|
)
|
||||||
|
|
||||||
|
case class NestedFormConfig(
|
||||||
|
fields: Map[String, FormFieldConfig]
|
||||||
|
)
|
||||||
|
|
||||||
|
case class FieldsYamlConfig(
|
||||||
|
fields: Option[Map[String, FormFieldConfig]] = None,
|
||||||
|
tabs: Option[TabsConfig] = None,
|
||||||
|
secondaryTabs: Option[TabsConfig] = None
|
||||||
|
)
|
||||||
|
|
||||||
|
object FieldsYamlConfig {
|
||||||
|
implicit val presetDecoder: Decoder[PresetConfig] = deriveDecoder
|
||||||
|
implicit val triggerDecoder: Decoder[TriggerConfig] = deriveDecoder
|
||||||
|
implicit val nestedFormDecoder: Decoder[NestedFormConfig] = deriveDecoder
|
||||||
|
implicit val fieldDecoder: Decoder[FormFieldConfig] = deriveDecoder
|
||||||
|
implicit val tabsDecoder: Decoder[TabsConfig] = deriveDecoder
|
||||||
|
implicit val configDecoder: Decoder[FieldsYamlConfig] = deriveDecoder
|
||||||
|
|
||||||
|
def parse(yaml: String): Either[Error, FieldsYamlConfig] =
|
||||||
|
parser.parse(yaml).flatMap(_.as[FieldsYamlConfig])
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Text Widget Implementation
|
||||||
|
```scala
|
||||||
|
import scalatags.Text.all._
|
||||||
|
|
||||||
|
object TextWidget extends FormWidget {
|
||||||
|
def render(field: FormFieldConfig, name: String, value: Any, ctx: FormContext): Frag = {
|
||||||
|
val inputType = field.`type`.getOrElse("text") match {
|
||||||
|
case "password" => "password"
|
||||||
|
case "email" => "email"
|
||||||
|
case "url" => "url"
|
||||||
|
case "number" => "number"
|
||||||
|
case _ => "text"
|
||||||
|
}
|
||||||
|
|
||||||
|
input(
|
||||||
|
cls := "form-control",
|
||||||
|
`type` := inputType,
|
||||||
|
attr("name") := name,
|
||||||
|
attr("value") := Option(value).map(_.toString).getOrElse(""),
|
||||||
|
field.placeholder.map(p => attr("placeholder") := p),
|
||||||
|
field.required.filter(identity).map(_ => attr("required") := "required"),
|
||||||
|
field.disabled.filter(identity).map(_ => attr("disabled") := "disabled"),
|
||||||
|
field.readOnly.filter(identity).map(_ => attr("readonly") := "readonly"),
|
||||||
|
field.attributes.map(_.toSeq.map { case (k, v) => attr(k) := v }).getOrElse(Nil)
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
def getSaveValue(field: FormFieldConfig, postData: Map[String, Any]): Any =
|
||||||
|
postData.get(field.name).map(_.toString.trim).filter(_.nonEmpty)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### List View with HTMX Sorting and Pagination
|
||||||
|
```scala
|
||||||
|
def renderListView(config: ColumnsYamlConfig, records: Seq[Model], pagination: PaginationState): Frag = {
|
||||||
|
div(cls := "list-widget",
|
||||||
|
// Toolbar
|
||||||
|
div(cls := "list-toolbar",
|
||||||
|
button(cls := "btn btn-primary",
|
||||||
|
attr("hx-get") := "/admin/posts/create",
|
||||||
|
attr("hx-target") := "#form-modal .modal-content",
|
||||||
|
"Create"
|
||||||
|
),
|
||||||
|
button(cls := "btn btn-danger",
|
||||||
|
attr("hx-post") := "/admin/posts/bulk-delete",
|
||||||
|
attr("hx-include") := "[name='checked[]']",
|
||||||
|
attr("hx-confirm") := "Delete selected records?",
|
||||||
|
"Delete Selected"
|
||||||
|
)
|
||||||
|
),
|
||||||
|
|
||||||
|
// Table
|
||||||
|
table(cls := "table list-table",
|
||||||
|
thead(
|
||||||
|
tr(
|
||||||
|
th(cls := "list-checkbox",
|
||||||
|
input(`type` := "checkbox", cls := "select-all")
|
||||||
|
),
|
||||||
|
config.columns.filter(!_.invisible.getOrElse(false)).map { case (name, col) =>
|
||||||
|
th(
|
||||||
|
col.sortable.getOrElse(true).option(
|
||||||
|
attr("hx-get") := s"/admin/posts?sort=$name&dir=${toggleDir(pagination.sortDir)}",
|
||||||
|
attr("hx-target") := ".list-widget",
|
||||||
|
cls := "sortable"
|
||||||
|
),
|
||||||
|
col.label,
|
||||||
|
(pagination.sortColumn == name).option(
|
||||||
|
i(cls := s"sort-icon ${pagination.sortDir}")
|
||||||
|
)
|
||||||
|
)
|
||||||
|
}
|
||||||
|
)
|
||||||
|
),
|
||||||
|
tbody(
|
||||||
|
records.map { record =>
|
||||||
|
tr(
|
||||||
|
attr("hx-get") := s"/admin/posts/${record.id}/update",
|
||||||
|
attr("hx-target") := "#form-container",
|
||||||
|
td(cls := "list-checkbox",
|
||||||
|
input(`type` := "checkbox", attr("name") := "checked[]", attr("value") := record.id)
|
||||||
|
),
|
||||||
|
config.columns.filter(!_.invisible.getOrElse(false)).map { case (name, col) =>
|
||||||
|
td(renderColumnValue(col, name, record))
|
||||||
|
}
|
||||||
|
)
|
||||||
|
}
|
||||||
|
)
|
||||||
|
),
|
||||||
|
|
||||||
|
// Pagination
|
||||||
|
renderPagination(pagination)
|
||||||
|
)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## State of the Art
|
||||||
|
|
||||||
|
| Old Approach | Current Approach | When Changed | Impact |
|
||||||
|
|--------------|------------------|--------------|--------|
|
||||||
|
| jQuery AJAX forms | HTMX declarative | 2020+ | Simpler, less JS, server-rendered |
|
||||||
|
| PHP template YAML | Type-safe ADT parsing | N/A (new) | Compile-time validation |
|
||||||
|
| Runtime widget resolution | Registry pattern | Standard | Explicit, testable |
|
||||||
|
| Inline validation | Submit-only validation | Decision | Simpler UX, server authority |
|
||||||
|
|
||||||
|
**Deprecated/outdated:**
|
||||||
|
- Bootstrap 3 styles: Use modern CSS Grid/Flexbox
|
||||||
|
- jQuery plugins: Use vanilla JS or dedicated libraries
|
||||||
|
- Inline event handlers: Use HTMX data attributes
|
||||||
|
|
||||||
|
## Open Questions
|
||||||
|
|
||||||
|
1. **Lazy tab loading implementation**
|
||||||
|
- What we know: WinterCMS supports lazy tab loading via `lazy` config
|
||||||
|
- What's unclear: Best HTMX pattern for lazy content loading in tabs
|
||||||
|
- Recommendation: Use `hx-trigger="revealed"` on tab content divs
|
||||||
|
|
||||||
|
2. **Custom widget packaging**
|
||||||
|
- What we know: Plugins register widgets via boot lifecycle
|
||||||
|
- What's unclear: How to package widget assets (CSS/JS) with plugin
|
||||||
|
- Recommendation: Define asset bundling convention in plugin system phase
|
||||||
|
|
||||||
|
3. **RelationController modal form context**
|
||||||
|
- What we know: Modals need separate session keys and form contexts
|
||||||
|
- What's unclear: How to pass parent context to modal for deferred bindings
|
||||||
|
- Recommendation: Include session key in modal URL params; store in hidden field
|
||||||
|
|
||||||
|
## Sources
|
||||||
|
|
||||||
|
### Primary (HIGH confidence)
|
||||||
|
- WinterCMS reference implementation (`golem15-wintercms-starter/modules/backend/`)
|
||||||
|
- FormField.php - Field definition and trigger/preset handling
|
||||||
|
- Form.php - Form widget container and field rendering
|
||||||
|
- Lists.php - List widget with columns and pagination
|
||||||
|
- ListColumn.php - Column definition and value extraction
|
||||||
|
- FilterScope.php - Filter scope types and conditions
|
||||||
|
- Repeater.php - Repeater widget implementation
|
||||||
|
- RelationController.php - Relation management behavior
|
||||||
|
- [Circe-YAML GitHub](https://github.com/circe/circe-yaml) - YAML parsing documentation
|
||||||
|
- [ScalaTags Documentation](https://com-lihaoyi.github.io/scalatags/) - HTML generation
|
||||||
|
|
||||||
|
### Secondary (MEDIUM confidence)
|
||||||
|
- [HTMX Examples - Inline Validation](https://htmx.org/examples/inline-validation/) - Form validation patterns
|
||||||
|
- [Handling Form Errors in HTMX](https://dev.to/yawaramin/handling-form-errors-in-htmx-3ncg) - Error display patterns
|
||||||
|
- [Baeldung - Handling YAML in Scala 3](https://www.baeldung.com/scala/yaml-scala-3) - YAML library comparison
|
||||||
|
|
||||||
|
### Tertiary (LOW confidence)
|
||||||
|
- WebSearch results on schema-driven form generation patterns
|
||||||
|
- Community discussions on Scala YAML libraries
|
||||||
|
|
||||||
|
## Metadata
|
||||||
|
|
||||||
|
**Confidence breakdown:**
|
||||||
|
- Standard stack: HIGH - Based on official library docs and established patterns
|
||||||
|
- Architecture: HIGH - Based on thorough WinterCMS reference analysis
|
||||||
|
- Pitfalls: MEDIUM - Derived from WinterCMS patterns, may have Scala-specific issues
|
||||||
|
- Code examples: MEDIUM - Adapted from WinterCMS PHP patterns to Scala
|
||||||
|
|
||||||
|
**Research date:** 2026-02-05
|
||||||
|
**Valid until:** 2026-03-05 (30 days - stable domain)
|
||||||
Reference in New Issue
Block a user