Events API
Subscribe to platform events to respond to connection changes, settings updates, and tool lifecycle events.
Event Subscription
toolboxAPI.events.on(handler)
Subscribe to events relevant to your tool.
toolboxAPI.events.on((details, payload) => {
switch (payload.event) {
case 'connection:updated':
refreshConnectionInfo()
break
case 'terminal:command:completed':
handleCommandCompleted(payload.data)
break
case 'settings:updated':
if (payload.data && payload.data.theme) {
applyTheme(payload.data.theme)
}
break
}
})
Parameters:
handler:(event: any, payload: ToolBoxEventPayload) => void- Callback function to handle events
ToolBoxEventPayload:
interface ToolBoxEventPayload {
event: ToolBoxEvent
data: unknown
timestamp: string
}
Event Types
The following events are available for subscription:
tool:loaded / tool:unloaded
Fired when a tool instance is loaded or unloaded.
toolboxAPI.events.on((_, payload) => {
if (payload.event === 'tool:loaded') {
initializeTool()
}
if (payload.event === 'tool:unloaded') {
cleanupResources()
}
})
connection:created / connection:updated / connection:deleted
Fired when Dataverse connections are created, updated, or deleted.
toolboxAPI.events.on((_, payload) => {
if (payload.event === 'connection:updated') {
console.log('Connection event:', payload.data)
refreshConnectionInfo()
}
})
settings:updated
Fired when tool settings are changed.
toolboxAPI.events.on((_, payload) => {
if (payload.event === 'settings:updated') {
console.log('Settings updated:', payload.data)
}
})
notification:shown
Fired when a notification is displayed.
toolboxAPI.events.on((_, payload) => {
if (payload.event === 'notification:shown') {
console.log('Notification shown:', payload.data)
}
})
terminal:created / terminal:closed / terminal:output / terminal:command:completed / terminal:error
Fired for terminal lifecycle, output streaming, command completion, and terminal errors.
toolboxAPI.events.on((_, payload) => {
switch (payload.event) {
case 'terminal:created':
console.log('Terminal created:', payload.data)
break
case 'terminal:output':
console.log('Terminal output:', payload.data)
break
case 'terminal:command:completed':
console.log('Command completed:', payload.data)
break
case 'terminal:error':
console.error('Terminal error:', payload.data)
break
}
})
Best Practices
Event Handler Registration: Subscribe to events early in your tool's initialization to avoid missing important events.
Register Once
Register your event handler only once during initialization:
// Good: Register once during initialization
function initializeTool() {
toolboxAPI.events.on(handleEvent)
}
function handleEvent(event, payload) {
// Handle all events in one place
}
initializeTool()
Avoid Multiple Handlers
Don't register multiple event handlers for the same events:
// Bad: Multiple handlers
toolboxAPI.events.on(handler1)
toolboxAPI.events.on(handler2)
// Good: Single handler with routing
toolboxAPI.events.on((event, payload) => {
switch (event) {
case 'connection:updated':
handleConnectionUpdate(payload)
break
case 'settings:updated':
handleSettingsUpdate(payload)
break
}
})
Error Handling
Always wrap event handler logic in try-catch blocks:
toolboxAPI.events.on((event, payload) => {
try {
switch (payload.event) {
case 'connection:updated':
refreshData()
break
case 'settings:updated':
applySettings(payload.data)
break
}
} catch (error) {
console.error('Error handling event:', payload.event, error)
}
})