Référence des widgets des Portails

Cette page décrit les widgets inclus dans le catalogue initial. Les propriétés se modifient dans l’Inspector en tant qu’objet JSON ; le titre, la géométrie et le style commun disposent également de contrôles visuels.

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.

Carte (content.card)

Combine title, text, image et lien interne. Dans les grilles, utilisez des dimensions uniformes ; .portal-card__media permet de régler le ratio d’aspect et object-fit.

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 les enregistre dans un Working Dataset associé. Le binding doit autoriser l’ajout d’enregistrements ; la validation est répétée sur le serveur et le navigateur n’accède jamais directement au stockage. Après un enregistrement réussi, les tableaux et graphiques liés sont actualisés sans recharger la page.

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.

Export de données (data.export)

Propose CSV et XLSX uniquement si la Data Resource autorise l’export. Le fichier généré est temporaire, respecte les droits du lecteur 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.

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;
}

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.