SAP Analytics Cloud Custom Widget Development
Related Skills
- sap-sac-scripting: Use when custom widgets interact with SAC scripting, widgets, or story/application APIs
- sap-sac-planning: Use when widgets participate in planning workflows or planning table interactions
- sapui5: Use for Web Component/UI5 frontend implementation patterns and browser-side quality
- sap-dependency-security: Use when adding third-party charting or build dependencies to widget projects
Table of Contents
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.
When to Use This Skill
Use this skill when:
- Building custom visualizations not available in standard SAC
- Generating prompt-driven widget ideas, branded widget packages, or composite-ready widget designs
- 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+)
AI-Assisted Generation
For prompt-driven widget creation, first classify the widget role and data-source mode, then suggest 2-3 role-aware options before generating the selected complete package. Keep AI-generated code SAC-compatible, preserve data-binding order when used, and validate/repair before import. See references/ai-assisted-composite-generation.md for output contracts, RAG context patterns, brand styling, and composite caveats.
Widget Discovery and Evidence Intake
Before generating a table, chart, KPI, menu, sidebar, filter, or hybrid control, select both its widget role and data-source mode. Request dimensions, measures/key figures, dates, versions, filters, and feed order only for SAC-bound widgets. For pure UI controls, collect interaction, navigation, state, method/event, accessibility, and responsive-layout requirements instead. Accept user-provided screenshots, PDFs, images, brand guides, and sanitized data as evidence, but confirm technical IDs, feed mappings, asset rights, and licenses before code generation. See references/widget-discovery-intake.md for the Widget Brief, evidence boundaries, and hosted-tool safeguards.
Local Custom Widget Builder
For enterprise or locked-down local environments, offer templates/local-builder/ as the standard no-install scaffold builder. It runs as static HTML/CSS/vanilla JavaScript, avoids public CDNs and external packages, and exports SAC upload artifacts as two separate downloads: widget.json and a Resource-ZIP containing only root-level component JavaScript files. Use Node's server.mjs fallback when direct file:// use is blocked. When a user explicitly permits public-web use for a non-sensitive desktop prototype, optionally suggest the Custom Widget Builder or live demo; never send tenant material or trust its exports without local validation. See references/local-builder-workflow.md for builder boundaries, export rules, hosted-tool safeguards, and validation checks.
SAP Sample Widget Lessons
Before generating a chart, KPI, hierarchy, input utility, Widget Add-On, or build-based widget, consult references/sap-sample-widget-lessons.md. It audits every SAP sample folder and distills reusable lessons for Data Binding-first scaffolds, root-relative Resource-ZIP URLs, styling/builder panel separation, support flags, custom types, script methods/events, add-on extensions[], and build-based app caveats. Use the lessons for structure and risk checks only; do not copy SAP sample code or assets into generated packages.
Browser Design Runtime
Generated widget packages should include templates/design-runtime/ as a no-build, file-first browser preview scaffold. Use it after generation to mock custom-widget essentials outside SAP, adjust properties/design tokens/sample data/viewports, compare multiple widgets, and export an agent iteration payload. See references/browser-design-runtime.md for runtime boundaries and configuration/export contracts. Use templates/local-builder/ for scaffold generation/export; use templates/design-runtime/ for preview and iteration.
CSS and Styling Compliance
Style custom widgets inside their Web Component/Shadow DOM boundary. Do not rely on SAC optimized story theme CSS, SAP shell selectors, or global story CSS to style widget internals. For generated packages, confirm the hosting mode before splitting CSS/HTML into separate files, because SAC ZIP upload packages support component JavaScript and PNG/JPG icons only. See references/css-and-styling-compliance.md for SAP Help-backed allowed/restricted styling rules.
SAC Import and Packaging
Decide the delivery mode before generating widget.json: SAC Resource-ZIP upload and external HTTPS hosting use different URL rules. For SAC Resource-ZIP upload, deliver widget.json separately, upload it first, and only then upload a Resource-ZIP containing root-level component JavaScript files such as widget.js, builder.js, and styling.js. Do not include widget.json, subfolders, tests, README files, CSS, or HTML in that Resource-ZIP.
For Resource-ZIP manifests, use root-relative component URLs such as "/widget.js"; for external hosting, use complete HTTPS URLs. Keep local-preview paths like "widget.js" in preview-only configs unless the target SAC flow explicitly documents that resolution mode. Model simple configurable colors as string properties with hex defaults such as "#f4f7fa"; use the Color type only after the exact SAC tenant and target panel flow accepts it. Browser preview and Node tests are useful, but they are not proof of SAC importability. For widgets with builder/styling panels, preserve focus and collapse state during text edits, keep component JS self-contained, and validate final outputs/ artifacts rather than source-only previews. When the widget is done, the final chat response must offer both completed upload artifacts for download: the widget.json manifest and the Resource-ZIP. See references/sac-import-packaging-lessons.md for upload sequence, ZIP content checks, final-artifact tests, builder/tree rules, final download handoff, and SAC error triage.
Production Audit Lessons
When a widget is rejected by SAC despite passing local tests, consult references/production-widget-lessons.md. It covers raw control characters in bundles, Analytics Designer method-body limits, required integrity states, client-side-only manifest validation, icon and font isolation, user and language boundaries, bookmark risk, opaque-error bisection, behavioral preflight guards, and browser-preview limits. Treat its evidence labels as part of the guidance: tenant observations, SAP-documented behavior, and unconfirmed hypotheses must not be presented as equivalent.
Property Lifecycle
Treat SAC properties as an external state stream. SAC may deliver properties one at a time, echo
values written by the widget, and change their representation. Merge updates, normalize through one
read path, and render from the merged state. Do not assume property order or consume builder
initialization flags on an empty first render. Manifest method bodies are Analytics Designer script:
they may read or write declared properties, but they cannot call private component methods.
Builder and styling panels are stateful editors. Keep text edits targeted so focus, caret, selection,
search, and collapse state survive. Preserve unknown configuration keys when two editors share a
document, and keep one user action to one property dispatch and one undo step. For structured import
or export, preserve stable ids, deep-copy nested templates, use null-prototype maps for
user-authored names, and test every language slot. See references/property-lifecycle.md.
Verification and Artifact Discipline
Validate the built component files and final Resource-ZIP, not only source helpers or a browser
preview. Generate all outputs first, validate them, then write them. Test the final bundles
standalone, verify exact SRI bytes, scan for raw control characters, and use a real browser for
layout, focus, font, pointer, and lifecycle behavior that DOM emulation cannot represent. See
references/verification-and-artifacts.md.
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, local builder, and browser design runtime |
/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
builder-panel.js - Design-time configuration panel
local-builder/ - Static local scaffold builder and SAC artifact exporter
design-runtime/ - Browser preview and design iteration runtime
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)
{
"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",
"integrity": "",
"ignoreIntegrity": true
}
],
"properties": {
"title": {
"type": "string",
"default": "My Widget"
}
},
"methods": {},
"events": {}
}
2. widget.js (Web Component)
(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 a community sample repository with 17 custom widget sample folders:
Repository: SAP-samples/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: Most samples assume Data Binding and Optimized View Mode (OVM) or Optimized and Unified Story Experience.
Note: Check third-party library licenses before production use, adjust hosted component paths when moving samples, and treat live SAC import/runtime validation as tenant-specific. See references/sap-sample-widget-lessons.md for the per-sample audit and creation lessons.
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:
{
"dataBindings": {
"myDataBinding": {
"feeds": [
{
"id": "dimensions",
"description": "Dimensions",
"type": "dimension"
},
{
"id": "measures",
"description": "Measures",
"type": "mainStructureMember"
}
]
}
}
}
Access data in 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
for (let i = 0; i < this.myDataBinding.data.length; i++) {
const row = this.myDataBinding.data[i];
const dimensionValue = row.dimensions_0 ? row.dimensions_0.label : "";
const measureValue = row.measures_0 ? row.measures_0.raw : 0;
}
Hosting Options
1. SAC-Hosted (Recommended, QRC Q2 2023+)
- Upload files directly to SAC > Files > Public Files
- For Resource-ZIP upload flows, upload
widget.json first, then upload a separate Resource-ZIP when SAC enables the Resource File button
- For Resource-ZIP upload flows, use root-relative URLs such as
"/widget.js"; do not use local Windows backslashes or bare local preview paths in the production manifest
- 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
3. External Web Server
- AWS S3, Azure Blob, or any HTTPS server
- Must include CORS headers:
Access-Control-Allow-Origin: *
Security: Integrity Hash
For production, generate a SHA256 integrity value with Node.js for Windows/macOS/Linux:
# Generate integrity hash for widget.js
node -e "const fs=require('node:fs');const crypto=require('node:crypto');const file=process.argv[1]||'widget.js';console.log('sha256-'+crypto.createHash('sha256').update(fs.readFileSync(file)).digest('base64'));" widget.js
# Update JSON
"integrity": "sha256-abc123...",
"ignoreIntegrity": false
On macOS/Linux or Git Bash, OpenSSL is also acceptable; prefix the output with sha256- before adding it to the manifest:
openssl dgst -sha256 -binary widget.js | openssl base64 -A
Common Errors & Solutions
| Error |
Cause |
Solution |
| "The system couldn't load the custom widget" |
Incorrect URL or hosting issue |
Verify URL is accessible, check CORS |
| "Integrity check failed" |
Hash mismatch |
Regenerate hash after JS changes |
| Widget not appearing |
Missing connectedCallback render |
Call render in onCustomWidgetAfterUpdate |
| Properties not updating |
Missing propertiesChanged dispatch |
Use dispatchEvent with propertiesChanged |
| Data not displaying |
Data binding misconfigured |
Verify feeds in JSON match usage |
CUSTOM_WIDGET_SERVICE_EXCEPTION or opaque HTTP 500 |
Raw control or ambiguous code point, malformed method body, manifest/ZIP pair, or another upload constraint |
Scan source and bundles for control code points, BOM, zero-width characters, and line separators, then use one-variable JSON and ZIP probes |
| Method body rejected with unknown function or type errors |
Body calls component internals instead of using declared properties |
Declare the state as a property and have the body read or write that property |
Manifest rejected for missing integrity |
webcomponents[] omitted the required field |
Add integrity and use either development "" plus ignoreIntegrity: true or a real sha256-... digest plus false |
| Icons render blank |
Icon name is not bundled or was guessed |
Generate and search a committed icon map; do not depend on IconPool inside the widget |
| Widget has the wrong font |
Form controls use their UA font or panel CSS overrides SAC |
Inherit the font on controls and avoid custom font stacks in design-time panels |
| Personal or language value is empty or wrong |
Widget tried to discover user or SAC locale context |
Pass it through a declared property from story script |
"Color" is not a valid type or default expected as Color |
Tenant/import flow rejected simple color properties |
Use string plus hex defaults for simple configurable colors |
| Main component could not be loaded |
Resource URL, ZIP content, or JS syntax problem |
Check root-relative webcomponents[].url, Resource-ZIP root contents, then node --check |
| Resource File upload is disabled |
widget.json has not validated yet |
Upload and validate widget.json first, then upload the Resource-ZIP |
| Resource-ZIP imports/later load fails |
ZIP contains manifest, folders, CSS/HTML, or unrelated files |
Keep only root-level JS component files and optional PNG/JPG icons |
| Builder input loses focus or collapse state |
Text edits trigger full render |
Update field/row/JSON text directly; reserve full render for structural changes |
| Preview works but SAC component fails standalone |
Preview depends on a shared source helper not present in bundled JS |
Test final widget.js, builder.js, and styling.js without preview-only helper scripts |
| Duplicate menu items collide |
Subtree duplicate rewrote only root ID |
Rewrite descendant IDs and test uniqueness across the whole tree |
| Panel shows a value that runtime ignores |
Property is stored or exported but never read by the runtime |
Add a runtime-use check and a behavior test for every manifest property |
| Valid zero becomes a default |
Numeric coercion uses `Number(value) |
|
| Builder loses typed text or search state |
Every update rebuilds the panel |
Patch fields in place and restore focus, selection, and caret when structural rendering is required |
| Rename or duplicate leaves stale state |
Identity is positional or a shallow copy aliases nested data |
Preserve stable ids, deep-copy templates, and enumerate every reference holder |
| Layout passes DOM tests but fails in SAC |
Test environment has no layout or font metrics |
Verify geometry and font-dependent behavior in a real browser |
| A user-authored name behaves inconsistently by case |
Membership checks use exact comparisons in multiple sites |
Centralize the matching rule and test a case-only rename |
Debugging
Browser DevTools
- Open Chrome DevTools (F12)
- Sources tab: Find widget.js, set breakpoints
- Console tab: View console.log output
- Network tab: Check if files load (200 status)
Debug Pattern
onCustomWidgetAfterUpdate(changedProperties) {
console.log("Widget updated:", changedProperties);
console.log("Current props:", this._props);
console.log("Data binding:", this.myDataBinding && this.myDataBinding.data);
this._render();
}
Widget Add-Ons (QRC Q4 2023+)
Widget Add-Ons extend built-in SAC widgets without building from scratch.
Use Cases:
- Customize chart tooltips
- Add visual elements to plot areas
- Override built-in styling
Supported Charts: Bar/Column, Stacked Bar/Column, Line, Stacked Area, Numeric Point
Key Differences:
- Only
main and builder components (no styling)
- Must specify extension target (
tooltip, plotArea, numericPoint)
- SAC provides chart context data via methods
See references/widget-addon-guide.md for complete implementation.
Bundled Resources
Templates (Ready-to-Use Code)
templates/basic-widget.js - Minimal Web Component scaffold (~60 lines)
templates/data-bound-chart.js - ECharts widget with SAC data binding (~120 lines)
templates/styling-panel.js - Styling panel for runtime customization (~150 lines)
templates/builder-panel.js - Builder panel for design-time configuration
templates/local-builder/ - No-install local builder for metadata, feeds, properties, methods, events, and SAC two-file export
templates/design-runtime/ - No-build browser preview, design-token controls, scenario switching, and agent iteration export
templates/widget.json-minimal - Bare-minimum metadata (~25 lines)
templates/widget.json-complete - Full-featured metadata (~100 lines)
Reference Documentation
references/json-schema-reference.md - Complete JSON schema documentation
references/widget-templates.md - Additional widget template patterns (6 templates)
references/echarts-integration.md - ECharts library integration guide
references/widget-addon-guide.md - Widget Add-On development (QRC Q4 2023+)
references/best-practices-guide.md - Performance, security, and development guidelines
references/advanced-topics.md - Custom types, script API types, installation
references/integration-and-migration.md - Script integration, content transport
references/script-api-reference.md - DataSource, Selection, MemberInfo APIs
references/ai-assisted-composite-generation.md - Prompt-driven generation, RAG, brand styling, validation, and composite-ready output guidance
references/local-builder-workflow.md - Enterprise-safe local builder workflow, export contract, and validation checklist
references/sap-sample-widget-lessons.md - SAP sample widget audit matrix, reusable generation lessons, and add-on/build-based routing caveats
references/browser-design-runtime.md - Non-SAP browser preview runtime, sidecar config, and agent iteration export
references/css-and-styling-compliance.md - SAP Help-backed CSS, theme, Shadow DOM, and packaging guidance for generated widgets
references/sac-import-packaging-lessons.md - SAC-hosted Resource-ZIP upload sequence, URL rules, ZIP hygiene, builder/tree state rules, self-contained component checks, final-artifact tests, and SAC error triage
references/widget-discovery-intake.md - Widget role/data-source selection, attachment intake, Widget Brief, and hosted-tool safeguards
references/production-widget-lessons.md - Tenant-observed upload failures, script method limits, integrity, isolation, bisection, and preflight guards
references/property-lifecycle.md - SAC property normalization, script method boundaries, stateful editors, persistence, and structured data rules
references/verification-and-artifacts.md - Built-bundle verification, test blind spots, mutation evidence, upload triage, and deterministic artifact checks
Official Documentation Links
Primary References (for skill updates):
Sample Widgets:
Version History
Unreleased
- Added property lifecycle and artifact verification guidance from the consolidated custom-widget lessons, including canonical coercion, stateful panel editing, runtime-use checks, real-browser boundaries, and deterministic final-package checks
- Clarified hosting-mode URL validation, dangerous Unicode/control-code-point scanning, declared-locale handling, and missing-tool verification outcomes
- Added production audit lessons for control-character upload failures, property-only Analytics Designer method bodies, required integrity states, opaque-error bisection, isolated icons/fonts, bookmark risks, and behavioral preflight checks
- Corrected JSON method guidance so manifest method bodies do not call web component internals
- Added an enterprise-safe
templates/local-builder/ scaffold for local widget metadata, property/feed configuration, and SAC two-file artifact export
- Added
templates/builder-panel.js so builder panel generation has a bundled self-contained template
- Added local builder validation coverage without advancing
last_verified; live SAC upload/runtime validation remains pending
- Added SAP sample-widget lessons and local-builder pattern hints for data-bound charts, KPI/gauge widgets, flow/hierarchy widgets, input utilities, Widget Add-ons, and build-based apps without copying upstream sample code
v2.3.2 (2026-07-06)
- Added SAC Resource-ZIP import lessons from the Configurable Menu Navigation project
- Clarified separate
widget.json and Resource-ZIP upload flow, root-relative SAC-hosted URLs, Resource-ZIP content hygiene, and simple color property portability
- Added hook warnings for bare Resource-ZIP component URLs and risky
Color property usage
- Expanded Configurable Menu Navigation lessons for builder focus/collapse state, tree duplicate ID rewrites, self-contained component JS, preview parity, stale panel cleanup, layout/styling property sync, safe output cleanup, and artifact naming
- Required final chat handoff to offer both the
widget.json manifest and Resource-ZIP as separate downloadable artifacts
v2.1.0 (2026-06-12)
- Refreshed to SAC Q2 2026 (version 2026.8)
- No custom-widget framework changes in QRC1/QRC2 2026; lifecycle functions and JSON schema unchanged
- Documented previously missing root-level properties:
eula, imports, supportsMobile, supportsExport, supportsLinkedAnalysisFilterOnSelection, supportsViewportLoading, supportsBookmark, types
- Documented webcomponent
type property for ES module loading
- Documented
includeInBookmarks per-property flag, boolean[]/integer[] types
- Added
serializeCustomWidgetToImage() and customWidgetRenderComplete to advanced topics
- Confirmed: all four lifecycle functions unchanged, feed types unchanged, templates valid
v2.0.0 (2025-12-27)
- Added 3 specialized agents: widget-architect, widget-debugger, widget-api-assistant
- Added 3 slash commands: /widget-validate, /widget-generate, /widget-lint
- Added validation hooks for automatic quality checks on Write/Edit
- Added 5 docs-audited templates in templates/ directory
- Enhanced plugin structure to match comprehensive plugin pattern
- Updated last verified date
v1.2.0 (2025-11-26)
- Updated SAC version reference to 2025.21
- Optimized SKILL.md length from 563 to ~200 lines
- Added Table of Contents to all 8 reference files
- Improved progressive disclosure architecture
v1.1.0 (2025-11-22)
- Added Widget Add-On feature documentation (QRC Q4 2023+)
- Added best practices guide (performance, security, development)
- Added advanced topics (custom types, script API types, installation)
- Enhanced description with additional keywords
- Increased error prevention coverage to 25+
v1.0.0 (2025-11-22)
- Initial release
- Complete JSON metadata reference
- Lifecycle functions documentation
- Data binding guide
- Styling panel implementation
- Hosting options (SAC-hosted, GitHub, external)
- Security (integrity hash, CORS)
- Common errors and debugging
SAC Version: 2026.8
1---
2name: sap-sac-custom-widget
3description: "SAP Analytics Cloud (SAC) Custom Widget development. Use when building custom visualizations, extending SAC with Web Components, or creating Widget Add-Ons. Covers JSON metadata, JavaScript Web Components, lifecycle functions, data binding with feeds, styling/builder panels, property/event/method definitions, third-party library integration, hosting, security, performance, and debugging. Includes Widget Add-On feature (QRC Q4 2023+) and templates for widgets, charts, and KPI cards."
4
5license: GPL-3.0
6metadata:
7 source: https://skillmd.com/skills/secondsky/sap-sac-custom-widget
8 maintainer: "Eduard Jiglau"
9 maintainer_email: "hello@sap-ai-skills.com"
10 website: "https://sap-ai-skills.com"
11 version: "2.4.1"
12 last_verified: 2026-06-12
13 sac_version: "2026.8"
14 errors_prevented: 40+
15 official_docs:
16 - "https://help.sap.com/docs/SAP_ANALYTICS_CLOUD/0ac8c6754ff84605a4372468d002f2bf/75311f67527c41638ceb89af9cd8af3e.html"
17 - "https://help.sap.com/doc/c813a28922b54e50bd2a307b099787dc/release/en-US/CustomWidgetDevGuide_en.pdf"
18 samples_repo: "https://github.com/SAP-samples/analytics-cloud-datasphere-community-content/tree/main/SAC_Custom_Widgets"
19 keywords: [sap analytics cloud, sac custom widget, web component sac, json metadata widget, widget lifecycle functions, onCustomWidgetBeforeUpdate, onCustomWidgetAfterUpdate, onCustomWidgetResize, onCustomWidgetDestroy, sac data binding, dataBindings feeds, styling panel widget, builder panel widget, sac echarts integration, sac d3js integration, third party library sac, widget hosting sac, integrity hash widget, sha256 integrity, widget security cors, sac widget debugging, sac analytics designer widget, optimized story experience widget, sac widget api, widget add-on, sac script api widget, shadow dom web component, sac tooltip customization, plot area addon, sac resource zip upload, root relative widget url, resource file upload, builder focus collapse state, self contained component js, resource zip artifact naming, chat download artifacts]
20allowed-tools:
21 - Read
22 - Bash
23 - WebFetch
24---
25
26# SAP Analytics Cloud Custom Widget Development
27
28## Related Skills
29
30- **sap-sac-scripting**: Use when custom widgets interact with SAC scripting, widgets, or story/application APIs
31- **sap-sac-planning**: Use when widgets participate in planning workflows or planning table interactions
32- **sapui5**: Use for Web Component/UI5 frontend implementation patterns and browser-side quality
33- **sap-dependency-security**: Use when adding third-party charting or build dependencies to widget projects
34
35## Table of Contents
36- [Overview](#overview)
37- [AI-Assisted Generation](#ai-assisted-generation)
38- [Widget Discovery and Evidence Intake](#widget-discovery-and-evidence-intake)
39- [Local Custom Widget Builder](#local-custom-widget-builder)
40- [SAP Sample Widget Lessons](#sap-sample-widget-lessons)
41- [Browser Design Runtime](#browser-design-runtime)
42- [CSS and Styling Compliance](#css-and-styling-compliance)
43- [SAC Import and Packaging](#sac-import-and-packaging)
44- [Production Audit Lessons](#production-audit-lessons)
45- [Property Lifecycle](#property-lifecycle)
46- [Verification and Artifact Discipline](#verification-and-artifact-discipline)
47- [Plugin Components](#plugin-components)
48- [Quick Start](#quick-start)
49- [Community Sample Widgets](#community-sample-widgets)
50- [Key Concepts](#key-concepts)
51- [Common Errors & Solutions](#common-errors--solutions)
52- [Bundled Resources](#bundled-resources)
53
54## Overview
55
56This 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.
57
58## When to Use This Skill
59
60**Use this skill when**:
61- Building custom visualizations not available in standard SAC
62- Generating prompt-driven widget ideas, branded widget packages, or composite-ready widget designs
63- Integrating third-party charting libraries (ECharts, D3.js, Chart.js)
64- Creating interactive input components for SAC applications
65- Implementing specialized data displays or KPI widgets
66- Extending Analytics Designer applications with custom functionality
67- Troubleshooting custom widget loading or data binding issues
68
69**Requirements**:
70- SAC tenant with Optimized Story Experience or Analytics Designer
71- JavaScript/Web Components knowledge
72- External hosting (GitHub Pages, AWS S3, Azure) OR SAC-hosted resources (QRC Q2 2023+)
73
74---
75
76## AI-Assisted Generation
77
78For prompt-driven widget creation, first classify the widget role and data-source mode, then suggest 2-3 role-aware options before generating the selected complete package. Keep AI-generated code SAC-compatible, preserve data-binding order when used, and validate/repair before import. See **`references/ai-assisted-composite-generation.md`** for output contracts, RAG context patterns, brand styling, and composite caveats.
79
80---
81
82## Widget Discovery and Evidence Intake
83
84Before generating a table, chart, KPI, menu, sidebar, filter, or hybrid control, select both its widget role and data-source mode. Request dimensions, measures/key figures, dates, versions, filters, and feed order only for SAC-bound widgets. For pure UI controls, collect interaction, navigation, state, method/event, accessibility, and responsive-layout requirements instead. Accept user-provided screenshots, PDFs, images, brand guides, and sanitized data as evidence, but confirm technical IDs, feed mappings, asset rights, and licenses before code generation. See **`references/widget-discovery-intake.md`** for the Widget Brief, evidence boundaries, and hosted-tool safeguards.
85
86---
87
88## Local Custom Widget Builder
89
90For enterprise or locked-down local environments, offer **`templates/local-builder/`** as the standard no-install scaffold builder. It runs as static HTML/CSS/vanilla JavaScript, avoids public CDNs and external packages, and exports SAC upload artifacts as two separate downloads: `widget.json` and a Resource-ZIP containing only root-level component JavaScript files. Use Node's `server.mjs` fallback when direct `file://` use is blocked. When a user explicitly permits public-web use for a non-sensitive desktop prototype, optionally suggest the [Custom Widget Builder](https://www.custom-widgets.de/custom-widget-builder) or [live demo](https://www.custom-widgets.de/demo); never send tenant material or trust its exports without local validation. See **`references/local-builder-workflow.md`** for builder boundaries, export rules, hosted-tool safeguards, and validation checks.
91
92---
93
94## SAP Sample Widget Lessons
95
96Before generating a chart, KPI, hierarchy, input utility, Widget Add-On, or build-based widget, consult **`references/sap-sample-widget-lessons.md`**. It audits every SAP sample folder and distills reusable lessons for Data Binding-first scaffolds, root-relative Resource-ZIP URLs, styling/builder panel separation, support flags, custom `types`, script methods/events, add-on `extensions[]`, and build-based app caveats. Use the lessons for structure and risk checks only; do not copy SAP sample code or assets into generated packages.
97
98---
99
100## Browser Design Runtime
101
102Generated widget packages should include **`templates/design-runtime/`** as a no-build, file-first browser preview scaffold. Use it after generation to mock custom-widget essentials outside SAP, adjust properties/design tokens/sample data/viewports, compare multiple widgets, and export an agent iteration payload. See **`references/browser-design-runtime.md`** for runtime boundaries and configuration/export contracts. Use `templates/local-builder/` for scaffold generation/export; use `templates/design-runtime/` for preview and iteration.
103
104---
105
106## CSS and Styling Compliance
107
108Style custom widgets inside their Web Component/Shadow DOM boundary. Do not rely on SAC optimized story theme CSS, SAP shell selectors, or global story CSS to style widget internals. For generated packages, confirm the hosting mode before splitting CSS/HTML into separate files, because SAC ZIP upload packages support component JavaScript and PNG/JPG icons only. See **`references/css-and-styling-compliance.md`** for SAP Help-backed allowed/restricted styling rules.
109
110---
111
112## SAC Import and Packaging
113
114Decide the delivery mode before generating `widget.json`: SAC Resource-ZIP upload and external HTTPS hosting use different URL rules. For SAC Resource-ZIP upload, deliver `widget.json` separately, upload it first, and only then upload a Resource-ZIP containing root-level component JavaScript files such as `widget.js`, `builder.js`, and `styling.js`. Do not include `widget.json`, subfolders, tests, README files, CSS, or HTML in that Resource-ZIP.
115
116For Resource-ZIP manifests, use root-relative component URLs such as `"/widget.js"`; for external hosting, use complete HTTPS URLs. Keep local-preview paths like `"widget.js"` in preview-only configs unless the target SAC flow explicitly documents that resolution mode. Model simple configurable colors as `string` properties with hex defaults such as `"#f4f7fa"`; use the `Color` type only after the exact SAC tenant and target panel flow accepts it. Browser preview and Node tests are useful, but they are not proof of SAC importability. For widgets with builder/styling panels, preserve focus and collapse state during text edits, keep component JS self-contained, and validate final `outputs/` artifacts rather than source-only previews. When the widget is done, the final chat response must offer both completed upload artifacts for download: the `widget.json` manifest and the Resource-ZIP. See **`references/sac-import-packaging-lessons.md`** for upload sequence, ZIP content checks, final-artifact tests, builder/tree rules, final download handoff, and SAC error triage.
117
118---
119
120## Production Audit Lessons
121
122When a widget is rejected by SAC despite passing local tests, consult **`references/production-widget-lessons.md`**. It covers raw control characters in bundles, Analytics Designer method-body limits, required integrity states, client-side-only manifest validation, icon and font isolation, user and language boundaries, bookmark risk, opaque-error bisection, behavioral preflight guards, and browser-preview limits. Treat its evidence labels as part of the guidance: tenant observations, SAP-documented behavior, and unconfirmed hypotheses must not be presented as equivalent.
123
124## Property Lifecycle
125
126Treat SAC properties as an external state stream. SAC may deliver properties one at a time, echo
127values written by the widget, and change their representation. Merge updates, normalize through one
128read path, and render from the merged state. Do not assume property order or consume builder
129initialization flags on an empty first render. Manifest method bodies are Analytics Designer script:
130they may read or write declared properties, but they cannot call private component methods.
131
132Builder and styling panels are stateful editors. Keep text edits targeted so focus, caret, selection,
133search, and collapse state survive. Preserve unknown configuration keys when two editors share a
134document, and keep one user action to one property dispatch and one undo step. For structured import
135or export, preserve stable ids, deep-copy nested templates, use null-prototype maps for
136user-authored names, and test every language slot. See **`references/property-lifecycle.md`**.
137
138## Verification and Artifact Discipline
139
140Validate the built component files and final Resource-ZIP, not only source helpers or a browser
141preview. Generate all outputs first, validate them, then write them. Test the final bundles
142standalone, verify exact SRI bytes, scan for raw control characters, and use a real browser for
143layout, focus, font, pointer, and lifecycle behavior that DOM emulation cannot represent. See
144**`references/verification-and-artifacts.md`**.
145
146---
147
148## Plugin Components
149
150This plugin provides specialized agents, commands, and validation hooks for comprehensive widget development support.
151
152### Agents
153
154| Agent | Color | Purpose | Trigger Examples |
155|-------|-------|---------|------------------|
156| **widget-architect** | Blue | Design widget structure, metadata, and integration patterns | "design custom widget", "plan widget architecture" |
157| **widget-debugger** | Yellow | Troubleshoot loading, data binding, CORS, and runtime issues | "widget won't load", "CORS error", "data not binding" |
158| **widget-api-assistant** | Green | Write JavaScript widget code, lifecycle functions, API integrations | "write widget code", "implement lifecycle functions" |
159
160### Commands
161
162| Command | Usage | Description |
163|---------|-------|-------------|
164| `/widget-validate` | `/widget-validate [file]` | Validate widget.json schema and widget.js structure |
165| `/widget-generate` | `/widget-generate` | Interactively generate widget scaffold with JSON, JS, local builder, and browser design runtime |
166| `/widget-lint` | `/widget-lint [file]` | Performance, security, and best practices analysis |
167
168### Validation Hooks
169
170Automatic quality checks triggered on Write/Edit operations:
171- **widget.json**: Required fields, tag naming, property types, data binding config
172- **widget.js**: Lifecycle functions, Shadow DOM, propertiesChanged dispatch
173- **Performance**: Resize debouncing, chart disposal, XSS prevention
174- **Context Reminders**: Template suggestions, command recommendations
175
176### Templates
177
178Ready-to-use scaffolds in `templates/` directory:
179- `basic-widget.js` - Minimal Web Component with all lifecycle functions
180- `data-bound-chart.js` - ECharts widget with data binding
181- `styling-panel.js` - Runtime customization panel
182- `builder-panel.js` - Design-time configuration panel
183- `local-builder/` - Static local scaffold builder and SAC artifact exporter
184- `design-runtime/` - Browser preview and design iteration runtime
185- `widget.json-minimal` - Bare-minimum metadata
186- `widget.json-complete` - Full-featured metadata with all options
187
188---
189
190## Quick Start
191
192### Minimal Custom Widget Structure
193
194A custom widget requires two files:
195
196**1. widget.json** (Metadata)
197```json
198{
199 "id": "com.company.mywidget",
200 "version": "1.0.0",
201 "name": "My Custom Widget",
202 "description": "A simple custom widget",
203 "vendor": "Company Name",
204 "license": "MIT",
205 "icon": "",
206 "webcomponents": [
207 {
208 "kind": "main",
209 "tag": "my-custom-widget",
210 "url": "https://your-host.com/widget.js",
211 "integrity": "",
212 "ignoreIntegrity": true
213 }
214 ],
215 "properties": {
216 "title": {
217 "type": "string",
218 "default": "My Widget"
219 }
220 },
221 "methods": {},
222 "events": {}
223}
224```
225
226**2. widget.js** (Web Component)
227```javascript
228(function() {
229 const template = document.createElement("template");
230 template.innerHTML = `
231 <style>
232 :host {
233 display: block;
234 width: 100%;
235 height: 100%;
236 }
237 .container {
238 padding: 16px;
239 font-family: Arial, sans-serif;
240 }
241 </style>
242 <div class="container">
243 <h3 id="title">My Widget</h3>
244 <div id="content"></div>
245 </div>
246 `;
247
248 class MyCustomWidget extends HTMLElement {
249 constructor() {
250 super();
251 this._shadowRoot = this.attachShadow({ mode: "open" });
252 this._shadowRoot.appendChild(template.content.cloneNode(true));
253 this._props = {};
254 }
255
256 connectedCallback() {
257 // Called when element is added to DOM
258 }
259
260 onCustomWidgetBeforeUpdate(changedProperties) {
261 // Called BEFORE properties are updated
262 this._props = { ...this._props, ...changedProperties };
263 }
264
265 onCustomWidgetAfterUpdate(changedProperties) {
266 // Called AFTER properties are updated - render here
267 if (changedProperties.title !== undefined) {
268 this._shadowRoot.getElementById("title").textContent = changedProperties.title;
269 }
270 }
271
272 onCustomWidgetResize() {
273 // Called when widget is resized
274 }
275
276 onCustomWidgetDestroy() {
277 // Cleanup when widget is removed
278 }
279
280 // Property getter/setter (required for SAC framework)
281 get title() {
282 return this._props.title;
283 }
284 set title(value) {
285 this._props.title = value;
286 this.dispatchEvent(new CustomEvent("propertiesChanged", {
287 detail: { properties: { title: value } }
288 }));
289 }
290 }
291
292 customElements.define("my-custom-widget", MyCustomWidget);
293})();
294```
295
296**⚠️ Production Note**: The `ignoreIntegrity: true` setting above is **development only**. For production deployments, generate a SHA256 integrity hash and set `ignoreIntegrity: false`.
297
298---
299
300## Community Sample Widgets
301
302SAP provides a community sample repository with 17 custom widget sample folders:
303
304**Repository**: [SAP-samples/SAC_Custom_Widgets](https://github.com/SAP-samples/analytics-cloud-datasphere-community-content/tree/main/SAC_Custom_Widgets)
305
306| Category | Widgets |
307|----------|---------|
308| **Charts** | Funnel, Pareto, Sankey, Sunburst, Tree, Line, UI5 Gantt |
309| **KPI/Gauge** | KPI Ring, Gauge Grade, Half Donut, Nested Pie, Custom Pie |
310| **Utilities** | File Upload, Word Cloud, Bar Gradient, Widget Add-on Sample |
311
312**Requirements**: Most samples assume Data Binding and Optimized View Mode (OVM) or Optimized and Unified Story Experience.
313
314**Note**: Check third-party library licenses before production use, adjust hosted component paths when moving samples, and treat live SAC import/runtime validation as tenant-specific. See **`references/sap-sample-widget-lessons.md`** for the per-sample audit and creation lessons.
315
316---
317
318## Key Concepts
319
320### Lifecycle Functions
321Essential functions called by SAC framework:
322- `onCustomWidgetBeforeUpdate(changedProperties)` - Pre-update hook
323- `onCustomWidgetAfterUpdate(changedProperties)` - Post-update (render here)
324- `onCustomWidgetResize()` - Handle resize events
325- `onCustomWidgetDestroy()` - Cleanup resources
326
327### Data Binding
328Configure in widget.json to receive SAC model data:
329```json
330{
331 "dataBindings": {
332 "myDataBinding": {
333 "feeds": [
334 {
335 "id": "dimensions",
336 "description": "Dimensions",
337 "type": "dimension"
338 },
339 {
340 "id": "measures",
341 "description": "Measures",
342 "type": "mainStructureMember"
343 }
344 ]
345 }
346 }
347}
348```
349
350Access data in JavaScript:
351```javascript
352// Get data binding
353const dataBinding = this.dataBindings.getDataBinding("myDataBinding");
354
355// Access result set
356const data = this.myDataBinding.data;
357const metadata = this.myDataBinding.metadata;
358
359// Iterate over rows
360for (let i = 0; i < this.myDataBinding.data.length; i++) {
361 const row = this.myDataBinding.data[i];
362 const dimensionValue = row.dimensions_0 ? row.dimensions_0.label : "";
363 const measureValue = row.measures_0 ? row.measures_0.raw : 0;
364}
365```
366
367### Hosting Options
368
369**1. SAC-Hosted (Recommended, QRC Q2 2023+)**
370- Upload files directly to SAC > Files > Public Files
371- For Resource-ZIP upload flows, upload `widget.json` first, then upload a separate Resource-ZIP when SAC enables the Resource File button
372- For Resource-ZIP upload flows, use root-relative URLs such as `"/widget.js"`; do not use local Windows backslashes or bare local preview paths in the production manifest
373- Set `"integrity": ""` and `"ignoreIntegrity": true`
374
375**2. GitHub Pages**
376- Create repository with widget files
377- Enable GitHub Pages in Settings
378- Use URL: `https://username.github.io/repo/widget.js`
379
380**3. External Web Server**
381- AWS S3, Azure Blob, or any HTTPS server
382- Must include CORS headers: `Access-Control-Allow-Origin: *`
383
384### Security: Integrity Hash
385
386For production, generate a SHA256 integrity value with Node.js for Windows/macOS/Linux:
387```bash
388# Generate integrity hash for widget.js
389node -e "const fs=require('node:fs');const crypto=require('node:crypto');const file=process.argv[1]||'widget.js';console.log('sha256-'+crypto.createHash('sha256').update(fs.readFileSync(file)).digest('base64'));" widget.js
390
391# Update JSON
392"integrity": "sha256-abc123...",
393"ignoreIntegrity": false
394```
395
396On macOS/Linux or Git Bash, OpenSSL is also acceptable; prefix the output with `sha256-` before adding it to the manifest:
397```bash
398openssl dgst -sha256 -binary widget.js | openssl base64 -A
399```
400
401---
402
403## Common Errors & Solutions
404
405| Error | Cause | Solution |
406|-------|-------|----------|
407| "The system couldn't load the custom widget" | Incorrect URL or hosting issue | Verify URL is accessible, check CORS |
408| "Integrity check failed" | Hash mismatch | Regenerate hash after JS changes |
409| Widget not appearing | Missing connectedCallback render | Call render in onCustomWidgetAfterUpdate |
410| Properties not updating | Missing propertiesChanged dispatch | Use dispatchEvent with propertiesChanged |
411| Data not displaying | Data binding misconfigured | Verify feeds in JSON match usage |
412| `CUSTOM_WIDGET_SERVICE_EXCEPTION` or opaque HTTP 500 | Raw control or ambiguous code point, malformed method body, manifest/ZIP pair, or another upload constraint | Scan source and bundles for control code points, BOM, zero-width characters, and line separators, then use one-variable JSON and ZIP probes |
413| Method body rejected with unknown function or type errors | Body calls component internals instead of using declared properties | Declare the state as a property and have the body read or write that property |
414| Manifest rejected for missing `integrity` | `webcomponents[]` omitted the required field | Add `integrity` and use either development `""` plus `ignoreIntegrity: true` or a real `sha256-...` digest plus `false` |
415| Icons render blank | Icon name is not bundled or was guessed | Generate and search a committed icon map; do not depend on `IconPool` inside the widget |
416| Widget has the wrong font | Form controls use their UA font or panel CSS overrides SAC | Inherit the font on controls and avoid custom font stacks in design-time panels |
417| Personal or language value is empty or wrong | Widget tried to discover user or SAC locale context | Pass it through a declared property from story script |
418| `"Color" is not a valid type` or default expected as Color | Tenant/import flow rejected simple color properties | Use `string` plus hex defaults for simple configurable colors |
419| Main component could not be loaded | Resource URL, ZIP content, or JS syntax problem | Check root-relative `webcomponents[].url`, Resource-ZIP root contents, then `node --check` |
420| Resource File upload is disabled | `widget.json` has not validated yet | Upload and validate `widget.json` first, then upload the Resource-ZIP |
421| Resource-ZIP imports/later load fails | ZIP contains manifest, folders, CSS/HTML, or unrelated files | Keep only root-level JS component files and optional PNG/JPG icons |
422| Builder input loses focus or collapse state | Text edits trigger full render | Update field/row/JSON text directly; reserve full render for structural changes |
423| Preview works but SAC component fails standalone | Preview depends on a shared source helper not present in bundled JS | Test final `widget.js`, `builder.js`, and `styling.js` without preview-only helper scripts |
424| Duplicate menu items collide | Subtree duplicate rewrote only root ID | Rewrite descendant IDs and test uniqueness across the whole tree |
425| Panel shows a value that runtime ignores | Property is stored or exported but never read by the runtime | Add a runtime-use check and a behavior test for every manifest property |
426| Valid zero becomes a default | Numeric coercion uses `Number(value) || fallback` | Use an explicit finite-value check |
427| Builder loses typed text or search state | Every update rebuilds the panel | Patch fields in place and restore focus, selection, and caret when structural rendering is required |
428| Rename or duplicate leaves stale state | Identity is positional or a shallow copy aliases nested data | Preserve stable ids, deep-copy templates, and enumerate every reference holder |
429| Layout passes DOM tests but fails in SAC | Test environment has no layout or font metrics | Verify geometry and font-dependent behavior in a real browser |
430| A user-authored name behaves inconsistently by case | Membership checks use exact comparisons in multiple sites | Centralize the matching rule and test a case-only rename |
431
432---
433
434## Debugging
435
436### Browser DevTools
4371. Open Chrome DevTools (F12)
4382. Sources tab: Find widget.js, set breakpoints
4393. Console tab: View console.log output
4404. Network tab: Check if files load (200 status)
441
442### Debug Pattern
443```javascript
444onCustomWidgetAfterUpdate(changedProperties) {
445 console.log("Widget updated:", changedProperties);
446 console.log("Current props:", this._props);
447 console.log("Data binding:", this.myDataBinding && this.myDataBinding.data);
448 this._render();
449}
450```
451
452---
453
454## Widget Add-Ons (QRC Q4 2023+)
455
456Widget Add-Ons extend built-in SAC widgets without building from scratch.
457
458**Use Cases**:
459- Customize chart tooltips
460- Add visual elements to plot areas
461- Override built-in styling
462
463**Supported Charts**: Bar/Column, Stacked Bar/Column, Line, Stacked Area, Numeric Point
464
465**Key Differences**:
466- Only `main` and `builder` components (no `styling`)
467- Must specify extension target (`tooltip`, `plotArea`, `numericPoint`)
468- SAC provides chart context data via methods
469
470See **`references/widget-addon-guide.md`** for complete implementation.
471
472---
473
474## Bundled Resources
475
476### Templates (Ready-to-Use Code)
477
478- **`templates/basic-widget.js`** - Minimal Web Component scaffold (~60 lines)
479- **`templates/data-bound-chart.js`** - ECharts widget with SAC data binding (~120 lines)
480- **`templates/styling-panel.js`** - Styling panel for runtime customization (~150 lines)
481- **`templates/builder-panel.js`** - Builder panel for design-time configuration
482- **`templates/local-builder/`** - No-install local builder for metadata, feeds, properties, methods, events, and SAC two-file export
483- **`templates/design-runtime/`** - No-build browser preview, design-token controls, scenario switching, and agent iteration export
484- **`templates/widget.json-minimal`** - Bare-minimum metadata (~25 lines)
485- **`templates/widget.json-complete`** - Full-featured metadata (~100 lines)
486
487### Reference Documentation
488
4891. **`references/json-schema-reference.md`** - Complete JSON schema documentation
4902. **`references/widget-templates.md`** - Additional widget template patterns (6 templates)
4913. **`references/echarts-integration.md`** - ECharts library integration guide
4924. **`references/widget-addon-guide.md`** - Widget Add-On development (QRC Q4 2023+)
4935. **`references/best-practices-guide.md`** - Performance, security, and development guidelines
4946. **`references/advanced-topics.md`** - Custom types, script API types, installation
4957. **`references/integration-and-migration.md`** - Script integration, content transport
4968. **`references/script-api-reference.md`** - DataSource, Selection, MemberInfo APIs
4979. **`references/ai-assisted-composite-generation.md`** - Prompt-driven generation, RAG, brand styling, validation, and composite-ready output guidance
49810. **`references/local-builder-workflow.md`** - Enterprise-safe local builder workflow, export contract, and validation checklist
49911. **`references/sap-sample-widget-lessons.md`** - SAP sample widget audit matrix, reusable generation lessons, and add-on/build-based routing caveats
50012. **`references/browser-design-runtime.md`** - Non-SAP browser preview runtime, sidecar config, and agent iteration export
50113. **`references/css-and-styling-compliance.md`** - SAP Help-backed CSS, theme, Shadow DOM, and packaging guidance for generated widgets
50214. **`references/sac-import-packaging-lessons.md`** - SAC-hosted Resource-ZIP upload sequence, URL rules, ZIP hygiene, builder/tree state rules, self-contained component checks, final-artifact tests, and SAC error triage
50315. **`references/widget-discovery-intake.md`** - Widget role/data-source selection, attachment intake, Widget Brief, and hosted-tool safeguards
50416. **`references/production-widget-lessons.md`** - Tenant-observed upload failures, script method limits, integrity, isolation, bisection, and preflight guards
50517. **`references/property-lifecycle.md`** - SAC property normalization, script method boundaries, stateful editors, persistence, and structured data rules
50618. **`references/verification-and-artifacts.md`** - Built-bundle verification, test blind spots, mutation evidence, upload triage, and deterministic artifact checks
507
508---
509
510## Official Documentation Links
511
512**Primary References** (for skill updates):
513- [Custom Widget Developer Guide](https://help.sap.com/docs/SAP_ANALYTICS_CLOUD/0ac8c6754ff84605a4372468d002f2bf/75311f67527c41638ceb89af9cd8af3e.html)
514- [Developer Guide PDF](https://help.sap.com/doc/c813a28922b54e50bd2a307b099787dc/release/en-US/CustomWidgetDevGuide_en.pdf)
515- [Widget API PDF (2025)](https://help.sap.com/doc/7e0efa0e68dc45958e568699f8226ad7/cloud/en-US/SAC_Widget_API_en.pdf)
516
517**Sample Widgets**:
518- [SAP Samples Repository](https://github.com/SAP-samples/analytics-cloud-datasphere-community-content/tree/main/SAC_Custom_Widgets)
519- [SAP Custom Widget GitHub](https://github.com/SAP-Custom-Widget)
520
521---
522
523## Version History
524
525**Unreleased**
526- Added property lifecycle and artifact verification guidance from the consolidated custom-widget lessons, including canonical coercion, stateful panel editing, runtime-use checks, real-browser boundaries, and deterministic final-package checks
527- Clarified hosting-mode URL validation, dangerous Unicode/control-code-point scanning, declared-locale handling, and missing-tool verification outcomes
528- Added production audit lessons for control-character upload failures, property-only Analytics Designer method bodies, required integrity states, opaque-error bisection, isolated icons/fonts, bookmark risks, and behavioral preflight checks
529- Corrected JSON method guidance so manifest method bodies do not call web component internals
530- Added an enterprise-safe `templates/local-builder/` scaffold for local widget metadata, property/feed configuration, and SAC two-file artifact export
531- Added `templates/builder-panel.js` so builder panel generation has a bundled self-contained template
532- Added local builder validation coverage without advancing `last_verified`; live SAC upload/runtime validation remains pending
533- Added SAP sample-widget lessons and local-builder pattern hints for data-bound charts, KPI/gauge widgets, flow/hierarchy widgets, input utilities, Widget Add-ons, and build-based apps without copying upstream sample code
534
535**v2.3.2** (2026-07-06)
536- Added SAC Resource-ZIP import lessons from the Configurable Menu Navigation project
537- Clarified separate `widget.json` and Resource-ZIP upload flow, root-relative SAC-hosted URLs, Resource-ZIP content hygiene, and simple color property portability
538- Added hook warnings for bare Resource-ZIP component URLs and risky `Color` property usage
539- Expanded Configurable Menu Navigation lessons for builder focus/collapse state, tree duplicate ID rewrites, self-contained component JS, preview parity, stale panel cleanup, layout/styling property sync, safe output cleanup, and artifact naming
540- Required final chat handoff to offer both the `widget.json` manifest and Resource-ZIP as separate downloadable artifacts
541
542**v2.1.0** (2026-06-12)
543- Refreshed to SAC Q2 2026 (version 2026.8)
544- No custom-widget framework changes in QRC1/QRC2 2026; lifecycle functions and JSON schema unchanged
545- Documented previously missing root-level properties: `eula`, `imports`, `supportsMobile`, `supportsExport`, `supportsLinkedAnalysisFilterOnSelection`, `supportsViewportLoading`, `supportsBookmark`, `types`
546- Documented webcomponent `type` property for ES module loading
547- Documented `includeInBookmarks` per-property flag, `boolean[]`/`integer[]` types
548- Added `serializeCustomWidgetToImage()` and `customWidgetRenderComplete` to advanced topics
549- Confirmed: all four lifecycle functions unchanged, feed types unchanged, templates valid
550
551**v2.0.0** (2025-12-27)
552- Added 3 specialized agents: widget-architect, widget-debugger, widget-api-assistant
553- Added 3 slash commands: /widget-validate, /widget-generate, /widget-lint
554- Added validation hooks for automatic quality checks on Write/Edit
555- Added 5 docs-audited templates in templates/ directory
556- Enhanced plugin structure to match comprehensive plugin pattern
557- Updated last verified date
558
559**v1.2.0** (2025-11-26)
560- Updated SAC version reference to 2025.21
561- Optimized SKILL.md length from 563 to ~200 lines
562- Added Table of Contents to all 8 reference files
563- Improved progressive disclosure architecture
564
565**v1.1.0** (2025-11-22)
566- Added Widget Add-On feature documentation (QRC Q4 2023+)
567- Added best practices guide (performance, security, development)
568- Added advanced topics (custom types, script API types, installation)
569- Enhanced description with additional keywords
570- Increased error prevention coverage to 25+
571
572**v1.0.0** (2025-11-22)
573- Initial release
574- Complete JSON metadata reference
575- Lifecycle functions documentation
576- Data binding guide
577- Styling panel implementation
578- Hosting options (SAC-hosted, GitHub, external)
579- Security (integrity hash, CORS)
580- Common errors and debugging
581
582---
583
584**SAC Version**: 2026.8