Portal Widgets Reference

This page describes the widgets included in the initial catalog. Properties are modified in the Inspector as a JSON object; title, geometry, and common style also have visual controls.

Common Properties

Property	Type	Usage
title	string	Optional title for the widget.
hidden	boolean	Hides the widget when set to true.
placement.x, placement.y	integer	Position in the grid, starting from 1.
placement.w, placement.h	integer	Width and height in cells.
style	object	CSS properties, states, and breakpoint of the instance.
style.rawCss	string	Advanced scoped CSS rules.

In the Inspector, the Title field and the JSON property title are synchronised in both directions. A string entered in one of the two is also reflected in the other. To remove the heading, delete title from the JSON or clear Title; the guided control automatically saves the change.

Guided controls are automatically saved and show a confirmation toaster. For JSON Properties, JSON Style, and Scoped CSS, use Save Advanced Changes instead.

Section (layout.section)

Groups related content. title controls the visible heading. It is also useful as a destination structure for custom components.

Text (content.text)

The text property contains plain text; line breaks are preserved.

{"title": "Avviso", "text": "Intervento programmato\nDalle 18:00 alle 19:00"}

To change only the content, use .portal-text in scoped CSS.

Hero (content.hero)

Opening block with eyebrow, title, subtitle, image (assetPath) and optional button (buttonLabel, routeId). routeId accepts only an internal route. Use only one main Hero per page and fill imageAlt when an image is present.

Card (content.card)

Combines title, text, image and internal link. In grids use uniform dimensions; .portal-card__media allows adjusting aspect ratio and object-fit.

Divider (content.divider)

orientation can be horizontal or vertical; title is an optional label. A vertical divider requires adequate grid height.

Link (navigation.link)

• label: button label;
• routeId: identifier of an internal route declared in portal.json.

The widget does not open external URLs.

{"label": "Apri ordini", "routeId": "orders"}

Menu (navigation.menu)

items is an array of {label, routeId} selected from existing routes. orientation can be horizontal or vertical; collapseOnMobile enables compact mode on small screens.

Navigation Tabs (navigation.tabs)

Shows related routes as tabs. items preserves order, while stretch distributes tabs across available width. On mobile, tabs scroll horizontally.

Breadcrumb (navigation.breadcrumb)

items describes the hierarchical path; the last item may not have routeId. separator accepts short text. The Breadcrumb does not replace the main menu.

Image (media.image)

• assetPath: image path in the repository;
• alt: accessible alternative description.

Load the file from Explorer first and then use the same path:

{"title": "Marchio", "assetPath": "assets/logo.png", "alt": "Logo aziendale"}

PNG, JPEG, GIF and WebP files can be loaded up to the limit indicated by the editor. Height placement.h also sizes the image, which uses all available space without distortion. To change the crop, use, for example, .portal-image { object-fit: cover; } in scoped CSS.

Read-only Form (form.readonly)

fields is an array of objects with key, label and value:

{
  "title": "Ordine",
  "fields": [
    {"key": "number", "label": "Numero", "value": "SO-1001"},
    {"key": "status", "label": "Stato", "value": "Aperto"}
  ]
}

Collapsible panel (layout.collapsible)

title is always visible, content contains the text and openByDefault selects the initial state. Do not hide mandatory errors or confirmations in a closed panel.

Sidebar (layout.sidebar)

Side area confined within the widget. side is left or right; collapsible and collapsedByDefault govern compact control. For complete navigation, a vertical menu is preferably used.

Drawer (layout.drawer)

Overlaid Panel opened by buttonLabel. side selects the side and closeOnScrim enables closing on background. The runtime handles Escape and focus return; do not use the Drawer for blocking messages.

Data table (data.table)

• columns: ordered list of keys to display;
• bindings.data.resourceKey: Data Resource declared in the data folder.

{
  "props": {"title": "Ordini", "columns": ["number", "status"]},
  "bindings": {"data": {"resourceKey": "orders"}}
}

The Data Resource can query authorized objects, data sources, or Semantic Models. The browser does not access the source directly.

The Data command creates and modifies resources with visual selection of connection, schema, table, dimensions, measures, and aggregations, or of a published Semantic Model, fields, and measures. Open JSON enables advanced configurations after the first save.

Data form (form.write)

Collects typed fields and stores them in an associated Working Dataset. The binding must allow appending records; validation is repeated on the server and the browser never accesses the store directly. After a successful save, connected tables and charts refresh without reloading the page.

Bar chart (data.chart)

Displays server-calculated metrics as accessible horizontal bars. series lists the key, label and optional colour for each metric; the binding must reference an aggregate Data Resource.

Data export (data.export)

Provides CSV and XLSX only when the Data Resource allows export. The generated file is temporary, respects reader permissions and neutralises values that may be unsafe in spreadsheets.

User View (user-view.embed)

• viewId: User View ID;
• versionId: Published version ID to block in the release.

Both values are mandatory. In Visual mode, the dropdown displays only published User Views belonging to the Portal Project and automatically populates both IDs. The version pin prevents a subsequent modification of the View from changing an already approved Portal release.

In Preview and the Published Portal, the View is displayed directly in the widget, without requiring a second access. If the session or permissions are no longer valid, the widget displays diagnostics instead of the View.

In the Portal, the extended header of the View does not occupy space: updates, filters, and view options are gathered in a floating icon-only toolbar.

User View Widget (user-view.widget)

Incorpora un singolo widget standard o personalizzato di una Vista pubblicata. La palette e l'Inspector mostrano solo i widget delle Viste accessibili nel Progetto e registrano viewId, versionId e widgetKey. Sono supportati anche grafici, KPI, tabelle, mappe e widget provenienti dal catalogo personalizzato delle Viste.

The runtime loads only the portion of the View and the data source required for the selected widget; it is not possible to change widgetKey to access a different data source.

Workflow Action (workflow.action)

• workflowId: Associated workflow;
• buttonLabel: button text;
• confirmationText: optional confirmation;
• fields: parameters collected before startup;
• bindings.workflow.workflowId: must match props.workflowId.

In Visual mode, the dropdown displays only the executable Workflows of the Portal Project. For each parameter, the Inspector generates a choice between a default value (default), a user-provided value (prompt), and a fixed value (literal). Sensitive parameters do not allow fixed values; Workflows with file parameters are not selectable.

In Preview, the action performs a dry-run. In the active Portal, it starts the Workflow only if the user, Portal, and release are authorised.

BPMN diagram (bpmn.viewer)

• templateId: BPMN object belonging to the Project;
• versionId: deployed, pinned version.

The selector fills both values and shows accessible diagrams only. Preview and runtime use a read-only viewer and revalidate the reader's permissions.

Report Power BI (bi.powerbi)

The widget supports both Secure URL, with the viewer's Microsoft session, and App owns data, with a Project-governed profile and binding. Publish to web URLs and values containing tokens or credentials are rejected. See Power BI: Secure URL and App owns data for the complete configuration of both modes.

Dashboard Qlik (bi.qlik)

• embedMode: secure_url or oauth_impersonation;
• embedUrl: Qlik HTTPS URL, only for Secure URL;
• bindingKey: Project logical binding, only for OAuth impersonation;
• allowFullscreen: enables fullscreen.

Governed mode stores the App ID and content type in the binding and uses a short-lived token generated by Sybot. Profile and endpoint must pass Diagnostics, and the release retains the binding revision. See Governed integrations.

Custom widget sandbox (custom.sandbox)

A custom component uses this structure:

components/my-widget/
├── component.json
├── template.html
├── styles.css
└── index.js

component.json declares files and capabilities:

{
  "schemaVersion": 1,
  "name": "My widget",
  "executionMode": "sandboxed",
  "template": "template.html",
  "styles": "styles.css",
  "entry": "index.js",
  "capabilities": ["data:query", "events:emit"]
}

JavaScript can modify the DOM inside its own iframe. For data and actions, use PortalWidgetSDK; direct network calls, access to the parent document, cookies and session storage are not allowed.

The Inspector exposes Open component code, which automatically switches to Code and opens manifest, template, CSS and JavaScript. The Project Catalogue can also copy a component from another Portal; the component becomes a versionable copy in the current repository.

export async function mount(sdk) {
  const result = await sdk.query('orders', {status: 'open'});
  document.querySelector('[data-count]').textContent = result.rows.length;
}

Styles, states and breakpoints

CSS properties use kebab-case names. The states and breakpoints sections apply local variations:

{
  "background-color": "#ffffff",
  "padding": "1rem",
  "border-radius": "8px",
  "states": {
    "hover": {"box-shadow": "0 8px 24px rgba(15, 23, 42, .18)"}
  },
  "breakpoints": {
    "md": {"padding": "1.5rem"}
  }
}

Supported states are hover, focus, active and disabled; breakpoints are sm, md, lg and xl. Always verify Desktop, Tablet, Mobile and Preview.

Power BI: Secure URL and App owns data

The bi.powerbi widget provides two modes:

• Secure URL uses a reportEmbed link and the viewer's Microsoft session. The sign-in page is expected when the viewer is not already authenticated.
• App owns data uses a project Power BI binding. Sybot obtains a short-lived token on the server; credentials and tokens are never stored in the widget.

For App owns data, a Super Admin first creates the secret in the Control Center's Credential Vault tab. The project owner then opens Manage profiles and reports in the Portal Editor and creates a profile, a binding and at least the Authoring endpoint. The selectors load workspaces and reports available to that profile. Run Diagnostics before Preview.

Each Project can use multiple profiles, including different Power BI tenants or users, and select a profile for each endpoint. Microsoft public cloud, US Government GCC and Power BI China are available. The Vault supports installation or Project scope, expiration, rotation, disabling and permanent revocation. RLS is configured with a Sybot identity, a static value and roles; advanced SDK settings remain optional.

Property	Purpose
embedMode	secure_url or app_owns_data.
embedUrl	reportEmbed URL, only for Secure URL.
reportBindingKey	Project logical binding, only for App owns data.
variantKey	Endpoint variant, normally default.
pageName	Optional initial page.
showFilters	Shows or hides the filter pane.
showPageNavigation	Shows or hides page navigation.

A binding can resolve different reports and identities for Authoring, Development, Staging, Production or a specific target. Rotating a Vault secret does not require changing the widget. The embed token is refreshed automatically before expiry.

Before deployment, every App owns data binding and variant in the release must have a diagnosed endpoint for the target or its environment fallback. If it is missing, preflight blocks deployment and identifies the configuration to fix; Secure URL does not require this check.