Create amazing custom widgets and run them inside TagoIO Admin with this comprehensive toolkit. The Custom Widget SDK provides a powerful JavaScript interface for building interactive IoT dashboards and data visualization components.
The simplest way to get started is to include the SDK directly in your HTML:
<!DOCTYPE html>
<html>
<head>
<title>My Custom Widget</title>
<script src="https://admin.tago.io/dist/custom-widget.min.js"></script>
<link rel="stylesheet" href="https://admin.tago.io/dist/custom-widget.min.css"> <!-- OPTIONAL -->
</head>
<body>
<script>
// Your widget code here
window.TagoIO.onStart(function(widget) {
console.log('Widget started!', widget);
});
window.TagoIO.ready();
</script>
</body>
</html>For projects using webpack or other build tools:
npm install @tago-io/custom-widget --saveThen import in your entry component:
import "@tago-io/custom-widget";
import "@tago-io/custom-widget/dist/custom-widget.css"; // OPTIONALThe TagoIO Custom Widget SDK provides a comprehensive API through the global window.TagoIO object:
TagoIO.ready(options)- [You send] Signal to TagoIO that your widget has finished loading and is ready to receive data and events. This must be called to activate your widget.TagoIO.onStart(callback)- [You receive] Asynchronous event triggered when TagoIO starts your widget and provides configuration data, variables, and settings.TagoIO.onError(callback)- [You receive] Asynchronous event triggered when API errors or widget issues occur during runtime.
Note: These data operations are heavily dependent on the Custom Widget configuration at TagoIO. A widget can only manipulate data that is within the Custom Widget settings and permissions.
TagoIO.sendData(data, callback)- [You send] Send data to TagoIO devices asynchronouslyTagoIO.editData(data, callback)- [You send] Edit existing device data asynchronouslyTagoIO.deleteData(data, callback)- [You send] Delete device data asynchronouslyTagoIO.editResourceData(data, callback)- [You send] Edit platform resources asynchronously
TagoIO.onRealtime(callback)- [You receive] Asynchronous event triggered when new data is received through dashboard real-time events from connected devices. This callback is invoked automatically whenever real-time data updates occur based on the dashboard's real-time configuration.TagoIO.onSyncUserInformation(callback)- [You receive] Asynchronous event triggered when user context changes or authentication updates occur. Provides user context, authentication tokens, and session information based on dashboard real-time events.TagoIO.onSyncBlueprintDevices(callback)- [You receive] Asynchronous event triggered when blueprint device configurations change or device selections are updated. Provides blueprint device configurations and selected devices through dashboard real-time events.
TagoIO.openLink(url)- Navigate to other dashboards or external linksTagoIO.closeModal()- Close widget modal (for header button widgets)
TagoIO.autoFill- Boolean flag to enable/disable automatic device/bucket ID filling
For detailed API documentation, type definitions, and advanced usage patterns, visit:
The repository includes:
- Full TypeScript type definitions
- Detailed function parameters and return types
- Advanced usage examples
- Integration guides for different frameworks
This repository includes a comprehensive /examples folder with 7 different HTML examples:
| Example | Purpose | Best For |
|---|---|---|
| basic-widget.html | Minimal setup and widget lifecycle | Beginners learning the basics |
| read-data.html | Displaying real-time device data | Data visualization widgets |
| read-resource.html | Accessing platform resources | User context and blueprint devices |
| read-entity.html | Complex structured data handling | Advanced data relationships |
| send-data.html | Sending data back to devices | Interactive input widgets |
| time-interval.html | Time-based data analysis | Historical data and time controls |
| custom-units.html | Unit conversions and formatting | Multi-unit sensor displays |
Complete project implementations:
-
Boilerplate Project: Basic boilerplate project using Preact, showing fundamental SDK usage patterns.
-
SendData Widget: Simple example demonstrating how to send data from your Custom Widget to TagoIO.
-
Wizard Widget: Advanced demo showing a multi-step wizard built using TagoIO's Custom Widget SDK.
-
ECharts Custom Gauge Widget: Example of a custom gauge widget using the TagoIO Custom Widget SDK.
- Start with a basic structure:
document.addEventListener('DOMContentLoaded', function() {
// Initialize your widget when DOM is ready
window.TagoIO.onStart(function(widget) {
// Widget configuration and variables available here
console.log('Widget config:', widget);
});
// Handle errors gracefully
window.TagoIO.onError(function(error) {
console.error('Widget error:', error);
});
// Signal that your widget is ready
window.TagoIO.ready({
header: {
color: '#2196F3' // Optional header customization
}
});
});- Handle real-time data:
window.TagoIO.onRealtime(function(realtimeData) {
realtimeData.forEach(function(dataGroup) {
if (dataGroup.result) {
dataGroup.result.forEach(function(dataPoint) {
// Process each data point
console.log('Variable:', dataPoint.variable);
console.log('Value:', dataPoint.value);
console.log('Time:', dataPoint.time);
});
}
});
});- Send data back to devices:
async function sendSensorData() {
try {
const result = await window.TagoIO.sendData({
variable: 'temperature',
value: 25.5,
unit: '°C',
time: new Date().toISOString()
});
console.log('Data sent successfully:', result);
} catch (error) {
console.error('Failed to send data:', error);
}
}Always implement comprehensive error handling:
window.TagoIO.onError(function(error) {
// Log for debugging
console.error('Widget error:', error);
// Show user-friendly message
showUserMessage('Something went wrong: ' + error.message);
});- Use
window.TagoIO.autoFill = trueto automatically handle device/bucket IDs - Implement data throttling for high-frequency updates
- Clean up timers and event listeners when the widget is destroyed
- Limit stored data to prevent memory issues
The SDK includes comprehensive TypeScript definitions. For TypeScript projects:
import "@tago-io/custom-widget";
// Types are automatically available
window.TagoIO.onStart((widget: TWidget) => {
// Full type safety and IntelliSense support
widget.display.variables.forEach((variable: TWidgetVariable) => {
console.log(`Variable: ${variable.variable}, Device: ${variable.origin.id}`);
});
});window.TagoIO.onSyncBlueprintDevices(function(blueprintData) {
// Access blueprint device configurations
console.log('Blueprint settings:', blueprintData.settings);
// Get currently selected devices
console.log('Selected devices:', blueprintData.selected);
});window.TagoIO.onSyncUserInformation(function(userInfo) {
// Access user language, token, and run URL
console.log('User language:', userInfo.language);
console.log('Has token:', !!userInfo.token);
console.log('Run URL:', userInfo.runURL);
});// Navigate to another dashboard
window.TagoIO.openLink('https://admin.tago.io/dashboards/info/dashboard-id');
// Close modal (for header button widgets)
window.TagoIO.closeModal();# Install dependencies
npm install
# Build the library
npm run build
# Run tests
npm test
# Type checking
npm run check:types
# Generate coverage report
npm run coverageWe welcome contributions! Please:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and add tests
- Ensure all tests pass:
npm test - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
- 📖 Help Documentation - Complete guide on creating custom widgets
- 💬 Community Forum - Ask questions and share knowledge
- 🐛 Issue Tracker - Report bugs and request features
- 📧 Support Email - Direct technical support
This project is licensed under the Apache-2.0 License - see the LICENSE.md file for details.
Made by Tago LLC
For more information about TagoIO's IoT platform and services, visit tago.io.