Référence des widgets des Portails

Cette page décrit les widgets inclus dans le catalogue initial. Les widgets core disposent de contrôles visuels et, le cas échéant, de propriétés JSON avancées ; les types natifs des Vues Utilisateur se configurent entièrement avec des contrôles guidés.

Propriétés communes

Propriété	Type	Usage
title	chaîne	Titre optionnel du widget.
hidden	booléen	Cache le widget lorsqu’il est défini sur true.
placement.x, placement.y	entier	Position dans la grille, à partir de 1.
placement.w, placement.h	entier	Largeur et hauteur en cellules.
style	objet	Propriétés CSS, états et breakpoint de l’instance.
style.rawCss	chaîne	Règles CSS avancées et scope.

Dans l’Inspector, le champ Titre et la propriété JSON title sont synchronisés dans les deux sens. Une chaîne saisie dans l’un des deux est également reportée dans l’autre. Pour supprimer l’en-tête, supprimez title du JSON ou videz Titre ; le contrôleur guidé enregistre automatiquement la modification.

Les contrôles guidés sont enregistrés automatiquement et affichent un toast de confirmation. Pour Propriétés JSON, Style JSON et CSS scope, utilisez plutôt Enregistrer les modifications avancées.

Section (layout.section)

Regroupe des contenus liés. title contrôle l’en-tête visible. Il est également utile comme structure de destination pour des composants personnalisés.

Texte (content.text)

La propriété text contient le texte brut ; les sauts de ligne sont conservés.

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

Pour modifier uniquement le contenu, utilisez .portal-text dans le CSS scope.

Hero (content.hero)

Bloc d’ouverture avec eyebrow, title, subtitle, image (assetPath) et bouton facultatif (buttonLabel, routeId). routeId n’accepte qu’un seul chemin interne. Utilisez un seul Hero principal par page et remplissez imageAlt lorsqu’une image est présente. Disposition de l’image permet de l’utiliser comme arrière-plan ou de la placer en haut, au centre ou en bas sans la déformer.

Carte (content.card)

Combine title, text, image et lien interne. Dans les grilles, utilisez des dimensions uniformes ; Disposition de l’image permet de l’utiliser comme arrière-plan de la carte ou de la placer en haut, au centre ou en bas en conservant ses proportions.

Séparateur (content.divider)

orientation peut être horizontal ou vertical ; title est une étiquette facultative. Un séparateur vertical nécessite une hauteur de grille adéquate.

Lien (navigation.link)

• label : libellé du bouton ;
• routeId : identifiant d’un chemin interne déclaré dans portal.json.

Le widget n’ouvre pas d’URL externes.

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

Menu (navigation.menu)

items est un tableau de {label, routeId} sélectionnés parmi les chemins existants. orientation peut être horizontal ou vertical ; collapseOnMobile active le mode compact sur les petits écrans.

Onglets de navigation (navigation.tabs)

Affiche des chemins liés sous forme d’onglets. items conserve l’ordre, tandis que stretch répartit les onglets sur la largeur disponible. Sur mobile, les onglets défilent horizontalement.

Fil d’ariane (navigation.breadcrumb)

items décrit le chemin hiérarchique ; le dernier élément peut ne pas avoir routeId. separator accepte un texte court. Le fil d’ariane ne remplace pas le menu principal.

Image (media.image)

• assetPath : chemin de l’image dans le référentiel ;
• alt : description alternative accessible.

Chargez d’abord le fichier depuis l’Explorer puis utilisez le même chemin :

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

Les formats PNG, JPEG, GIF et WebP sont chargables jusqu’à la limite indiquée par l’éditeur. La hauteur placement.h dimensionne également l’image, qui utilise tout l’espace disponible sans se déformer. Pour modifier le recadrage, utilisez par exemple .portal-image { object-fit: cover; } dans le CSS scope.

Formulaire en lecture seule (form.readonly)

fields est un tableau d’objets avec key, label et value :

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

Panneau pliable (layout.collapsible)

title reste toujours visible, content contient le texte et openByDefault choisit l'état initial. Ne cachez pas dans un panneau fermé les erreurs ou les confirmations obligatoires.

Barre latérale (layout.sidebar)

Zone latérale confinée dans le widget. side est left ou right ; collapsible et collapsedByDefault régissent le contrôle compact. Pour une navigation complète, il est préférable d'utiliser un Menu vertical.

tiroir (layout.drawer)

Panneau superposé ouvert via buttonLabel. side sélectionne le côté et closeOnScrim active la fermeture en arrière-plan. Le runtime gère la touche Échap et la restitution du focus ; n'utilisez pas le Drawer pour des messages bloquants.

Tableau de données (data.table)

• columns: liste ordonnée des clés à afficher;
• bindings.data.resourceKey: Ressource de données déclarée dans le dossier data.

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

La Data Resource peut interroger des objets autorisés, des sources de données ou des modèles sémantiques. Le navigateur n'accède pas directement à la source.

La commande Données crée et modifie la ressource avec une sélection visuelle de la connexion, du schéma, de la table, des dimensions, des mesures et des agrégations, ou du Modèle Sémantique publié, des champs et des mesures. Ouvrir JSON permet les configurations avancées après le premier enregistrement.

Formulaire de données (form.write)

Collecte des champs typés et démarre un Workflow autorisé. Définir les champs ouvre une boîte de dialogue dédiée à la clé, au libellé, au type, à la valeur par défaut, au caractère obligatoire, au minimum et au maximum ; au moins un champ est requis et les limites ne sont actives que pour les nombres, les dates et les dates/heures. Le Workflow est obligatoire et la liste affiche uniquement les Workflows exécutables du Projet qui reçoivent des données en entrée. Les valeurs par défaut du Workflow et les valeurs fixes doivent être associées à un champ du formulaire ; dans l’Aperçu, elles remplacent sa valeur par défaut et apparaissent directement dans le champ désactivé, sans ligne de texte supplémentaire. Le Formulaire de données ne nécessite aucune Data Resource : cette section n’apparaît donc pas dans l’Inspector et la modification d’une ancienne configuration supprime automatiquement tout binding de données obsolète.

Le type Liste de valeurs utilise les options configurées dans le Workflow et s’affiche sous forme de liste déroulante. Il n’expose ni valeur par défaut, ni minimum, ni maximum, n’accepte pas de valeur fixe et ne peut être associé qu’à un paramètre Workflow du même type. Les libellés et les valeurs restent distincts et le choix est validé avant l’exécution.

Graphique en barres (data.chart)

Affiche des métriques calculées sur le serveur sous forme de barres horizontales accessibles. series indique la clé, le libellé et la couleur facultative de chaque métrique ; le binding doit viser une Data Resource agrégée.

Téléverser un fichier (form.upload)

Le lecteur peut déposer un document dans la zone de téléversement ou le choisir sur son appareil. Le widget met à jour son état sans recharger la page, puis affiche le nom, la taille et l’action de suppression. Le bouton Télécharger n’est disponible que s’il est activé dans l’Inspector.

La configuration accepte PDF, PNG, JPG/JPEG, DOCX, TXT, CSV et XLSX, une taille maximale de 1 à 256 Mo et l’option Chiffrer le fichier sur le serveur. Sybot vérifie le contenu réel avant l’enregistrement et refuse les exécutables ou scripts déguisés ainsi que les fichiers incompatibles avec leur extension. Chaque lecteur ne peut télécharger ou supprimer que ses propres fichiers.

Export de données (data.export)

Les cases à cocher de l’Inspector permettent de proposer CSV, XLSX ou les deux ; au moins un format doit rester sélectionné. Aucune commande d’export ne doit être activée dans la Data Resource : les Connexions, les Modèles Sémantiques et les Working Datasets interrogeables sont pris en charge. Le binding du widget, l’accès au Portail et les droits sur la source restent vérifiés. Le fichier généré est temporaire et neutralise les valeurs potentiellement dangereuses pour les tableurs.

Vue Utilisateur (user-view.embed)

• viewId: ID de la Vue Utilisateur;
• versionId: ID de la version publiée à bloquer dans la release.

Les deux valeurs sont obligatoires. En mode Visuel, la tendina affiche uniquement les Vues Utilisateur publiées appartenant au Projet du Portail et remplit automatiquement les deux ID. Le pin de version empêche une modification ultérieure de la Vue de modifier une release Portail déjà approuvée.

Dans l'Aperçu et dans le Portail publié, la Vue est affichée directement dans le widget, sans nécessiter un nouvel accès. Si la session ou les autorisations ne sont plus valides, le widget affiche un diagnostic à la place de la Vue.

Dans le Portail, l'en-tête étendu de la Vue n'occupe pas d'espace : la mise à jour, les filtres et l'affichage sont regroupés dans une barre flottante à icônes uniquement.

Widget Vue Utilisateur (user-view.widget)

Incorporez un seul widget standard ou personnalisé d'une Vue publiée. La palette et l'Inspector affichent uniquement les widgets des Vues accessibles dans le Projet et enregistrent viewId, versionId et widgetKey. Les graphiques, les KPI, les tableaux, les cartes et les widgets provenant du catalogue personnalisé des Vues sont également pris en charge.

Le runtime charge uniquement la partie de la Vue et la source de données nécessaires au widget sélectionné ; il n'est pas possible de modifier widgetKey pour accéder à une source différente.

Types natifs partagés avec les Vues Utilisateur

Le Portail peut créer de nouvelles instances de tous les types disponibles dans l’éditeur des Vues Utilisateur. La palette présente le type, et non les instances déjà configurées dans chaque Vue. Les nouvelles instances appartiennent au Portail et utilisent les propriétés, l’aide et le renderer partagés.

Les familles disponibles comprennent les graphiques, cartes, KPI, détails d’enregistrement, contenus, mises en page, contrôles de navigation et de filtrage, actions Workflow, diagnostics et Table de données. Les types de données nécessitent une Data Resource du Portail ; les types qui démarrent un Workflow nécessitent le binding correspondant.

L’Inspector regroupe les propriétés en sections et propose des contrôles visuels pour les colonnes, widgets liés, seuils, intervalles et mappings : aucune modification JSON n’est nécessaire. Les sections conservent leur état ouvert ou fermé pendant l’enregistrement automatique. Les types portant le même nom qu’un widget core du Portail restent distincts ; l’entrée native de la Vue Utilisateur ne remplace ni ne modifie l’implémentation core.

Action Workflow (workflow.action)

• workflowId: Workflow associé;
• buttonLabel: texte du bouton;
• confirmationText: confirmation optionnelle;
• fields: paramètres collectés avant le démarrage;
• bindings.workflow.workflowId: doit correspondre à props.workflowId.

En mode Visuel, la tendina affiche uniquement les workflows exécutables du projet du portail. Pour chaque paramètre, l'inspecteur génère un choix entre une valeur par défaut (default), une demande à l'utilisateur (prompt) et une valeur fixe (literal). Les paramètres sensibles n'admettent pas de valeurs fixes ; les workflows avec des paramètres de fichier ne sont pas sélectionnables.

En Prévisualisation, l'action effectue un dry-run. Dans le Portail actif, le Workflow est lancé uniquement si l'utilisateur, le Portail et la release sont autorisés.

Diagramme BPMN (bpmn.viewer)

• templateId : BPMN appartenant au Projet ;
• versionId : version déployée et pinned.

La liste renseigne les deux valeurs et ne montre que les diagrammes accessibles. La Prévisualisation et le runtime utilisent un viewer read-only et revérifient les droits du lecteur.

Rapport Power BI (bi.powerbi)

Le widget prend en charge Secure URL, avec la session Microsoft du lecteur, et App owns data, avec un profil et une liaison gouvernés par le Projet. Les URL Publish to web et les valeurs contenant des jetons ou des identifiants sont refusées. Consultez Power BI : Secure URL et App owns data pour la configuration complète des deux modes.

Dashboard Qlik (bi.qlik)

• embedMode: secure_url ou oauth_impersonation ;
• embedUrl: URL HTTPS Qlik, uniquement pour Secure URL ;
• bindingKey: liaison logique du Projet, uniquement pour OAuth impersonation ;
• allowFullscreen: active le plein écran.

Le mode gouverné conserve l'App ID et le type de contenu dans la liaison et utilise un jeton court généré par Sybot. Le profil et l'endpoint doivent réussir le Diagnostic et la release conserve la révision de la liaison. Voir Intégrations gouvernées.

Widget custom sandbox (custom.sandbox)

Une composante custom utilise cette structure :

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

component.json déclare les fichiers et les capacités :

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

Le JavaScript peut modifier le DOM interne à son propre iframe. Pour les données et les actions, utilisez PortalWidgetSDK ; les appels réseau directs, l'accès au document parent, les cookies et le stockage de session ne sont pas autorisés.

L'Inspector expose Ouvrir le code de la composante, qui passe automatiquement à Code et ouvre le manifeste, les modèles, le CSS et le JavaScript. Le catalogue du Projet peut également copier une composante d'un autre Portail ; la composante devient une copie versionnable dans le dépôt actuel.

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

Pour les mises à jour en direct, enregistrez sdk.onDataInvalidated(listener) et relancez la requête lorsque l’événement inclut la ressource utilisée par le widget. Après une mutation, appelez sdk.invalidateData(resourceKey). setContext() et getContext() gèrent le contexte partagé sans accéder au document parent.

Activez Autoriser le widget à démarrer des Workflows dans l’Inspector pour gérer la capability workflow:start sans modifier le JSON. Un widget custom n’a pas besoin de bindings.workflow. Utilisez sdk.runWorkflow(nomOuId, paramètres) ou l’alias sdk.startWorkflow() pour démarrer tout Workflow exécutable du Projet actuel ; le périmètre du Projet et les autorisations de l’utilisateur restent vérifiés à l’exécution.

Style, états et breakpoint

Les propriétés CSS utilisent des noms kebab-case. Les sections states et breakpoints appliquent des variations locales :

{
  "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"}
  }
}

Les états pris en charge sont hover, focus, active et disabled ; les breakpoint sont sm, md, lg et xl. Vérifiez toujours Desktop, Tablet, Mobile et Preview.

Power BI : Secure URL et App owns data

Le widget bi.powerbi propose deux modes :

• Secure URL utilise un lien reportEmbed et la session Microsoft du lecteur. La page de connexion est normale si le lecteur n'est pas déjà authentifié.
• App owns data utilise une liaison Power BI du Projet. Sybot obtient un jeton temporaire sur le serveur ; les identifiants et jetons ne sont jamais stockés dans le widget.

Pour App owns data, un Super Admin crée d'abord le secret dans l'onglet Credential Vault du Control Center. Le propriétaire du Projet ouvre ensuite Gérer les profils et les rapports dans le Portal Editor et crée un profil, une liaison et au moins le point de terminaison Authoring. Les listes chargent les espaces de travail et rapports accessibles au profil. Lancez le Diagnostic avant la Prévisualisation.

Chaque Projet peut utiliser plusieurs profils, y compris pour des tenants ou utilisateurs Power BI différents, et choisir le profil de chaque point de terminaison. Microsoft public cloud, US Government GCC et Power BI China sont disponibles. Le Vault prend en charge la portée installation ou Projet, l’expiration, la rotation, la désactivation et la révocation définitive. La RLS se configure avec une identité Sybot, une valeur statique et des rôles ; les paramètres SDK avancés restent facultatifs.

Propriété	Utilisation
embedMode	secure_url ou app_owns_data.
embedUrl	URL reportEmbed, uniquement pour Secure URL.
reportBindingKey	Liaison logique du Projet, uniquement pour App owns data.
variantKey	Variante du point de terminaison, normalement default.
pageName	Page initiale facultative.
showFilters	Affiche ou masque le volet des filtres.
showPageNavigation	Affiche ou masque la navigation des pages.

Une liaison peut résoudre des rapports et identités différents pour Authoring, Development, Staging, Production ou une cible spécifique. La rotation d'un secret du Vault ne nécessite pas de modifier le widget. Le jeton d'intégration est renouvelé automatiquement avant son expiration.

Avant le déploiement, chaque liaison et variante App owns data de la release doit disposer d’un point de terminaison diagnostiqué pour la cible ou le fallback de son environnement. S’il manque, le contrôle préalable bloque le déploiement et indique la configuration à corriger ; Secure URL ne nécessite pas ce contrôle.