sap-sac-custom-widget

What this skill does

# SAP Analytics Cloud Custom Widget Development

## Table of Contents
- [Overview](#overview)
- [Plugin Components](#plugin-components)
- [Quick Start](#quick-start)
- [Community Sample Widgets](#community-sample-widgets)
- [Key Concepts](#key-concepts)
- [Common Errors & Solutions](#common-errors--solutions)
- [Bundled Resources](#bundled-resources)

## Overview

This skill enables development of custom widgets for SAP Analytics Cloud (SAC). Custom widgets are Web Components that extend SAC stories and applications with custom visualizations, interactive elements, and specialized functionality.

**Use this skill when**:
- Building custom visualizations not available in standard SAC
- Integrating third-party charting libraries (ECharts, D3.js, Chart.js)
- Creating interactive input components for SAC applications
- Implementing specialized data displays or KPI widgets
- Extending Analytics Designer applications with custom functionality
- Troubleshooting custom widget loading or data binding issues

**Requirements**:
- SAC tenant with Optimized Story Experience or Analytics Designer
- JavaScript/Web Components knowledge
- External hosting (GitHub Pages, AWS S3, Azure) OR SAC-hosted resources (QRC Q2 2023+)

---

## Plugin Components

This plugin provides specialized agents, commands, and validation hooks for comprehensive widget development support.

### Agents

| Agent | Color | Purpose | Trigger Examples |
|-------|-------|---------|------------------|
| **widget-architect** | Blue | Design widget structure, metadata, and integration patterns | "design custom widget", "plan widget architecture" |
| **widget-debugger** | Yellow | Troubleshoot loading, data binding, CORS, and runtime issues | "widget won't load", "CORS error", "data not binding" |
| **widget-api-assistant** | Green | Write JavaScript widget code, lifecycle functions, API integrations | "write widget code", "implement lifecycle functions" |

### Commands

| Command | Usage | Description |
|---------|-------|-------------|
| `/widget-validate` | `/widget-validate [file]` | Validate widget.json schema and widget.js structure |
| `/widget-generate` | `/widget-generate` | Interactively generate widget scaffold with JSON + JS |
| `/widget-lint` | `/widget-lint [file]` | Performance, security, and best practices analysis |

### Validation Hooks

Automatic quality checks triggered on Write/Edit operations:
- **widget.json**: Required fields, tag naming, property types, data binding config
- **widget.js**: Lifecycle functions, Shadow DOM, propertiesChanged dispatch
- **Performance**: Resize debouncing, chart disposal, XSS prevention
- **Context Reminders**: Template suggestions, command recommendations

### Templates

Ready-to-use scaffolds in `templates/` directory:
- `basic-widget.js` - Minimal Web Component with all lifecycle functions
- `data-bound-chart.js` - ECharts widget with data binding
- `styling-panel.js` - Runtime customization panel
- `widget.json-minimal` - Bare-minimum metadata
- `widget.json-complete` - Full-featured metadata with all options

---

## Quick Start

### Minimal Custom Widget Structure

A custom widget requires two files:

**1. widget.json** (Metadata)
```json
{
  "id": "com.company.mywidget",
  "version": "1.0.0",
  "name": "My Custom Widget",
  "description": "A simple custom widget",
  "vendor": "Company Name",
  "license": "MIT",
  "icon": "",
  "webcomponents": [
    {
      "kind": "main",
      "tag": "my-custom-widget",
      "url": "[https://your-host.com/widget.js",](https://your-host.com/widget.js",)
      "integrity": "",
      "ignoreIntegrity": true
    }
  ],
  "properties": {
    "title": {
      "type": "string",
      "default": "My Widget"
    }
  },
  "methods": {},
  "events": {}
}
```

**2. widget.js** (Web Component)
```javascript
(function() {
  const template = document.createElement("template");
  template.innerHTML = `
    <style>
      :host {
        display: block;
        width: 100%;
        height: 100%;
      }
      .container {
        padding: 16px;
        font-family: Arial, sans-serif;
      }
    </style>
    <div class="container">
      <h3 id="title">My Widget</h3>
      <div id="content"></div>
    </div>
  `;

  class MyCustomWidget extends HTMLElement {
    constructor() {
      super();
      this._shadowRoot = this.attachShadow({ mode: "open" });
      this._shadowRoot.appendChild(template.content.cloneNode(true));
      this._props = {};
    }

    connectedCallback() {
      // Called when element is added to DOM
    }

    onCustomWidgetBeforeUpdate(changedProperties) {
      // Called BEFORE properties are updated
      this._props = { ...this._props, ...changedProperties };
    }

    onCustomWidgetAfterUpdate(changedProperties) {
      // Called AFTER properties are updated - render here
      if (changedProperties.title !== undefined) {
        this._shadowRoot.getElementById("title").textContent = changedProperties.title;
      }
    }

    onCustomWidgetResize() {
      // Called when widget is resized
    }

    onCustomWidgetDestroy() {
      // Cleanup when widget is removed
    }

    // Property getter/setter (required for SAC framework)
    get title() {
      return this._props.title;
    }
    set title(value) {
      this._props.title = value;
      this.dispatchEvent(new CustomEvent("propertiesChanged", {
        detail: { properties: { title: value } }
      }));
    }
  }

  customElements.define("my-custom-widget", MyCustomWidget);
})();
```

**⚠️ Production Note**: The `ignoreIntegrity: true` setting above is **development only**. For production deployments, generate a SHA256 integrity hash and set `ignoreIntegrity: false`.

---

## Community Sample Widgets

SAP provides 15+ ready-to-use custom widget samples:

**Repository**: [SAP-samples/SAC_Custom_Widgets](https://github.com/SAP-samples/analytics-cloud-datasphere-community-content/tree/main/SAC_Custom_Widgets)

| Category | Widgets |
|----------|---------|
| **Charts** | Funnel, Pareto, Sankey, Sunburst, Tree, Line, UI5 Gantt |
| **KPI/Gauge** | KPI Ring, Gauge Grade, Half Donut, Nested Pie, Custom Pie |
| **Utilities** | File Upload, Word Cloud, Bar Gradient, Widget Add-on Sample |

**Requirements**: Optimized View Mode (OVM) enabled, data binding support

**Note**: Check third-party library licenses before production use.

---

## Key Concepts

### Lifecycle Functions
Essential functions called by SAC framework:
- `onCustomWidgetBeforeUpdate(changedProperties)` - Pre-update hook
- `onCustomWidgetAfterUpdate(changedProperties)` - Post-update (render here)
- `onCustomWidgetResize()` - Handle resize events
- `onCustomWidgetDestroy()` - Cleanup resources

### Data Binding
Configure in widget.json to receive SAC model data:
```json
{
  "dataBindings": {
    "myDataBinding": {
      "feeds": [
        {
          "id": "dimensions",
          "description": "Dimensions",
          "type": "dimension"
        },
        {
          "id": "measures",
          "description": "Measures",
          "type": "mainStructureMember"
        }
      ]
    }
  }
}
```

Access data in JavaScript:
```javascript
// Get data binding
const dataBinding = this.dataBindings.getDataBinding("myDataBinding");

// Access result set
const data = this.myDataBinding.data;
const metadata = this.myDataBinding.metadata;

// Iterate over rows
this.myDataBinding.data.forEach(row => {
  const dimensionValue = row.dimensions_0.label;
  const measureValue = row.measures_0.raw;
});
```

### Hosting Options

**1. SAC-Hosted (Recommended, QRC Q2 2023+)**
- Upload files directly to SAC > Files > Public Files
- Use relative paths: `"/path/to/widget.js"`
- Set `"integrity": ""` and `"ignoreIntegrity": true`

**2. GitHub Pages**
- Create repository with widget files
- Enable GitHub Pages in Settings
- Use URL: `[https://username.github.io/repo/widget.js`](https://username.github.io/repo/widget.js`)

**3. External Web Server**
- AWS S3, Azure Blob, or any HTTPS server
- Must inclu