Permettre aux visiteurs de joindre un fichier

Objectif

Permettre à une personne sur votre portail de joindre un document — un reçu, une photo, un formulaire signé — à l’enregistrement qu’elle est en train de créer.

Avant de commencer

• Un portail dont Qui peut l’ouvrir est réglé sur Personnes qui se connectent, car joindre un fichier fait partie d’une écriture, et une écriture doit pouvoir être attribuée à quelqu’un. Voir Demander aux visiteurs de se connecter.
• Une table dotée d’une colonne Fichier ou Image.
• La ligne Création déjà présente dans la liste d’autorisation du portail, depuis Permettre aux visiteurs d’enregistrer des modifications. Il n’y a rien à ajouter pour le fichier — il voyage dans le corps de l’écriture.

Étapes

1. Dessinez un sélecteur de fichier sur votre écran et liez sa valeur à un champ d’état de l’écran — state.document.

2. Envoyez-le avec l’enregistrement. Le sélecteur remet à votre écran le fichier, et non son nom : il va donc dans le même objet que tout le reste :

   createRecord("par_claim", {
     par_name: getState("subject"),
     par_document: getState("document")
   }, "saved");

3. Décrivez-le dans le schéma de requête de l’API, sous forme d’un objet à quatre propriétés :

   "par_document": {
     "type": "object",
     "additionalProperties": false,
     "required": ["fileName", "contentType", "contentBase64"],
     "properties": {
       "fileName":      { "type": "string", "maxLength": 260 },
       "contentType":   { "type": "string", "maxLength": 200 },
       "sizeBytes":     { "type": "integer" },
       "contentBase64": { "type": "string", "maxLength": 5600000 }
     }
   }

4. Stockez d’abord l’enregistrement, puis le fichier, car un fichier appartient à un enregistrement et il n’y a rien à quoi le joindre tant que la ligne n’existe pas :

   var file = getInput('par_document');
   
   var id = createRecord('par_claim', {
     par_name: getInput('par_name'),
     par_raised_by_email: portalEmail(),
     par_document_name: isEmpty(file) ? '' : file.fileName
   });
   
   if (!isEmpty(file)) {
     putRecordFile('par_claim', id, 'par_document',
       file.fileName, file.contentType, file.contentBase64);
   }

5. Videz-le après un envoi réussi, pour que le sélecteur se vide avec le reste du formulaire :

   setState("document", null);

Ce qu’est réellement un fichier choisi

Quatre champs, les mêmes que ceux qu’un script récupère avec getRecordFile — un fichier qui part et un fichier qui revient ont donc une seule et même forme :

fileName	son nom sur la machine du visiteur
contentType	son type de média, tel que l’a indiqué le navigateur
sizeBytes	sa taille — ce qu’affiche une légende
contentBase64	les octets, sous forme de texte

Une légende liée à l’ensemble affiche le nom du fichier : text(state.document) indique donc contract.pdf plutôt que quelque chose d’illisible. Pour afficher une image choisie, liez la source d’un img à fileUrl(state.document).

Pourquoi il n’y a pas de ligne « joindre un fichier » dans la liste d’autorisation

La liste d’autorisation d’un portail nomme des opérations sur les tables — lire une liste, en lire un, créer, modifier, supprimer — et un fichier n’en fait pas partie. Il voyage dans le corps de l’écriture : un portail autorisé à créer une réclamation peut placer un document sur la réclamation qu’il crée, et un portail qui ne l’est pas ne le peut pas. Il n’y a rien de plus à accorder, et rien de plus à oublier de retirer.

C’est aussi pourquoi aucun point de terminaison de fichiers n’est exposé sur l’internet public. Les octets vont à votre API personnalisée, votre script décide de l’enregistrement où ils aboutissent, et putRecordFile les stocke selon les autorisations propres à l’enregistrement — il a besoin de Mise à jour sur cette ligne, exactement comme un formulaire à l’intérieur de la plateforme.

Joindre à un enregistrement qui existe déjà

De la même façon, par une modification. Envoyez le fichier dans les valeurs de updateRecord, et faites que l’API personnalisée derrière la ligne Modifier un enregistrement lise l’enregistrement, le mette à jour, puis appelle putRecordFile. Sur une table dotée d’une règle sur les enregistrements qu’un visiteur voit, le fichier respecte aussi la règle : un visiteur ne peut joindre un fichier qu’à un enregistrement que la règle lui donne.

Taille maximale d’un fichier

4 Mo, et le sélecteur l’indique avant tout téléversement.

C’est moins que ce que la plateforme peut stocker — un déploiement doté d’un stockage d’objets accepte des fichiers bien plus volumineux par le point de terminaison de fichiers propre à un enregistrement — et cette différence est délibérée. Ici, le fichier est encodé en texte dans un corps JSON et conservé dans le navigateur du visiteur pendant qu’il finit de remplir le formulaire. Une très grosse pièce jointe sur ce chemin, c’est une très longue chaîne dans le navigateur d’un inconnu, et un corps qu’aucun contrat ne devrait avoir à analyser.

Le même écran à l’intérieur de la plateforme

Rien ne change. Ouvrez la même application dans Parsware et le même gestionnaire écrit directement dans la table, le fichier allant dans la colonne Fichier de l’enregistrement par le point de terminaison propre à la plateforme. Vous dessinez un seul écran, pas deux.

Trois pièges fréquents

• Écrivez l’enregistrement avant le fichier. putRecordFile a besoin d’un identifiant d’enregistrement. Un script qui tente de joindre le fichier en premier n’a rien à quoi le joindre.
• Conservez le nom du fichier dans une colonne de texte à côté. Une liste qui veut afficher « 📎 invoice.pdf » doit lire une simple colonne de texte, et non récupérer chaque fichier pour en connaître le nom.
• Un refus est lu par des inconnus. Si vous refusez une pièce jointe — un type de fichier inadapté, par exemple — rédigez la phrase pour le public : elle apparaît à côté du bouton sur lequel la personne a appuyé.

Vérifier que cela a fonctionné

Joignez un fichier sur le portail, appuyez sur le bouton, puis ouvrez l’enregistrement dans la plateforme. Le document se trouve dans son champ Fichier, avec le nom que vous avez stocké à côté — et le portail n’a jamais vu de point de terminaison d’enregistrement.