Éditeur et widgets des Portails

L'Éditeur de Portails combine un répertoire de fichiers navigable avec un composeur visuel. Les deux modes opèrent sur le même brouillon : les modifications visuelles mettent à jour les sources et les parties gérées directement dans le code sont préservées.

Au démarrage, l'Éditeur ouvre la première page disponible en mode Visuel. Si le Portail ne contient aucune page, il ouvre portal.json en mode Code.

L’interface de l’Éditeur suit immédiatement le thème clair ou sombre choisi dans Sybot. La barre d’outils, les panneaux, l’Inspector et les boîtes de dialogue changent de palette sans recharger la page ; le Canvas et les widgets du Portail conservent le thème et les styles définis pour le contenu publié.

Les sélecteurs Code et Visuel se trouvent entre le nom du Portail et l’état de sauvegarde. Guide des widgets précède Exporter dans la barre d’actions. Sur les écrans étroits, la ligne reste unique : les libellés disparaissent progressivement de droite à gauche, en laissant les icônes avec infobulles et noms accessibles. L’aide au glisser et au redimensionnement reste visible dans la barre du Canvas sans l’ancien résumé des raccourcis clavier.

Sur le côté gauche, la barre d’activités ouvre alternativement Ajouter un Widget, Pages, Images, Explorateur, Diagnostic et Problèmes et Propriétés du Portail. L’icône des propriétés se trouve au bas de la barre. Un seul panneau est visible à la fois ; sélectionner à nouveau l’icône active le ferme. En mode Visuel, l’Inspector reste fixe à droite. Pendant la session, l’Éditeur mémorise le panneau ouvert et la largeur choisie pour la colonne de gauche.

Ajouter un Widget affiche d’abord les catégories avec le nombre d’éléments et un chevron. Sélectionnez une catégorie pour développer ses cartes ; Business Intelligence contient séparément Rapport Power BI et Tableau de bord Qlik. Rechercher un widget filtre en temps réel les noms, les catégories et les clés techniques et ouvre automatiquement les groupes contenant des résultats.

Le panneau Pages maintient Ajouter une page en haut et affiche toutes les pages du Portail. La page active est mise en évidence ; les noms longs sont tronqués sans casser la mise en page et leur valeur complète reste disponible au survol. Sélectionner une page l’ouvre directement dans le Canvas. Passer à Widgets, Explorateur ou Problèmes ne change pas la page courante. Ajouter une page demande un nom, crée et enregistre de façon asynchrone le document initial sous pages/, puis l’ouvre dans le Canvas.

Le panneau Images regroupe le lien vers le catalogue partagé, le téléversement depuis l’ordinateur et les images déjà présentes dans le Portail. Chaque image affiche un aperçu et son nom et peut être supprimée après confirmation ; la grille se met à jour sans recharger l’Éditeur.

Dans le Canvas, chaque widget est représenté par une carte compacte affichant son icône, son nom, son type, sa taille dans la grille et sa visibilité sur ordinateur, tablette et smartphone. La carte conserve les couleurs, l’arrière-plan et la typographie configurés, tandis que les textes longs sont tronqués sans recouvrir les commandes de déplacement et de redimensionnement. Utilisez Aperçu pour tester le contenu et le comportement complets du widget.

Dupliquer le widget crée une instance indépendante sur la même page ou une autre page. Pour un widget personnalisé, tous les fichiers du composant et les modifications des sources non enregistrées sont aussi copiés avec une nouvelle clé de composant. La configuration, les liaisons, le style et les associations externes sont conservés ; modifier ou supprimer la copie ne touche pas l’original. La copie reste locale, conserve son mode sandboxed/trusted et n’hérite pas du lien vers la version signée du catalogue ; le partage nécessite un enregistrement explicite dans le catalogue. Le composant et la page sont enregistrés ensemble : en cas d’erreur, la duplication est annulée. Les instances existantes qui partagent un composant continuent à le partager.

Chaque copie locale peut être enregistrée dans le catalogue comme un package distinct à partir de v1, dans n’importe quel ordre. Le bouton disparaît uniquement pour le composant déjà lié ; il reste disponible pour les copies non liées. Si les noms sont identiques, le serveur ajoute un suffixe et met à jour le nom et le manifeste dans l’éditeur, en conservant les fichiers auxiliaires. Le catalogue des widgets personnalisés affiche uniquement les packages enregistrés explicitement dans le catalogue. Les composants locaux et les copies non encore enregistrées ne génèrent jamais de cartes dans le catalogue ; ils restent disponibles dans le Canvas et l’Explorateur.

Pour supprimer un widget, sélectionner Supprimer le widget dans l’Inspecteur, ou appuyer sur Suppr ou Retour arrière hors d’un champ. Après confirmation, seule l’instance sélectionnée est retirée de la page. Tant que d’autres instances référencent le composant, y compris sur d’autres pages, ses sources et son association au catalogue restent inchangées. Supprimer la dernière instance d’un composant enregistré dans le catalogue retire ses sources locales et détache le package de manière atomique : le widget reste dans les Objets non utilisés, prêt à être réinséré. La commande explicite de l’Explorateur supprime le composant entier et toutes les références dans les pages.

Mode Code

Le mode Code affiche :

• Explorateur, pour rechercher, créer, renommer et organiser les fichiers ;
• Télécharger une image, pour ajouter au répertoire des assets PNG, JPEG, GIF ou WebP ;
• des onglets pour les fichiers ouverts ;
• un éditeur avec coloration syntaxique pour JSON, HTML, CSS et JavaScript ;
• l'état de sauvegarde et le numéro de révision actuel ;
• un panneau Problèmes avec les erreurs et les indications corrigeables.

Dans l'Explorateur, le chevron placé à côté de chaque répertoire permet aussi de développer ou réduire uniquement cette branche. L'état des répertoires est conservé pendant la session d'édition, tandis qu'une recherche développe temporairement les branches nécessaires pour afficher les résultats.

Les modifications sont sauvegardées de manière asynchrone. Si le brouillon a été mis à jour par une autre session, l'éditeur interrompt la sauvegarde et signale le conflit : recharger la version actuelle avant de reprendre le travail.

Lorsque vous fermez ou quittez l'Éditeur, la session de modification est libérée immédiatement. Un autre utilisateur peut alors modifier le même Portail sans attendre l'expiration automatique de la session précédente.

Utiliser Point de contrôle pour fixer une révision immuable et reconnaissable du brouillon. Un point de contrôle ne publie pas le Portail.

En ouvrant un fichier qui ne représente pas une page — par exemple portal.json, une Data Resource, un CSS ou un fichier de composant — l'éditeur passe automatiquement en Code. Le composeur Visuel reste associé uniquement aux pages et ne montre jamais la toile d'un fichier ouvert précédemment. Le mode choisi pour chaque page est mémorisé pendant la session d'édition : si une page était ouverte en mode Visuel, elle revient automatiquement en mode Visuel après la consultation d'un fichier de configuration.

Pour créer une page, sélectionner Nouveau fichier et utiliser un chemin JSON sous pages/, par exemple pages/dashboard.json ou pages/orders/detail.json. Le nom du fichier est libre : l'éditeur génère automatiquement un UUID, un titre, une mise en page en grille et une liste de widgets. L’Éditeur ajoute la route dans portal.json et l’entrée de navigation dans shell.json automatiquement. La suppression de la page retire les deux associations sans recharger l’interface.

Mode Visuel

Le mode Visuel met à disposition des palettes, une toile et l'Inspecteur. La sélection d’un widget ouvre toujours Propriétés et organise sa configuration en trois onglets :

• Propriétés contient le titre, les données, les sources, les bindings et les options fonctionnelles ;
• Style contient les contrôles visuels, le Style JSON et le CSS scoped ;
• Avancé contient la position, la largeur, la hauteur et les Propriétés JSON.

Changer d’onglet ne désélectionne pas le widget et ne perd pas les valeurs courantes, y compris pendant la sauvegarde asynchrone. Les mêmes onglets sont disponibles pour les widgets standards et personnalisés, les Vues Utilisateur, BPMN, Power BI et Qlik. Les flèches gauche/droite, Début et Fin permettent aussi de naviguer entre les onglets.

Les propriétés guidées sont appliquées et sauvegardées lorsque le contrôle change ; un toaster confirme le résultat. Enregistrer les modifications avancées sert plutôt aux blocs JSON et CSS, où il est normal d'avoir un contenu temporairement non valide pendant la frappe. L'état dans l'en-tête distingue les modifications en cours, la sauvegarde et la source sauvegardée.

Les champs de l'Inspecteur dépendent du widget : les routes, les images, les Vues Utilisateur, les widgets uniques d'une Vue, le Workflow, les paramètres et les Data Resources sont choisis dans des menus filtrés sur le Projet. Les sélecteurs de route affichent uniquement les pages de la navigation active du Portail et se mettent à jour sans ouvrir manuellement les fichiers source. Les couleurs peuvent être choisies avec le sélecteur ou saisies comme valeur CSS ou jeton de conception.

Les préréglages Viewport déclarent la taille simulée. La barre de zoom offre −, +, le retour à 100 % et Adapter. Adapter utilise à la fois la largeur et la hauteur disponibles, réduit uniformément la toile et conserve les proportions de la Prévisualisation. Un clic sur le pourcentage rétablit 100 % ; un double-clic permet de saisir une valeur de 5 % à 200 %. Avec un zoom personnalisé, les barres de défilement donnent accès aux zones hors de l'espace de travail. Le zoom modifie uniquement l'affichage dans l'éditeur, jamais la géométrie enregistrée ni le rendu d'exécution. Chaque widget affiche aussi son badge largeur × hauteur en cellules de grille.

Pour modifier la géométrie d'un widget :

• faire glisser la poignée en haut à gauche pour le déplacer ;
• faire glisser la poignée dans le coin inférieur droit pour le redimensionner ;
• utiliser Alt + flèche pour le déplacer d'une cellule ;
• utiliser Maj + Alt + flèche pour modifier sa largeur ou sa hauteur d'une cellule.

Pour supprimer un widget, le sélectionner et utiliser Supprimer le widget dans l'Inspecteur. Alternativement, appuyer sur Suppr ou Backspace lorsque le curseur n'est pas dans un champ. L'éditeur demande toujours confirmation.

Lorsqu'une région contient des propriétés non gérées par le composeur, l'éditeur la identifie comme gérée par le code et la conserve lors des mises à jour visuelles.

Pour configurer la page plutôt qu'un widget, cliquer sur une zone libre de l'arrière-plan de la toile. L'Inspecteur Style de la page permet de définir la couleur, l'arrière-plan, l'espacement interne et la hauteur minimale ; Style JSON et CSS scoped de la page restent disponibles pour les ajustements avancés.

Propriétés du Portail s’ouvre dans la colonne de gauche et laisse l’Inspector de droite disponible pour le widget sélectionné. L’onglet Général contient le nom, le code trusted et les contrôles Afficher le Header et Afficher la Navigation. Ces deux contrôles de la Shell sont enregistrés immédiatement et l’Aperçu reflète le titre et la barre de navigation. Pour les Owners, Accès contient les collaborateurs, les permissions et l’audience runtime. Le changement d’onglet conserve les valeurs non enregistrées ; le chargement, la sauvegarde et les diagnostics restent asynchrones sans recharger l’Éditeur.

Configurer l'apparence et le CSS

Le Style guidé expose la couleur, l'arrière-plan, la taille du texte, l'alignement, l'espacement et le rayon de bordure. Les valeurs acceptent une syntaxe CSS normale, par exemple #0f172a, 1rem ou 8px.

La Configuration avancée permet d'utiliser des propriétés CSS en kebab-case, des états et des points de rupture :

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

Le champ CSS scoped permet d'intervenir sur n'importe quel détail sans influencer les autres widgets. & représente le conteneur de l'instance ; .portal-text sélectionne le contenu du widget Texte :

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

Sélectionner Sauvegarder les modifications avancées pour enregistrer le JSON et le CSS dans la page. L'Aperçu montre le rendu compilé définitif.

Catalogues du Projet

Les boutons Widget personnalisé et Images ouvrent un catalogue unifié. Chaque élément indique toujours son origine : Portail actuel, autre Portail du même Projet, Vue Utilisateur publiée ou catalogue partagé des Vues. Les objets externes au Projet ou non accessibles à l'utilisateur ne sont pas affichés.

Dans Widget personnalisé, le sélecteur près de la recherche alterne les vues Cartes et Tableau. Le tableau permet le tri, la sélection multiple et une pagination de dix éléments. Le menu de chaque widget permet d'insérer la version choisie, d'exporter son JSON, d'ouvrir un aperçu statique sécurisé ou de le supprimer ; la confirmation indique les Portails qui l'utilisent. Importer le widget charge un JSON exporté depuis un autre Projet. Chaque sauvegarde crée une nouvelle version incrémentale sans écraser les versions existantes.

La palette comprend également les widgets des Vues Utilisateurs publiées du Projet. Il est possible d'intégrer à la fois des widgets standards — y compris des graphiques, des KPI, des tableaux et des cartes — et des widgets du catalogue personnalisé. La sélection enregistre la Vue, la version publiée et la clé du widget ; une version reste donc stable même si la Vue est modifiée ultérieurement.

Lorsqu'un image ou un composant provenant d'un autre objet est utilisé, l'éditeur en crée une copie dans le référentiel du Portail. Cette matérialisation rend les points de contrôle, les builds et les versions reproductibles ; la carte du catalogue conserve l'indication de l'origine pour éviter toute ambiguïté.

Widgets disponibles

Le catalogue géré comprend :

• Texte, Hero, Card, Image et Séparateur ;
• Lien, Menu, Onglets de navigation et Fil d'Ariane ;
• Section, Panneau rétractable, Barre latérale et Tiroir ;
• Formulaire lecture seule, Formulaire de données, Tableau de données, Graphique en barres et Export de données ;
• Vue Utilisateur complète et widget unique de Vue Utilisateur ;
• Action de flux de travail ;
• Rapport Power BI et Tableau de bord Qlik ;
• Widget personnalisé sandbox.

Chaque widget prend en charge des propriétés de style, des états visuels et des points de rupture. Le CSS scoped permet de personnaliser même les états de survol, de focus, actif et désactivé sans modifier les autres composants de la page.

Le bouton Guide du widget ouvre la référence intégrée du widget sélectionné : il liste les propriétés, les types, les valeurs par défaut, les capacités et des exemples de style. La référence complète est également disponible dans Reference dei widget.

Charger et utiliser une image

1. Si le fichier est local, utiliser Télécharger une image dans l'Explorateur et choisir un PNG, JPEG, GIF ou WebP.
2. Pour réutiliser un asset, ouvrir Images et filtrer le catalogue par nom ou origine.
3. Sélectionner Utiliser l'image ou Copier et utiliser : l'éditeur propose un chemin sous assets/ et valorise le widget sélectionné.
4. Toujours remplir alt, puis choisir l'adaptation (contain, cover, fill, none, scale-down) et la position.
5. Vérifier le résultat dans l'Aperçu.

La hauteur définie pour le widget dans la grille détermine également l'espace occupé par l'image. Par défaut, l'image est contenue sans déformation ; le CSS scoped peut modifier object-fit via le sélecteur .portal-image.

Data Manager et requêtes visuelles

Données ouvre le Data Manager du Portail. Il n'est pas nécessaire de connaître à l'avance la structure du dossier data/ :

1. Créer une ressource de données et attribuer une clé et un nom ;
2. Choisir Environnement de connexion ou Modèle sémantique ;
3. Pour l'Environnement, charger le catalogue, puis choisir le schéma, la table, les dimensions, les mesures, les agrégations et les alias ;
4. Pour un Modèle sémantique, choisir la version publiée du Projet, puis les champs et mesures gérés ;
5. Définir les lignes maximales, le délai d'attente et les paramètres uniquement si nécessaire ;
6. Sauvegarder : le fichier data/<chiave>.resource.json est créé et associé au widget sélectionné.

Le mode SQL personnalisé avancé est réservé aux requêtes en lecture seule qui ne sont pas exprimables par le configurateur. Il nécessite également la déclaration des colonnes de sortie. Les jointures, filtres ou tris complexes peuvent être affinés en ouvrant le JSON généré en mode Code.

Le navigateur ne reçoit pas les identifiants et n'interroge pas directement la source. Les requêtes, paramètres, limites et autorisations sont revérifiés à l'exécution.

Données et intégrations Sybot

Les ressources de données peuvent utiliser des sources et des Modèles sémantiques autorisés. Les requêtes sont en lecture seule et respectent à nouveau les autorisations de l'utilisateur au moment de l'exécution.

Dans le widget Formulaire de données, un Workflow du Projet est obligatoire. Chaque paramètre peut utiliser un champ du formulaire, la valeur par défaut du Workflow ou une valeur fixe non sensible. Les champs Liste de valeurs désactivent la valeur par défaut, le minimum et le maximum et ne peuvent être associés qu’à des paramètres Workflow du même type. L’éditeur importe les libellés et les valeurs du Workflow et affiche une liste déroulante dans le Portail. Les valeurs fixes ne sont pas disponibles pour ces paramètres : l’option choisie est validée et transmise directement au Workflow.

Dans le widget Vue utilisateur, choisir dans le menu déroulant une vue publiée du Projet du Portail. La sélection enregistre automatiquement à la fois la vue et la version publiée épinglée.

Dans le widget Action de flux de travail, choisir un flux de travail exécutable du Projet. Pour chaque paramètre, indiquer s'il faut utiliser la valeur par défaut, demander la valeur à l'utilisateur ou enregistrer une valeur fixe. Les paramètres sensibles ne peuvent être demandés qu'à l'exécution ; les flux de travail avec des paramètres de fichier, non pris en charge, ne peuvent pas être sélectionnés. La Prévisualisation n'exécute que la vérification de la configuration.

Écrire un widget personnalisé

En ajoutant Widget personnalisé sandbox, l'éditeur crée un dossier explicite :

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

Ouvrir le code du composant passe en Code et ouvre les quatre fichiers. template.html contient le balisage, styles.css le style isolé, index.js exporte mount(sdk) et component.json déclare les fichiers et les capacités. Le code peut modifier le DOM de son iframe, réagir aux événements et utiliser PortalWidgetSDK pour les données, la navigation interne et les flux de travail autorisés. Il ne peut pas accéder au document parent, à la session, aux autres widgets, aux cookies ou au réseau direct.

Dans template.html, styles.css et index.js, l’éditeur propose une saisie semi-automatique contextuelle pendant la frappe ; elle peut aussi être ouverte avec Ctrl+Espace ou Cmd+Espace. Après sdk., seules les méthodes autorisées par les capacités du component.json actuel sont affichées. La marge signale les erreurs de syntaxe JavaScript, les identifiants non définis, les balises HTML non équilibrées et les propriétés CSS non valides sans interrompre l’enregistrement automatique.

Guide des widgets → Widget sandbox personnalisé → SDK Sandbox documente la signature, les paramètres, la valeur renvoyée, la capacité requise et un exemple pour chaque méthode, notamment query, emit, navigate, les opérations Workflow, invalidateData, setContext, getContext et onDataInvalidated.

Après une mutation, sdk.invalidateData() signale les Data Resources modifiées. Les Tables et Graphiques liés s’actualisent en arrière-plan sans recharger la page, tandis que sdk.onDataInvalidated() permet au Custom Widget de relancer sa requête. sdk.setContext() met à jour le contexte partagé et notifie tous les consommateurs ; sdk.getContext() en renvoie une copie locale.

Les Data Resources basées sur un Modèle Sémantique sont également actualisées lorsqu’une mutation provient d’une ressource directe avec une clé différente.

Pour autoriser l’exécution, sélectionnez le widget et activez Autoriser le widget à démarrer des Workflows dans l’Inspector. L’éditeur met à jour le manifeste automatiquement : aucun binding de page ni modification JSON n’est nécessaire. sdk.runWorkflow(nomOuId, paramètres) et sdk.startWorkflow(nomOuId, paramètres) peuvent appeler un Workflow exécutable du Projet actuel ; les autorisations sont de nouveau vérifiées à l’exécution.

Les requêtes de données simultanées de différents widgets restent indépendantes et disposent d’un délai maximal. Si le code du widget ne gère pas une erreur au démarrage, le Portail termine tout de même le chargement et affiche un message dans le widget.

Power BI et Qlik

Rapport Power BI 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. Tableau de bord Qlik prend en charge Secure URL et OAuth impersonation avec qlik-embed. Dans les deux cas, les secrets restent dans la configuration administrative et le widget ne conserve qu'une URL ou une liaison logique. Lancez le Diagnostic avant la Prévisualisation et testez les droits, licences et règles du fournisseur sur le domaine publié.

Voir Intégrations gouvernées pour la procédure complète.

Valider et prévisualiser l'ébauche

1. Sauvegarder le fichier ou appliquer les propriétés depuis le compositeur.
2. Sélectionner Valider.
3. Corriger les éléments listés dans le panneau Problèmes.
4. Sélectionner Construire pour vérifier la construction de l'ébauche.
5. Sélectionner Prévisualiser et tester la mise en page, les données et les interactions.

La Prévisualisation est séparée de la version publiée. Les erreurs affichent un message utilisable et, lorsqu'il est disponible, un identifiant à communiquer au support.

Pour les accès et le cycle de publication, consulter Pubblicazione e accessi.