gamertan
206d09e4cd
verify / verify (push) Successful in 2m58s
Sanitized snapshot of private source 144ca0a9544042b0477ae732c1356cf0b9d62b3f. Add package selection, adoption workflow, and optional Sandwich Hime integration guidance. AI-Assistance: OpenAI Codex assisted documentation, verification, and publication. Signed-off-by: Cole Speelman <crspeelman@gmail.com>
72 lines
2.9 KiB
Markdown
72 lines
2.9 KiB
Markdown
<!-- SPDX-License-Identifier: MPL-2.0 -->
|
|
|
|
# HTML with Sandwich Hime
|
|
|
|
Gamertan Web Foundations owns reusable web-application boundaries; it does not
|
|
own HTML or a template language. [Sandwich Hime](https://sandwichhime.com/) is
|
|
the preferred companion for Gamertan applications that want HTML-first,
|
|
ahead-of-time templates with typed Go composition.
|
|
|
|
The relationship is intentionally optional:
|
|
|
|
| Application responsibility | Owner |
|
|
| --- | --- |
|
|
| Request identity, logging, security primitives, sessions, and analytics | Web Foundations packages selected by the application |
|
|
| Routing, authorization decisions, status, headers, caching, and deployment | The application |
|
|
| Visible HTML and typed component composition | Authored `.sando` templates |
|
|
| Template parsing, contextual analysis, and Go generation | Hime-san during development or CI |
|
|
| Rendering generated components | The small `sando` runtime in production |
|
|
|
|
Web Foundations does not import Sandwich Hime. Sandwich Hime does not import
|
|
Web Foundations. An application chooses both and provides the seam between
|
|
them.
|
|
|
|
## Request flow
|
|
|
|
```text
|
|
request
|
|
-> requestmeta / selected middleware
|
|
-> application router and handler
|
|
-> typed view data
|
|
-> generated Sandwich Hime component
|
|
-> buffered sando.Render
|
|
-> application-owned HTTP response
|
|
```
|
|
|
|
Buffer the component before committing a successful response so a rendering
|
|
error can still become a clean application error:
|
|
|
|
```go
|
|
func renderHTML(response http.ResponseWriter, request *http.Request, status int, component sando.Component) {
|
|
var output bytes.Buffer
|
|
if err := sando.Render(request.Context(), &output, component); err != nil {
|
|
log.Printf("render page: %v", err)
|
|
response.Header().Set("Cache-Control", "no-store")
|
|
http.Error(response, "could not render page", http.StatusInternalServerError)
|
|
return
|
|
}
|
|
response.Header().Set("Content-Type", "text/html; charset=utf-8")
|
|
response.WriteHeader(status)
|
|
_, _ = response.Write(output.Bytes())
|
|
}
|
|
```
|
|
|
|
The handler—not the template—should interpret request metadata, principals,
|
|
permissions, analytics, or storage errors. It passes only the resulting typed
|
|
display data into the component. Templates should not acquire an implicit
|
|
request global or turn middleware context into an inheritance framework.
|
|
|
|
Handwritten `sando.Component` implementations and `Trust*` values are explicit
|
|
trusted-output capabilities. Keep them conspicuous and review them separately
|
|
from ordinary untrusted values.
|
|
|
|
## Continue with the official lessons
|
|
|
|
- [Build a component, page, and small site](https://sandwichhime.com/docs/tutorial/).
|
|
- [Follow a request through a larger Go application](https://sandwichhime.com/docs/tutorial/application/).
|
|
- [Review the Sandwich Hime security boundary](https://sandwichhime.com/docs/security/).
|
|
|
|
Those tutorials own the template syntax and compiler workflow. This repository
|
|
documents only the application seam so the two projects do not drift into a
|
|
single mandatory framework.
|