Portal Editor and Widgets

The Portal Editor combines a navigable file repository with a visual composer. Both modes operate on the same draft: visual updates refresh the sources, and parts managed directly in code are preserved.

On startup, the Editor opens the first available page in Visual mode. If the Portal has no pages, it opens portal.json in Code mode instead.

The Editor interface immediately follows the light or dark theme selected in Sybot. Toolbar, panels, Inspector, and dialogs change palette without reloading the page; the Portal canvas and widgets keep the theme and styles defined for published content.

The Code and Visual selectors sit between the Portal name and the save status. Widget Guide precedes Export in the action bar. On narrow viewports the row remains single: labels progressively disappear from right to left, leaving icons with tooltips and accessible names. The drag and resize helper remains visible in the Canvas toolbar without the previous keyboard shortcut summary.

On the left, the Activity Bar opens Add Widget, Pages, Images, Explorer, Diagnostics and Problems, and Portal Properties one at a time. The properties icon sits at the bottom of the bar. Only one panel is visible; selecting the active icon again closes it. In Visual mode, the Inspector remains fixed on the right. During the session, the Editor remembers the open panel and the selected width of the left column.

Add Widget initially shows categories with their item count and a chevron. Select a category to expand its cards; Business Intelligence separately contains Power BI Report and Qlik Dashboard. Search widgets filters names, categories and technical keys in real time and automatically opens groups containing results.

The Pages panel keeps Add Page at the top and lists every Portal page below it. The current page is highlighted; long names are truncated without breaking the layout, while the complete name remains available on hover. Selecting a page opens it directly in the Canvas. Switching to Widgets, Explorer, or Problems does not change the current page. Add Page asks for a name, creates and asynchronously saves the initial document under pages/, and then opens it in the Canvas.

The Images panel contains the shared catalog link, upload from the computer, and the images already stored in the Portal. Each image shows a preview and file name and can be deleted after confirmation; the grid updates without reloading the Editor.

On the Canvas, each widget is represented by a compact card showing its icon, name, type, grid size, and visibility on desktop, tablet, and smartphone. The card preserves the configured colours, background, and typography, while long text is truncated without covering the drag and resize controls. Use Preview to test the widget's complete content and behaviour.

Duplicate widget creates an independent instance on the same page or another page. For a custom widget, it also copies every component file and unsaved source changes under a new component key. Configuration, bindings, style and external associations are preserved; editing or deleting the copy does not affect the original. The copy stays local, keeps its sandboxed/trusted mode and does not inherit the link to the signed catalog version; sharing requires explicitly saving it to the catalog. The component and page are saved together: if an error occurs, duplication is rolled back. Existing instances that share a component continue to share it.

Each local copy can be saved to the catalog as a separate package starting at v1, in either order. The button disappears only for the component already linked; it remains available for unlinked copies. When names match, the server adds a suffix and updates the name and manifest in the editor, preserving auxiliary files. The custom widget catalog shows only packages explicitly saved to the catalog. Local components and copies not yet saved never generate catalog cards; they remain available on the Canvas and in the Explorer.

To delete a widget, select Delete widget in the Inspector, or press Delete or Backspace outside an input field. After confirmation, only the selected instance is removed from that page. While other instances reference the component, including on other pages, its sources and catalog association remain unchanged. Removing the last instance of a component saved to the catalog atomically removes its local sources and detaches the package: the widget remains under Unused objects, ready to be inserted again. The explicit Explorer command instead deletes the entire component and all page references.

Code Mode

Code Mode displays:

• Explorer, to search, create, rename, and organise files;
• Upload image, to add PNG, JPEG, GIF or WebP assets to the repository;
• tabs for open files;
• editors with syntax highlighting for JSON, HTML, CSS and JavaScript;
• save status and current revision number;
• Problems panel with errors and fixable suggestions.

In Explorer, the chevron next to each directory expands or collapses that branch only. Directory state is retained for the editing session, while a search temporarily expands the branches required to show matches.

Changes are saved asynchronously. If the draft has been updated by another session, the editor halts saving and reports a conflict: reload the current version before resuming work.

When you close or leave the Editor, the editing session is released immediately. Another user can then edit the same Portal without waiting for the previous session to expire automatically.

Use Checkpoint to lock an immutable and identifiable revision of the draft. A checkpoint does not publish the Portal.

Opening a file that does not represent a page—for example portal.json, a Data Resource, a CSS file or a component file—automatically switches the editor to Code. The Visual Composer remains associated only with pages and never displays the canvas of a previously opened file. The editor remembers the mode selected for each page during the editing session: if a page was open in Visual mode, it automatically returns to Visual after you inspect a configuration file.

To create a page, select New file and use a JSON path under pages/, for example pages/dashboard.json or pages/orders/detail.json. The file name is free: the editor automatically generates a UUID, title, grid layout and widget list. The Editor adds the route to portal.json and the navigation entry to shell.json automatically. Deleting the page removes both associations without reloading the interface.

Visual Mode

Visual Mode provides palettes, canvas and Inspector. Selecting a widget always opens Properties, and the Inspector organises its configuration into three tabs:

• Properties contains title, data, sources, bindings, and functional options;
• Style contains visual controls, Style JSON, and scoped CSS;
• Advanced contains position, width, height, and Properties JSON.

Switching tabs does not deselect the widget or lose current values, including during asynchronous saving. The same tabs are available for standard and custom widgets, User Views, BPMN, Power BI, and Qlik. You can also navigate the tabs with Left/Right Arrow, Home, and End.

Guided properties are applied and saved when the control changes; a toaster confirms the result. Save advanced changes is instead used for JSON and CSS panels, where it is normal to have temporarily invalid content while typing. The status in the header distinguishes between in-progress changes, saving and saved source.

Inspector fields depend on the widget: routes, images, User Views, individual widgets of a View, Workflows, parameters and Data Resources are selected from Project-filtered menus. Route selectors show only pages in the Portal's active navigation and update without opening the source files manually. Colors can be chosen with the picker or entered as a CSS value or design token.

Viewport presets declare the simulated size. The zoom toolbar provides −, +, reset to 100%, and Fit. Fit uses both the available width and height, uniformly scaling down the canvas while preserving Preview proportions. Click the percentage to reset to 100%; double-click it to enter a value from 5% to 200%. At a custom zoom level, use the scrollbars to explore areas outside the workspace. Zoom affects only the editor display, not saved geometry or runtime rendering. Each widget also shows its width × height badge in grid cells.

To modify a widget's geometry:

• drag the handle in the top-left corner to move it;
• drag the handle in the bottom-right corner to resize it;
• use Alt + arrow to move it by one cell;
• use Shift + Alt + arrow to modify its width or height by one cell.

To delete a widget, select it and use Delete widget in the Inspector. Alternatively, press Delete or Backspace when the cursor is not in a field. The editor always asks for confirmation.

When a region contains properties not managed by the composer, the editor identifies it as code-managed and preserves it during visual updates.

To configure the page rather than a widget, click on a free area of the canvas background. The Page Style Inspector allows setting colour, background, internal spacing and minimum height; Page JSON Style and Page scoped CSS remain available for advanced adjustments.

Portal Properties opens in the left column, leaving the right Inspector available for the selected widget. Its General tab contains the name, trusted-code setting, and Show Header and Show Navigation controls. The two Shell controls are saved immediately and Preview reflects the title and navigation bar. For Owners, Access contains collaborators, permissions, and runtime audience. Switching tabs preserves unsaved values; loading, saving, and diagnostics remain asynchronous without reloading the Editor.

Configure appearance and CSS

Guided Style exposes colour, background, text size, alignment, spacing and border radius. Accepted values use normal CSS syntax, for example #0f172a, 1rem or 8px.

Advanced Configuration allows you to use CSS properties in kebab-case, states, and breakpoints:

{
  "color": "#0f172a",
  "background-color": "#ffffff",
  "padding": "1rem",
  "states": {
    "hover": {"background-color": "#e0f2fe"}
  },
  "breakpoints": {
    "md": {"font-size": "18px"}
  }
}

The Scoped CSS field allows you to intervene on any detail without affecting other widgets. & represents the instance container; .portal-text selects the content of the Text widget:

&:hover { transform: translateY(-2px); }
.portal-text { font-weight: 600; letter-spacing: .02em; }

Select Save advanced changes to register JSON and CSS on the page. The Preview shows the final compiled rendering.

Project Catalogs

The Custom Widgets and Images buttons open a unified catalog. Each item always indicates its origin: Current Portal, another Portal of the same Project, Published User View, or Shared Views Catalog. Objects external to the Project or not accessible to the user are not shown.

In Custom Widgets, use the switch beside search to alternate Card and Table views. The table supports sorting, multi-selection and pages of ten records. Each widget menu can insert the selected version, export its JSON, open a safe static preview or delete it; deletion confirms which Portals use it. Import widget loads a JSON previously exported from another Project. Saving a custom widget always creates a new incremental version and never overwrites an existing one.

The palette also includes widgets from the Published User Views of the Project. You can embed both standard widgets—including charts, KPIs, tables, and maps—and custom catalog widgets. The selection registers the View, published version, and widget key; a release therefore remains stable even if the View is subsequently modified.

When using an image or component from another object, the editor creates a copy in the Portal repository. This materialisation makes checkpoints, builds, and releases reproducible; the catalog card retains the origin indication to avoid ambiguity.

Available Widgets

The managed catalog includes:

• Text, Hero, Card, Image, and Divider;
• Link, Menu, Navigation Tabs, and Breadcrumbs;
• Section, Collapsible Panel, Sidebar, and Drawer;
• Read-only Form, Data Form, Data Table, Bar Chart and Data Export;
• Complete User View and single User View widget;
• Workflow Action;
• Power BI Report and Qlik Dashboard;
• Custom sandbox widget.

Each widget supports style properties, visual states, and breakpoints. Scoped CSS allows you to customise hover, focus, active, and disabled states without modifying other page components.

The Widget Guide button opens the integrated reference for the selected widget: it lists properties, types, default values, capabilities, and style examples. The full reference is also available at Reference dei widget.

Load and Use an Image

1. If the file is local, use Upload Image in the Explorer and choose a PNG, JPEG, GIF, or WebP.
2. To reuse an asset, open Images and filter the catalog by name or origin.
3. Select Use Image or Copy and Use: the editor proposes a path under assets/ and populates the selected widget.
4. Always fill in alt, then choose the fit (contain, cover, fill, none, scale-down) and position.
5. Verify the result in Preview.

The height set for the widget in the grid also determines the space occupied by the image. By default, the image is contained without distortion; scoped CSS can modify object-fit via the selector .portal-image.

Data Manager and Visual Queries

Data opens the Portal Data Manager. You do not need to know the structure of the data/ folder in advance:

1. Create a Data Resource and assign a key and name;
2. choose Environment Connection or Semantic Model;
3. for Environment, load the catalog, then select schema, table, dimensions, measures, aggregations and aliases;
4. for a Semantic Model, select the published version of the Project, then governed fields and measures;
5. set maximum rows, timeout and parameters only when necessary;
6. save: the file data/<chiave>.resource.json is created and associated with the selected widget.

The Advanced custom SQL mode is reserved for read-only queries that cannot be expressed by the configurator. It also requires declaring the output columns. Complex joins, filters or sorts can be refined by opening the generated JSON in Code mode.

The browser does not receive credentials and does not query the source directly. Queries, parameters, limits and permissions are rechecked at runtime.

Sybot Data and integrations

Data resources can use authorised sources and Semantic Models. Queries are read-only and re-check user permissions at execution time.

In the Data Form widget, a Project Workflow is required. Each parameter can use a form field, the Workflow default or a non-sensitive fixed value. Value list fields disable default, minimum and maximum and can only be mapped to Workflow parameters of the same type. The editor imports labels and values from the Workflow and renders a dropdown in the Portal. Fixed values are not available for these parameters: the selected option is validated and passed directly to the Workflow.

In the User View widget, select a published view of the Portal Project from the dropdown. The selection automatically registers both the view and the pinned published version.

In the Workflow Action widget, select an executable Workflow of the Project. For each parameter, indicate whether to use the default value, request the value from the user or save a fixed value. Sensitive parameters can only be requested at runtime; Workflows with unsupported file parameters are not selectable. In Preview, only the configuration check is performed.

Write a custom widget

By adding Custom sandbox widget, the editor creates an explicit folder:

components/<chiave>/
├── component.json
├── template.html
├── styles.css
└── index.js

Open component code switches to Code and opens all four files. template.html contains the markup, styles.css the isolated style, index.js exports mount(sdk) and component.json declares files and capabilities. The code can modify the DOM of its own iframe, react to events and use PortalWidgetSDK for data, internal navigation and authorised Workflows. It cannot access the parent document, session, other widgets, cookies or direct network.

In template.html, styles.css and index.js, the editor offers contextual completion while typing; it can also be opened with Ctrl+Space or Cmd+Space. After sdk., only the methods allowed by the current component.json capabilities are shown. The gutter reports JavaScript syntax errors, undefined identifiers, unbalanced HTML tags and invalid CSS properties without interrupting autosave.

Widget guide → Custom sandbox widget → Sandbox SDK documents the signature, parameters, return value, required capability and example for every method, including query, emit, navigate, Workflow operations, invalidateData, setContext, getContext and onDataInvalidated.

After a mutation, sdk.invalidateData() notifies the changed Data Resources. Connected Tables and Charts update in the background without reloading the page, while sdk.onDataInvalidated() lets a Custom Widget query again. sdk.setContext() updates the shared context and notifies all consumers; sdk.getContext() returns a local copy.

Semantic Model Data Resources are also updated when a mutation originates from a direct resource with a different key.

To enable Workflow execution, select the widget and turn on Allow the widget to start Workflows in the Inspector. The editor updates the manifest automatically: no page binding or manual JSON editing is required. sdk.runWorkflow(nameOrId, parameters) and sdk.startWorkflow(nameOrId, parameters) can target an executable Workflow in the current Project; permissions are checked again at runtime.

Concurrent data requests from different widgets remain independent and have a time limit. If the widget code does not handle an error during startup, the Portal still ends the loading state and displays a message inside the widget.

Power BI and Qlik

Power BI Report supports Secure URL with the reader's Microsoft session and App owns data with a Project-governed profile and binding. Qlik Dashboard supports Secure URL and OAuth impersonation with qlik-embed. In both integrations, secrets remain in administrative configuration and the widget stores only an URL or logical binding. Run Diagnostics before Preview and test provider permissions, licensing and policies on the published domain.

See Governed integrations for the complete procedure.

Validate and test the draft

1. Save the file or apply properties from the composer.
2. Select Validate.
3. Correct the items listed in the Issues panel.
4. Select Build to verify the draft construction.
5. Select Preview and test layout, data and interactions.

Preview is separate from the published version. Errors show a usable message and, when available, an identifier to communicate to support.

For access and publication cycle, consult Pubblicazione e accessi.