Tree API ClientSide DataProvider
The CAPITreeClientDataProvider extends the standard Tree ClientSide provider to interact directly with internal or external APIs via the RequestProvider to manage hierarchical data structures.
This provider manages data fetching, caching strategies, and deduplication for API requests, automatically updating the local UI hierarchical state.
Extends: Tree ClientSide DataProvider
Uses: RequestProvider
// --- Client Side (Vue) ---
import { CAPITreeClientDataProvider } from '@katlux/providers/data'
const provider = new CAPITreeClientDataProvider({
cacheStrategy: 'Memory',
cacheLifetime: 60000
})
await provider.setAPIUrl('/api/v1/categories') // Automatically fetches all nodes
// --- Server Side (Nuxt Nitro) ---
// server/api/v1/categories.get.ts
export default defineEventHandler(async (event) => {
// Expected returning structure format: { rows: Array<any>, rowCount: number }
// rows: Must be a flat array of dataset nodes possessing unique `id` and valid `parentId` mapping identifiers
return {
rows: allData,
rowCount: allData.length
}
})
// server/api/v1/categories.post.ts
export default defineEventHandler(async (event) => {
// Data arrives exactly as sent by the client `provider.create({ name: 'New Node', parentId: 1 })`
const body = await readBody(event) // Expected Format: { name: 'New Node', parentId: 1 }
const newNode = await insertDatabaseTaxonomy(body)
// Returning the inserted object integrates it back into the local cached hierarchy automatically by `parentId`
// Expected returned format: { id: 25, parentId: 1, name: 'New Node' }
return newNode
})Configuration options for hierarchical API data providers.
| Property | Type | Default | Description |
|---|---|---|---|
| idKey | string | 'id' | The unique identifier field for each node |
| parentKey | string | 'parentId' | The field used to establish parent-child relationships |
| expandedByDefault | boolean | false | Whether to show all nodes as expanded on initial load |
| paginateBy | TreePaginationMode | 'all' | Determines if pageSize limits total visible nodes or just top-level roots |
| pageSize | number | 10 | Number of visible nodes (or roots) to display per page |
| currentPage | number | 1 | Initial page index |
| SSR | boolean | false | Enables Server Side Rendering support via useAsyncData |
| cacheStrategy | ECacheStrategy | null | Strategy for caching API responses |
| deduplicate | boolean | true | Prevents duplicate concurrent API requests |
Control methods for hierarchy and data flow.
| Name | Type | Description |
|---|---|---|
| toggleNode | (id: string | number) => void | Expands or collapses a specific node locally |
| expandAll / collapseAll | () => void | Bulk controls for all parent nodes in the dataset |
| rowCount | Ref<number> | Total visible nodes (after filtering and expansion rules) |
| pageData | Ref<any[]> | The currently visible slice of the hierarchy for the active page |
| apiUrl | Ref<string> | Reactive API endpoint |
| setAPIUrl | (url: string) => Promise<void> | Sets URL and immediately fetches the full dataset |
| refresh | (hardRefresh?: boolean) => Promise<void> | Re-fetches the dataset from the API. Cache will only be overridden if hardRefresh is true. |
| create / update / delete | (item: any) => Promise<void> | API mutations that maintain hierarchy markers |
Note: Unlike server-side tree providers, client-side API tree providers do not use a TTreePageDataHandler. The entire dataset is loaded once from the API URL, and tree rebuilding, expansion, sorting, and pagination are performed entirely in-memory on the client.
The API must return a flat array of plain objects. The provider builds the tree hierarchy on the client using id and parentId fields. Root nodes must have null (or an absent value) for their parent field.
// Server response shape (fetched once at setAPIUrl)
{
rowCount: 5,
rows: [
{ id: 1, parentId: null, name: 'Root Category' },
{ id: 2, parentId: 1, name: 'Sub Category A' },
{ id: 3, parentId: 1, name: 'Sub Category B' },
{ id: 4, parentId: 2, name: 'Leaf Node' },
{ id: 5, parentId: null, name: 'Another Root' }
]
}The id and parentId field names are configurable via the idKey and parentKey constructor options.