XCon Studio

Appearance

Widget Resources ​

Widget Resources is a configuration system used to define external resources (CSS, JS, images) used by widgets. These resources are specified in the widget config and document the widget's requirements.

Resource Structure ​

typescript
interface WidgetResource {
  name?: string;           // Resource name (optional)
  type: 'css' | 'js' | 'image';  // Resource type
  extension?: boolean;     // Is it an extension resource?
  url: string;            // Resource URL
  order?: number;         // Loading order
}

Basic Usage ​

Defining Resources in Widget Config ​

typescript
@Widget({
  selector: '.my-widget',
  template: '<div>My Widget</div>',
  resources: [
    {
      type: 'css',
      url: './styles/widget-styles.css',
      name: 'widget-styles'
    },
    {
      type: 'js',
      url: 'https://cdn.jsdelivr.net/npm/chart.js',
      name: 'chartjs'
    },
    {
      type: 'image',
      url: './images/widget-bg.jpg',
      name: 'background'
    }
  ]
})
export class MyWidget {
  // Widget implementation
}

Resource Types ​

CSS Resources ​

Stylesheet files that the widget needs:

typescript
resources: [
  {
    type: 'css',
    url: './styles/main.css',
    name: 'main-styles'
  },
  {
    type: 'css',
    url: 'https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/css/bootstrap.min.css',
    name: 'bootstrap',
    order: 1  // Should be loaded first
  }
]

JavaScript Resources ​

JavaScript libraries that the widget depends on:

typescript
resources: [
  {
    type: 'js',
    url: 'https://cdn.jsdelivr.net/npm/lodash@4.17.21/lodash.min.js',
    name: 'lodash'
  },
  {
    type: 'js',
    url: './libs/custom-library.js',
    name: 'custom-lib',
    order: 2
  }
]

Image Resources ​

Image files used by the widget:

typescript
resources: [
  {
    type: 'image',
    url: './images/icon.png',
    name: 'widget-icon'
  },
  {
    type: 'image',
    url: './images/background.jpg',
    name: 'background-image'
  }
]

Extension Resources ​

The extension flag is used for resources coming from extensions:

typescript
resources: [
  {
    type: 'css',
    url: './extension-styles.css',
    name: 'extension-styles',
    extension: true  // This resource comes from an extension
  }
]

Ordering ​

The order property is used to determine the loading order of resources:

typescript
resources: [
  {
    type: 'js',
    url: './dependencies/jquery.js',
    name: 'jquery',
    order: 1  // Will be loaded first
  },
  {
    type: 'js', 
    url: './dependencies/bootstrap.js',
    name: 'bootstrap',
    order: 2  // Will be loaded after jQuery
  },
  {
    type: 'js',
    url: './widget-main.js',
    name: 'widget-main',
    order: 3  // Will be loaded last
  }
]

Practical Examples ​

Chart Widget Resources ​

typescript
@Widget({
  selector: '.chart-widget',
  template: `<div class="chart-container">Chart will render here</div>`,
  resources: [
    {
      type: 'css',
      url: './styles/chart-widget.css',
      name: 'chart-styles'
    },
    {
      type: 'js',
      url: 'https://cdn.jsdelivr.net/npm/chart.js',
      name: 'chartjs'
    },
    {
      type: 'js',
      url: './utils/chart-helpers.js',
      name: 'chart-helpers',
      order: 2
    }
  ]
})
export class ChartWidget {
  // Chart implementation
}

Map Widget Resources ​

typescript
@Widget({
  selector: '.map-widget',
  template: `<div class="map-container">Map loading...</div>`,
  resources: [
    {
      type: 'css',
      url: 'https://unpkg.com/leaflet@1.9.4/dist/leaflet.css',
      name: 'leaflet-css'
    },
    {
      type: 'js',
      url: 'https://unpkg.com/leaflet@1.9.4/dist/leaflet.js',
      name: 'leaflet'
    },
    {
      type: 'image',
      url: './images/map-markers.png',
      name: 'map-markers'
    }
  ]
})
export class MapWidget {
  // Map implementation
}
typescript
@Widget({
  selector: '.gallery-widget',
  template: `<div class="gallery">Gallery content</div>`,
  resources: [
    {
      type: 'css',
      url: './styles/gallery.css',
      name: 'gallery-styles'
    },
    {
      type: 'css',
      url: 'https://cdn.jsdelivr.net/npm/swiper@8/swiper-bundle.min.css',
      name: 'swiper-css'
    },
    {
      type: 'js',
      url: 'https://cdn.jsdelivr.net/npm/swiper@8/swiper-bundle.min.js',
      name: 'swiper'
    },
    {
      type: 'image',
      url: './images/placeholder.jpg',
      name: 'placeholder'
    },
    {
      type: 'image',
      url: './images/loading-spinner.gif',
      name: 'loading-spinner'
    }
  ]
})
export class GalleryWidget {
  // Gallery implementation
}

Resource Organization ​

Categorical Grouping ​

typescript
resources: [
  // Core dependencies - order 1-10
  {
    type: 'js',
    url: './core/jquery.js',
    name: 'jquery',
    order: 1
  },
  
  // UI Libraries - order 11-20
  {
    type: 'css',
    url: './ui/bootstrap.css',
    name: 'bootstrap-css',
    order: 11
  },
  {
    type: 'js',
    url: './ui/bootstrap.js', 
    name: 'bootstrap-js',
    order: 12
  },
  
  // Widget specific - order 21+
  {
    type: 'css',
    url: './widget-styles.css',
    name: 'widget-styles',
    order: 21
  }
]

Environment-based Resources ​

typescript
resources: [
  // Development
  {
    type: 'js',
    url: './debug/debug-tools.js',
    name: 'debug-tools'
  },
  
  // Production
  {
    type: 'js',
    url: 'https://cdn.example.com/prod-analytics.min.js',
    name: 'analytics'
  }
]

Resource Metadata ​

Detailed Resource Information ​

typescript
resources: [
  {
    name: 'primary-chart-library',
    type: 'js',
    url: 'https://cdn.jsdelivr.net/npm/chart.js@4.3.0/dist/chart.min.js',
    order: 1
  },
  {
    name: 'chart-theme-dark',
    type: 'css', 
    url: './themes/chart-dark.css',
    order: 2
  },
  {
    name: 'widget-background',
    type: 'image',
    url: './assets/images/dashboard-bg.jpg'
  }
]

Best Practices ​

1. Naming Convention ​

typescript
// ✅ Good - descriptive names
name: 'bootstrap-css'
name: 'chart-library'
name: 'widget-background-image'

// ❌ Bad - unclear names
name: 'lib1'
name: 'style'
name: 'img'

2. URL Patterns ​

typescript
// ✅ Good - consistent URL structure
url: './styles/widget.css'
url: './scripts/widget.js'
url: './images/widget-icon.png'

// ✅ Good - CDN usage
url: 'https://cdn.jsdelivr.net/npm/package@version/file.js'

3. Dependency Order ​

typescript
// ✅ Good - dependency order
resources: [
  { name: 'jquery', order: 1 },      // Base dependency
  { name: 'bootstrap', order: 2 },   // Depends on jQuery
  { name: 'widget-main', order: 3 }  // Depends on both
]

4. Resource Grouping ​

typescript
// ✅ Good - grouping by type
resources: [
  // CSS Resources
  { type: 'css', url: './base.css' },
  { type: 'css', url: './theme.css' },
  
  // JS Resources  
  { type: 'js', url: './lib1.js' },
  { type: 'js', url: './lib2.js' },
  
  // Images
  { type: 'image', url: './icon.png' },
  { type: 'image', url: './bg.jpg' }
]

Documentation Purposes ​

The resources configuration is used for the following purposes:

1. Dependency Documentation ​

Documenting which external resources the widget needs

2. Development Guidelines ​

Resource requirements guide for developers

3. Build Process Information ​

Resource list for build tools

4. Performance Analysis ​

Resource size and loading performance analysis

5. Security Auditing ​

External resource security audit

Summary ​

The Widget Resources system:

  • ✅ Is used for dependency tracking
  • ✅ Provides resource documentation
  • ✅ Informs the build process
  • ✅ Creates development guidelines
  • ✅ Supports performance analysis
  • ✅ Facilitates security auditing
  • ✅ Documents widget requirements

This system provides centralized management and documentation of widget resource requirements.