Web Widget Configuration

Custom configuration settings and features for the web platform.

Overview

When the web provider is selected, the widget runs in a standard web environment and additional platform-specific features are available.

Provider Definition

json

{
  "configurations": {
    "provider": "web",
    "id": "my-web-widget",
    "type": "latest"
  }
}

Web Platform Features

1. Type Parameters (Data Configuration)

Custom data configuration for web widgets:

json

{
  "data": {
    "dataKeys": [],
    "dataKeysFunction": "",
    "latestDataKeys": [],
    "latestDataKeysFunction": "",
    "additionalTypeParameters": {
      "refreshInterval": 1000,
      "autoRefresh": true,
      "cacheEnabled": false
    },
    "defaultConfig": {
      "title": "Web Widget",
      "backgroundColor": "#ffffff",
      "textColor": "#000000",
      "showLegend": false,
      "showTitle": true,
      "enableAnimation": true,
      "settings": {},
      "width": 400,
      "height": 300
    }
  }
}

additionalTypeParameters (Web Specific)

Additional parameters for web platform:

Parameter	Type	Default	Description
`refreshInterval`	number	1000	Refresh interval (ms)
`autoRefresh`	boolean	true	Auto refresh
`cacheEnabled`	boolean	false	Data caching
`apiEndpoint`	string	-	API endpoint URL
`authRequired`	boolean	false	Authentication requirement

Example:

json

{
  "data": {
    "additionalTypeParameters": {
      "refreshInterval": 5000,
      "autoRefresh": true,
      "cacheEnabled": true,
      "apiEndpoint": "https://api.example.com/data",
      "authRequired": false
    }
  }
}

defaultConfig (Web Specific)

Default visual configuration for web widget:

json

{
  "data": {
    "defaultConfig": {
      "title": "My Web Widget",
      "backgroundColor": "#f5f5f5",
      "textColor": "#333333",
      "color": "#1976d2",
      "showLegend": false,
      "showTitle": true,
      "enableAnimation": true,
      "width": 800,
      "height": 600,
      "settings": {
        "theme": "light",
        "responsive": true,
        "showGrid": true
      }
    }
  }
}

2. External Libraries (Web Optimized)

Optimized external library management for web platform:

json

{
  "build": {
    "externals": {
      "chart.js": "Chart",
      "d3": "d3",
      "leaflet": "L",
      "three": "THREE"
    }
  }
}

Usage with widget resources:

typescript

import Chart from 'chart.js';
import * as d3 from 'd3';
import L from 'leaflet';

@Widget({
  resources: [
    {
      id: 'chartjs',
      name: 'Chart.js',
      type: 'js',
      extension: true,
      url: 'https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js',
      order: 1
    },
    {
      id: 'd3',
      name: 'D3.js',
      type: 'js',
      extension: true,
      url: 'https://d3js.org/d3.v7.min.js',
      order: 2
    },
    {
      id: 'leaflet-css',
      name: 'Leaflet CSS',
      type: 'css',
      extension: true,
      url: 'https://unpkg.com/leaflet@1.9.4/dist/leaflet.css',
      order: 3
    },
    {
      id: 'leaflet-js',
      name: 'Leaflet',
      type: 'js',
      extension: true,
      url: 'https://unpkg.com/leaflet@1.9.4/dist/leaflet.js',
      order: 4
    }
  ]
})
export class MyWebWidget {
  onInit() {
    const chart = new Chart(ctx, config);
    const svg = d3.select('svg');
    const map = L.map('map');
  }
}

3. Web Wrapper Features

Web wrapper is automatically added and provides the following features:

Code injected by wrapper:

javascript

// Widget lifecycle
var widgetInstance = null;
var widgetContext = null;

// Type parameters return
self.typeParameters = function() {
  return {
    defaultDataKeysFunction: function() { 
      return [/* dataKeys */]; 
    },
    defaultLatestDataKeysFunction: function() { 
      return [/* latestDataKeys */]; 
    },
    // Additional parameters...
    refreshInterval: 1000,
    autoRefresh: true
  };
};

// Widget activation
widgetInstance = window.XConWidgets.registry.activateWidget(
  WidgetConstructor, 
  context
);

Web Platform Build Profiles

Development Profile (Web)

json

{
  "configurations": {
    "provider": "web"
  },
  "build": {
    "debug": true,
    "entry": "widget.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json"
  },
  "data": {
    "additionalTypeParameters": {
      "enableDebugConsole": true,
      "logLevel": "debug"
    }
  }
}

Production Profile (Web)

json

{
  "configurations": {
    "provider": "web"
  },
  "build": {
    "debug": false,
    "entry": "widget.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.min.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json",
    "externals": {
      "chart.js": "Chart",
      "lodash": "_"
    }
  },
  "data": {
    "additionalTypeParameters": {
      "enableDebugConsole": false,
      "logLevel": "error"
    }
  }
}

Custom Scenarios

json

{
  "configurations": {
    "provider": "web",
    "id": "chart-widget",
    "type": "latest"
  },
  "build": {
    "entry": "chart-widget.ts",
    "sourceRoot": "src",
    "outputFilename": "chart.min.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json",
    "externals": {
      "chart.js": "Chart"
    }
  },
  "data": {
    "dataKeys": [
      {
        "name": "value",
        "label": "Value",
        "type": "timeseries",
        "settings": {
          "chartType": "line",
          "color": "#2196F3"
        }
      }
    ],
    "additionalTypeParameters": {
      "chartType": "line",
      "responsive": true,
      "maintainAspectRatio": false
    },
    "defaultConfig": {
      "title": "Chart Widget",
      "backgroundColor": "#ffffff",
      "enableAnimation": true,
      "showLegend": true,
      "width": 600,
      "height": 400
    }
  }
}

json

{
  "configurations": {
    "provider": "web",
    "id": "map-widget",
    "type": "latest"
  },
  "build": {
    "entry": "map-widget.ts",
    "sourceRoot": "src",
    "outputFilename": "map.min.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json",
    "externals": {
      "leaflet": "L"
    }
  },
  "data": {
    "dataKeys": [
      {
        "name": "latitude",
        "label": "Latitude",
        "type": "timeseries"
      },
      {
        "name": "longitude",
        "label": "Longitude",
        "type": "timeseries"
      }
    ],
    "additionalTypeParameters": {
      "mapProvider": "openstreetmap",
      "defaultZoom": 10,
      "enableClustering": true
    },
    "defaultConfig": {
      "title": "Map Widget",
      "width": 800,
      "height": 600,
      "settings": {
        "center": [39.9334, 32.8597],
        "zoom": 10
      }
    }
  }
}

json

{
  "configurations": {
    "provider": "web",
    "id": "dashboard-widget",
    "type": "latest"
  },
  "build": {
    "entry": "dashboard.ts",
    "sourceRoot": "src",
    "outputFilename": "dashboard.min.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json",
    "externals": {
      "chart.js": "Chart",
      "lodash": "_"
    }
  },
  "data": {
    "additionalTypeParameters": {
      "layout": "grid",
      "columns": 3,
      "autoRefresh": true,
      "refreshInterval": 5000
    },
    "defaultConfig": {
      "title": "Dashboard",
      "backgroundColor": "#f5f5f5",
      "width": 1200,
      "height": 800,
      "settings": {
        "theme": "light",
        "responsive": true
      }
    }
  }
}

Web Platform Validation

Configuration Check

CLI automatically performs web-specific validation:

Required fields:

json

{
  "configurations": {
    "provider": "web"  // REQUIRED
  },
  "build": {
    "entry": "...",           // REQUIRED
    "sourceRoot": "...",      // REQUIRED
    "outputFilename": "...",  // REQUIRED
    "outputPath": "..."       // REQUIRED
  }
}

Error Messages (Web Specific)

Invalid web configuration:

Error: Web wrapper validation failed: Missing default configuration

External library not found:

Error: External library 'chart.js' referenced but not in resources

Performance Optimization (Web)

Bundle Size Optimization

json

{
  "build": {
    "externals": {
      "@xcons/common": "XConsCommon",
      "@xcons/widget": "XConWidgetCore",
      "chart.js": "Chart",
      "lodash": "_",
      "moment": "moment"
    }
  }
}

Bundle size comparison:

NO Externals: ~500KB
WITH Externals: ~50KB (10x smaller!)

Lazy Loading Resources

typescript

@Widget({
  resources: [
    {
      id: 'xcons-common',
      type: 'js',
      extension: true,
      url: 'https://unpkg.com/@xcons/common@latest/core.js',
      order: 1  // Will be loaded first
    },
    {
      id: 'chart-js',
      type: 'js',
      extension: true,
      url: 'https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js',
      order: 2  // Will be loaded next
    }
  ]
})

Troubleshooting (Web Specific)

Issue: Widget is not initializing in web platform

Solution 1 - Check provider:

json

{
  "configurations": {
    "provider": "web"  // Not "thingsboard"!
  }
}

Solution 2 - Check resources:

typescript

@Widget({
  resources: [
    {
      id: 'xcons-widget',
      type: 'js',
      extension: true,
      url: 'https://unpkg.com/@xcons/widget@latest/core.js',
      order: 2
    }
  ]
})

External Library Undefined

Issue: Chart is not defined error

Solution:

json

{
  "build": {
    "externals": {
      "chart.js": "Chart"  // Global variable name correct
    }
  }
}

typescript

@Widget({
  resources: [
    {
      id: 'chartjs',
      type: 'js',
      extension: true,
      url: 'https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js',
      order: 1  // Must be loaded BEFORE XConWidgets
    }
  ]
})

Best Practices (Web)

1. External Library Usage

Recommended:

json

{
  "build": {
    "externals": {
      "chart.js": "Chart",
      "lodash": "_"
    }
  }
}

Not Recommended:

json

{
  "build": {
    "externals": {}  // All libraries included in bundle (large size)
  }
}

2. Default Config

Good:

json

{
  "data": {
    "defaultConfig": {
      "title": "My Widget",
      "width": 600,
      "height": 400,
      "backgroundColor": "#ffffff"
    }
  }
}

Bad:

json

{
  "data": {
    "defaultConfig": {}  // Empty config
  }
}

3. Resource Loading Order

Correct ordering:

typescript

@Widget({
  resources: [
    {
      id: 'xcons-common',
      url: '...',
      order: 1  // Framework first
    },
    {
      id: 'xcons-widget',
      url: '...',
      order: 2  // Widget core next
    },
    {
      id: 'external-lib',
      url: '...',
      order: 3  // External libraries last
    }
  ]
})

Example Configurations

json

{
  "configurations": {
    "provider": "web",
    "id": "simple-widget"
  },
  "build": {
    "entry": "widget.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.min.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json"
  },
  "projectType": "widget",
  "version": "1.0"
}

json

{
  "configurations": {
    "provider": "web",
    "id": "advanced-widget",
    "type": "latest",
    "fqn": "com.example.AdvancedWidget"
  },
  "build": {
    "debug": false,
    "entry": "widget.ts",
    "sourceRoot": "src",
    "outputFilename": "widget.min.js",
    "outputPath": "dist",
    "tsConfig": "tsconfig.json",
    "externals": {
      "@xcons/common": "XConsCommon",
      "@xcons/widget": "XConWidgetCore",
      "chart.js": "Chart",
      "lodash": "_"
    }
  },
  "data": {
    "dataKeys": [
      {
        "name": "value",
        "label": "Value",
        "type": "timeseries"
      }
    ],
    "additionalTypeParameters": {
      "refreshInterval": 5000,
      "autoRefresh": true,
      "cacheEnabled": true
    },
    "defaultConfig": {
      "title": "Advanced Widget",
      "backgroundColor": "#ffffff",
      "showLegend": true,
      "enableAnimation": true,
      "width": 800,
      "height": 600
    }
  },
  "projectType": "widget",
  "version": "1.0"
}

Migration Guide

Migration from ThingsBoard to Web

ThingsBoard config:

json

{
  "configurations": {
    "provider": "thingsboard"
  },
  "data": {
    "additionalTypeParameters": {
      "maxDatasources": 1,
      "embedTitlePanel": true
    }
  }
}

Web config:

json

{
  "configurations": {
    "provider": "web"
  },
  "data": {
    "additionalTypeParameters": {
      "refreshInterval": 1000,
      "autoRefresh": true
    }
  }
}

Your web widget configuration is ready!

bash

# Build command
xcons widget build --production

Web Widget

Dotnet Widget

Thingsboard Widget

ThingsBoard CLI

Widget Commands

Bundle Commands

Web Widget Configuration

Overview

Provider Definition

Web Platform Features

1. Type Parameters (Data Configuration)

additionalTypeParameters (Web Specific)

defaultConfig (Web Specific)

2. External Libraries (Web Optimized)

3. Web Wrapper Features

Web Platform Build Profiles

Development Profile (Web)

Production Profile (Web)

Custom Scenarios

1. Chart Widget (Web)

2. Map Widget (Web)

3. Dashboard Widget (Web)

Web Platform Validation

Configuration Check

Error Messages (Web Specific)

Performance Optimization (Web)

Bundle Size Optimization

Lazy Loading Resources

Troubleshooting (Web Specific)

Widget Not Working in Runtime

External Library Undefined

Best Practices (Web)

1. External Library Usage

2. Default Config

3. Resource Loading Order

Example Configurations

Minimal Web Widget

Advanced Web Widget

Migration Guide

Migration from ThingsBoard to Web

Web Widget Configuration ​

Overview ​

Provider Definition ​

Web Platform Features ​

1. Type Parameters (Data Configuration) ​

additionalTypeParameters (Web Specific) ​

defaultConfig (Web Specific) ​

2. External Libraries (Web Optimized) ​

3. Web Wrapper Features ​

Web Platform Build Profiles ​

Development Profile (Web) ​

Production Profile (Web) ​

Custom Scenarios ​

1. Chart Widget (Web) ​

2. Map Widget (Web) ​

3. Dashboard Widget (Web) ​

Web Platform Validation ​

Configuration Check ​

Error Messages (Web Specific) ​

Performance Optimization (Web) ​

Bundle Size Optimization ​

Lazy Loading Resources ​

Troubleshooting (Web Specific) ​

Widget Not Working in Runtime ​

External Library Undefined ​

Best Practices (Web) ​

1. External Library Usage ​

2. Default Config ​

3. Resource Loading Order ​

Example Configurations ​

Minimal Web Widget ​

Advanced Web Widget ​

Migration Guide ​

Migration from ThingsBoard to Web ​

Web Widget Configuration

Overview

Provider Definition

Web Platform Features

1. Type Parameters (Data Configuration)

additionalTypeParameters (Web Specific)

defaultConfig (Web Specific)

2. External Libraries (Web Optimized)

3. Web Wrapper Features

Web Platform Build Profiles

Development Profile (Web)

Production Profile (Web)

Custom Scenarios

1. Chart Widget (Web)

2. Map Widget (Web)

3. Dashboard Widget (Web)

Web Platform Validation

Configuration Check

Error Messages (Web Specific)

Performance Optimization (Web)

Bundle Size Optimization

Lazy Loading Resources

Troubleshooting (Web Specific)

Widget Not Working in Runtime

External Library Undefined

Best Practices (Web)

1. External Library Usage

2. Default Config

3. Resource Loading Order

Example Configurations

Minimal Web Widget

Advanced Web Widget

Migration Guide

Migration from ThingsBoard to Web