Documentatie

Bestandsuploads verwerken

Stap-voor-stap gids voor het configureren van veilige bestandsuploadformulieren met opslagintegratie.

1. Uploadveld toevoegen aan je schema

Om bestanden te accepteren, definieer je een veld met type: 'file' in je JSON-schema. Dit vertelt Formly om een upload-interface te genereren die compatibel is met moderne browsers.

Je kunt dit veld uitbreiden met label, help-tekst en verplichte validaties. Hieronder zie je een basisconfiguratie:

Voorbeeld van een bestandsuploadveld in de JSON-editor 
{
  "key": "cv_upload",
  "type": "file",
  "templateOptions": {
    "label": "Upload je CV",
    "placeholder": "Klik hier om een bestand te kiezen",
    "accept": ".pdf,.doc,.docx",
    "maxSize": 10485760
  }
}

2. Bestandstype- en groottevalidatie instellen

Bescherm je applicatie tegen ongeldige bestanden door strikte validaties toe te passen.

  • accept: Een string of array met MIME types of bestandsextensies (bijv. .png,.jpg).
  • maxSize: De maximale grootte in bytes (bijv. 5242880 voor 5MB).
  • required: Zet dit op true om te forceren dat een bestand wordt geüpload.

Formly valideert dit direct in de frontend voordat de gebruiker de knop indrukt, wat zorgt voor een soepelere ervaring.

3. Opslagdoelen: Formly-opslag, AWS S3, Azure Blob

Kies waar je bestanden veilig worden opgeslagen.

Formly Storage

De eenvoudigste optie. Geef geen API keys aan je frontend. Formly beheert de vertrouwelijke credentials en uploadt veilig naar onze eigen infrastructuur (EU-regio). Ideaal voor quickstarts.

AWS S3

Gebruik de aws-s3 adapter. Upload direct naar jouw eigen bucket met directe toegang. Geschikt voor teams die al volledig in de AWS-ecosysteem zitten.

Azure Blob

Via de azure-blob adapter. Synchroniseer bestanden met jouw Azure Storage Account. Volledige integratie met bestaande Azure pipelines.

4. Voortgangsindicator implementeren in de UI

Gebruikers willen weten hoe ver de upload is. Formly ondersteunt een onUploadProgress callback in je SDK. Dit ontvangt een percentage en de huidige snelheid (kb/s).

In de UI kan je dit verwerken met een CSS Progress Bar. Hieronder een conceptueel voorbeeld van de logica: 

const onProgress = (progress) => {
  const percent = Math.round(progress.loaded / progress.total * 100);
  console.log(`Uploading: ${percent}%`);
  // Update je progress bar width via ref
}

5. Virusscanning en beveiligingsoverwegingen

Bestandsuploads zijn een risico voor beveiliging. Formly biedt ingebouwde SecureScan functionaliteit.

Wanneer je een bestand uploadt naar Formly Storage, wordt dit automatisch gescand op bekende virussen en malware voordat het beschikbaar wordt gesteld via de API. Voor S3/Azure integraties kun je eventueel een webhook triggeren naar een externe scanner zoals ClamAV.

6. Bestanden ophalen via de API na inzending

Zodra een bestand is geüpload, ontvang je in de API-response een unieke fileId. Om het bestand op te halen, gebruik je de volgende endpoint:

GET /v1/files/{fileId}

Deze aanvraag retourneert de directe download-URL, de bestandsgrootte, MIME-type en de hash (SHA-256) voor verificatie in je backend.

7. Codevoorbeeld: Vue 3 uploadformulier

Hier is een compleet voorbeeld van een Vue 3 component dat gebruikmaakt van de Formly SDK, bevat validatie en een real-time voortgangsbalk. 

<template>
  <div class="upload-container">
    <formly-form
      :model="model"
      :fields="fields"
      :options="options"
    />

    <div v-if="uploadProgress > 0" class="progress-wrapper">
      <div class="progress-bar" :style="{ width: uploadProgress + '%' }"></div>
      <p class="progress-text">{{ uploadProgress }}% geüpload</p>
    </div>

    <button type="button" @click="submitForm">Versturen</button>
  </div>
</template>

<script setup>
import { ref, reactive } from 'vue';
import { FormlyForm, FormlyModule } from '@formly/vue';
import { createFormly } from '@formly/core';

const model = reactive({});
const options = reactive({});

const uploadProgress = ref(0);

const fields = [
  {
    key: 'resume',
    type: 'file',
    templateOptions: {
      label: 'Upload CV',
      accept: '.pdf',
      maxSize: 5242880,
      onUploadProgress: (event) => {
        uploadProgress.value = Math.round((event.loaded / event.total) * 100);
      }
    }
  }
];

const submitForm = async () => {
  // Formly verzendt de payload automatisch naar de API
  console.log('Formulier verstuurd met bestands-ID:', model.resume?.fileId);
};
</script>

<style scoped>
.upload-container { max-width: 600px; margin: 0 auto; }
.progress-wrapper { margin: 1rem 0; }
.progress-bar { height: 8px; background: var(--clr-accent); border-radius: 4px; transition: width 0.3s; }
.progress-text { font-size: 0.8rem; color: white; margin-top: 0.5rem; }
</style>