README
¶
github.com/linkdata/jaws/lib/ui
This package is the home of JaWS widget implementations.
Goals
- Keep widget logic out of JaWS core request/session internals.
- Make new widget authoring local to this package.
- Provide short widget naming (
ui.Span,ui.NewSpan). - Expose template context types (
ui.RequestWriter,ui.With).
RequestWriter helper calls
ui.RequestWriter exposes helper methods like rw.Span(...),
rw.Text(...), and rw.Select(...) for concise template use.
You can also use explicit constructors through:
rw.UI(ui.NewX(...), params...)
Examples:
rw.UI(ui.NewDiv(bind.MakeHTMLGetter("content")))
rw.UI(ui.NewCheckbox(myBoolSetter), "disabled")
rw.UI(ui.NewRange(myFloatSetter))
Building blocks
HTMLInner- For tags like
<div>...</div>,<span>...</span>,<td>...</td>.
- For tags like
Input,InputText,InputBool,InputFloat,InputDate- For interactive inputs with typed parse/update behavior.
ContainerHelper- For widgets that render and maintain dynamic child lists.
Widget lifetime
UI widget values are render-scoped. Construct them during rendering, typically
through RequestWriter helpers such as $.Container(...) and $.Tbody(...).
Do not cache and reuse *ui.Container / *ui.Tbody instances across requests.
Those widgets keep internal render/update bookkeeping and are intended to be
created fresh for each render.
Adding a simple static widget
Use HTMLInner:
type Article struct{ ui.HTMLInner }
func NewArticle(inner bind.HTMLGetter) *Article {
return &Article{HTMLInner: ui.HTMLInner{HTMLGetter: inner}}
}
func (w *Article) JawsRender(e *jaws.Element, wr io.Writer, params []any) error {
return w.renderInner(e, wr, "article", "", params)
}
Adding an interactive input widget
Use one of the typed input bases:
InputTextfor string-based inputsInputBoolfor boolean inputsInputFloatfor numeric inputsInputDatefortime.Timeinputs
Each base handles:
- tracking last rendered value
- receiving
what.Input - applying dirty tags on successful set
- update-driven
SetValuepushes
Adding a container widget
Use ContainerHelper:
type UList struct{ ui.ContainerHelper }
func NewUList(c jaws.Container) *UList {
return &UList{ContainerHelper: ui.NewContainerHelper(c)}
}
func (w *UList) JawsRender(e *jaws.Element, wr io.Writer, params []any) error {
return w.RenderContainer(e, wr, "ul", params)
}
func (w *UList) JawsUpdate(e *jaws.Element) {
w.UpdateContainer(e)
}
Container error behavior
ContainerHelper treats child render/update failures as application bugs.
- During initial render, child render failures are returned as errors.
- During updates, append render failures are reported through
MustLog(and may panic if no logger is configured). - After such failures, partial DOM/request state updates are expected; state may remain inconsistent until a subsequent full render/reload.
Documentation
¶
Overview ¶
Package ui contains the standard JaWS widget implementations.
The package is intentionally organized around extension-oriented building blocks so new widgets can be authored here without reading JaWS core code:
- `HTMLInner`: base renderer for tags with inner HTML content.
- `Input`, `InputText`, `InputBool`, `InputFloat`, `InputDate`: typed input helpers that handle event/update flow.
- `ContainerHelper`: helper for widgets that render dynamic child UI lists.
Naming follows short widget names (`Span`, `NewSpan`) instead of the legacy core names (`UiSpan`, `NewUiSpan`).
Index ¶
- Variables
- func Clickable(innerHTML any, onclick func(elem *jaws.Element, click jaws.Click) (err error)) jaws.ClickHandlerdeprecated
- func Handler(jw *jaws.Jaws, name string, dot any) http.Handler
- type A
- type Button
- type Checkbox
- type ClickedHook
- type Container
- type ContainerHelper
- type ContextMenuHook
- type Date
- type Div
- type HTMLInner
- type Img
- type InitialHTMLAttrHook
- type Input
- type InputBool
- type InputDate
- type InputFloat
- type InputText
- type IsJsVar
- type JsVar
- func (ui *JsVar[T]) JawsEvent(e *jaws.Element, wht what.What, val string) (err error)
- func (ui *JsVar[T]) JawsGet(elem *jaws.Element) (value T)
- func (ui *JsVar[T]) JawsGetPath(elem *jaws.Element, jspath string) (value any)
- func (ui *JsVar[T]) JawsGetTag(tag.Context) any
- func (ui *JsVar[T]) JawsRender(e *jaws.Element, w io.Writer, params []any) (err error)
- func (ui *JsVar[T]) JawsSet(elem *jaws.Element, value T) (err error)
- func (ui *JsVar[T]) JawsSetPath(elem *jaws.Element, jspath string, value any) (err error)
- func (ui *JsVar[T]) JawsUpdate(e *jaws.Element)
- type JsVarMaker
- type Label
- type Li
- type Number
- type Object
- type Option
- type Password
- type PathSetter
- type Radio
- type RadioElement
- type Range
- type Register
- type RequestWriter
- func (rw RequestWriter) A(innerHTML any, params ...any) error
- func (rw RequestWriter) Button(innerHTML any, params ...any) error
- func (rw RequestWriter) Checkbox(value any, params ...any) error
- func (rw RequestWriter) Container(outerHTMLTag string, c jaws.Container, params ...any) error
- func (rw RequestWriter) Date(value any, params ...any) error
- func (rw RequestWriter) Div(innerHTML any, params ...any) error
- func (rqw RequestWriter) Get(key string) (val any)
- func (rqw RequestWriter) HeadHTML() error
- func (rw RequestWriter) Img(imageSrc any, params ...any) error
- func (rqw RequestWriter) Initial() *http.Request
- func (rqw RequestWriter) JsVar(jsvarname string, jsvar any, params ...any) (err error)
- func (rw RequestWriter) Label(innerHTML any, params ...any) error
- func (rw RequestWriter) Li(innerHTML any, params ...any) error
- func (rw RequestWriter) Number(value any, params ...any) error
- func (rw RequestWriter) Password(value any, params ...any) error
- func (rw RequestWriter) Radio(value any, params ...any) error
- func (rw RequestWriter) RadioGroup(nba *named.BoolArray) (rel []RadioElement)
- func (rw RequestWriter) Range(value any, params ...any) error
- func (rqw RequestWriter) Register(updater jaws.Updater, params ...any) jid.Jid
- func (rw RequestWriter) Select(sh named.SelectHandler, params ...any) error
- func (rqw RequestWriter) Session() *jaws.Session
- func (rqw RequestWriter) Set(key string, val any)
- func (rw RequestWriter) Span(innerHTML any, params ...any) error
- func (rqw RequestWriter) TailHTML() error
- func (rw RequestWriter) Tbody(c jaws.Container, params ...any) error
- func (rw RequestWriter) Td(innerHTML any, params ...any) error
- func (rqw RequestWriter) Template(name string, dot any, params ...any) error
- func (rw RequestWriter) Text(value any, params ...any) error
- func (rw RequestWriter) Textarea(value any, params ...any) error
- func (rw RequestWriter) Tr(innerHTML any, params ...any) error
- func (rqw RequestWriter) UI(ui jaws.UI, params ...any) (err error)
- func (rqw RequestWriter) Write(p []byte) (n int, err error)
- type Select
- type SetPather
- type Span
- type Tbody
- type Td
- type Template
- type Text
- type Textarea
- type Tr
- type With
Constants ¶
This section is empty.
Variables ¶
var ErrIllegalJsVarName errIllegalJsVarName
ErrIllegalJsVarName is returned when a JsVar name is missing, not a string, or does not follow valid top-level identifier syntax.
var ErrJsVarArgumentType = errors.New("expected jaws.UI or JsVarMaker")
ErrJsVarArgumentType is returned when RequestWriter.JsVar receives an argument that is neither a jaws.UI nor a JsVarMaker.
var ErrMissingTemplate errMissingTemplate
ErrMissingTemplate is returned when trying to render an undefined template by name.
Functions ¶
func Clickable
deprecated
added in
v0.304.0
func Clickable(innerHTML any, onclick func(elem *jaws.Element, click jaws.Click) (err error)) jaws.ClickHandler
Clickable returns an object implementing bind.HTMLGetter, jaws.ClickHandler and jaws.TagGetter. innerHTML is passed to MakeHTMLGetter(), which may or may not provide tags.
Deprecated: use New(innerHTML).Clicked(...) directly.
Types ¶
type Button ¶
type Button struct{ HTMLInner }
func NewButton ¶
func NewButton(innerHTML bind.HTMLGetter) *Button
type ClickedHook ¶ added in v0.400.0
ClickedHook is a function to call when a click event is received.
type Container ¶
type Container struct {
OuterHTMLTag string
ContainerHelper
}
func (*Container) JawsRender ¶
func (*Container) JawsUpdate ¶
type ContainerHelper ¶
type ContainerHelper struct {
Container jaws.Container
Tag any
// contains filtered or unexported fields
}
ContainerHelper is a helper for widgets that render dynamic child collections.
It tracks previously rendered child elements and performs append/remove/order updates during JawsUpdate.
A ContainerHelper belongs to a widget instance and is intended for render-scoped widget lifetimes (for example widgets created via RequestWriter helper methods).
Error model: Child render/update failures are treated as application bugs. Initial-render errors are returned to the caller, and update-time append render errors are reported through MustLog (which may panic when no logger is configured). After such failures, DOM and request-tracked element state may be partially updated and therefore inconsistent until the next full render/reload.
func NewContainerHelper ¶
func NewContainerHelper(c jaws.Container) ContainerHelper
func (*ContainerHelper) RenderContainer ¶
func (*ContainerHelper) UpdateContainer ¶
func (ui *ContainerHelper) UpdateContainer(e *jaws.Element)
type ContextMenuHook ¶ added in v0.400.0
ContextMenuHook is a function to call when a context menu event is received.
type HTMLInner ¶
type HTMLInner struct {
HTMLGetter bind.HTMLGetter
}
HTMLInner is a reusable base for widgets that render as `<tag>inner</tag>`.
func (*HTMLInner) JawsUpdate ¶
type InitialHTMLAttrHook ¶ added in v0.400.0
InitialHTMLAttrHook is a function to call when an Element is initially rendered.
type Input ¶
Input stores common state for interactive input widgets. There is one of these per request and input widget.
type InputFloat ¶
func (*InputFloat) JawsUpdate ¶
func (ui *InputFloat) JawsUpdate(e *jaws.Element)
type IsJsVar ¶
type IsJsVar interface {
bind.RWLocker
jaws.UI
jaws.EventHandler
PathSetter
}
type JsVar ¶
func NewJsVar ¶
NewJsVar creates a JsVar over v protected by l.
The locker l must be non-nil and must remain valid for the lifetime of the JsVar.
func (*JsVar[T]) JawsGetPath ¶
func (*JsVar[T]) JawsRender ¶
func (*JsVar[T]) JawsSetPath ¶
func (*JsVar[T]) JawsUpdate ¶
type JsVarMaker ¶
type Label ¶
type Label struct{ HTMLInner }
func NewLabel ¶
func NewLabel(innerHTML bind.HTMLGetter) *Label
type Number ¶
type Number struct{ InputFloat }
type Object ¶ added in v0.400.0
type Object interface {
bind.HTMLGetter
tag.TagGetter
jaws.ClickHandler
jaws.ContextMenuHandler
jaws.InitialHTMLAttrHandler
// Clicked returns an Object that will call fn when JawsClick is invoked.
Clicked(fn ClickedHook) (newobj Object)
// ContextMenu returns an Object that will call fn when JawsContextMenu
// is invoked.
ContextMenu(fn ContextMenuHook) (newobj Object)
// InitialHTMLAttr returns an Object that will call fn when
// JawsInitialHTMLAttr is invoked.
InitialHTMLAttr(fn InitialHTMLAttrHook) (newobj Object)
}
type PathSetter ¶
type RadioElement ¶
type RadioElement struct {
// contains filtered or unexported fields
}
type Range ¶
type Range struct{ InputFloat }
type RequestWriter ¶
func (RequestWriter) Get ¶
func (rqw RequestWriter) Get(key string) (val any)
Get calls Request().Get()
func (RequestWriter) HeadHTML ¶
func (rqw RequestWriter) HeadHTML() error
HeadHTML outputs the HTML code needed in the HEAD section.
func (RequestWriter) Initial ¶
func (rqw RequestWriter) Initial() *http.Request
Initial returns the initial http.Request.
func (RequestWriter) JsVar ¶
func (rqw RequestWriter) JsVar(jsvarname string, jsvar any, params ...any) (err error)
JsVar binds a JsVar[T] to a named Javascript variable.
You can also pass a JsVarMaker instead of a JsVar[T].
func (RequestWriter) RadioGroup ¶
func (rw RequestWriter) RadioGroup(nba *named.BoolArray) (rel []RadioElement)
func (RequestWriter) Register ¶
Register creates a new Element with the given Updater as a tag for dynamic updates. Additional tags may be provided in params. The updaters JawsUpdate method will be called immediately to ensure the initial rendering is correct.
Returns a Jid, suitable for including as a HTML "id" attribute:
<div id="{{$.Register .MyUpdater}}">...</div>
func (RequestWriter) Select ¶
func (rw RequestWriter) Select(sh named.SelectHandler, params ...any) error
func (RequestWriter) Session ¶
func (rqw RequestWriter) Session() *jaws.Session
Session returns the Requests's Session, or nil.
func (RequestWriter) Set ¶
func (rqw RequestWriter) Set(key string, val any)
Set calls Request().Set()
func (RequestWriter) TailHTML ¶
func (rqw RequestWriter) TailHTML() error
TailHTML writes optional HTML code at the end of the page's BODY section that will immediately apply updates made during initial rendering.
type Select ¶
type Select struct {
ContainerHelper
}
func NewSelect ¶
func NewSelect(sh named.SelectHandler) *Select
func (*Select) JawsRender ¶
func (*Select) JawsUpdate ¶
type Span ¶
type Span struct{ HTMLInner }
func NewSpan ¶
func NewSpan(innerHTML bind.HTMLGetter) *Span
type Tbody ¶
type Tbody struct {
ContainerHelper
}
func (*Tbody) JawsRender ¶
func (*Tbody) JawsUpdate ¶
type Template ¶
type Template struct {
Name string // Template name to be looked up using Jaws.LookupTemplate()
Dot any // Dot value to place in With structure
}
Template references a Go html/template to be rendered through JaWS.
The Name field identifies the template to execute and Dot contains the data that will be exposed to the template through the With structure constructed during rendering. Additional tag bindings and event handlers can be supplied at render time through the RequestWriter.Template helper.
func NewTemplate ¶
NewTemplate constructs a Template with the provided name and data value.
It is a small helper that makes it convenient to use Template values with other JaWS helpers without having to fill the struct fields manually.
func (Template) JawsRender ¶
func (Template) JawsUpdate ¶
type With ¶
type With struct {
*jaws.Element // the Element being rendered using a template.
RequestWriter // the RequestWriter
Dot any // user data parameter
Attrs template.HTMLAttr // HTML attributes string
Auth jaws.Auth // (optional) authentication information returned by MakeAuthFn
}
With is passed as the data parameter when using RequestWriter.Template(), populated with all required members set.
Source Files
¶
- a.go
- button.go
- checkbox.go
- clickable.go
- common.go
- container.go
- containerhelper.go
- date.go
- div.go
- doc.go
- errjsvar.go
- errmissingtemplate.go
- handler.go
- html_widgets.go
- img.go
- input_widgets.go
- jsvar.go
- label.go
- li.go
- number.go
- object.go
- option.go
- password.go
- radio.go
- radiogroup.go
- range.go
- register.go
- requestwriter.go
- rwlocker.go
- select.go
- span.go
- tbody.go
- td.go
- template.go
- text.go
- textarea.go
- tr.go
- with.go