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.
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.
license
GPL-3.0
metadata
{"maintainer":"Eduard Jiglau","maintainer_email":"hello@sap-ai-skills.com","website":"https://sap-ai-skills.com","version":"2.4.1","last_verified":"2026-06-12T00:00:00.000Z","sac_version":"2026.8","errors_prevented":"40+","official_docs":["https://help.sap.com/docs/SAP_ANALYTICS_CLOUD/0ac8c6754ff84605a4372468d002f2bf/75311f67527c41638ceb89af9cd8af3e.html","https://help.sap.com/doc/c813a28922b54e50bd2a307b099787dc/release/en-US/CustomWidgetDevGuide_en.pdf"],"samples_repo":"https://github.com/SAP-samples/analytics-cloud-datasphere-community-content/tree/main/SAC_Custom_Widgets","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","[Truncated]"]}
allowed-tools
["Read","Bash","WebFetch"]
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
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
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
(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>
`;
classMyCustomWidgetextendsHTMLElement {
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 updatedthis._props = { ...this._props, ...changedProperties };
}
onCustomWidgetAfterUpdate(changedProperties) {
// Called AFTER properties are updated - render hereif (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)gettitle() {
returnthis._props.title;
}
settitle(value) {
this._props.title = value;
this.dispatchEvent(newCustomEvent("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:
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.
// Get data bindingconst dataBinding = this.dataBindings.getDataBinding("myDataBinding");
// Access result setconst data = this.myDataBinding.data;
const metadata = this.myDataBinding.metadata;
// Iterate over rowsfor (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:
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
