DataProviders

Binding view state to service cache data — automatic synchronization without plumbing.

A DataProvider owns a view’s state and keeps it synchronized with service cache data through declarative bindings.

Why a DataProvider

Without one, you wire data into views by hand: call a service, setState(), repeat on every change. A DataProvider replaces that with a declaration: “this view’s todos state key is the Todo entities matching this filter, kept up to date automatically.”

Defining one

A DataProvider takes the view it serves, an initial state, an optional schema, and a binding map — one rule per state key:

import { DataProvider } from "/lib/altseven/dist/a7.js";
import { Todo } from "../entity/todo.js";

export class TodoListDP extends DataProvider {
	constructor( props ) {
		props.binding = {
			todos: {
				entityClass: Todo,
				func: todoService.refreshActiveTodos,  // how to (re)load the data
				renderOn: [ "create", "delete" ]       // which cache actions re-render
			},
			selected: {
				entityClass: Todo,
				id: null        // bound to a single entity; id fixed at runtime
			}
		};

		props.schema = {
			todos:    { type: "map", entityClass: Todo },
			selected: { type: "object", entityClass: Todo },
			filterText: { type: "string" }
		};

		super( props );
	}
}

Binding rule properties:

Property Meaning
entityClass The entity type this key holds — used to find the matching service
func A refresh function (usually on the service) that returns the entities to bind
id Bind to a single entity by id instead of a collection
filter Client-side filter applied to bound data, e.g. { done: [ "=", false ] }
sort Sort applied to bound data, e.g. { created: "desc" }
renderOn Only re-render on these cache actions: create, update, delete
dependencies Re-run the binding when these state keys change (see below)

Registration — two steps

A DataProvider must be registered with both the application and the view:

const dp = new TodoListDP( { view: todosView } );

myApp.dataproviders.register( dp );        // wires bindings to services
todosView.registerDataProvider( dp );      // view state now flows through the DP

Once registered, todosView.setState() / getState() delegate to the DataProvider, and cache changes push new data into view state automatically — the view repaints through the normal stateChanged → mustRender path.

Collection binding

With a func (or the service cache as a whole), the DataProvider listens to the service’s cacheChanged event, re-resolves the bound data, applies filter/sort, and writes the result into view state. renderOn limits which actions trigger this — e.g. a list that doesn’t need to repaint when an existing item is merely updated can declare renderOn: [ "create", "delete" ].

Entity-specific binding

With an id, the binding tracks a single entity: when that entity changes, the view’s state key is set to the new entity; when it is deleted, the key is set to null. This is the normal shape for a detail view.

For an entity whose id is not known until runtime, declare the binding with id: null. The first matching entityChanged event sets the state (since 9.1.3 an id-less object binding correctly receives the event’s entity rather than the whole cache map).

Dependencies

dependencies re-runs a binding when related state changes — either in the same view ("filterText") or another view ("toolbar.selectedUserID"):

props.binding = {
	todos: {
		entityClass: Todo,
		func: todoService.refreshByFilter,
		dependencies: [ "filterText", "toolbar.selectedUserID" ]
	}
};

When filterText changes in this view (or selectedUserID changes in the toolbar view), the todos binding re-resolves — the func receives the current DP state and can use those values as its query parameters.

EntityMap relations

For master/detail loads (a page of items plus their parents), declare a relation in the schema and load it explicitly:

props.schema = {
	todos: {
		type: "entityMap",
		service: "todos",             // service id
		fetchMethod: "todo.byUser",   // returns an array of ids (or { ids: [...] })
		defaultCriteria: { userID: 7, limit: 20 }
	}
};
// fetch the id list, then readMany() the entities (cache-aware)
await dp.loadRelation( "todos", { userID: 7 } );

// paginate: merges with the stored criteria by default
await dp.refresh( "todos", { limit: 40 } );
await dp.refresh( "todos", { limit: 20 }, { reload: true } );  // replace criteria

dp.getRelationCriteria( "todos" );  // the currently stored criteria
dp.clearRelation( "todos" );        // empty the Map and forget the criteria

loadRelation fires relationLoaded, refresh fires relationRefreshed, clearRelation fires relationCleared.

When to use what

  • Plain view state — UI-only values (drafts, tab selection). No DataProvider needed.
  • DataProvider with bindings — view state that mirrors cached entities.
  • Model bindings (data-bind) — simple two-way field binding for form inputs backed by the application model.