boff

type Action ¶

type Action struct {
	Description    string // e.g. "Cancel item Sword-Pack"
	ButtonText     string // e.g. "Cancel"
	Endpoint       string // e.g. "/orders/backoffice/v1/orders/123/items/1/cancel"
	ConfirmMessage string // optional confirmation prompt; empty = submit immediately
	StatusText     string // non-empty = show label instead of button

	// true renders a link to Endpoint instead of a form, for an action that only
	// navigates. Ignores ConfirmMessage.
	Link bool

	// RequiredRole gates the whole action: "write" or "admin" means that role on
	// this service's own audience, "payment-service:admin" names another
	// audience. Empty means always shown. A viewer who may not perform the action
	// does not see it at all - a disabled button still tells a read-only user
	// which endpoint to curl.
	RequiredRole Role
}

Action is one row in the actions table on a backoffice page. When StatusText is non-empty the row renders a static label instead of a button (e.g. "Cancelled"); otherwise a plain HTML form that POSTs to Endpoint.

The page ships no JavaScript: the form is a form, and a ConfirmMessage renders a Bootstrap modal driven by Bootstrap's own JS. Endpoint must therefore be a URL the browser can resolve - a service behind backoffice builds it from the base path backoffice sends with the fragment request, not from its own internal path.

func (a Action) GatingRole() Role

type ActionsBlock ¶

type ActionsBlock []Action

ActionsBlock is an Action list rendered as the actions table. It gates itself at render time: the actions a viewer may not perform are dropped. Renders nothing when empty.

The slice is the block: boff.ActionsBlock{...} or a boff.ActionsBlock(actions) conversion both give you a Block.

func (b ActionsBlock) Render(rc RenderContext) (template.HTML, error)

type Block ¶

type Block interface {
	Render(rc RenderContext) (template.HTML, error)
}

Block is one renderable section of a page. Blocks are rendered top to bottom in the order given, so a page is just a slice of them. Providing your own Block is how you extend a page beyond its built-in sections without touching the page shell.

Render receives a RenderContext carrying the viewing identity and the shell template. A block gates itself here - it consults rc.May and emits only what the viewer may see. Because the context is passed on every call, a container block hands the same rc to its children, so gating and template resolution compose to any nesting depth.

A block is free to produce any HTML it likes. An empty block returns no bytes and is simply skipped.

func Blocks(children ...Block) Block

func FiltersBlock(filters []OverviewFilter) Block

func Gate(required Role, block Block) Block

func PagerBlock(m PagerModel) Block

func ScopeNoteBlock(note string) Block

func TableBlock(headers []string, rows []OverviewRow) Block

type BlockFunc ¶

type BlockFunc func(rc RenderContext) (template.HTML, error)

BlockFunc adapts a plain function to a Block, so a one-off block needs no named type.

func (f BlockFunc) Render(rc RenderContext) (template.HTML, error)

type CardBlock ¶

type CardBlock struct {
	Title    string
	Subtitle string
	Body     Block
	// Raised adds a small drop shadow (Bootstrap shadow-sm) to lift the card off
	// the page.
	Raised bool
}

CardBlock wraps a body block in a Bootstrap card with a title and optional subtitle. The body is itself a Block, rendered inline by the card template via the render func (RenderTemplate), with the same rc - so gating and nested blocks compose inside a card like anywhere else.

func (b CardBlock) Render(rc RenderContext) (template.HTML, error)

type DefaultOverviewBlocks ¶

type DefaultOverviewBlocks struct {
	Header    Block
	Filters   Block
	ScopeNote Block
	Pager     Block
	Table     Block
}

DefaultOverviewBlocks are the built-in blocks an overview page renders out of the box, handed to an OverviewConfig.Blocks callback so custom layouts can reuse them. Pager is shared by the top and bottom pager.

func (d DefaultOverviewBlocks) All() []Block

type FilterOption ¶

type FilterOption struct {
	Value string
	Label string
}

FilterOption is one entry of an OverviewFilter dropdown.

type HTMLBlock ¶

type HTMLBlock template.HTML

HTMLBlock is a block of pre-rendered HTML, for callers that want to drop in arbitrary markup without a template.

func (b HTMLBlock) Render(RenderContext) (template.HTML, error)

type HasRequiredRole ¶

type HasRequiredRole interface {
	GatingRole() Role
}

HasRequiredRole is implemented by anything a viewer can be gated against - an Action, a NavLink. GateSlice uses it to drop the entries a viewer may not see, so a new gated element type only has to report its role, not its own filter.

type HeaderBlock ¶

type HeaderBlock struct {
	Title        string
	Subtitle     string
	ErrorMessage string
}

HeaderBlock is the page heading: an h1 title, an optional monospace subtitle, and an optional error alert. It was the shell's built-in header; as a block a page places it wherever it likes (or drops it), for full control of the page layout.

func (b HeaderBlock) Render(rc RenderContext) (template.HTML, error)

type NavBlock ¶

type NavBlock []NavLink

NavBlock is a NavLink list rendered as a <nav> bar. It gates itself at render time: the links a viewer may not follow are dropped. Renders nothing when empty.

The slice is the block: boff.NavBlock{...} or a boff.NavBlock(links) conversion both give you a Block.

func (b NavBlock) Render(rc RenderContext) (template.HTML, error)

type NavLink ¶

type NavLink struct {
	Label  string // e.g. "Orders"
	Href   string // e.g. "/orders/backoffice/v1/orders"
	Active bool   // true renders the current page's entry as active

	// RequiredRole gates the link, in the same notation as Action.RequiredRole. A
	// viewer who lacks the role does not see the entry at all - a nav link is a
	// pointer to a page, and pointing a read-only user at a page they cannot open
	// is noise.
	RequiredRole Role
}

NavLink is one entry of a NavBlock: a labelled link in the page's navigation bar. Active marks the current page, so the nav can highlight where the viewer is.

func (l NavLink) GatingRole() Role

type OverviewCell ¶

type OverviewCell struct {
	Text string
	Link string
}

OverviewCell is one table cell with its optional own link.

type OverviewConfig ¶

type OverviewConfig struct {
	Title     string
	Headers   []string
	Rows      []OverviewRow
	Filters   []OverviewFilter
	ScopeNote string

	// Page is the 1-based page number shown; 0 and 1 both mean the first page.
	// HasNext tells the pager that another page exists - the caller knows this by
	// loading one row more than it displays, so no count query is needed.
	Page    int
	HasNext bool
	// TotalPages enables the jump to the last page. Leave it 0 when counting the
	// whole result set is not worth a second query; the pager then only walks.
	TotalPages int

	// Blocks overrides the sections rendered on the page. When nil the page uses
	// its default layout: FiltersBlock, ScopeNoteBlock, a PagerBlock, TableBlock
	// and a trailing PagerBlock built from the fields above. When set, the
	// callback receives those default blocks and returns the blocks to render in
	// order - so a caller can reorder them, drop one, or splice its own Block in.
	Blocks func(defaults DefaultOverviewBlocks) []Block
}

OverviewConfig bundles everything the overview page renders.

type OverviewFilter ¶

type OverviewFilter struct {
	Label       string
	Name        string
	Value       string
	Placeholder string
	// Type is the HTML input type; empty means "text". "date" gets the browser's
	// own date picker, no JavaScript needed.
	Type string
	// Options, when non-empty, renders a <select> instead of an input. The empty
	// value must be part of the list to allow "no filter".
	Options []FilterOption
	// Hidden keeps the value in the form and in the pagination links without
	// showing a control - for a filter the page receives from elsewhere (a deep
	// link carrying a player id) rather than one the viewer types.
	Hidden bool
}

OverviewFilter is one field of the overview filter form. Value is the currently applied value, echoed back so the form stays sticky.

func (f OverviewFilter) InputType() string

type OverviewRow ¶

type OverviewRow struct {
	Link      string
	Cells     []string
	CellLinks []string
}

OverviewRow is one list entry; Cells aligns with the overview Headers.

Link makes the whole row navigate to one detail page. CellLinks instead links individual cells (index-aligned with Cells, empty entry = plain text), which is what a table with several targets needs - an id column pointing at this service's detail page, a foreign id pointing at the owning service. A cell link is rendered as a visible link; a row link stays inconspicuous.

func (r OverviewRow) CellAt(i int) OverviewCell

type PagerModel ¶

type PagerModel struct {
	Page       int
	TotalPages int
	FirstLink  string
	PrevLink   string
	NextLink   string
	LastLink   string
}

PagerModel is the pagination state a PagerBlock renders. Both pagers (above and below the table) render the same model. The Link fields are empty when there is no such page.

type RenderConfig ¶

type RenderConfig struct {
	Title  string
	Viewer *jwt.Identity
	Blocks []Block
}

RenderConfig is the caller-supplied config for the shell. Title feeds the document <title>; the visible page heading is a HeaderBlock a page adds to Blocks. Blocks are rendered into the shell body in order.

Viewer is the identity the page's gated blocks filter themselves against. It is put into the RenderContext each block renders with. Leave it nil to fail closed - every gated element is then hidden. Use ViewerOf to derive it from the request context.

type RenderContext ¶

type RenderContext struct {
	// Viewer is the identity gated blocks filter themselves against. Nil means
	// fail closed: May reports false for everything gated.
	Viewer *jwt.Identity
}

RenderContext carries everything a Block needs while it renders - currently the viewing identity to gate against. It is passed to every Block.Render, including nested ones: a container block hands its own rc straight to its children, so gating reaches any depth.

It is a struct (not a bare *jwt.Identity) so more render-time values can be propagated later - a base path for URL building, a nonce, feature flags - without churning the Block interface again.

func (rc RenderContext) May(required Role) bool

type Role ¶

type Role string

Role names the permission a gated element requires, in the notation the whole package shares: "write" or "admin" means that role on this service's own audience; "payment-service:admin" names a role on a foreign audience. The empty Role is ungated - always shown.

func RoleOf(audience, role string) Role

type SummaryBlock ¶

type SummaryBlock []SummaryItem

SummaryBlock is a SummaryItem list rendered as the current-state summary card. It gates itself at render time: the links a viewer may not follow are demoted to plain values. Renders nothing when empty.

The slice is the block: boff.SummaryBlock{...} or a boff.SummaryBlock(items) conversion both give you a Block.

func (b SummaryBlock) Render(rc RenderContext) (template.HTML, error)

type SummaryItem ¶

type SummaryItem struct {
	Label string
	Value string
	// Link, when non-empty, renders Value as an <a href> to this URL instead of
	// plain text - e.g. a cross-service backoffice link to the page that owns the
	// referenced entity (a payment or draw history page behind the api-gateway).
	Link string

	// RequiredRole gates the Link only, in the same notation as
	// Action.RequiredRole. A denied item still shows Label and Value, just not as
	// an anchor: the value itself is not the secret, the page behind it is.
	RequiredRole Role
}

SummaryItem is one label/value row shown above the page content, describing the current state of the tracked object. Ordered slice (not a map) so the page renders stably.

type TemplateBlock ¶

type TemplateBlock struct {
	Name     string
	Model    any
	Empty    bool
	Template *template.Template
}

TemplateBlock renders a named (sub-)template with a model. It is the common shape of the built-in blocks and the easiest way to add your own: give it the Name of a template and a Model to execute it with.

Template must contain a definition for Name. The built-in blocks set it to the package shell, so they resolve the sub-templates defined alongside the shell. Set Empty to render nothing, which is how a section vanishes when it has no content.

func (b TemplateBlock) Render(rc RenderContext) (template.HTML, error)