Your First App

Build a complete, runnable altseven application with views, events and routing.

This tutorial builds a small but complete note-taking app: multiple views, child views, template event handlers, pub/sub events and URL routing. It runs entirely in the browser with no back end — and every line of it has been verified against altseven 9.1.4.

Project layout

notes-app/
├── index.html
└── js/
    ├── app.js        # bootstrap: Application, subscriptions, views, routing
    ├── notes.js      # state + actions for the notes data
    └── views.js      # view components

Serve the folder with any static server, with the framework available at /lib/altseven/dist/a7.js (see Getting Started).

index.html

<!doctype html>
<html>
	<head>
		<title>altseven — notes</title>
		<script type="module">
			import { application } from "./js/app.js";
			application();
		</script>
	</head>
	<body>
		<div id="app"></div>
	</body>
</html>

Every mount point needs a matching selector: the view’s props.selector must resolve to a node that exists in the page (or is created by a parent view’s template). If a top-level selector never resolves, the view is silently unregistered — this is the single most common altseven mistake.

app.js

The application module wires everything together. Note the shape:

  • Module scope creates the Application (which only stores options and logging — see the Getting Started warnings) and declares placeholders for the views.
  • Inside application(), after await myApp.init(), we subscribe to events, create the views, and route the current URL.
import { Application } from "/lib/altseven/dist/a7.js";
import { notes } from "./notes.js";
import { App, NotesList } from "./views.js";

export const myApp = new Application( {
	name: "notes",
	security: { enabled: false },
	remote: {},
	logging: { logLevel: "ERROR,FATAL,INFO", toBrowserConsole: true },
	router: {
		routes: [
			[ "/", "app.home" ],
			[ "/notes/:noteID", "app.note" ]
		]
	}
} );

// these exist only after init(); views are created inside application()
export let app;
export let notesList;

export async function application() {
	try {
		await myApp.init();

		// pub/sub wiring
		myApp.events.subscribe( "notes.changed", () => {
			notesList.setState( { items: notes.all() } );
		} );
		myApp.events.subscribe( "app.home", () => {
			notesList.setState( { items: notes.all() } );
		} );
		myApp.events.subscribe( "app.note", ( params ) => {
			notesList.setState( { items: notes.all(), selected: params.noteID } );
		} );

		// views: the parent renders into #app; the child renders into
		// the #notesList div that the parent's template creates
		app = App( { id: "app", selector: "#app" } );
		notesList = NotesList( {
			id: "notesList",
			parentID: "app",
			selector: "#notesList"
		} );

		// routes are NOT matched automatically on page load — do it here
		myApp.router.match( document.location.pathname + document.location.search );
	} catch( e ) {
		console.error( "App init failed:", e );
	}
}

Two things to notice:

  • Routes map paths to events. [ "/notes/:noteID", "app.note" ] declares a URL pattern with a parameter; when the URL matches, the app.note event is published with the extracted parameters (plus anything passed to router.open()) as its payload.
  • The router does not fire on load. window.onpopstate (back/forward) is handled for you, but the initial URL must be matched explicitly with myApp.router.match().

notes.js

Application state that is not view state lives in plain modules. This one is an in-memory store standing in for a server API:

let seed = 1;
const store = new Map();

export const notes = {
	add( text ) {
		const note = { noteID: `n${ seed++ }`, text, done: false };
		store.set( note.noteID, note );
		return note;
	},
	toggle( noteID ) {
		const note = store.get( noteID );
		if( note ) note.done = !note.done;
		return note;
	},
	remove( noteID ) {
		store.delete( noteID );
	},
	all() {
		return Array.from( store.values() );
	}
};

In a real application this module would call a Service, which caches entities and notifies your views automatically — but the shape of the code stays the same.

views.js

Views own their appearance and their DOM event handlers. The template is a function that returns an HTML string built from state; elements with data-on<event> attributes get event listeners bound to methods on view.eventHandlers after each render.

import { myApp } from "./app.js";
import { View } from "/lib/altseven/dist/a7.js";

export function App( props ) {

	const app = new View( props );

	app.template = function() {
		return `
		<nav class="app-nav">
			<h1>Notes</h1>
			<a href="/" data-onclick="goHome">All notes</a>
		</nav>
		<div id="notesList"></div>`;
	};

	app.eventHandlers = {
		goHome: function( event ) {
			event.preventDefault();
			myApp.router.open( "/" );
		}
	};

	myApp.ui.register( app );
	return app;
}

export function NotesList( props ) {

	const notesList = new View( props );

	notesList.state = { items: [], draft: "" };

	notesList.template = function() {
		const state = notesList.getState();
		const items = state.items.map( note => `
			<li>
				<label>
					<input type="checkbox" data-onchange="toggleNote"
						data-id="${ note.noteID }" ${ note.done ? "checked" : "" }>
					${ note.text }
				</label>
				<button data-onclick="removeNote" data-id="${ note.noteID }">✕</button>
			</li>` ).join( "" );

		return `
		<form data-onsubmit="addNote">
			<input type="text" name="draft" value="${ state.draft }"
				placeholder="Write a note…">
			<button type="submit">Add</button>
		</form>
		<ul>${ items }</ul>
		<p>${ state.items.length } note(s)</p>`;
	};

	notesList.eventHandlers = {

		addNote: function( event ) {
			event.preventDefault();
			const draft = event.target.elements.draft.value.trim();
			if( draft === "" ) return;
			notes.add( draft );
			event.target.elements.draft.value = "";
			// notify the app that notes data changed
			myApp.events.publish( "notes.changed", {} );
		},

		toggleNote: function( event ) {
			notes.toggle( event.target.dataset.id );
			myApp.events.publish( "notes.changed", {} );
		},

		removeNote: function( event ) {
			notes.remove( event.target.dataset.id );
			myApp.events.publish( "notes.changed", {} );
		}
	};

	myApp.ui.register( notesList );
	return notesList;
}

Note the pattern:

  1. A DOM event handler (data-onclick, data-onchange, data-onsubmit, …) mutates application data and publishes an event.
  2. The notes.changed subscriber calls setState() on the affected view.
  3. setState() schedules a debounced re-render of that view; the template re-evaluates and the container repaints.

You never touch innerHTML yourself, and you never re-render other views manually. The supported data-on<event> names cover the standard browser event groups (mouse, keyboard, focus, form — including submit — media, clipboard, and more); data-onclick="goHome" becomes a click listener, data-onsubmit="addNote" a submit listener.

Run it

$ npx http-server . -p 8417

Open http://localhost:8417, add a few notes, tick them, and watch the URL change as you navigate. The full flow — DOM event → data change → pub/sub event → setState() → debounced repaint — is the core loop of every altseven application.

Gotchas worth knowing

These are all behaviors verified against 9.1.4:

  • remote: {} is required. Omitting the remote option makes init() throw (Object.keys(undefined) in the remote manager) — even for apps with no back end at all.
  • Nothing that touches modules may run before await myApp.init(). Views created at module scope crash with “cannot read properties of undefined”; myApp.events.subscribe at module scope crashes the same way. Create views and subscriptions inside your startup function, after init.
  • Routes don’t fire on load. Call myApp.router.match(location.pathname + location.search) once your views exist, or a fresh visit to /notes/123 renders an empty shell.
  • A missing selector silently unregisters a top-level view. If nothing appears, the first thing to check is that every selector in your code matches an id in the HTML or a node created by a parent template.

Where to go next

  • Views — the view lifecycle, child views and rendering rules
  • Events — the publish/subscribe system in depth
  • Routing — route patterns, parameters and history
  • The Data Layer — replace the in-memory store with entities, services and data providers backed by a real API