DataProviders
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.
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.