context-dashboard-state/context-dashboard-state.service.ts
Manages dashboard-level state with dirty tracking and persistence capabilities.
This service provides a centralized state management system for context-aware dashboards. It tracks the original (default) state from the dashboard configuration, maintains a working copy of the state, and determines when changes need to be saved based on deep equality comparison.
Key responsibilities:
// Dashboard with global time context state
interface TimeContextState {
dateFrom: string;
dateTo: string;
interval: string;
}
const stateService = inject(ContextDashboardStateService<TimeContextState>);
// Set dashboard and extract its default state
stateService.setSelectedDashboard(dashboard);
// Update state (triggers dirty tracking)
stateService.updateGlobalState({ dateFrom: '2024-01-01' });
// Check if save is needed
stateService.isSaveDisabled.subscribe(disabled => {
if (!disabled) {
// Save button enabled - state has changed
}
});
Properties |
|
Methods |
| extractStateFromDashboard | ||||||||
extractStateFromDashboard(dashboard: DashboardWithState
|
||||||||
|
Extracts state from the standard dashboard structure. Retrieves the state object stored at the conventional path:
Parameters :
Returns :
StateType | null
Extracted state object, or null if dashboard is null or has no state |
| getGlobalState |
getGlobalState()
|
|
Returns a deep clone of the current working state. The returned object is a deep copy, so modifications won't affect the internal state. Use this when you need to read state without risking accidental mutations.
Returns :
StateType | null
Deep cloned copy of current state, or null if no state exists |
| resetGlobalState |
resetGlobalState()
|
|
Reverts the working state back to the dashboard's original default state. This effectively discards all changes made since the dashboard was selected, resetting to the state that was extracted from c8y_Dashboard.dashboardState. Also disables the save button since state now matches the default. Use case: Called when user clicks "Cancel" or "Reset" to discard unsaved changes.
Returns :
void
|
| Async saveDashboardState | ||||||||||||
saveDashboardState(mo: any, state: Record
|
||||||||||||
|
Persists state changes to the dashboard via the Cumulocity inventory API. Updates the dashboard's c8y_Dashboard.dashboardState property with the provided state object and saves it to the backend. Creates the c8y_Dashboard object if it doesn't exist. Note: This method doesn't automatically update the local signals. After a successful save, you should emit to dashboardSaved to notify listeners.
Parameters :
Returns :
Promise<any>
Promise resolving to the updated dashboard object from the API |
| setSelectedDashboard | ||||||||
setSelectedDashboard(dashboard: DashboardWithState
|
||||||||
|
Selects a dashboard and initializes state management for it. This method performs the complete initialization workflow when a dashboard is selected:
Deep cloning strategy: Both default state and global state are deep cloned to ensure complete isolation. This prevents accidental mutations from affecting the comparison baseline. Null handling: When null/undefined is passed, all state is cleared and signals/observables are reset. or null to clear the selection
Parameters :
Returns :
void
|
| updateGlobalState | ||||||||
updateGlobalState(newState: Partial<StateType>)
|
||||||||
|
Merges partial state updates into the current working state with dirty tracking. This method applies partial updates to the global state using a shallow merge strategy, then performs deep equality comparison against the default state to determine if save should be enabled. Example :
Parameters :
Returns :
void
|
| Readonly dashboardDefaultState |
Type : unknown
|
Default value : signal<StateType | null>(null)
|
|
Immutable snapshot of the dashboard's original state, used for comparison |
| Readonly dashboardSaved |
Type : unknown
|
Default value : new BehaviorSubject<any>(null)
|
|
Observable emitting the dashboard object after successful save operations |
| Readonly globalState |
Type : unknown
|
Default value : signal<StateType | null>(null)
|
|
Current working state that can be modified, separate from the default state |
| Readonly inventory |
Type : unknown
|
Default value : inject(InventoryService)
|
| Readonly isSaveDisabled |
Type : unknown
|
Default value : new BehaviorSubject<boolean>(true)
|
|
Observable indicating whether save should be disabled (true when no changes detected) |
| Readonly selected$ |
Type : unknown
|
Default value : new BehaviorSubject<DashboardWithState<StateType> | null>(null)
|
|
Observable for dashboard selection changes (legacy support) |
| Readonly selectedDashboard |
Type : unknown
|
Default value : signal<DashboardWithState<StateType> | null>(null)
|
|
Currently selected dashboard object with its embedded state |