Documentation
¶
Overview ¶
Package webui provides the embedded Next.js static export. Without the embed_frontend build tag, no frontend is included and the Go server only handles API routes (dev mode uses a separate `next dev` process on :3000).
Index ¶
Constants ¶
const ( DefaultSiteName = "HTCondor" DefaultSiteTagline = "Access Point" )
Default presentation, matching what the frontend hard-codes.
const CSSPath = "/branding.css"
CSSPath is where the site stylesheet is served, when there is one.
Variables ¶
This section is empty.
Functions ¶
func IsEmbedded ¶
func IsEmbedded() bool
IsEmbedded reports whether the frontend is compiled into this binary.
func NewSPAHandler ¶
NewSPAHandler returns an http.Handler that serves the embedded frontend. It resolves Next.js static-export dynamic routes (e.g. [id] -> _) and falls back to index.html for client-side routing.
When the frontend is not embedded (no embed_frontend build tag), the returned handler responds with 404 so the caller can fall back to a non-SPA welcome page.
func NewSPAHandlerFS ¶ added in v0.23.0
NewSPAHandlerFS serves a static export from an arbitrary fs.FS, with the same route resolution NewSPAHandler applies to the embedded frontend.
Site apps are served through this, from a zip bundle or from a directory rather than from embed.FS. That is what makes the path validation in serveFile load-bearing rather than belt-and-braces: embed.FS cannot reach anything outside the binary, and these filesystems can reach the real one.
Types ¶
type Branding ¶ added in v0.21.0
type Branding struct {
// SiteName is the sidebar heading, SiteTagline the line beneath it,
// and PageTitle the browser tab -- the two joined.
SiteName string `json:"site_name"`
SiteTagline string `json:"site_tagline"`
PageTitle string `json:"page_title"`
// Nil is the band the UI ships with (CHTC, Morgridge, UW-Madison);
// an empty list is no logos at all.
FooterLogos []Logo `json:"footer_logos"`
// SoftwareCredit asks the footer for its one-line "Powered by
// HTCondor" credit, naming the Center for High Throughput Computing.
// Set whenever the shipped logo band is not shown, so who wrote the
// software is still said on every page -- and distinguished from who
// runs the service, which is what the band above it says.
SoftwareCredit bool `json:"software_credit"`
// Favicon replaces the HTCondor mark in the browser tab.
Favicon string `json:"favicon,omitempty"`
// CustomCSS reports that this server serves a site stylesheet at
// /branding.css, loaded after the page's own.
CustomCSS bool `json:"custom_css,omitempty"`
// Rev changes whenever anything above does. It busts the injected
// HTML cache and the stylesheet's URL after a reconfigure.
Rev uint64 `json:"-"`
}
Branding is the resolved presentation of one deployment's web UI.
func Build ¶ added in v0.21.0
Build resolves configured values into a Branding.
Every part is independent, and a part that does not parse falls back to the shipped default rather than taking the rest of the branding down with it: a typo in the logo list should cost a site its logos, not its web UI. The error names every such fallback, for the caller to log.
func DefaultBranding ¶ added in v0.21.0
func DefaultBranding() Branding
DefaultBranding is the presentation of an unconfigured deployment.
func (Branding) Inject ¶ added in v0.21.0
Inject rewrites one exported HTML page to carry this branding.
Three edits, all inside <head>: the title, the favicon link, and a trailing block with the branding as a JavaScript global plus the site stylesheet. The stylesheet goes last on purpose -- it is loaded after the app's own, which is what lets a site redefine the --color-brand-* variables and recolour the whole UI.
A page with no </head> is returned untouched; there is no such page in the export, and guessing where to put the block would be worse than leaving the site unbranded.
type Logo ¶ added in v0.21.0
type Logo struct {
// Src is the image URL: site-relative ("/branding/af.svg", normally
// something out of HTTP_API_WEBUI_BRANDING_DIR) or absolute http(s).
Src string `json:"src"`
// Alt is the text a screen reader reads and a broken image shows.
// Required: an unlabelled institutional logo tells a blind user
// nothing about who runs the service.
Alt string `json:"alt"`
// Href, when set, makes the logo a link.
Href string `json:"href,omitempty"`
}
Logo is one image in the footer's institutional band.
func ParseLogos ¶ added in v0.21.0
ParseLogos reads the configured footer band.
Returns nil for an unset value -- the shipped band -- and a non-nil empty slice for "[]", which is a site saying it wants no logos.
type Option ¶ added in v0.21.0
type Option func(*spaHandler)
An Option configures the SPA handler.
func WithBranding ¶ added in v0.21.0
WithBranding gives the handler a source of site branding to splice into every HTML page it serves (see Branding.Inject). The function is called per request, so a reconfigure takes effect on the next page load; it may return the default branding, which injects nothing.
func WithHeadHTML ¶ added in v0.23.0
WithHeadHTML splices a fixed block into the head of every HTML page this handler serves.
Unlike branding, which an operator can change at runtime, this block is constant for the life of the handler: a site app is told its id and mount point, and those are properties of the bundle that was loaded. A reloaded bundle gets a new handler.
type Options ¶ added in v0.21.0
type Options struct {
SiteName string
SiteTagline string
// FooterLogos is a JSON array of {"src","alt","href"}. Empty keeps
// the shipped band; "[]" removes it.
Favicon string
// CustomCSS reports that HTTP_API_WEBUI_CUSTOM_CSS names a readable
// stylesheet. Resolving the path is the caller's job; this only
// decides whether the page links to it.
CustomCSS bool
}
Options are the raw configured values, as they come out of the configuration file.