Documentation
¶
Overview ¶
Package nethttp adapts ghtmx rendering to net/http handlers with opt-in automatic render-mode selection (FR-035).
Automatic selection is active only inside Render: htmx requests (HX-Request: true) receive the standalone fragment, every other request receives the full page. The core runtime never inspects request headers, and an application that imports no adapter keeps the fully supported explicit path — calling Render or RenderFragment itself (FR-034).
Defaults, and how to override them:
- Render mode: selected from HX-Request. Override with Mode.
- Status code: 200 via the response's first write. Override with Status, which calls WriteHeader before the body.
- Content-Type: set to "text/html; charset=utf-8" when the handler has not set one. Pre-set the header to override.
- htmx response headers: none. Opt in per response with Retarget, Reswap, Reselect, PushURL, and ReplaceURL; they apply only on htmx requests, where the headers have meaning. Headers outside the current swap (HX-Redirect, HX-Refresh, HX-Location, HX-Trigger emitters) are set before calling Render with the typed helpers in the root package and the generated event emitters.
Render streams: an error returned mid-render may leave the response partially written. The runtime's error is returned unchanged.
Index ¶
- func Render(w http.ResponseWriter, r *http.Request, f ghtmx.Fragment, opts ...Option) error
- func WithPage(page ghtmx.Component, fragment ghtmx.Fragment) ghtmx.Fragment
- type Option
- func Mode(m RenderMode) Option
- func PushURL(url string) Option
- func PushURLDisabled() Option
- func ReplaceURL(url string) Option
- func ReplaceURLDisabled() Option
- func Reselect(selector string) Option
- func Reswap(style ghtmx.SwapStyle, modifiers ...ghtmx.SwapModifier) Option
- func Retarget(selector string) Option
- func Status(code int) Option
- type RenderMode
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Render ¶
Render renders f in the mode selected for the request: standalone for htmx requests, full page otherwise (FR-035). It sets the status code and htmx response headers per the package defaults and the given options, then delegates to the runtime and returns its error unchanged.
Pass a generated standalone fragment when both modes render the same markup, or pair a page with its fragment via WithPage:
func show(w http.ResponseWriter, r *http.Request) {
page := ItemsPage(items)
row := ItemRowFragment(item.ID, item.Name)
if err := nethttp.Render(w, r, nethttp.WithPage(page, row)); err != nil {
// The response may be partially written by now, so a
// replacement error page cannot be sent reliably: log and
// let the client see the truncated response.
log.Printf("render /items: %v", err)
}
}
func WithPage ¶
WithPage pairs a full page with the fragment an htmx request should receive: the full-page mode renders page, the standalone mode renders only fragment. Generated standalone fragments render identically in both modes, so the pairing is what makes automatic selection choose between genuinely different responses.
Both arguments must be non-nil; WithPage panics immediately rather than mid-request.
Types ¶
type Option ¶
type Option func(*config)
Option configures one Render call.
When adding an option constructor, mirror it in every framework adapter under adapters/ — the chi module's parity test enforces that their sets stay complete.
func Mode ¶
func Mode(m RenderMode) Option
Mode overrides the automatic render-mode selection. It changes only what renders: htmx response headers still follow the request — an htmx request keeps them even under ModeFull, and a plain request never gets them, ModeStandalone or not.
func PushURL ¶
PushURL sets HX-Push-URL to push a URL into the browser history. Applied only on htmx requests.
func PushURLDisabled ¶
func PushURLDisabled() Option
PushURLDisabled sets HX-Push-URL: false, preventing a history entry. Applied only on htmx requests.
func ReplaceURL ¶
ReplaceURL sets HX-Replace-URL to replace the current URL in the browser location bar. Applied only on htmx requests.
func ReplaceURLDisabled ¶
func ReplaceURLDisabled() Option
ReplaceURLDisabled sets HX-Replace-URL: false, preventing the location-bar update. Applied only on htmx requests.
func Reselect ¶
Reselect sets HX-Reselect to choose the part of the response to swap in. Applied only on htmx requests.
func Reswap ¶
func Reswap(style ghtmx.SwapStyle, modifiers ...ghtmx.SwapModifier) Option
Reswap sets HX-Reswap to override the swap style. Applied only on htmx requests.
type RenderMode ¶
type RenderMode int
RenderMode is the render mode Render uses for a request.
const ( // ModeAuto selects from the request: htmx requests render // standalone, everything else renders the full page. ModeAuto RenderMode = iota // ModeFull always renders the full page. ModeFull // ModeStandalone always renders only the fragment. ModeStandalone )