Events

The publish/subscribe event system and the conventions for using it well.

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.