Bezoekers een bestand laten bijvoegen

Doel

Laat iemand op je portal een document bijvoegen — een bon, een foto, een ondertekend formulier — bij het record dat hij aanmaakt.

Voordat je begint

• Een portal waarop Wie kan het openen op Mensen die zich aanmelden staat, omdat een bestand bijvoegen deel uitmaakt van een schrijfactie, en een schrijfactie iemand nodig heeft aan wie hij kan worden toegeschreven. Zie Bezoekers vragen zich aan te melden.
• Een tabel met een kolom van het type Bestand of Afbeelding.
• De rij Maken staat al in de toestemmingslijst van de portal, uit Bezoekers wijzigingen laten opslaan. Voor het bestand hoef je niets toe te voegen — het reist mee in de body van de schrijfactie.

Stappen

1. Teken een bestandskiezer op je scherm en koppel de waarde aan een statusveld van het scherm — state.document.

2. Stuur het mee met het record. De kiezer geeft je scherm het bestand, niet de naam ervan, dus het gaat in hetzelfde object als al het andere:

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

3. Beschrijf het in het aanvraagschema van de API, als een object met vier eigenschappen:

   "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. Sla eerst het record op en daarna het bestand, want een bestand hoort bij een record, en zolang de rij niet bestaat, is er niets om het aan te koppelen:

   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. Maak het leeg na een geslaagde verzending, zodat de kiezer samen met de rest van het formulier leeg wordt:

   setState("document", null);

Wat een gekozen bestand eigenlijk is

Vier velden, en het zijn dezelfde vier die een script terugkrijgt van getRecordFile — een bestand dat vertrekt en een bestand dat terugkomt, hebben dus één vorm:

fileName	hoe het heet op de eigen computer van de bezoeker
contentType	het mediatype, zoals de browser het doorgaf
sizeBytes	hoe groot het is — wat een bijschrift vermeldt
contentBase64	de bytes, als tekst

Een bijschrift dat aan het geheel is gekoppeld, toont de naam van het bestand, dus text(state.document) zegt contract.pdf in plaats van iets onleesbaars. Om een gekozen afbeelding te tonen, koppel je de bron van een img aan fileUrl(state.document).

Waarom er geen rij "bestand bijvoegen" in de toestemmingslijst staat

De toestemmingslijst van een portal noemt bewerkingen op tabellen — een lijst lezen, één record lezen, maken, wijzigen, verwijderen — en een bestand is daar geen van. Het reist mee in de body van de schrijfactie, dus een portal die een claim mag maken, mag een document zetten op de claim die hij maakt, en een portal die dat niet mag, kan het niet. Er is niets extra's om toe te kennen, en niets extra's om te vergeten in te trekken.

Daarom staat er ook geen bestandsendpoint op het openbare internet. De bytes gaan naar je aangepaste API, je script bepaalt op welk record ze terechtkomen, en putRecordFile slaat ze op onder de eigen machtigingen van het record — het heeft Bijwerken op die rij nodig, precies zoals een formulier binnen het platform.

Bijvoegen bij een record dat al bestaat

Hetzelfde, via een wijziging. Stuur het bestand mee in de waarden van updateRecord, en laat de aangepaste API achter de rij Een record wijzigen het record lezen, bijwerken en daarna putRecordFile aanroepen. Bij een tabel met een regel over wiens records een bezoeker ziet volgt het bestand die regel ook: een bezoeker kan alleen een bestand bijvoegen bij een record dat de regel hem geeft.

Hoe groot een bestand mag zijn

4 MB, en de kiezer zegt dat al voordat er iets wordt geüpload.

Dat is kleiner dan wat het platform opslaat — een installatie met objectopslag geconfigureerd neemt via het eigen bestandsendpoint van een record veel grotere bestanden aan — en het verschil is bewust. Hier wordt het bestand als tekst gecodeerd in een JSON-body en in de browser van de bezoeker vastgehouden terwijl die het formulier verder invult. Een heel grote bijlage op die weg is een heel grote tekenreeks in de browser van een onbekende, en een body die je geen enkel contract zou moeten laten verwerken.

Hetzelfde scherm binnen het platform

Er verandert niets. Open dezelfde app in Parsware en dezelfde handler schrijft rechtstreeks in de tabel, waarbij het bestand via het eigen endpoint van het platform naar de kolom Bestand van het record gaat. Je tekent één scherm, niet twee.

Drie dingen waar mensen over struikelen

• Schrijf het record vóór het bestand. putRecordFile heeft een record-id nodig. Een script dat eerst probeert bij te voegen, heeft niets om aan te koppelen.
• Bewaar de naam van het bestand in een tekstkolom ernaast. Een lijst die "📎 invoice.pdf" wil tonen, moet een gewone tekstkolom lezen, niet elk bestand ophalen om de naam te weten te komen.
• Een weigering wordt door onbekenden gelezen. Weiger je een bijlage — bijvoorbeeld een verkeerd soort bestand — schrijf de zin dan voor het publiek: hij verschijnt naast de knop waarop werd gedrukt.

Controleer of het werkte

Voeg op de portal een bestand toe, druk op de knop en open daarna het record in het platform. Het document staat in het veld Bestand, met de naam die je ernaast hebt opgeslagen — en de portal heeft nooit een recordendpoint gezien.