jaws

package module
v0.106.3 Latest Latest
Warning

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

 Go to latest Published: Feb 13, 2025 License: MIT Imports: 35 Imported by: 7

README

build coverage goreport Docs

JaWS

Javascript and WebSockets used to create responsive webpages.

  • Moves web application state fully to the server.
  • Does not trust the web browser or the Javascript.
  • Binds application data to UI elements using user-definable 'tags'.

There is a demo application with plenty of comments to use as a tutorial.

Usage

import (
	"html/template"
	"log/slog"
	"net/http"

	"github.com/linkdata/jaws"
)

const indexhtml = `
<html>
<head>{{$.HeadHTML}}</head>
<body>{{$.Range .Dot}}</body>
</html>
`

func main() {
	jw := jaws.New()           // create a default JaWS instance
	defer jw.Close()           // ensure we clean up
	jw.Logger = slog.Default() // optionally set the logger to use

	// parse our template and inform JaWS about it
	templates := template.Must(template.New("index").Parse(indexhtml))
	jw.AddTemplateLookuper(templates)

	go jw.Serve()                             // start the JaWS processing loop
	http.DefaultServeMux.Handle("/jaws/", jw) // ensure the JaWS routes are handled

	var f jaws.Float // somewhere to store the slider data
	http.DefaultServeMux.Handle("/", jw.Handler("index", &f))
	slog.Error(http.ListenAndServe("localhost:8080", nil).Error())
}
Creating HTML entities

When JawsRender() is called for a UI object, it can call NewElement() to create new Elements while writing their initial HTML code to the web page. Each Element is a unique instance of a UI object bound to a specific Request, and will have a unique HTML id.

If a HTML entity is not registered in a Request, JaWS will not forward events from it, nor perform DOM manipulations for it.

Dynamic updates of HTML entities is done using the different methods on the Element object when the JawsUpdate() method is called.

Javascript events

Supported Javascript events are sent to the server and are handled by the Element's UI type. If that didn't handle the event, any extra objects added to the Element are invoked (in order) until one handles the event. If none handle the event, it is ignored.

The generic event handler is JawsEvent. An event handler should return ErrEventUnhandled if it didn't handle the event or wants to pass it to the next handler.

  • onclick invokes JawsClick if present, otherwise JawsEvent with what.Click
  • oninput invokes JawsEvent with what.Input

Technical notes

HTTP request flow and associating the WebSocket

When a new HTTP request is received, create a JaWS Request using the JaWS object's NewRequest() method, and then use the Request's HeadHTML() method to get the HTML code needed in the HEAD section of the HTML page.

When the client has finished loading the document and parsed the scripts, the JaWS Javascript will request a WebSocket connection on /jaws/*, with the * being the encoded Request.JawsKey value.

On receiving the WebSocket HTTP request, decode the key parameter from the URL and call the JaWS object's UseRequest() method to retrieve the Request created in the first step. Then call it's ServeHTTP() method to start up the WebSocket and begin processing Javascript events and DOM updates.

Routing

JaWS doesn't enforce any particular router, but it does require several endpoints to be registered in whichever router you choose to use. All of the endpoints start with "/jaws/", and Jaws.ServeHTTP() will handle all of them.

  • /jaws/jaws.*.js

    The exact URL is the value of jaws.JavascriptPath. It must return the client-side Javascript, the uncompressed contents of which can be had with jaws.JavascriptText, or a gzipped version with jaws.JavascriptGZip.

    The response should be cached indefinitely.

  • /jaws/[0-9a-z]+

    The WebSocket endpoint. The trailing string must be decoded using jaws.JawsKeyValue() and then the matching JaWS Request retrieved using the JaWS object's UseRequest() method.

    If the Request is not found, return a 404 Not Found, otherwise call the Request ServeHTTP() method to start the WebSocket and begin processing events and updates.

  • /jaws/.ping

    This endpoint is called by the Javascript while waiting for the server to come online. This is done in order to not spam the WebSocket endpoint with connection requests, and browsers are better at handling XHR requests failing.

    If you don't have a JaWS object, or if it's completion channel is closed (see Jaws.Done()), return 503 Service Unavailable. If you're ready to serve requests, return 204 No Content.

    The response should not be cached.

Handling the routes with the standard library's http.DefaultServeMux:

jw := jaws.New()
defer jw.Close()
go jw.Serve()
http.DefaultServeMux.Handle("/jaws/", jw)

Handling the routes with Echo:

jw := jaws.New()
defer jw.Close()
go jw.Serve()
router := echo.New()
router.GET("/jaws/*", func(c echo.Context) error {
  jw.ServeHTTP(c.Response().Writer, c.Request())
  return nil
})
HTML rendering

HTML output elements (e.g. jaws.RequestWriter.Div()) require a jaws.HTMLGetter or something that can be made into one using jaws.MakeHTMLGetter().

In order of precedence, this can be:

  • jaws.HTMLGetter: JawsGetHTML(*Element) template.HTML to be used as-is.
  • jaws.Getter[string]: JawsGet(*Element) string that will be escaped using html.EscapeString.
  • jaws.AnyGetter: JawsGetAny(*Element) any that will be rendered using fmt.Sprint() and escaped using html.EscapeString.
  • fmt.Stringer: String() string that will be escaped using html.EscapeString.
  • a static template.HTML or string to be used as-is with no HTML escaping.
  • everything else is rendered using fmt.Sprint() and escaped using html.EscapeString.

You can use jaws.Bind().FormatHTML(), jaws.HTMLGetterFunc() or jaws.StringGetterFunc() to build a custom renderer for trivial rendering tasks, or define a custom type implementing HTMLGetter.

Data binding

HTML input elements (e.g. jaws.RequestWriter.Range()) require bi-directional data flow between the server and the browser. The first argument to these is usually a Setter[T] where T is one of string, float64, bool or time.Time. It can also be a Getter[T], in which case the HTML element should be made read-only.

Since all data access need to be protected with locks, you will usually use jaws.Bind() to create a jaws.Binder[T] that combines a (RW)Locker and a pointer to a value of type T. It also allows you to add chained setters, getters and on-success handlers.

Session handling

JaWS has non-persistent session handling integrated. Sessions won't be persisted across restarts and must have an expiry time. A new session is created with EnsureSession() and sending it's Cookie() to the client browser.

When subsequent Requests are created with NewRequest(), if the HTTP request has the cookie set and comes from the correct IP, the new Request will have access to that Session.

Session key-value pairs can be accessed using Request.Set() and Request.Get(), or directly using a Session object. It's safe to do this if there is no session; Get() will return nil, and Set() will be a no-op.

Sessions are bound to the client IP. Attempting to access an existing session from a new IP will fail.

No data is stored in the client browser except the randomly generated session cookie. You can set the cookie name in Jaws.CookieName, the default is jaws.

A note on the Context

The Request object embeds a context.Context inside it's struct, contrary to recommended Go practice.

The reason is that there is no unbroken call chain from the time the Request object is created when the initial HTTP request comes in and when it's requested during the Javascript WebSocket HTTP request.

Security of the WebSocket callback

Each JaWS request gets a unique 64-bit random value assigned to it when you create the Request object. This value is written to the HTML output so it can be read by the Javascript, and used to construct the WebSocket callback URL.

Once the WebSocket call comes in, the value is consumed by that request, and is no longer valid until, theoretically, another Request gets the same random value. And that's fine, since JaWS guarantees that no two Requests waiting for WebSocket calls can have the same value at the same time.

In addition to this, Requests that are not claimed by a WebSocket call get cleaned up at regular intervals. By default an unclaimed Request is removed after 10 seconds.

In order to guess (and thus hijack) a WebSocket you'd have to make on the order of 2^63 requests before the genuine request comes in, or 10 seconds pass assuming you can reliably prevent the genuine WebSocket request.

Dependencies

We try to minimize dependencies outside of the standard library.

Documentation

Overview

Package jaws provides a mechanism to create dynamic webpages using Javascript and WebSockets.

It integrates well with Go's html/template package, but can be used without it. It can be used with any router that supports the standard ServeHTTP interface.

Example 
package main

import (
	"html/template"
	"log/slog"
	"net/http"
	"sync"

	"github.com/linkdata/jaws"
)

const indexhtml = `
<html>
  <head>{{$.HeadHTML}}</head>
  <body>{{with .Dot}}
    {{$.Range .}}
    {{$.TailHTML}}
  {{end}}</body>
</html>
`

func main() {
	jw := jaws.New()           // create a default JaWS instance
	defer jw.Close()           // ensure we clean up
	jw.Logger = slog.Default() // optionally set the logger to use

	// parse our template and inform JaWS about it
	templates := template.Must(template.New("index").Parse(indexhtml))
	jw.AddTemplateLookuper(templates)

	go jw.Serve()                             // start the JaWS processing loop
	http.DefaultServeMux.Handle("/jaws/", jw) // ensure the JaWS routes are handled

	var mu sync.Mutex
	var f float64

	http.DefaultServeMux.Handle("/", jw.Handler("index", jaws.Bind(&mu, &f)))
	slog.Error(http.ListenAndServe("localhost:8080", nil).Error())
}

Output:

Index

Examples

Constants

View Source 
const (
	DefaultUpdateInterval = time.Millisecond * 100 // Default browser update interval
)
View Source 
const ISO8601 = "2006-01-02"

Variables

View Source 
var DefaultCookieName string

DefaultCookieName holds the default JaWS cookie name. It will be generated from the executable name, or "jaws" if that fails.

View Source 
var ErrEventUnhandled = errEventUnhandled{}

ErrEventUnhandled returned by JawsEvent() or JawsClick() causes the next available handler to be invoked.

View Source 
var ErrIllegalTagType errIllegalTagType

ErrIllegalTagType is returned when a UI tag type is disallowed

View Source 
var ErrJavascriptDisabled = errors.New("javascript is disabled")
View Source 
var ErrNoWebSocketRequest errNoWebSocketRequest

ErrNoWebSocketRequest is returned when the WebSocket callback was not received within the timeout period. Most common reason is that client is not using Javascript.

View Source 
var ErrNotComparable errNotComparable

ErrNotComparable is returned when a UI object or tag is not comparable.

View Source 
var ErrPendingCancelled errPendingCancelled

ErrPendingCancelled indicates a pending Request was cancelled. Use Unwrap() to see the underlying cause.

View Source 
var ErrRequestAlreadyClaimed = errors.New("request already claimed")
View Source 
var ErrTooManyTags = errTooManyTags{}
View Source 
var ErrValueNotSettable = errors.New("value not settable")
View Source 
var ErrValueUnchanged = errors.New("value unchanged")

ErrValueUnchanged can be returned from JawsSet[Type] functions to indicate that while there was no error, the underlying value was already the desired value.

View Source 
var JavascriptGZip = makeJavascriptGZip()

JavascriptGZip is the embedded Javascript library GZipped.

View Source 
var JavascriptPath = makeJavascriptPath()

JavascriptPath is the path for the embedded JaWS Javascript library.

View Source 
var JavascriptText []byte

JavascriptText is the source code for the client-side JaWS Javascript library.

Functions

func AppendID added in v0.31.0 

func AppendID(b []byte) []byte

AppendID appends the result of NextID() in text form to the given slice.

func JawsKeyAppend added in v0.52.0 

func JawsKeyAppend(b []byte, jawsKey uint64) []byte

JawsKeyAppend appends the JaWS key as a string to the buffer.

func JawsKeyString 

func JawsKeyString(jawsKey uint64) string

JawsKeyString returns the string to be used for the given JaWS key.

func JawsKeyValue added in v0.11.0 

func JawsKeyValue(jawsKey string) uint64

JawsKeyValue parses a key string (as returned JawsKeyString) into a uint64.

func MakeID added in v0.24.0 

func MakeID() string

MakeID returns a string in the form 'jaws.X' where X is a unique string within lifetime of the program.

func MustTagExpand added in v0.34.0 

func MustTagExpand(rq *Request, tag any) []any

func NextID added in v0.31.0 

func NextID() int64

NextID returns a uint64 unique within lifetime of the program.

func PreloadHTML added in v0.71.0 

func PreloadHTML(urls ...*url.URL) string

PreloadHTML returns HTML code to load the given resources efficiently.

func TagExpand added in v0.31.0 

func TagExpand(rq *Request, tag any) ([]any, error)

func TagString added in v0.31.0 

func TagString(tag any) string

func WriteHTMLInner added in v0.104.0 

func WriteHTMLInner(w io.Writer, jid jid.Jid, htmlTag, typeAttr string, innerHTML template.HTML, attrs ...template.HTMLAttr) (err error)

func WriteHTMLInput added in v0.104.0 

func WriteHTMLInput(w io.Writer, jid jid.Jid, typeAttr, valueAttr string, attrs []template.HTMLAttr) (err error)

func WriteHTMLSelect added in v0.104.0 

func WriteHTMLSelect(w io.Writer, jid jid.Jid, nba *NamedBoolArray, attrs []template.HTMLAttr) (err error)

func WriteHTMLTag added in v0.104.0 

func WriteHTMLTag(w io.Writer, jid jid.Jid, htmlTag, typeAttr, valueAttr string, attrs []template.HTMLAttr) (err error)

Types

type AnyGetter added in v0.102.0 

type AnyGetter interface {
	JawsGetAny(elem *Element) (value any)
}

type AnySetter added in v0.75.0 

type AnySetter interface {
	AnyGetter
	// JawsSetAny may return ErrValueUnchanged to indicate value was already set.
	// It may panic if the type of v cannot be handled.
	JawsSetAny(e *Element, v any) (err error)
}

type Auth added in v0.85.0 

type Auth interface {
	Data() map[string]any // returns authenticated user data, or nil
	Email() string        // returns authenticated user email, or an empty string
	IsAdmin() bool        // return true if admins are defined and current user is one, or if no admins are defined
}

type BindGetHook added in v0.100.0 

type BindGetHook[T comparable] func(bind Binder[T], elem *Element) (value T)

BindGetHook is a function that replaces JawsGetLocked for a Binder.

The lock will be held before calling the function, preferring RLock over Lock, if available. Do not lock or unlock the Binder in the function. Do not call JawsGet.

The bind argument is the previous Binder in the chain, and you probably want to call it's JawsGetLocked first.

type BindSetHook added in v0.100.0 

type BindSetHook[T comparable] func(bind Binder[T], elem *Element, value T) (err error)

BindSetHook is a function that replaces JawsSetLocked for a Binder.

The lock will be held before calling the function, preferring RLock over Lock, if available. Do not lock or unlock the Binder in the function. Do not call JawsSet.

The bind argument is the previous Binder in the chain, and you probably want to call it's JawsSetLocked first.

type BindSuccessHook added in v0.100.0 

type BindSuccessHook func(*Element) (err error)

BindSuccessHook is a function to call when a call to JawsSet returns with no error.

The Binder locks are not held when the function is called.

Success hooks in a Binder chain are called in the order they were registered. If one of them returns an error, that error is returned from JawsSet and no more success hooks are called.

type Binder added in v0.100.0 

type Binder[T comparable] interface {
	RWLocker
	Setter[T]
	AnySetter
	TagGetter

	JawsBinderPrev() Binder[T] // returns the previous Binder in the chain, or nil
	JawsGetLocked(elem *Element) (value T)
	JawsSetLocked(elem *Element, value T) (err error)

	// SetLocked returns a Binder[T] that will call fn instead of JawsSetLocked.
	//
	// The lock will be held at this point.
	// Do not lock or unlock the Binder within fn. Do not call JawsSet.
	//
	// The bind argument to the function is the previous Binder in the chain,
	// and you probably want to call it's JawsSetLocked first.
	SetLocked(fn BindSetHook[T]) (newbind Binder[T])

	// GetLocked returns a Binder[T] that will call fn instead of JawsGetLocked.
	//
	// The lock will be held at this point, preferring RLock over Lock, if available.
	// Do not lock or unlock the Binder within fn. Do not call JawsGet.
	//
	// The bind argument to the function is the previous Binder in the chain,
	// and you probably want to call it's JawsGetLocked first.
	GetLocked(fn BindGetHook[T]) (newbind Binder[T])

	// Success returns a Binder[T] that will call fn after the value has been set
	// with no errors. No locks are held when the function is called.
	// If the function returns an error, that will be returned from JawsSet.
	//
	// The function must have one of the following signatures:
	//  * func()
	//  * func() error
	//  * func(*Element)
	//  * func(*Element) error
	Success(fn any) (newbind Binder[T])

	// Format returns a Getter[string] using fmt.Sprintf(f, JawsGet[T](elem))
	Format(f string) (getter Getter[string])

	// FormatHTML returns a HTMLGetter using fmt.Sprintf(f, JawsGet[T](elem))
	FormatHTML(f string) (getter HTMLGetter)
}

func Bind added in v0.78.0 

func Bind[T comparable](l sync.Locker, p *T) Binder[T]

Bind returns a Binder[T] with the given sync.Locker (or RWLocker) and a pointer to the underlying value of type T.

The pointer will be used as the UI tag.

type ClickHandler added in v0.31.0 

type ClickHandler interface {
	// JawsClick is called when an Element's HTML element or something within it
	// is clicked in the browser.
	//
	// The name parameter is taken from the first 'name' HTML attribute or HTML
	// 'button' textContent found when traversing the DOM. It may be empty.
	JawsClick(e *Element, name string) (err error)
}

type ConnectFn 

type ConnectFn = func(rq *Request) error

ConnectFn can be used to interact with a Request before message processing starts. Returning an error causes the Request to abort, and the WebSocket connection to close.

type Container added in v0.31.0 

type Container interface {
	// JawsContains must return a slice of hashable UI objects. The slice contents must not be modified after returning it.
	JawsContains(e *Element) (contents []UI)
}

type Element added in v0.31.0 

type Element struct {
	*Request // (read-only) the Request the Element belongs to
	// contains filtered or unexported fields
}

An Element is an instance of a *Request, an UI object and a Jid.

func (*Element) Append added in v0.31.0 

func (e *Element) Append(htmlCode template.HTML)

Append appends a new HTML element as a child to the current one.

Call this only during JawsRender() or JawsUpdate() processing.

func (*Element) ApplyGetter added in v0.75.0 

func (e *Element) ApplyGetter(getter any) (tag any)

ApplyGetter examines getter, and if it's not nil, either adds it as a Tag, or, if it is a TagGetter, adds the result of that as a Tag. If getter is a ClickHandler or an EventHandler, it's added to the list of handlers for the Element.

Returns the Tag added, or nil if getter was nil.

func (*Element) ApplyParams added in v0.60.0 

func (e *Element) ApplyParams(params []any) (retv []template.HTMLAttr)

ApplyParams parses the parameters passed to UI() when creating a new Element, adding UI tags, adding any additional event handlers found.

Returns the list of HTML attributes found, if any.

func (*Element) HasTag added in v0.31.0 

func (e *Element) HasTag(tag any) bool

HasTag returns true if this Element has the given tag.

func (*Element) JawsRender added in v0.55.0 

func (e *Element) JawsRender(w io.Writer, params []any) (err error)

JawsRender calls Ui().JawsRender() for this Element.

Do not call this yourself unless it's from within another JawsRender implementation.

func (*Element) JawsUpdate added in v0.55.0 

func (e *Element) JawsUpdate()

JawsUpdate calls Ui().JawsUpdate() for this Element.

Do not call this yourself unless it's from within another JawsUpdate implementation.

func (*Element) Jid added in v0.31.0 

func (e *Element) Jid() jid.Jid

Jid returns the JaWS ID for this Element, unique within it's Request.

func (*Element) JsCall added in v0.75.0 

func (e *Element) JsCall(arg string)

JsCall queues a Javascript function invocation to be sent to the browser. The string 'arg' must be valid JSON.

The browser will respond by setting this Element's value to the function return value (unless there was a Javascript exception).

func (*Element) JsSet added in v0.75.0 

func (e *Element) JsSet(val string)

JsSet sends a Javascript variable update to the browser. The string 'val' must be valid JSON.

func (*Element) Order added in v0.31.0 

func (e *Element) Order(jidList []jid.Jid)

Order reorders the HTML elements.

Call this only during JawsRender() or JawsUpdate() processing.

func (*Element) Remove added in v0.31.0 

func (e *Element) Remove(htmlId string)

Remove requests that the HTML child with the given HTML ID of this Element is removed from the Request and it's HTML element from the browser.

Call this only during JawsRender() or JawsUpdate() processing.

func (*Element) RemoveAttr added in v0.31.0 

func (e *Element) RemoveAttr(attr string)

RemoveAttr queues sending a request to remove an attribute to the browser for the Element with the given JaWS ID in this Request.

Call this only during JawsRender() or JawsUpdate() processing.

func (*Element) RemoveClass added in v0.31.0 

func (e *Element) RemoveClass(cls string)

RemoveClass queues sending a request to remove a class to the browser for the Element with the given JaWS ID in this Request.

Call this only during JawsRender() or JawsUpdate() processing.

func (*Element) Replace added in v0.31.0 

func (e *Element) Replace(htmlCode template.HTML)

Replace replaces the elements entire HTML DOM node with new HTML code. If the HTML code doesn't seem to contain correct HTML ID, it panics.

Call this only during JawsRender() or JawsUpdate() processing.

func (*Element) SetAttr added in v0.31.0 

func (e *Element) SetAttr(attr, val string)

SetAttr queues sending a new attribute value to the browser for the Element with the given JaWS ID in this Request.

Call this only during JawsRender() or JawsUpdate() processing.

func (*Element) SetClass added in v0.31.0 

func (e *Element) SetClass(cls string)

SetClass a queues sending a class to the browser for the Element with the given JaWS ID in this Request.

Call this only during JawsRender() or JawsUpdate() processing.

func (*Element) SetInner added in v0.31.0 

func (e *Element) SetInner(innerHTML template.HTML)

SetInner queues sending a new inner HTML content to the browser for the Element.

Call this only during JawsRender() or JawsUpdate() processing.

func (*Element) SetValue added in v0.31.0 

func (e *Element) SetValue(val string)

SetValue queues sending a new current input value in textual form to the browser for the Element with the given JaWS ID in this Request.

Call this only during JawsRender() or JawsUpdate() processing.

func (*Element) String added in v0.31.0 

func (e *Element) String() string

func (*Element) Tag added in v0.31.0 

func (e *Element) Tag(tags ...any)

Tag adds the given tags to the Element.

func (*Element) Ui added in v0.31.0 

func (e *Element) Ui() UI

Ui returns the UI object.

type EventFn 

type EventFn = func(e *Element, wht what.What, val string) (err error)

EventFn is the signature of a event handling function to be called when JaWS receives an event message from the Javascript via the WebSocket connection.

type EventHandler added in v0.31.0 

type EventHandler interface {
	JawsEvent(e *Element, wht what.What, val string) (err error)
}

func ParseParams added in v0.60.0 

func ParseParams(params []any) (tags []any, handlers []EventHandler, attrs []string)

ParseParams parses the parameters passed to UI() when creating a new Element, returning UI tags, event handlers and HTML attributes.

type Getter added in v0.78.0 

type Getter[T comparable] interface {
	JawsGet(elem *Element) (value T)
}

func StringGetterFunc added in v0.95.0 

func StringGetterFunc(fn func(elem *Element) (s string), tags ...any) Getter[string]

StringGetterFunc wraps a function and returns a Getter[string]

type HTMLGetter added in v0.104.0 

type HTMLGetter interface {
	JawsGetHTML(e *Element) template.HTML
}

A HTMLGetter is the primary way to deliver generated HTML content to dynamic HTML nodes.

func HTMLGetterFunc added in v0.104.0 

func HTMLGetterFunc(fn func(elem *Element) (tmpl template.HTML), tags ...any) HTMLGetter

HTMLGetterFunc wraps a function and returns a HTMLGetter.

func MakeHTMLGetter added in v0.104.0 

func MakeHTMLGetter(v any) HTMLGetter

MakeHTMLGetter returns a HTMLGetter for v.

Depending on the type of v, we return:

  • jaws.HTMLGetter: `JawsGetHTML(e *Element) template.HTML` to be used as-is.
  • jaws.Getter[string]: `JawsGet(elem *Element) string` that will be escaped using `html.EscapeString`.
  • jaws.AnyGetter: `JawsGetAny(elem *Element) any` that will be rendered using `fmt.Sprint()` and escaped using `html.EscapeString`.
  • fmt.Stringer: `String() string` that will be escaped using `html.EscapeString`.
  • a static `template.HTML` or `string` to be used as-is with no HTML escaping.
  • everything else is rendered using `fmt.Sprint()` and escaped using `html.EscapeString`.

type Handler added in v0.65.0 

type Handler struct {
	*Jaws
	Template
}

Handler implements ServeHTTP with a jaws.Template

func (Handler) ServeHTTP added in v0.65.0 

func (h Handler) ServeHTTP(wr http.ResponseWriter, r *http.Request)

type IsJsVar added in v0.78.0 

type IsJsVar interface {
	JawsIsJsVar()
	EventHandler
	AppendJSON(b []byte, e *Element) []byte
}

type Jaws 

type Jaws struct {
	CookieName string       // Name for session cookies, defaults to "jaws"
	Logger     *slog.Logger // Optional logger to use
	Debug      bool         // Set to true to enable debug info in generated HTML code
	MakeAuth   MakeAuthFn   // Optional function to create With.Auth for Templates
	// contains filtered or unexported fields
}

func New 

func New() (jw *Jaws)

New returns a new JaWS object that must be closed using Close(). This is expected to be created once per HTTP server and handles publishing HTML changes across all connections.

func NewWithDone 

func NewWithDone(doneCh <-chan struct{}) (jw *Jaws)

NewWithDone returns a new JaWS object using the given completion channel. This is expected to be created once per HTTP server and handles publishing HTML changes across all connections.

func (*Jaws) AddTemplateLookuper added in v0.45.0 

func (jw *Jaws) AddTemplateLookuper(tl TemplateLookuper)

AddTemplateLookuper adds an object that can resolve strings to *template.Template.

func (*Jaws) Alert 

func (jw *Jaws) Alert(lvl, msg string)

Alert sends an alert to all Requests. The lvl argument should be one of Bootstraps alert levels: primary, secondary, success, danger, warning, info, light or dark.

func (*Jaws) Append 

func (jw *Jaws) Append(target any, html template.HTML)

Append calls the Javascript 'appendChild()' method on all HTML elements matching target.

func (*Jaws) Broadcast 

func (jw *Jaws) Broadcast(msg Message)

Broadcast sends a message to all Requests.

func (*Jaws) Close 

func (jw *Jaws) Close()

Close frees resources associated with the JaWS object, and closes the completion channel if the JaWS was created with New(). Once the completion channel is closed, broadcasts and sends may be discarded. Subsequent calls to Close() have no effect.

func (*Jaws) Delete added in v0.31.0 

func (jw *Jaws) Delete(target any)

Delete removes the HTML element(s) matching target.

func (*Jaws) Dirty added in v0.31.0 

func (jw *Jaws) Dirty(tags ...any)

Dirty marks all Elements that have one or more of the given tags as dirty.

Note that if any of the tags are a TagGetter, it will be called with a nil Request. Prefer using Request.Dirty() which avoids this.

func (*Jaws) Done 

func (jw *Jaws) Done() <-chan struct{}

Done returns the completion channel.

func (*Jaws) GenerateHeadHTML added in v0.5.0 

func (jw *Jaws) GenerateHeadHTML(extra ...string) (err error)

GenerateHeadHTML (re-)generates the HTML code that goes in the HEAD section, ensuring that the provided URL resources in `extra` are loaded, along with the JaWS javascript.

You only need to call this if you want to add your own scripts and stylesheets.

func (*Jaws) GetSession added in v0.11.0 

func (jw *Jaws) GetSession(hr *http.Request) (sess *Session)

GetSession returns the Session associated with the given *http.Request, or nil.

func (*Jaws) Handler added in v0.65.0 

func (jw *Jaws) Handler(name string, dot any) http.Handler

Handler returns a http.Handler using a jaws.Template

func (*Jaws) Insert 

func (jw *Jaws) Insert(target any, where, html string)

Insert calls the Javascript 'insertBefore()' method on all HTML elements matching target.

The position parameter 'where' may be either a HTML ID, an child index or the text 'null'.

func (*Jaws) Log 

func (jw *Jaws) Log(err error) error

Log sends an error to the Logger set in the Jaws. Has no effect if the err is nil or the Logger is nil. Returns err.

func (*Jaws) LookupTemplate added in v0.66.0 

func (jw *Jaws) LookupTemplate(name string) *template.Template

LookupTemplate queries the known TemplateLookupers in the order they were added and returns the first found.

func (*Jaws) MustLog added in v0.1.1 

func (jw *Jaws) MustLog(err error)

MustLog sends an error to the Logger set in the Jaws or panics with the given error if no Logger is set. Has no effect if the err is nil.

func (*Jaws) NewRequest 

func (jw *Jaws) NewRequest(hr *http.Request) (rq *Request)

NewRequest returns a new pending JaWS request that times out after 10 seconds.

Call this as soon as you start processing a HTML request, and store the returned Request pointer so it can be used while constructing the HTML response in order to register the JaWS id's you use in the response, and use it's Key attribute when sending the Javascript portion of the reply.

func (*Jaws) NewSession added in v0.26.0 

func (jw *Jaws) NewSession(w http.ResponseWriter, hr *http.Request) (sess *Session)

NewSession creates a new Session.

Any pre-existing Session will be cleared and closed.

Subsequent Requests created with `NewRequest()` that have the cookie set and originates from the same IP will be able to access the Session.

func (*Jaws) Pending 

func (jw *Jaws) Pending() (n int)

Count returns the number of requests waiting for their WebSocket callbacks.

func (*Jaws) Redirect 

func (jw *Jaws) Redirect(url string)

Redirect requests all Requests to navigate to the given URL.

func (*Jaws) Reload 

func (jw *Jaws) Reload()

Reload requests all Requests to reload their current page.

func (*Jaws) RemoveAttr 

func (jw *Jaws) RemoveAttr(target any, attr string)

RemoveAttr sends a request to remove the given attribute from all HTML elements matching target.

func (*Jaws) RemoveClass added in v0.31.0 

func (jw *Jaws) RemoveClass(target any, cls string)

RemoveClass sends a request to remove the given class from all HTML elements matching target.

func (*Jaws) RemoveTemplateLookuper added in v0.45.0 

func (jw *Jaws) RemoveTemplateLookuper(tl TemplateLookuper)

RemoveTemplateLookuper removes the given object from the list of TemplateLookupers.

func (*Jaws) Replace 

func (jw *Jaws) Replace(target any, where, html string)

Replace replaces the HTML content on all HTML elements matching target.

The position parameter 'where' may be either a HTML ID or an index.

func (*Jaws) RequestCount added in v0.25.0 

func (jw *Jaws) RequestCount() (n int)

RequestCount returns the number of Requests.

The count includes all Requests, including those being rendered, those waiting for the WebSocket callback and those active.

func (*Jaws) Serve 

func (jw *Jaws) Serve()

Serve calls ServeWithTimeout(time.Second * 10).

func (*Jaws) ServeHTTP added in v0.19.0 

func (jw *Jaws) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP can handle the required JaWS endpoints, which all start with "/jaws/".

func (*Jaws) ServeWithTimeout 

func (jw *Jaws) ServeWithTimeout(requestTimeout time.Duration)

ServeWithTimeout begins processing requests with the given timeout. It is intended to run on it's own goroutine. It returns when the completion channel is closed.

func (*Jaws) Session added in v0.77.0 

func (jw *Jaws) Session(h http.Handler) http.Handler

Session returns a http.Handler that ensures a JaWS Session exists before invoking h.

func (*Jaws) SessionCount added in v0.11.0 

func (jw *Jaws) SessionCount() (n int)

SessionCount returns the number of active sessions.

func (*Jaws) Sessions added in v0.11.0 

func (jw *Jaws) Sessions() (sl []*Session)

Sessions returns a list of all active sessions, which may be nil.

func (*Jaws) SetAttr 

func (jw *Jaws) SetAttr(target any, attr, val string)

SetAttr sends a request to replace the given attribute value in all HTML elements matching target.

func (*Jaws) SetClass added in v0.31.0 

func (jw *Jaws) SetClass(target any, cls string)

SetClass sends a request to set the given class in all HTML elements matching target.

func (*Jaws) SetInner 

func (jw *Jaws) SetInner(target any, innerHTML template.HTML)

SetInner sends a request to replace the inner HTML of all HTML elements matching target.

func (*Jaws) SetValue 

func (jw *Jaws) SetValue(target any, val string)

SetValue sends a request to set the HTML "value" attribute of all HTML elements matching target.

func (*Jaws) UseRequest 

func (jw *Jaws) UseRequest(jawsKey uint64, hr *http.Request) (rq *Request)

UseRequest extracts the JaWS request with the given key from the request map if it exists and the HTTP request remote IP matches.

Call it when receiving the WebSocket connection on '/jaws/:key' to get the associated Request, and then call it's ServeHTTP method to process the WebSocket messages.

Returns nil if the key was not found or the IP doesn't match, in which case you should return a HTTP "404 Not Found" status.

type Jid added in v0.31.0 

type Jid = jid.Jid // convenience alias

type JsFunc added in v0.78.0 

type JsFunc struct {
	Arg  IsJsVar
	Retv IsJsVar
}

func NewJsFunc added in v0.78.0 

func NewJsFunc(arg IsJsVar, retv IsJsVar) JsFunc

func (JsFunc) JawsEvent added in v0.78.0 

func (ui JsFunc) JawsEvent(e *Element, wht what.What, val string) (err error)

func (JsFunc) JawsRender added in v0.78.0 

func (ui JsFunc) JawsRender(e *Element, w io.Writer, params []any) (err error)

func (JsFunc) JawsUpdate added in v0.78.0 

func (ui JsFunc) JawsUpdate(e *Element)

type JsVar added in v0.78.0 

type JsVar[T comparable] struct {
	Setter[T] // typed generic Setter
}

func NewJsVar added in v0.78.0 

func NewJsVar[T comparable](setter Setter[T]) (v JsVar[T])

func (JsVar[T]) AppendJSON added in v0.78.0 

func (ui JsVar[T]) AppendJSON(b []byte, e *Element) []byte

func (JsVar[T]) JawsEvent added in v0.78.0 

func (ui JsVar[T]) JawsEvent(e *Element, wht what.What, val string) (err error)

func (JsVar[T]) JawsGetTag added in v0.78.0 

func (ui JsVar[T]) JawsGetTag(rq *Request) any

func (JsVar[T]) JawsIsJsVar added in v0.78.0 

func (ui JsVar[T]) JawsIsJsVar()

func (JsVar[T]) JawsRender added in v0.78.0 

func (ui JsVar[T]) JawsRender(e *Element, w io.Writer, params []any) (err error)

func (JsVar[T]) JawsUpdate added in v0.78.0 

func (ui JsVar[T]) JawsUpdate(e *Element)

type MakeAuthFn added in v0.85.0 

type MakeAuthFn func(*Request) Auth

type Message 

type Message struct {
	Dest any       // destination (tag, html ID or *Element)
	What what.What // what to change or do
	Data string    // data (e.g. inner HTML content or slice of tags)
}

Message contains the elements of a message to be sent to Requests.

func (*Message) String 

func (msg *Message) String() string

String returns the Message in a form suitable for debug output.

type NamedBool 

type NamedBool struct {
	// contains filtered or unexported fields
}

NamedBool stores a named boolen value with a HTML representation.

func NewNamedBool added in v0.31.0 

func NewNamedBool(nba *NamedBoolArray, name string, html template.HTML, checked bool) *NamedBool

func (*NamedBool) Array added in v0.31.0 

func (nb *NamedBool) Array() *NamedBoolArray

func (*NamedBool) Checked 

func (nb *NamedBool) Checked() (checked bool)

func (*NamedBool) HTML added in v0.104.0 

func (nb *NamedBool) HTML() (h template.HTML)

func (*NamedBool) JawsGet added in v0.102.0 

func (nb *NamedBool) JawsGet(*Element) (v bool)

func (*NamedBool) JawsGetHTML added in v0.104.0 

func (nb *NamedBool) JawsGetHTML(*Element) (h template.HTML)

func (*NamedBool) JawsSet added in v0.102.0 

func (nb *NamedBool) JawsSet(e *Element, checked bool) (err error)

func (*NamedBool) Name added in v0.24.0 

func (nb *NamedBool) Name() (s string)

func (*NamedBool) Set added in v0.31.0 

func (nb *NamedBool) Set(checked bool) (changed bool)

func (*NamedBool) String 

func (nb *NamedBool) String() string

String returns a string representation of the NamedBool suitable for debugging.

type NamedBoolArray 

type NamedBoolArray struct {
	Multi bool // allow multiple NamedBools to be true
	// contains filtered or unexported fields
}

NamedBoolArray stores the data required to support HTML 'select' elements and sets of HTML radio buttons. It it safe to use from multiple goroutines concurrently.

func NewNamedBoolArray 

func NewNamedBoolArray() *NamedBoolArray

NewNamedBoolArray creates a new object to track a related set of named booleans.

The JaWS ID string 'jid' is used as the ID for <select> elements and the value for the 'name' attribute for radio buttons. If left empty, MakeID() will be used to assign a unique ID.

func (*NamedBoolArray) Add 

func (nba *NamedBoolArray) Add(name string, text template.HTML) *NamedBoolArray

Add adds a NamedBool with the given name and the given text. Returns itself.

Note that while it's legal to have multiple NamedBool with the same name since it's allowed in HTML, it's probably not a good idea.

func (*NamedBoolArray) Get added in v0.24.0 

func (nba *NamedBoolArray) Get() (name string)

Get returns the name of first NamedBool in the group that has it's Checked value set to true. Returns an empty string if none are true.

In case you can have more than one selected or you need to distinguish between a blank name and the fact that none are set to true, use ReadLocked() to inspect the data directly.

func (*NamedBoolArray) IsChecked added in v0.24.0 

func (nba *NamedBoolArray) IsChecked(name string) (state bool)

IsChecked returns true if any of the NamedBool in the set that have the given name are Checked. Returns false if the name is not found.

func (*NamedBoolArray) JawsContains added in v0.31.0 

func (nba *NamedBoolArray) JawsContains(e *Element) (contents []UI)

func (*NamedBoolArray) JawsGet added in v0.102.0 

func (nba *NamedBoolArray) JawsGet(e *Element) string

func (*NamedBoolArray) JawsSet added in v0.102.0 

func (nba *NamedBoolArray) JawsSet(e *Element, name string) (err error)

func (*NamedBoolArray) ReadLocked added in v0.24.0 

func (nba *NamedBoolArray) ReadLocked(fn func(nbl []*NamedBool))

ReadLocked calls the given function with the NamedBoolArray locked for reading.

func (*NamedBoolArray) Set 

func (nba *NamedBoolArray) Set(name string, state bool) (changed bool)

Set sets the Checked state for the NamedBool(s) with the given name.

func (*NamedBoolArray) String 

func (nba *NamedBoolArray) String() string

String returns a string representation of the NamedBoolArray suitable for debugging.

func (*NamedBoolArray) WriteLocked added in v0.24.0 

func (nba *NamedBoolArray) WriteLocked(fn func(nbl []*NamedBool) []*NamedBool)

WriteLocked calls the given function with the NamedBoolArray locked for writing and replaces the internal []*NamedBool slice with the return value.

type RWLocker added in v0.101.0 

type RWLocker interface {
	sync.Locker
	RLock()
	RUnlock()
}

type RadioElement added in v0.31.0 

type RadioElement struct {
	// contains filtered or unexported fields
}

func (RadioElement) Label added in v0.31.0 

func (re RadioElement) Label(params ...any) template.HTML

Label renders a HTML label element.

func (RadioElement) Radio added in v0.31.0 

func (re RadioElement) Radio(params ...any) template.HTML

Radio renders a HTML input element of type 'radio'.

type Renderer added in v0.60.0 

type Renderer interface {
	// JawsRender is called once per Element when rendering the initial webpage.
	// Do not call this yourself unless it's from within another JawsRender implementation.
	JawsRender(e *Element, w io.Writer, params []any) error
}

type Request 

type Request struct {
	Jaws    *Jaws  // (read-only) the JaWS instance the Request belongs to
	JawsKey uint64 // (read-only) a random number used in the WebSocket URI to identify this Request
	// contains filtered or unexported fields
}

Request maintains the state for a JaWS WebSocket connection, and handles processing of events and broadcasts.

Note that we have to store the context inside the struct because there is no call chain between the Request being created and it being used once the WebSocket is created.

func (*Request) Alert 

func (rq *Request) Alert(lvl, msg string)

Alert attempts to show an alert message on the current request webpage if it has an HTML element with the id 'jaws-alert'. The lvl argument should be one of Bootstraps alert levels: primary, secondary, success, danger, warning, info, light or dark.

The default JaWS javascript only supports Bootstrap.js dismissable alerts.

func (*Request) AlertError 

func (rq *Request) AlertError(err error)

AlertError calls Alert if the given error is not nil.

func (*Request) Context 

func (rq *Request) Context() (ctx context.Context)

Context returns the Request's Context, which is derived from the WebSocket's HTTP requests Context.

func (*Request) Dirty added in v0.31.0 

func (rq *Request) Dirty(tags ...any)

Dirty marks all Elements that have one or more of the given tags as dirty.

func (*Request) Done added in v0.31.0 

func (rq *Request) Done() (ch <-chan struct{})

Done returns the Request completion channel.

func (*Request) Get added in v0.11.0 

func (rq *Request) Get(key string) any

Get is shorthand for `Session().Get()` and returns the session value associated with the key, or nil. It no session is associated with the Request, returns nil.

func (*Request) GetConnectFn added in v0.7.0 

func (rq *Request) GetConnectFn() (fn ConnectFn)

GetConnectFn returns the currently set ConnectFn. That function will be called before starting the WebSocket tunnel if not nil.

func (*Request) GetElements added in v0.31.0 

func (rq *Request) GetElements(tagitem any) (elems []*Element)

GetElements returns a list of the UI elements in the Request that have the given tag(s).

func (*Request) HasTag added in v0.31.0 

func (rq *Request) HasTag(elem *Element, tag any) (yes bool)

func (*Request) HeadHTML 

func (rq *Request) HeadHTML(w io.Writer) (err error)

HeadHTML writes the HTML code needed in the HTML page's HEAD section.

func (*Request) Initial added in v0.8.0 

func (rq *Request) Initial() (r *http.Request)

Initial returns the Request's initial HTTP request, or nil.

func (*Request) JawsKeyString 

func (rq *Request) JawsKeyString() string

func (*Request) NewElement added in v0.31.0 

func (rq *Request) NewElement(ui UI) *Element

NewElement creates a new Element using the given UI object.

Panics if the build tag "debug" is set and the UI object doesn't satisfy all requirements.

func (*Request) Redirect 

func (rq *Request) Redirect(url string)

Redirect requests the current Request to navigate to the given URL.

func (*Request) ServeHTTP 

func (rq *Request) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.HanderFunc.

Requires UseRequest() have been successfully called for the Request.

func (*Request) Session added in v0.14.0 

func (rq *Request) Session() (sess *Session)

Session returns the Request's Session, or nil.

func (*Request) Set added in v0.11.0 

func (rq *Request) Set(key string, val any)

Set is shorthand for `Session().Set()` and sets a session value to be associated with the key. If value is nil, the key is removed from the session. Does nothing if there is no session is associated with the Request.

func (*Request) SetConnectFn added in v0.7.0 

func (rq *Request) SetConnectFn(fn ConnectFn)

SetConnectFn sets ConnectFn. That function will be called before starting the WebSocket tunnel if not nil.

func (*Request) String 

func (rq *Request) String() string

func (*Request) Tag added in v0.31.0 

func (rq *Request) Tag(elem *Element, tags ...any)

Tag adds the given tags to the given Element.

func (*Request) TagsOf added in v0.31.0 

func (rq *Request) TagsOf(elem *Element) (tags []any)

func (*Request) TailHTML added in v0.79.0 

func (rq *Request) TailHTML(w io.Writer) (err error)

TailHTML writes optional HTML code at the end of the page's BODY section that will immediately apply HTML attribute and class updates made during initial rendering, which eliminates flicker without having to write the correct value in templates or during JawsRender().

func (*Request) Writer added in v0.39.0 

func (rq *Request) Writer(w io.Writer) RequestWriter

Writer returns a RequestWriter with this Request and the given Writer.

type RequestWriter added in v0.39.0 

type RequestWriter struct {
	io.Writer
	// contains filtered or unexported fields
}

func (RequestWriter) A added in v0.39.0 

func (rq RequestWriter) A(innerHTML any, params ...any) error

func (RequestWriter) Button added in v0.39.0 

func (rq RequestWriter) Button(innerHTML any, params ...any) error

func (RequestWriter) Checkbox added in v0.39.0 

func (rq RequestWriter) Checkbox(value any, params ...any) error

func (RequestWriter) Container added in v0.39.0 

func (rq RequestWriter) Container(outerHTMLTag string, c Container, params ...any) error

func (RequestWriter) Date added in v0.39.0 

func (rq RequestWriter) Date(value any, params ...any) error

func (RequestWriter) Div added in v0.39.0 

func (rq RequestWriter) Div(innerHTML any, params ...any) error

func (RequestWriter) Get added in v0.40.0 

func (rw RequestWriter) Get(key string) (val any)

Get calls Request().Get()

func (RequestWriter) HeadHTML added in v0.40.0 

func (rw RequestWriter) HeadHTML() error

HeadHTML outputs the HTML code needed in the HEAD section.

func (RequestWriter) Img added in v0.39.0 

func (rq RequestWriter) Img(imageSrc any, params ...any) error

func (RequestWriter) Initial added in v0.40.0 

func (rw RequestWriter) Initial() *http.Request

Initial returns the initial http.Request.

func (RequestWriter) JsFunc added in v0.78.0 

func (rq RequestWriter) JsFunc(jsfuncname string, getter any, params ...any) (err error)

func (RequestWriter) JsVar added in v0.78.0 

func (rq RequestWriter) JsVar(jsvarname string, setter any, params ...any) (err error)

JsVar binds a Setter[T] to a named Javascript variable.

Alternatively you may also pass a VarMaker that returns an object that implements Setter[T] and UI.

func (RequestWriter) Label added in v0.39.0 

func (rq RequestWriter) Label(innerHTML any, params ...any) error

func (RequestWriter) Li added in v0.39.0 

func (rq RequestWriter) Li(innerHTML any, params ...any) error

func (RequestWriter) Number added in v0.39.0 

func (rq RequestWriter) Number(value any, params ...any) error

func (RequestWriter) Password added in v0.39.0 

func (rq RequestWriter) Password(value any, params ...any) error

func (RequestWriter) Radio added in v0.39.0 

func (rq RequestWriter) Radio(value any, params ...any) error

func (RequestWriter) RadioGroup added in v0.40.0 

func (rw RequestWriter) RadioGroup(nba *NamedBoolArray) (rel []RadioElement)

func (RequestWriter) Range added in v0.39.0 

func (rq RequestWriter) Range(value any, params ...any) error

func (RequestWriter) Register added in v0.78.0 

func (rq RequestWriter) Register(updater Updater, params ...any) jid.Jid

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) Request added in v0.40.0 

func (rw RequestWriter) Request() *Request

Request returns the current jaws.Request.

func (RequestWriter) Select added in v0.39.0 

func (rq RequestWriter) Select(sh SelectHandler, params ...any) error

func (RequestWriter) Session added in v0.40.0 

func (rw RequestWriter) Session() *Session

Session returns the Requests's Session, or nil.

func (RequestWriter) Set added in v0.40.0 

func (rw RequestWriter) Set(key string, val any)

Set calls Request().Set()

func (RequestWriter) Span added in v0.39.0 

func (rq RequestWriter) Span(innerHTML any, params ...any) error

func (RequestWriter) TailHTML added in v0.79.0 

func (rw 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.

func (RequestWriter) Tbody added in v0.39.0 

func (rq RequestWriter) Tbody(c Container, params ...any) error

func (RequestWriter) Td added in v0.39.0 

func (rq RequestWriter) Td(innerHTML any, params ...any) error

func (RequestWriter) Template added in v0.39.0 

func (rq RequestWriter) Template(name string, dot any, params ...any) error

Template renders the given template using jaws.With{Dot: dot} as data.

The name argument is a string to be resolved to a *template.Template using Jaws.LookupTemplate().

func (RequestWriter) Text added in v0.39.0 

func (rq RequestWriter) Text(value any, params ...any) error

func (RequestWriter) Textarea added in v0.39.0 

func (rq RequestWriter) Textarea(value any, params ...any) error

func (RequestWriter) Tr added in v0.39.0 

func (rq RequestWriter) Tr(innerHTML any, params ...any) error

func (RequestWriter) UI added in v0.39.0 

func (rw RequestWriter) UI(ui UI, params ...any) error

func (RequestWriter) Write added in v0.54.0 

func (rw RequestWriter) Write(p []byte) (n int, err error)

type SelectHandler added in v0.31.0 

type SelectHandler interface {
	Container
	Setter[string]
}

type Session added in v0.11.0 

type Session struct {
	// contains filtered or unexported fields
}

func (*Session) Broadcast added in v0.26.0 

func (sess *Session) Broadcast(msg Message)

Broadcast attempts to send a message to all Requests using this session. It is safe to call on a nil Session.

func (*Session) Clear added in v0.16.0 

func (sess *Session) Clear()

Clear removes all key/value pairs from the session. It is safe to call on a nil Session.

func (*Session) Close added in v0.17.0 

func (sess *Session) Close() (cookie *http.Cookie)

Close invalidates and expires the Session. Future Requests won't be able to associate with it, and Cookie() will return a deletion cookie.

Existing Requests already associated with the Session will ask the browser to reload the pages. Key/value pairs in the Session are left unmodified, you can use `Session.Clear()` to remove all of them.

Returns a cookie to be sent to the client browser that will delete the browser cookie. Returns nil if the session was not found or is already closed. It is safe to call on a nil Session.

func (*Session) Cookie added in v0.11.0 

func (sess *Session) Cookie() (cookie *http.Cookie)

Cookie returns a cookie for the Session. Returns a delete cookie if the Session is expired. It is safe to call on a nil Session, in which case it returns nil.

func (*Session) CookieValue added in v0.11.0 

func (sess *Session) CookieValue() (s string)

CookieValue returns the session cookie value. It is safe to call on a nil Session, in which case it returns an empty string.

func (*Session) Get added in v0.11.0 

func (sess *Session) Get(key string) (val any)

Get returns the value associated with the key, or nil. It is safe to call on a nil Session.

func (*Session) ID added in v0.11.0 

func (sess *Session) ID() (id uint64)

ID returns the session ID, a 64-bit random value. It is safe to call on a nil Session, in which case it returns zero.

func (*Session) IP added in v0.11.0 

func (sess *Session) IP() (ip netip.Addr)

IP returns the remote IP the session is bound to (which may be nil). It is safe to call on a nil Session, in which case it returns nil.

func (*Session) Jaws added in v0.81.0 

func (sess *Session) Jaws() (jw *Jaws)

Jaws returns the Jaws instance of the Session, or nil. It is safe to call on a nil Session.

func (*Session) Reload added in v0.17.0 

func (sess *Session) Reload()

Reload calls Broadcast with a message asking browsers to reload the page.

func (*Session) Requests added in v0.37.0 

func (sess *Session) Requests() (rl []*Request)

Requests returns a list of the Requests using this Session. It is safe to call on a nil Session.

func (*Session) Set added in v0.11.0 

func (sess *Session) Set(key string, val any)

Set sets a value to be associated with the key. If value is nil, the key is removed from the session. It is safe to call on a nil Session.

type Setter added in v0.78.0 

type Setter[T comparable] interface {
	Getter[T]
	// JawsSet may return ErrValueUnchanged to indicate value was already set.
	JawsSet(elem *Element, value T) (err error)
}

type Tag added in v0.31.0 

type Tag string

type TagGetter added in v0.31.0 

type TagGetter interface {
	JawsGetTag(rq *Request) any // Note that the Request may be nil
}

type Template added in v0.31.0 

type Template struct {
	Name string // Template name to be looked up using jaws.LookupTemplate()
	Dot  any    // Dot value to place in With structure
}

func NewTemplate added in v0.66.0 

func NewTemplate(name string, dot any) Template

NewTemplate simply returns a Template{} with the members set.

Provided as convenience so as to not have to name the structure members.

func (Template) JawsEvent added in v0.31.0 

func (t Template) JawsEvent(e *Element, wht what.What, val string) error

func (Template) JawsRender added in v0.31.0 

func (t Template) JawsRender(e *Element, wr io.Writer, params []any) error

func (Template) JawsUpdate added in v0.31.0 

func (t Template) JawsUpdate(e *Element)

func (Template) String added in v0.31.0 

func (t Template) String() string

type TemplateLookuper added in v0.45.0 

type TemplateLookuper interface {
	Lookup(name string) *template.Template
}

TemplateLookuper resolves a name to a *template.Template.

type UI added in v0.31.0 

type UI interface {
	Renderer
	Updater
}

UI defines the required methods on JaWS UI objects. In addition, all UI objects must be comparable so they can be used as map keys.

type UiA added in v0.31.0 

type UiA struct {
	UiHTMLInner
}

func NewUiA added in v0.31.0 

func NewUiA(innerHTML HTMLGetter) *UiA

func (*UiA) JawsRender added in v0.31.0 

func (ui *UiA) JawsRender(e *Element, w io.Writer, params []any) error

type UiButton added in v0.31.0 

type UiButton struct {
	UiHTMLInner
}

func NewUiButton added in v0.31.0 

func NewUiButton(innerHTML HTMLGetter) *UiButton

func (*UiButton) JawsRender added in v0.31.0 

func (ui *UiButton) JawsRender(e *Element, w io.Writer, params []any) error

type UiCheckbox added in v0.31.0 

type UiCheckbox struct {
	UiInputBool
}

func NewUiCheckbox added in v0.31.0 

func NewUiCheckbox(g Setter[bool]) *UiCheckbox

func (*UiCheckbox) JawsRender added in v0.31.0 

func (ui *UiCheckbox) JawsRender(e *Element, w io.Writer, params []any) error

type UiContainer added in v0.31.0 

type UiContainer struct {
	OuterHTMLTag string
	// contains filtered or unexported fields
}

func NewUiContainer added in v0.31.0 

func NewUiContainer(outerHTMLTag string, c Container) *UiContainer

func (*UiContainer) JawsRender added in v0.31.0 

func (ui *UiContainer) JawsRender(e *Element, w io.Writer, params []any) error

func (*UiContainer) JawsUpdate added in v0.31.0 

func (ui *UiContainer) JawsUpdate(e *Element)

type UiDate added in v0.31.0 

type UiDate struct {
	UiInputDate
}

func NewUiDate added in v0.31.0 

func NewUiDate(g Setter[time.Time]) *UiDate

func (*UiDate) JawsRender added in v0.31.0 

func (ui *UiDate) JawsRender(e *Element, w io.Writer, params []any) error

type UiDiv added in v0.31.0 

type UiDiv struct {
	UiHTMLInner
}

func NewUiDiv added in v0.31.0 

func NewUiDiv(innerHTML HTMLGetter) *UiDiv

func (*UiDiv) JawsRender added in v0.31.0 

func (ui *UiDiv) JawsRender(e *Element, w io.Writer, params []any) error

type UiHTMLInner added in v0.104.0 

type UiHTMLInner struct {
	HTMLGetter
}

func (*UiHTMLInner) JawsUpdate added in v0.104.0 

func (ui *UiHTMLInner) JawsUpdate(e *Element)

type UiImg added in v0.31.0 

type UiImg struct {
	Getter[string]
}

func NewUiImg added in v0.31.0 

func NewUiImg(g Getter[string]) *UiImg

func (*UiImg) JawsRender added in v0.31.0 

func (ui *UiImg) JawsRender(e *Element, w io.Writer, params []any) error

func (*UiImg) JawsUpdate added in v0.31.0 

func (ui *UiImg) JawsUpdate(e *Element)

type UiInput added in v0.31.0 

type UiInput struct {
	Tag  any
	Last atomic.Value
}

type UiInputBool added in v0.31.0 

type UiInputBool struct {
	UiInput
	Setter[bool]
}

func (*UiInputBool) JawsEvent added in v0.31.0 

func (ui *UiInputBool) JawsEvent(e *Element, wht what.What, val string) (err error)

func (*UiInputBool) JawsUpdate added in v0.31.0 

func (ui *UiInputBool) JawsUpdate(e *Element)

type UiInputDate added in v0.31.0 

type UiInputDate struct {
	UiInput
	Setter[time.Time]
}

func (*UiInputDate) JawsEvent added in v0.31.0 

func (ui *UiInputDate) JawsEvent(e *Element, wht what.What, val string) (err error)

func (*UiInputDate) JawsUpdate added in v0.31.0 

func (ui *UiInputDate) JawsUpdate(e *Element)

type UiInputFloat added in v0.31.0 

type UiInputFloat struct {
	UiInput
	Setter[float64]
}

func (*UiInputFloat) JawsEvent added in v0.31.0 

func (ui *UiInputFloat) JawsEvent(e *Element, wht what.What, val string) (err error)

func (*UiInputFloat) JawsUpdate added in v0.31.0 

func (ui *UiInputFloat) JawsUpdate(e *Element)

type UiInputText added in v0.31.0 

type UiInputText struct {
	UiInput
	Setter[string]
}

func (*UiInputText) JawsEvent added in v0.31.0 

func (ui *UiInputText) JawsEvent(e *Element, wht what.What, val string) (err error)

func (*UiInputText) JawsUpdate added in v0.31.0 

func (ui *UiInputText) JawsUpdate(e *Element)

type UiLabel added in v0.31.0 

type UiLabel struct {
	UiHTMLInner
}

func NewUiLabel added in v0.31.0 

func NewUiLabel(innerHTML HTMLGetter) *UiLabel

func (*UiLabel) JawsRender added in v0.31.0 

func (ui *UiLabel) JawsRender(e *Element, w io.Writer, params []any) error

type UiLi added in v0.31.0 

type UiLi struct {
	UiHTMLInner
}

func NewUiLi added in v0.31.0 

func NewUiLi(innerHTML HTMLGetter) *UiLi

func (*UiLi) JawsRender added in v0.31.0 

func (ui *UiLi) JawsRender(e *Element, w io.Writer, params []any) error

type UiNumber added in v0.31.0 

type UiNumber struct {
	UiInputFloat
}

func NewUiNumber added in v0.31.0 

func NewUiNumber(g Setter[float64]) *UiNumber

func (*UiNumber) JawsRender added in v0.31.0 

func (ui *UiNumber) JawsRender(e *Element, w io.Writer, params []any) error

type UiOption added in v0.31.0 

type UiOption struct{ *NamedBool }

func (UiOption) JawsRender added in v0.31.0 

func (ui UiOption) JawsRender(e *Element, w io.Writer, params []any) error

func (UiOption) JawsUpdate added in v0.31.0 

func (ui UiOption) JawsUpdate(e *Element)

type UiPassword added in v0.31.0 

type UiPassword struct {
	UiInputText
}

func NewUiPassword added in v0.31.0 

func NewUiPassword(g Setter[string]) *UiPassword

func (*UiPassword) JawsRender added in v0.31.0 

func (ui *UiPassword) JawsRender(e *Element, w io.Writer, params []any) error

type UiRadio added in v0.31.0 

type UiRadio struct {
	UiInputBool
}

func NewUiRadio added in v0.31.0 

func NewUiRadio(vp Setter[bool]) *UiRadio

func (*UiRadio) JawsRender added in v0.31.0 

func (ui *UiRadio) JawsRender(e *Element, w io.Writer, params []any) error

type UiRange added in v0.31.0 

type UiRange struct {
	UiInputFloat
}

func NewUiRange added in v0.31.0 

func NewUiRange(g Setter[float64]) *UiRange

func (*UiRange) JawsRender added in v0.31.0 

func (ui *UiRange) JawsRender(e *Element, w io.Writer, params []any) error

type UiRegister added in v0.78.0 

type UiRegister struct {
	Updater
}

func (UiRegister) JawsRender added in v0.78.0 

func (ui UiRegister) JawsRender(e *Element, w io.Writer, params []any) (err error)

type UiSelect added in v0.31.0 

type UiSelect struct {
	// contains filtered or unexported fields
}

func NewUiSelect added in v0.31.0 

func NewUiSelect(sh SelectHandler) *UiSelect

func (*UiSelect) JawsEvent added in v0.31.0 

func (ui *UiSelect) JawsEvent(e *Element, wht what.What, val string) (err error)

func (*UiSelect) JawsRender added in v0.31.0 

func (ui *UiSelect) JawsRender(e *Element, w io.Writer, params []any) error

func (*UiSelect) JawsUpdate added in v0.31.0 

func (ui *UiSelect) JawsUpdate(e *Element)

type UiSpan added in v0.31.0 

type UiSpan struct {
	UiHTMLInner
}

func NewUiSpan added in v0.31.0 

func NewUiSpan(innerHTML HTMLGetter) *UiSpan

func (*UiSpan) JawsRender added in v0.31.0 

func (ui *UiSpan) JawsRender(e *Element, w io.Writer, params []any) error

type UiTbody added in v0.31.0 

type UiTbody struct {
	// contains filtered or unexported fields
}

func NewUiTbody added in v0.31.0 

func NewUiTbody(c Container) *UiTbody

func (*UiTbody) JawsRender added in v0.31.0 

func (ui *UiTbody) JawsRender(e *Element, w io.Writer, params []any) error

func (*UiTbody) JawsUpdate added in v0.31.0 

func (ui *UiTbody) JawsUpdate(e *Element)

type UiTd added in v0.31.0 

type UiTd struct {
	UiHTMLInner
}

func NewUiTd added in v0.31.0 

func NewUiTd(innerHTML HTMLGetter) *UiTd

func (*UiTd) JawsRender added in v0.31.0 

func (ui *UiTd) JawsRender(e *Element, w io.Writer, params []any) error

type UiText added in v0.31.0 

type UiText struct {
	UiInputText
}

func NewUiText added in v0.31.0 

func NewUiText(vp Setter[string]) (ui *UiText)

func (*UiText) JawsRender added in v0.31.0 

func (ui *UiText) JawsRender(e *Element, w io.Writer, params []any) error

type UiTextarea added in v0.31.0 

type UiTextarea struct {
	UiInputText
}

func NewUiTextarea added in v0.31.0 

func NewUiTextarea(g Setter[string]) (ui *UiTextarea)

func (*UiTextarea) JawsRender added in v0.31.0 

func (ui *UiTextarea) JawsRender(e *Element, w io.Writer, params []any) error

func (*UiTextarea) JawsUpdate added in v0.31.0 

func (ui *UiTextarea) JawsUpdate(e *Element)

type UiTr added in v0.31.0 

type UiTr struct {
	UiHTMLInner
}

func NewUiTr added in v0.31.0 

func NewUiTr(innerHTML HTMLGetter) *UiTr

func (*UiTr) JawsRender added in v0.31.0 

func (ui *UiTr) JawsRender(e *Element, w io.Writer, params []any) error

type Updater added in v0.60.0 

type Updater interface {
	// JawsUpdate is called for an Element that has been marked dirty to update it's HTML.
	// Do not call this yourself unless it's from within another JawsUpdate implementation.
	JawsUpdate(e *Element)
}

type VarMaker added in v0.78.0 

type VarMaker interface {
	// JawsVarMake must return an object that implements IsJsVar, Setter[T] and UI, usually a JsVar[T].
	JawsVarMake(rq *Request) (IsJsVar, error)
}

type With added in v0.31.0 

type With struct {
	*Element                        // the Element being rendered using a template.
	RequestWriter                   // the RequestWriter
	Dot           any               // user data parameter
	Attrs         template.HTMLAttr // HTML attributes string
	Auth          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

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.