nethttp

package
v0.1.21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 21, 2026 License: Apache-2.0 Imports: 4 Imported by: 5

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func Render

func Render(w http.ResponseWriter, r *http.Request, f ghtmx.Fragment, opts ...Option) error

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

func WithPage(page ghtmx.Component, fragment ghtmx.Fragment) ghtmx.Fragment

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

func PushURL(url string) Option

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

func ReplaceURL(url string) Option

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

func Reselect(selector string) Option

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.

func Retarget

func Retarget(selector string) Option

Retarget sets HX-Retarget so htmx swaps into the selector instead of the requesting element's target. Applied only on htmx requests.

func Status

func Status(code int) Option

Status sets the HTTP status code instead of the implicit 200.

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
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL