README
¶
Work in progress
- Design the package
Roadmap
- Define a general template
- Define a general template context structure
- Consider some general values, like request path, etc.
- Not going to define one, at least for v1.
- Consider some general functions, etc.
- Not going to define one, at least for v1.
- Consider some general values, like request path, etc.
- Define a package api style (builder?, factory?, server?)
- constructors and plugins.
- Allow dev to serve
- static files
- simple filenames
- path patterns
- path mapping to a directory with a '404' file results in a 404 response.
-
runtime generated html - non-html template assets
- static files
- Allow devs to escape the htmplx framework
-
Check for runtime handlers before return 404. - ...
-
- HTMX support
- When given a GET request with the HX-Request, just find and compile the fragment.html.tmpl file at the path.
Usage
Simple.
Given a directory, or fs.FS, htmplx provides an http.Handler.
That http.Handler, when used with any http.Server, simply serves *.html.tmpl files from that directory or any subdirectories.
Those files should be html go templates.
Requirements
Each directory corresponding to a valid url must have a body.html.tmpl file or must have one defined in a parent directory.
All incoming http requests will be matched against a directory by http pattern. The directory must contain a head.html.tmpl and body.html.tmpl, with some exceptions. Each html template, head.html.tmpl and body.html.tmpl, will be resolved with an application context, and their resulting context appended to the and tags, respectively.
Layout Templates
An exception to each directory served must contain a head.html.tmpl and body.html.tmpl is if a parent directory contains one of these files, in which case the parent directory's template will be used if the respective template is not defined in the directory. This behavior is intended to allow for content or structure to be shared between pages.
Parent Content Templates
Minimized Templates
Using shared layout templates, unlocks a powerful feature, minimized templates. Minimized templates are merely templates not names head.html.tmpl or body.html.tmpl and declared in a shared layout template in a parent directory. Here's an example.
/static/dogs/head.html.tmpl
/static/dogs/body.html.tmpl
/static/dogs/terrier/title.html.tmpl
/static/dogs/terrier/content.html.tmpl
/static/dogs/doodle/title.html.tmpl
/static/dogs/doodle/content.html.tmpl
/static/dogs/head.html.tmpl
{{define "title"}}{{Dogs}}{{end-}}
<title>{{template "title"}}</title>
/static/dogs/body.html.tmpl
{{define "header"}}{{}}{{end-}}
{{define "content"}}{{This page is about a kind of dog}}{{end-}}
{{define "footer"}}{{}}{{end-}}
{{template "header"}}
{{template "content"}}
{{template "footer"}}
/static/dogs/terrier/title.html.tmpl
Terriers
/static/dogs/terrier/header.html.tmpl
JUST A HEADER
/static/dogs/terrier/content.html.tmpl
<em>Terriers are great!</em>
/static/dogs/terrier/footer.html.tmpl
JUST A FOOTER
/static/dogs/doodle/title.html.tmpl
Doodles
/static/dogs/doodle/header.html.tmpl
JUST A HEADER
/static/dogs/doodle/content.html.tmpl
<em>Doodles are great!</em>
/static/dogs/doodle/footer.html.tmpl
JUST A FOOTER
With this a request to GET /docs/doodle should result in the html
<DOCTYPE html>
<head>
<title>Doodle</title>
</head>
<body>
JUST A HEADER
<em>Doodles are great!</em>
JUST A FOOTER
</body>
API Design
The dev should get a http.Handler out of htmplx. The dev should be able to any combination of static file serving and generated html per route.
application -...-> htmplx
application <-http.Handler- htmplx
Generated HTML
Each request should result in a single html generating function call.
type HttpPattern string
type HTML string
type HTMLBuilder func(http.ResponseWriter, *http.Request) (HTML, error)
application -map[HttpPattern]HTMLBuilder-> htmplx
application <-http.Handler- htmplx
TODO: what to do about requests that should not result in html?
Static HTML
Each request should result in a file look up.
application -dir-> htmplx
application <-http.Handler (file server)- htmplx
Design
General Usage
Template Resolution
Documentation
¶
Index ¶
- type DirEntryWithSubmatches
- type Handler
- func (h *Handler[D]) ServeFile(r *http.Request) (out io.Reader, contentType string, err error)
- func (h *Handler[D]) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (h *Handler[D]) WithData(data func(*http.Request) D) *Handler[D]
- func (h *Handler[D]) WithFuncs(funcs func(*http.Request) template.FuncMap) *Handler[D]
- type KeyValuePair
- type PathExpressionSubmatches
- type RequestData
- type RequestDataMap
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DirEntryWithSubmatches ¶
type DirEntryWithSubmatches struct {
File fs.FileInfo
Submatches []KeyValuePair
}
type Handler ¶
type Handler[D RequestData] struct { // contains filtered or unexported fields }
func NewHandler ¶
func NewHandler[D RequestData](dir fs.FS) *Handler[D]
func NewHandlerForDirectory ¶
func NewHandlerForDirectory[D RequestData](dir string) *Handler[D]
type KeyValuePair ¶
type PathExpressionSubmatches ¶
PathExpressionSubmatches satisfies RequestData. An alternative to RequestDataMap. Embed into a struct type to satisfy RequestData and capture path expression submatches.
func (PathExpressionSubmatches) SetPathExpressionSubmatches ¶
func (m PathExpressionSubmatches) SetPathExpressionSubmatches(matches []DirEntryWithSubmatches)
type RequestData ¶
type RequestData interface {
SetPathExpressionSubmatches(matches []DirEntryWithSubmatches)
}
type RequestDataMap ¶
RequestDataMap satisfies RequestData.
func (RequestDataMap) SetPathExpressionSubmatches ¶
func (d RequestDataMap) SetPathExpressionSubmatches(matches []DirEntryWithSubmatches)
Source Files
Directories
