aicoded.dev

Live values

A live value is rendered on the server like any other, then rendered again and sent to the open page whenever it changes, over the page's one live connection. The browser gets text or escaped markup, never a template, and an input can write a value back through a check you write.

Declaring

<ssr:var name="visitorsOnline" type="int" reactive="true"/>
<ssr:var name="displayName" type="string" reactive="true" client-writable="true"/>

A page with live values gets a Subscribe hook, a ReactiveState with a Set<Name> method per live value, and a reactive_gen.ts for its script. Data sets the first value, as for any variable.

Sending values from the server

Subscribe runs while the page is open, on its own goroutine, and sends values with state.Set<Name>:

// Subscribe counts this page among the open home pages while it is open, and shows the count
// whenever a home page opens or closes.
func (p *DP) Subscribe(ctx context.Context, _ *web.Request, state *ReactiveState) error {
	sub := p.d.HomePages.Subscribe()
	defer func() {
		sub.Close()
		p.d.HomePages.Publish(struct{}{})
	}()
	p.d.HomePages.Publish(struct{}{})
	for {
		select {
		case <-ctx.Done():
			return nil
		case <-sub.Updates():
			n := p.d.HomePages.TotalSubs()
			state.SetVisitorsOnline(n)
			state.SetVisitorsTone(tone(n))
		}
	}
}

Waking Subscribe from elsewhere

Something else in the app changes the value: another page's form, another viewer. Package web/reactive has two hubs for this. Make them once, in deps.Deps, so every page shares them:

The add form of the people example publishes once the new user is stored:

p.d.UsersAdded.Publish(struct{}{})

and the users list counts the users again when it hears it:

// Subscribe counts the users again whenever one is added.
func (p *DP) Subscribe(ctx context.Context, _ *web.Request, state *ReactiveState) error {
	sub := p.d.UsersAdded.Subscribe()
	defer sub.Close()
	for {
		select {
		case <-ctx.Done():
			return nil
		case <-sub.Updates():
			n, err := p.d.CountUsers(ctx)
			if err != nil {
				return err
			}
			state.SetUserCount(n)
		}
	}
}

A topic works the same way, with a key: topic.Publish(login, t) and sub := topic.Subscribe(r.URLParam("login")).

The hubs live in the app's memory, so they reach the pages this instance of the app serves.

Values the page writes

A client-writable value needs Validate<Name>, which gets every value the page sends and returns the one to store:

// ValidateDisplayName accepts a display name of at most 50 characters.
func (p *DP) ValidateDisplayName(_ context.Context, _ *web.Request, val string) (string, error) {
	if utf8.RuneCountInString(val) > 50 {
		return "", web.Error(http.StatusUnprocessableEntity, "Use at most 50 characters.")
	}
	return val, nil
}

The page writes the value in one of two ways:

What updates

The generator finds every place in the template that reads a live value:

Place What the page gets
{{ count }} or {{ a + b }} in text the new text, in a <span> around it
a live value in an attribute the whole element, rendered again
an ssr:if chain that reads one the whole chain, in an <ssr-block> element
an ssr:for that reads one, in its list or its body the whole loop; a loop of <tr> rows is wrapped in a <tbody>

Text is shown as text; elements are markup rendered by the page's escapers. A part inside a bigger live part is sent with it, once. Keep live parts small: a live loop sends all its rows on every change.

Some places cannot update, and the generator refuses them:

The live connection

A page with live values or page calls opens one connection, at its address plus /__ws; the layouts' and the page's live values share it.

See also

Markdown · Source on GitHub · framework f46741f