Views
Views are the building blocks of an altseven UI. A view owns a mount point in the DOM, a state object, and a template that turns state into HTML.
Creating and registering a view
A view is created with new View( props ) and registered with the UI manager:
import { View } from "/lib/altseven/dist/a7.js";
const greeting = new View( {
id: "greeting", // unique id used to address the view
selector: "#greeting", // CSS selector of its mount point
parentID: "main", // omit for top-level views
cacheTemplate: false, // opt-in template caching (see below)
isTransient: false // transient views are garbage-collected
} );
greeting.state = { name: "world" };
greeting.template = function() {
return `<h3>Hello ${ greeting.state.name }!</h3>`;
};
myApp.ui.register( greeting );
register() injects the application’s log, model, UI manager, renderer and
debounce settings into the view, links it to its parent (if parentID is set),
and fires the registered event — which enqueues top-level views for their
first render. Child views render when their parent paints, not when they are
registered.
Templates
A template is either a string or a function returning a string. Template literal expressions are plain JavaScript:
todoList.template = function() {
const state = todoList.getState();
const items = state.items
.filter( t => !t.done )
.map( t => `<li data-id="${ t.id }">${ t.title }</li>` )
.join( "" );
return `<ul>${ items }</ul>
<p>${ state.items.length - state.items.filter( t => t.done ).length } remaining</p>`;
};
The rendered string is assigned to the mount point’s innerHTML, then the
framework scans it for data-on<event> and data-bind attributes (below).
Event handlers: data-on attributes
Event listeners cannot be embedded in template literals, so altseven uses a
declarative convention: an element attribute data-on<event> names a method on
the view’s eventHandlers object, and the framework binds the listener after
each render.
counter.template = function() {
return `<button data-onclick="increment">${ counter.state.count }</button>`;
};
counter.eventHandlers = {
increment: function( event ) {
counter.setState( { count: counter.state.count + 1 } );
}
};
The supported events are the standard browser event groups: mouse (click,
dblclick, mousedown, …), keyboard (keydown, keyup, …), focus, form
(submit, reset), clipboard, media, CSS animation/transition, printing, and
more.
Because listeners are re-bound after every render, handlers always operate on the current DOM — you never have to manually re-attach anything.
State
setState() merges the keys you pass into the existing state and schedules a
debounced repaint of that view:
// merge { count: 5 } into state; other keys are untouched
counter.setState( { count: 5 } );
const state = counter.getState(); // a copy of the current state
Since 8.0, setState() is a partial update: only the keys in the argument
change. The view repaints via the UI manager’s render queue; the debounce
interval defaults to 18ms and is configurable (ui.debounceTime).
If the view has a registered DataProvider, setState() and getState()
delegate to it (see DataProviders).
Child views
Views form a tree via props.parentID. A child’s selector must match a node
created by its parent’s template, not the static page HTML:
// parent
const main = new View( { id: "main", selector: "#main" } );
main.template = () => `
<header id="header"></header>
<section id="content"></section>`;
myApp.ui.register( main );
// children
const header = new View( {
id: "header",
parentID: "main",
selector: "#header"
} );
const content = new View( {
id: "content",
parentID: "main",
selector: "#content"
} );
myApp.ui.register( header );
myApp.ui.register( content );
After a parent renders, its onRendered() re-resolves and renders every
registered child, so children repaint whenever the parent repaints.
Timing gotcha (fixed in 9.1.4)
A child view whosesetState() is driven by an async load can be rendered
before its parent has painted — the parent’s debounced first render hasn’t
created the child’s mount point yet. Since 9.1.4 the framework recognizes this:
if the parent has never painted, the child stays registered and renders when
the parent paints. Before 9.1.4 this race silently and permanently destroyed
the child view.
The render lifecycle
You drive rendering through setState(); the framework handles the rest. The
internal sequence for a repaint:
setState()clears the view’s template cache and firesmustRender.mustRenderis debounced bydebounceTime; when it lands, the view is enqueued in the UI manager’s render queue.render()resolves the mount point, evaluates the template (or reuses the cached string — see below), paints, bindsdata-onlisteners anddata-bindmodel bindings.hasRenderedis set, then therenderedevent firesonRendered(), which renders the view’s children.- Errors in rendered callbacks are caught and logged — they cannot leave the render pipeline stuck or block other views in the queue (8.2.1).
If the mount point of a top-level view (or of a child whose parent has already painted) no longer exists, the view is removed from its parent and unregistered — that is a genuine misconfiguration, not a timing issue.
Template caching (opt-in)
Since 9.0, template caching is per-view and off by default. A view that
opts in with props.cacheTemplate: true (and the app-wide ui.cacheTemplates
not disabled) reuses the last rendered string on mayRender repaints — useful
when a view is repainted but its template output cannot have changed.
mustRender— template inputs may have changed; always re-evaluates the template. Fired bysetState().mayRender— repaint, allowed to use the cached template. Use when you know the output hasn’t changed (e.g. re-attach after a parent re-render).
You rarely fire these yourself — setState() covers the normal path.
Transient views
Set props.isTransient: true for views that should be garbage-collected if
their mount point disappears (e.g. overlays, modals). The framework schedules a
check after each render (interval: ui.timeout, default 10 minutes) and
unregisters the view when its selector no longer resolves.
Model bindings: data-bind
Any element with a data-bind="<key>" attribute is bound to a key in the
application model after each render: changes in the model update the element
and edits to the element update the model.
profile.template = () => `
<input type="text" data-bind="user.firstname">`;
See Configuring Your Application for the model
options, and the API reference for the full
View method list.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.