Skip to main content

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.

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.

Explorer and Problems can be collapsed using the button in their headers. In Explorer, the chevron next to each directory also 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.

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. To make it navigable, add a route in portal.json that points to the full path of the page.

Visual Mode​

Visual Mode provides palettes, canvas and Inspector. You can add a widget, select it and configure:

  • title and properties;
  • position, width and height in the grid;
  • styles for the individual instance;
  • scoped CSS;
  • Desktop, Tablet and Mobile rendering.

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. 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.

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.

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 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.

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.