Publier une application en tant que portail
Objectif
Prendre une application que vous avez déjà dessinée et lui donner sa propre adresse web, pour que des personnes extérieures à votre organisation — clients, candidats, grand public — puissent l’ouvrir sans jamais se connecter à la plateforme.
Avant de commencer
Il vous faut deux choses, et le portail ne s’enregistre pas sans la première :
- Une application Studio. Un portail publie un dessin ; il n’en contient pas. Voir Créer une application Studio.
- Une API personnalisée pour tout ce que lit le portail. Un portail ne lit jamais une table directement — voir Ce qu’un portail peut lire ci-dessous pour savoir pourquoi. Si votre portail n’affiche que du texte et des images, vous pouvez ignorer ce point.
Étapes
- Ouvrez votre solution et choisissez Portails.
- Appuyez sur Nouveau.
- Donnez-lui un nom. C’est ainsi que vos collègues et vous l’appellerez ; ce n’est pas ce que voient les visiteurs, car tout ce qu’un visiteur voit est dessiné.
- Choisissez l’application à publier dans la liste. Seules les applications de cet environnement y figurent.
- Saisissez une adresse web. Uniquement la première partie —
acme-support, pas l’adresse entière. Le reste de l’adresse appartient à votre déploiement Parsware, et l’indication sous la zone montre ce que sera l’adresse finale. - Choisissez qui peut l’ouvrir. Tout le monde signifie que l’adresse ouvre directement votre application ; Les personnes qui se connectent place un formulaire de connexion devant — voir Demander aux visiteurs de se connecter.
- Cochez ce qu’il peut lire — les API personnalisées que ce portail a le droit d’appeler.
- Choisissez en tant que quoi agissent les visiteurs — les rôles de sécurité que détient chaque visiteur de ce portail. Voir Les tables qu’un portail peut toucher.
- Laissez Publié décoché tant que vous travaillez encore, et cochez-le lorsque vous voulez que l’adresse commence à répondre.
- Appuyez sur Enregistrer.
Ce qu’un portail peut lire
Un portail lit via les API personnalisées que vous listez, et par rien d’autre. Il ne peut pas lire une table directement, et aucun réglage ne le lui permet.
C’est voulu. Dessiner un écran ne doit jamais devenir un moyen de mettre par accident une table sur l’Internet public. Une API personnalisée est quelque chose que quelqu’un a écrit délibérément : elle décide de ce qu’un inconnu peut voir, dans un script que vous pouvez lire. Une table n’est qu’une table.
Si un écran de votre portail a besoin de données, l’ordre est donc le suivant : définir l’API personnalisée, la cocher dans la liste du portail, et faire lire votre écran à travers elle.
Nommer l’API dans votre écran
Un écran de portail nomme le contrat qu’il lit, plutôt qu’une table :
loadRecords("api:par_articles@1", "articles", { top: 20, orderBy: "par_name" })
api: indique qu’il s’agit d’une API personnalisée ; par_articles est son nom logique ; @1 est
sa version, car deux versions d’une même API sont deux contrats différents. La même forme fonctionne
pour getRecord, createRecord, updateRecord et deleteRecord — c’est la fonction appelée qui
décide de ce que fait la plateforme, et le verbe propre à l’API doit pouvoir y répondre. Un
createRecord dirigé vers une API qui ne fait que lire échouera lorsque l’écran l’exécutera.
Dans la liste des applications, un écran dessiné lit ses tables directement — c’est ce que fait
l’application d’une personne connectée, et c’est pourquoi il peut paginer et filtrer. Sur un portail,
cette porte n’existe pas. Un écran qui nomme api: s’ouvre donc sur le portail et refuse dans le
Shell, en le disant plutôt qu’en affichant une liste vide.
Si vous voulez un même dessin aux deux endroits, il faut deux écrans. C’est le compromis que la plateforme a fait délibérément : votre portail lit via un contrat que vous avez écrit, et ce contrat décide de ce que voit un inconnu.
Votre API doit répondre { "rows": [...], "total": 12 } pour une liste. Si elle répond autre
chose, l’écran affiche une liste vide plutôt qu’une erreur : un portail n’est donc jamais cassé par
une erreur dans une API.
La liste est une autorisation, pas une carte. Cocher une API indique que ce portail peut l’appeler — rien de plus. C ’est votre écran qui décide quand, en la nommant. Une API que vous n’avez pas cochée est refusée même si un écran la demande, et c’est ce qui empêche une erreur de dessin de devenir une porte.
L’écriture exige des visiteurs qui se connectent — ou un défi. Une API qui répond à POST, PATCH, PUT ou DELETE ne peut être appelée que lorsque Qui peut l’ouvrir est réglé sur les personnes qui se connectent, car un portail ouvert n’a personne à qui attribuer une modification. La seule façon de contourner cela fait l’objet de la section suivante.
Demandez à la personne qui gère votre installation Parsware si l’hôte des portails a reçu la portée (scope) qu’exige votre API personnalisée. Chaque API personnalisée en nomme une, et c’est l’hôte des portails qui la détient au nom de vos visiteurs — sans elle, chaque lecture est refusée et la page n’affiche tout simplement rien.
Les tables qu’un portail peut toucher
Les API personnalisées que vous cochez indiquent quels contrats une page peut appeler. Les visiteurs agissent en tant que indique quelles tables ces contrats peuvent ensuite lire et écrire — les mêmes rôles de sécurité que ceux que vous donnez à vos propres collègues, avec les mêmes droits.
Donnez à un portail un rôle qui lui est propre et qui accorde exactement ce dont ses API ont besoin — Lecture et Création sur les Dossiers, par exemple — plutôt qu’un rôle utilisé par votre personnel. Chaque visiteur du portail le détient, connecté ou non.
N’en choisissez aucun et le portail n’atteint rien. Ses listes sont vides et chaque enregistrement répond Cela n’a pas pu être enregistré. C’est le sens le plus sûr, et c’est la première chose à vérifier lorsqu’un portail n’affiche rien sur une page qui semble correcte.
Sur un portail qui connecte ses visiteurs, le rôle n’est pas le dernier mot. Si la table a une règle indiquant à qui appartiennent les lignes — voir Décider des enregistrements qu’un visiteur voit — chaque visiteur est restreint aux lignes de sa propre entreprise après que le rôle l’a laissé entrer.
Le rôle d’administrateur de la plateforme n’est jamais proposé ici. Un visiteur qui le détiendrait détiendrait l’environnement tout entier.
Permettre à n’importe qui de vous envoyer quelque chose
Cochez Permettre à tout le monde de vous envoyer des éléments — cette case n’apparaît que tant que Qui peut l’ouvrir vaut Tout le monde — et un visiteur sans compte peut écrire, à condition que son navigateur consacre d’abord un instant à une énigme qui prouve qu’il n’est pas un script.
C’est ce qui rend possible un formulaire de contact. Sans cela, un portail que tout le monde peut ouvrir peut lire mais pas écrire, ce qui revient à demander à quelqu’un de créer un compte avant de pouvoir vous envoyer un message — et ce n’est pas un formulaire de contact.
Il n’y a rien à dessiner et rien à faire pour le visiteur. Aucune case à cocher, aucun mot déformé à déchiffrer, aucune photo de feux de circulation. La plateforme donne au navigateur un petit calcul ; un ordinateur portable le termine avant que vous ne le remarquiez, un vieux téléphone prend un instant et affiche Vérification que vous êtes une personne… sous le bouton pendant qu’il travaille. Rien n’est collecté sur le visiteur, et rien sur la page ne provient du serveur d’une autre entreprise.
Ce que cela arrête et ce que cela n’arrête pas. Cela rend les envois en masse coûteux : un script qui pouvait envoyer mille formulaires à l’heure paie désormais un vrai travail pour chacun, et en pratique il en envoie quarante. Cela n’arrête pas quelqu’un de déterminé qui est prêt à faire tourner de vrais navigateurs — et aucune case de ce genre ne l’arrête nulle part, quel que soit son nom. Considérez-la comme un filtre anti-spam qui a du mordant plutôt que comme un verrou.
Trois choses que cela ne change pas :
- Ce qui peut être appelé. Uniquement les API personnalisées que vous avez cochées plus haut, exactement comme avant.
- Ce qui peut être écrit. Le schéma de requête propre à l’API décide toujours des champs qu’un visiteur peut renseigner. Un contrat qui accepte un sujet et un message accepte un sujet et un message.
- L’identité de quiconque. Personne ne s’est connecté, donc rien n’est vérifié. Si votre API stocke une adresse e-mail saisie par le visiteur, c’est une adresse que quelqu’un a saisie. Là où cela compte, demandez plutôt aux visiteurs de se connecter.
portal-contact-form dans samples/solutions/ fait exactement cela : un portail ouvert, une
écriture, un fichier joint, et une page du site lui-même qui explique ce qu’il faut regarder.
L’ouvrir
Dès qu’un portail a une adresse, la liste l’affiche sous forme de lien, et Ouvrir le portail dans la barre de commandes l’ouvre dans un nouvel onglet. Ouvrez le portail pour le modifier : la même adresse apparaît sous la zone Adresse web, avec deux petits boutons à côté — l’un ouvre le portail, quand vous voulez le regarder, l’autre copie l’adresse, quand vous vous apprêtez à l’envoyer à quelqu’un. Aucun des deux n’affiche de texte — l’adresse est longue, et des libellés à côté repousseraient le second bouton sur sa propre ligne — survolez donc l’un ou l’autre pour savoir lequel c’est.
L’adresse n’apparaît qu’une fois enregistrée. Tant que vous saisissez encore un libellé, l’indication sous la zone montre à quoi ressemblera l’adresse finale ; un lien construit à partir de quelque chose que vous n’avez pas encore enregistré pointerait vers un portail qui n’existe pas.
Si votre installation ne sert aucun portail, il n’y a aucune adresse à ouvrir et l’indication reste là où serait le lien. Adressez-vous à la personne qui gère votre installation Parsware.
Cette phrase ne concerne jamais votre portail — c’est la plateforme qui dit qu’elle n’a pas pu répondre, et votre dessin, votre adresse et l’interrupteur Publié n’y sont pour rien. C’est l’une de deux choses, qui relèvent toutes deux de la personne qui gère votre installation : les services sont arrêtés, ou l’hôte des portails ne parvient pas à obtenir d’identifiants auprès de Parsware. Une mauvaise adresse affiche tout autre chose (« Rien n’est publié ici ») : vous pouvez donc les distinguer à partir de la page elle-même.
Ce que voit un visiteur
Deux aspects d’une page de portail appartiennent à la plateforme plutôt qu’à vous, et il vaut mieux les connaître avant qu’on vous pose la question.
Un portail s’ouvre en mode sombre. Vos propres applications dans Parsware s’ouvrent en mode clair, car c’est là que vous passez votre journée de travail ; un portail est l’endroit où un inconnu arrive depuis un lien dans un message, généralement sur un téléphone, et le sombre est une première impression plus agréable. Un petit bouton clair/sombre flotte dans le coin supérieur de chaque page de portail — à droite en anglais, à gauche en persan et en arabe — et la première fois qu’un visiteur appuie dessus, ce choix devient le sien : le navigateur s’en souvient, et le sombre par défaut ne contredit jamais quelqu’un qui a déjà répondu.
Vous pouvez toujours dessiner votre propre interrupteur. setTheme("light") et setTheme("dark")
sont disponibles dans n’importe quel gestionnaire d’un écran dessiné, et un bouton que vous dessinez
agit sur le même réglage que celui du coin. Celui du coin est le minimum garanti, pour qu’un portail
soit lisible avant que quiconque ne pense à en dessiner un.
Et le dessin se réorganise. Un écran est dessiné à une certaine taille, mais il n’est pas affiché à cette taille : les blocs qui couvrent la page gardent leur écart avec chaque marge et laissent le milieu s’ajuster, et les éléments dessinés côte à côte gardent leur part de la largeur. Un portail s’adapte donc à la fenêtre dans laquelle il est ouvert, quelle que soit sa largeur, et rien ne sort de la page.
Ce que la réorganisation ne peut pas faire, c’est réagencer. Deux colonnes dessinées côte à côte restent côte à côte — sur un téléphone, ce sont deux colonnes étroites, pas une colonne avec la seconde sous la première. Si un portail compte sur les téléphones, dessinez un écran pour téléphone : c’est à cela que servent les trois exemples A portal on a desktop / tablet / phone.
À propos de l’adresse
Une adresse répond pour un seul portail, sur toute l’installation. Pas une par environnement — une en tout. Il y a une seule porte d’entrée devant tous les environnements, et elle décide où va une requête en regardant l’adresse.
Cela a une conséquence que vous rencontrerez la première fois que vous promouvrez une solution :
Importez la même solution dans Test ou Production, et l’adresse qu’elle demande répond déjà pour l’environnement dans lequel vous l’avez construite. Le portail arrive donc sans adresse et désactivé, et apparaît comme Adresse requise dans cette liste.
Ce n’est pas une erreur, et rien ne s’est mal passé avec votre solution. Votre portail de développement et votre portail de production allaient toujours avoir besoin d’adresses différentes. Ouvrez le portail dans le nouvel environnement, donnez-lui l’adresse que vous voulez à cet endroit, et cochez Publié.
Un portail peut aussi répondre à une adresse qui appartient à votre propre organisation —
portal.acme.com — que vous ajoutez sous Vos propres domaines et dont vous prouvez ensuite
qu’elle vous appartient. Voir Utiliser votre propre domaine.
L’activer et le désactiver
Publié est la seule case du portail des créateurs dont l’état « activé » signifie n’importe qui au monde qui connaît l’adresse peut voir ceci. Donc :
- Elle est décochée au départ, et le reste jusqu’à ce que vous la cochiez.
- Elle ne peut pas être cochée tant que le portail n’a pas d’adresse — il n’y aurait nulle part où répondre. Un domaine qui vous appartient ne compte comme adresse qu’une fois vérifié, pour la même raison : rien ne répond à une adresse non vérifiée.
- La décocher arrête immédiatement l’adresse. L’application qu’elle publie n’est pas touchée.
Supprimer un portail
Supprimer un portail arrête l’adresse et la libère pour autre chose. Cela ne supprime pas l’application — le dessin reste une application que vos propres collaborateurs peuvent ouvrir dans le Shell, et c’est toute la raison pour laquelle publier est une chose distincte de dessiner.