Events
altseven uses a lightweight publish/subscribe system (myApp.events) for
communication between components, plus per-view instance events for the render
lifecycle.
Application events: publish/subscribe
The EventManager manages named topics. Any code can publish to a topic; any
code can subscribe:
// subscribe — returns a handle with .remove() to unsubscribe
const handle = myApp.events.subscribe( "user.profile", function( obj ) {
// load and display the user profile
} );
// later: handle.remove();
// publish
myApp.events.publish( "user.profile", { userID: user.userID } );
Publishing to a topic with no listeners is a no-op. Each listener is isolated
(since 9.1.2): a listener that throws is logged via myApp.log.error and the
remaining listeners still run — one bad subscriber can no longer take out
unrelated ones.
Declaring events at startup
The events option is a shorthand for subscribing a whole set of topics when
the application initializes:
export const myApp = new Application( {
events: {
"settings.foo.show": function( info ) { /* ... */ },
// a declared-but-unhandled topic: publishes won't warn, a view
// can subscribe later
"settings.foo.hide": null
}
} );
options.events may look like the natural place to wire everything — but
remember that subscriptions at module scope run before await myApp.init(),
when myApp.events doesn’t exist yet. The events option is safe (the
EventManager subscribes them during init); manual myApp.events.subscribe()
calls belong inside your startup function after init.
Built-in authentication topics
When the security module is enabled, the framework pre-subscribes these topics to the matching remote auth methods:
| Topic | Action |
|---|---|
auth.login |
Calls remote.invoke("auth.login", params) — the login flow |
auth.logout |
Calls remote.invoke("auth.logout", params) |
auth.refresh |
Calls remote.invoke("auth.refresh", params) — session refresh |
auth.sessionTimeout |
Invalidates the session |
auth.invalidateSession |
Invalidates the session |
So a login form publishes auth.login with { username, password, success, failure } — see Authentication for the full
flow.
Naming conventions
Topics are plain strings; organize them hierarchically by area of the app:
"notes.changed" // notes data changed anywhere
"user.profile" // user profile actions
"auth.login" // framework-reserved: authentication
A common pattern from the Your First App
tutorial: DOM event handlers in views mutate data and publish a domain event
(notes.changed); a single subscriber maps that event to setState() on the
views that care. This keeps views decoupled from each other.
View instance events
Separately from pub/sub, every view has instance-level events used by the render lifecycle (fired and consumed mostly by the framework):
| Event | Meaning |
|---|---|
mustRegister |
Fired by the View constructor |
registered |
Fired after ui.register(); top-level views then fire mustRender |
mustRender |
Template inputs may have changed — always re-evaluates the template |
mayRender |
Repaint; may reuse the cached template if the view opted in |
rendered |
The view painted; triggers onRendered() for children |
mustUnregister |
The view should be removed from the UI manager |
stateChanged |
State changed (fired by setState() or the DataProvider) |
You can hook these on a view with view.on( eventName, handler ) — the same
mechanism all framework components share — but you should rarely need to.
Component event bindings
All framework classes (views, services, data providers, the managers) extend a
common base with on(), fireEvent(), and subscribe()-style bindings.
Services use this to publish cacheChanged, entityChanged and entityDeleted
— which is what makes data binding work.
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.