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.
It comes with a small package 'jawsecho' that integrates with Echo and also doubles as an example for integration with other routers.
Index ¶
- Constants
- Variables
- func CastFloat64(i int) float64
- func CastInt(f float64) int
- func HeadHTML(jawsKey uint64, extraScripts []string) template.HTML
- func JavascriptGZip() []byte
- func JavascriptPath() string
- func JavascriptText() []byte
- func JawsKeyString(jawsKey uint64) string
- type ClickFn
- type ConnectFn
- type EventFn
- type InputBoolFn
- type InputDateFn
- type InputFloatFn
- type InputTextFn
- type Jaws
- func (jw *Jaws) Alert(lvl, msg string)
- func (jw *Jaws) Append(parentId, html string)
- func (jw *Jaws) Broadcast(msg *Message)
- func (jw *Jaws) Close()
- func (jw *Jaws) Done() <-chan struct{}
- func (jw *Jaws) Insert(parentId, where, html string)
- func (jw *Jaws) Log(err error) error
- func (jw *Jaws) MakeID() string
- func (jw *Jaws) MustLog(err error)
- func (jw *Jaws) NewRequest(ctx context.Context, remoteAddr string) (rq *Request)
- func (jw *Jaws) Pending() (n int)
- func (jw *Jaws) Redirect(url string)
- func (jw *Jaws) Reload()
- func (jw *Jaws) Remove(id string)
- func (jw *Jaws) RemoveAttr(id, attr string)
- func (jw *Jaws) Replace(id, where, html string)
- func (jw *Jaws) Serve()
- func (jw *Jaws) ServeWithTimeout(requestTimeout time.Duration)
- func (jw *Jaws) SetAttr(id, attr, val string)
- func (jw *Jaws) SetInner(id string, innerHtml string)
- func (jw *Jaws) SetValue(id, val string)
- func (jw *Jaws) Trigger(id, val string)
- func (jw *Jaws) UseRequest(jawsKey uint64, remoteAddr string) (rq *Request)
- type Message
- type NamedBool
- type NamedBoolArray
- type Request
- func (rq *Request) A(id, inner string, fn ClickFn, attrs string) template.HTML
- func (rq *Request) Alert(lvl, msg string)
- func (rq *Request) AlertError(err error)
- func (rq *Request) Broadcast(msg *Message)
- func (rq *Request) Button(id, txt string, fn ClickFn, attrs string) template.HTML
- func (rq *Request) Checkbox(id string, val bool, fn InputBoolFn, attrs string) template.HTML
- func (rq *Request) Context() (ctx context.Context)
- func (rq *Request) Date(id string, val time.Time, fn InputDateFn, attrs string) template.HTML
- func (rq *Request) Div(id, inner string, fn ClickFn, attrs string) template.HTML
- func (rq *Request) GetEventFn(id string) (fn EventFn, ok bool)
- func (rq *Request) HeadHTML() template.HTML
- func (rq *Request) JawsKeyString() string
- func (rq *Request) Li(id, inner string, fn ClickFn, attrs string) template.HTML
- func (rq *Request) OnClick(id string, fn ClickFn) error
- func (rq *Request) OnEvent(id string, fn EventFn) error
- func (rq *Request) OnInput(id string, fn InputTextFn) error
- func (rq *Request) Radio(id string, val bool, fn InputBoolFn, attrs string) template.HTML
- func (rq *Request) Range(id string, val float64, fn InputFloatFn, attrs string) template.HTML
- func (rq *Request) Redirect(url string)
- func (rq *Request) Register(id string) string
- func (rq *Request) RegisterEventFn(id string, fn EventFn) string
- func (rq *Request) RemoveAttr(id, attr string)
- func (rq *Request) Select(id string, val *NamedBoolArray, fn InputTextFn, attrs string) template.HTML
- func (rq *Request) Send(msg *Message) bool
- func (rq *Request) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (rq *Request) SetAttr(id, attr, val string)
- func (rq *Request) SetBoolValue(id string, val bool)
- func (rq *Request) SetDateValue(id string, val time.Time)
- func (rq *Request) SetEventFn(id string, fn EventFn)
- func (rq *Request) SetFloatValue(id string, val float64)
- func (rq *Request) SetInner(id string, innerHtml string)
- func (rq *Request) SetTextValue(id, val string)
- func (rq *Request) Span(id, inner string, fn ClickFn, attrs string) template.HTML
- func (rq *Request) String() string
- func (rq *Request) Td(id, inner string, fn ClickFn, attrs string) template.HTML
- func (rq *Request) Text(id, val string, fn InputTextFn, attrs string) template.HTML
- func (rq *Request) Trigger(id, val string)
Constants ¶
const ISO8601 = "2006-01-02"
Variables ¶
var FuncMap = template.FuncMap{ "int": CastInt, "float64": CastFloat64, }
Functions ¶
func CastFloat64 ¶
func HeadHTML ¶
HeadHTML returns the HTML code to load the required CSS and Javascript libraries along with any Javascript URL's given in extraScripts. Place the returned HTML code in the HEAD section of the document.
func JavascriptGZip ¶
func JavascriptGZip() []byte
JavascriptGZip returns the embedded Javascript library GZipped.
func JavascriptPath ¶
func JavascriptPath() string
JavascriptPath returns the path for the embedded JaWS Javascript library.
func JavascriptText ¶
func JavascriptText() []byte
JavascriptText returns the source code for the client-side JaWS Javascript library.
func JawsKeyString ¶
Types ¶
type ConnectFn ¶
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 EventFn ¶
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 InputBoolFn ¶
type InputFloatFn ¶
type InputTextFn ¶
type Jaws ¶
type Jaws struct { Logger *log.Logger // If not nil, send debug info and errors here // 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{}) *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) Alert ¶
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 ¶
Append calls the Javascript 'appendChild()' method on the given element on all Requests.
Only the requests that have registered the ID (either with Register or OnEvent) will be sent the message.
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 are discarded. Subsequent calls to Close() have no effect.
func (*Jaws) Insert ¶
Insert calls the Javascript 'insertBefore()' method on the given element on all Requests. The position parameter 'where' may be either a HTML ID, an child index or the text 'null'.
Only the requests that have registered the ID (either with Register or OnEvent) will be sent the message.
func (*Jaws) Log ¶
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) MakeID ¶
MakeID returns a string in the form 'jaws.X' where X is a string unique within the Jaws lifetime.
func (*Jaws) MustLog ¶ added in v0.1.1
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 ¶
NewRequest returns a new JaWS request. 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 HTML entity id's you use in the response, and use it's Key attribute when sending the Javascript portion of the reply with GetBodyFooter.
Don't use the http.Request's Context, as that will expire before the WebSocket call comes in.
func (*Jaws) Reload ¶
func (jw *Jaws) Reload()
Reload requests all Requests to reload their current page.
func (*Jaws) Remove ¶
Remove removes the HTML element with the given ID on all Requests.
Only the requests that have registered the ID (either with Register or OnEvent) will be sent the message.
func (*Jaws) RemoveAttr ¶
RemoveAttr removes a given attribute from the HTML id for all Requests.
Only the requests that have registered the ID (either with Register or OnEvent) will be sent the message.
func (*Jaws) Replace ¶
Replace calls the Javascript 'replaceChild()' method on the given element on all Requests. The position parameter 'where' may be either a HTML ID or an index.
Only the requests that have registered the ID (either with Register or OnEvent) will be sent the message.
func (*Jaws) ServeWithTimeout ¶
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) SetAttr ¶
SetAttr sends an HTML id and new attribute value to all Requests. If the value is an empty string, a value-less attribute will be added (such as "disabled")
Only the requests that have registered the ID (either with Register or OnEvent) will be sent the message.
func (*Jaws) SetInner ¶
SetInner sends an HTML id and new inner HTML to all Requests.
Only the requests that have registered the ID (either with Register or OnEvent) will be sent the message.
func (*Jaws) SetValue ¶
SetValue sends an HTML id and new input value to all Requests.
Only the requests that have registered the ID (either with Register or OnEvent) will be sent the message.
func (*Jaws) Trigger ¶
Trigger invokes the event handler for the given ID with a 'trigger' event on all Requests.
func (*Jaws) UseRequest ¶
UseRequest removes the JaWS request with the given key from the request map if it exists and the remoteAddr matches, and if so returns the Request.
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, in which case you should return a HTTP 404 Not Found code.
type Message ¶
type Message struct { Elem string // HTML element id or command (e.g. ' alert' or 'myButtonId') What string // what to change or do, (e.g. 'inner') Data string // data (e.g. inner HTML content) // contains filtered or unexported fields }
Message contains the elements of a message to be sent to Requests.
type NamedBool ¶
NamedBool stores the data required to support HTML 'select' elements and sets of HTML radio buttons.
type NamedBoolArray ¶
type NamedBoolArray []*NamedBool
NamedBoolArray is an array of pointers to NamedBool.
func NewNamedBoolArray ¶
func NewNamedBoolArray() *NamedBoolArray
NewNamedBoolArray allocates an array of *NamedBool and returns a pointer to it.
func (*NamedBoolArray) Add ¶
func (nb *NamedBoolArray) Add(val, text string)
Add creates a new NamedBool and appends it's pointer to the NamedBoolArray.
func (*NamedBoolArray) Check ¶
func (nb *NamedBoolArray) Check(val string)
Check sets all NamedBool's Checked to true in the NamedBoolArray that have the given Value.
func (*NamedBoolArray) Set ¶
func (nb *NamedBoolArray) Set(val string, state bool)
Set sets all NamedBool's Checked to state in the NamedBoolArray that have the given Value.
func (*NamedBoolArray) String ¶
func (nb *NamedBoolArray) String() string
type Request ¶
type Request struct { Jaws *Jaws // the JaWS instance the Request belongs to JawsKey uint64 // a random number used in the WebSocket URI to identify this Request ConnectFn ConnectFn // a ConnectFn to call before starting message processing for the Request Started time.Time // when the Request was started, used for automatic cleanup // 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 ¶
Alert attempts to show an alert message on the current request webpage if it has an HTML element with the id 'jaws-alert'.
The default JaWS javascript only supports Bootstrap.js dismissable alerts.
func (*Request) AlertError ¶
AlertError calls Alert if the given error is not nil.
func (*Request) GetEventFn ¶
GetEventFn checks if a given HTML element is registered and returns the it's event function (or nil) along with a boolean indicating if it's a registered HTML id.
func (*Request) HeadHTML ¶
HeadHTML returns the HTML code needed to write in the HTML page's HEAD section.
func (*Request) JawsKeyString ¶
func (*Request) OnClick ¶
OnClick registers a HTML id and a function to be called when it's click event fires. Returns a nil error so it can be used inside templates.
func (*Request) OnEvent ¶
OnEvent calls SetEventFn. Returns a nil error so it can be used inside templates.
func (*Request) OnInput ¶
func (rq *Request) OnInput(id string, fn InputTextFn) error
OnInput registers a HTML id and a function to be called when it's input event fires. Returns a nil error so it can be used inside templates.
func (*Request) Register ¶
Register calls RegisterEventFn(id, nil). Useful in template constructs like:
<div id="{{$.Register `foo`}}">
func (*Request) RegisterEventFn ¶
RegisterEventFn records the given HTML element ID as a valid target for dynamic updates using the given event function (which may be nil). All ID's in a HTML DOM tree must be unique.
If the id argument is an empty string, a unique ID will be generated.
If fn argument is nil, a pre-existing event function won't be overwritten.
Returns the (possibly generated) id.
func (*Request) RemoveAttr ¶
RemoveAttr removes a given attribute from the HTML id for the current Request only.
Only the requests that have registered the ID (either with Register or OnEvent) will be sent the message.
func (*Request) Select ¶
func (rq *Request) Select(id string, val *NamedBoolArray, fn InputTextFn, attrs string) template.HTML
func (*Request) Send ¶
Send queues up a message for sending to the current Request only. Returns true if the message was successfully queued for sending.
func (*Request) ServeHTTP ¶
func (rq *Request) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP implements http.HanderFunc
func (*Request) SetAttr ¶
SetAttr sets an attribute on the HTML element on the current Request only. If the value is an empty string, a value-less attribute will be added (such as "disabled").
Only the requests that have registered the ID (either with Register or OnEvent) will be sent the message.
func (*Request) SetBoolValue ¶
SetBoolValue sends an HTML id and new input value to all Requests except this one.
Only the requests that have registered the ID (either with Register or OnEvent) will be sent the message.
func (*Request) SetDateValue ¶
SetDateValue sends an HTML id and new input value to all Requests except this one.
Only the requests that have registered the ID (either with Register or OnEvent) will be sent the message.
func (*Request) SetEventFn ¶
SetEventFn sets the event function for the given HTML ID to be the given function. Passing nil for the function is legal, and has the effect of ensuring the ID can be the target of DOM updates but not to send Javascript events. Note that you can only have one event function per ID.
func (*Request) SetFloatValue ¶
SetFloatValue sends an HTML id and new input value to all Requests except this one.
Only the requests that have registered the ID (either with Register or OnEvent) will be sent the message.
func (*Request) SetInner ¶
SetInner sends an HTML id and new inner HTML to all Requests except this one.
Only the requests that have registered the ID (either with Register or OnEvent) will be sent the message.
func (*Request) SetTextValue ¶
SetTextValue sends an HTML id and new input value to all Requests except this one.
Only the requests that have registered the ID (either with Register or OnEvent) will be sent the message.