OW Forms — Documentatie

Een moderne, AVG-native formulierenbouwer voor WordPress. Auteur: OptionWeb — Julien Daniel Plugin-pagina: https://optionweb.dev/nl/addons/ow-forms/ Licentie: GPL-2.0-or-later Versie die dit document beslaat: 1.0.2

---

Inhoudsopgave

1. Overzicht
2. Installatie
3. Snelstart — je eerste formulier
4. Veldtypes
5. Anti-spam stack
6. AVG-functies
7. E-mailmeldingen
8. Webhooks
9. Bestandsuploads
10. Rendering: shortcode, Gutenberg, REST
11. Contact Form 7-importer
12. Instellingenreferentie
13. REST API
14. Developer hooks (filters & actions)
15. Integratie met OW Consent / OW Shield
16. Internationalisatie
17. Probleemoplossing
18. FAQ

---

Overzicht

OW Forms is een schema-gestuurde formulierenbouwer. Elk formulier is een JSON-document dat zijn velden, validatie en submit-gedrag beschrijft. De plugin rendert dat schema als toegankelijke HTML, valideert inzendingen aan de serverzijde, voert ze door een vierlagige anti-spam stack, bewaart wat je toestaat om te bewaren, en verstuurt e-mail- en webhook-meldingen.

Wat het meelevert (alles gratis, GPL-2):

• JSON-schema engine met 17 veldtypes
• 4-laagse anti-spam: honeypot, time-trap, multi-provider CAPTCHA, IP-reputatie
• Native AVG-toestemming + retentie + DSAR
• REST API (owf/v1 namespace) — publieke submit + admin CRUD
• Gutenberg-block + shortcode + PHP render-API
• HMAC-getekende uitgaande webhooks
• Contact Form 7 één-klik importer
• Detecteert automatisch OW Canvas thema-tokens voor visuele consistentie

Wat het bewust NIET doet:

• Betalingsverwerking (gebruik WooCommerce + een dedicated checkout)
• Multi-page wizards voorbij eenvoudige volgende/vorige (gebruik een dedicated wizard-plugin)
• Drag-and-drop visuele bouwer in v1 (alleen JSON-editor; visuele bouwer op de roadmap)

---

Installatie

Vanuit WordPress.org (aanbevolen)

1. WordPress admin → Plugins → Nieuwe plugin
2. Zoek naar OW Forms
3. Klik op Nu installeren, dan op Activeren

Vanuit .zip-upload

1. Download ow-forms-1.0.2.zip van https://optionweb.dev/nl/addons/ow-forms/
2. Plugins → Nieuwe plugin → Plugin uploaden
3. Kies het bestand, klik op Nu installeren, dan op Activeren

Vereisten

• WordPress 6.0 of nieuwer
• PHP 7.4 of nieuwer (8.1+ aanbevolen)
• MySQL/MariaDB met JSON-kolom-ondersteuning (5.7+ / 10.2+)

Wat wordt geïnstalleerd

Bij activatie maakt OW Forms drie aangepaste tabellen aan:

• {prefix}_owf_submissions — submission payloads + spam-metadata
• {prefix}_owf_files — register van geüploade bestanden
• {prefix}_owf_log — submission audit trail

Plus een Custom Post Type owf_form (niet publiek opvraagbaar) dat gebruikt wordt om de formulierschema's op te slaan.

---

Snelstart

Na activatie wordt automatisch een standaard "Contact"-formulier aangemaakt.

1. Ga naar OW Forms → Formulieren in de admin
2. Noteer het ID van het standaardformulier (bv. 1)
3. Plaats in een willekeurige pagina of bericht de shortcode:

[owf_form id="1"]

…of voeg het OW Forms Gutenberg-block toe en kies het formulier in de dropdown.

Dat is het. Het formulier wordt gerenderd, accepteert inzendingen, stuurt een admin-e-mail naar admin_email, en slaat de inzending op in de database.

Om het aan te passen, open je het formulier in OW Forms → Formulieren → [Bewerken] en pas je het JSON-schema rechtstreeks aan. Een visuele bouwer staat op de v1.1-roadmap.

---

Veldtypes

OW Forms ondersteunt 17 veldtypes. Elk veld in het schema is een object met minimaal type en name; de meeste accepteren ook label, help, required, placeholder, en type-specifieke opties.

Schema-voorbeeld

{
  "title": "Contact us",
  "fields": [
    {
      "type": "text",
      "name": "name",
      "label": "Your name",
      "required": true,
      "placeholder": "Jane Doe"
    },
    {
      "type": "email",
      "name": "email",
      "label": "Email",
      "required": true
    },
    {
      "type": "select",
      "name": "subject",
      "label": "How can we help?",
      "required": true,
      "options": [
        {"value": "quote",   "label": "Request a quote"},
        {"value": "support", "label": "Technical support"},
        {"value": "other",   "label": "Other"}
      ]
    },
    {
      "type": "textarea",
      "name": "message",
      "label": "Message",
      "required": true,
      "rows": 6
    }
  ],
  "submit": {
    "label": "Send",
    "success_message": "Thanks — we will reply within 24 hours.",
    "redirect_url": ""
  }
}

De name-waarden van velden worden sleutels in de opgeslagen payload en tokens die je kunt gebruiken in e-mailtemplates ({{name}}, {{email}}, etc.).

---

Anti-spam stack

OW Forms voert vier onafhankelijke lagen parallel uit. Elke laag draagt bij aan een score; een inzending met een score ≥ 80 wordt stil weggegooid — er wordt geen foutmelding teruggestuurd, zodat bots niet kunnen itereren tegen de bescherming.

1. Honeypot

Een visueel verborgen tekstinvoer die bots invullen en mensen niet. Instelling:

• spam_honeypot_enabled (standaard: true)

2. Time-trap

Wijst inzendingen af die sneller zijn afgerond dan een instelbare drempel (typische bots POSTen onmiddellijk).

• spam_timetrap_enabled (standaard: true)
• spam_timetrap_min_seconds (standaard: 2)

3. CAPTCHA (multi-provider)

Server-to-server token-validatie tegen de API van de leverancier. Kies één van:

• turnstile — Cloudflare Turnstile (aanbevolen, privacy-first, geen challenge UX)
• recaptcha_v3 — Google reCAPTCHA v3 (onzichtbaar)
• hcaptcha — hCaptcha (zichtbare widget)
• friendly_captcha — Friendly Captcha (self-hosted widget, MIT-licentie, EU-vriendelijk)

Stel spam_captcha_provider, spam_captcha_site_key en spam_captcha_secret_key in op het Anti-spam tabblad. Standaard is none.

Opmerking: Widget-JS van Turnstile / reCAPTCHA / hCaptcha wordt geladen vanuit de eigen origin van de leverancier (hun JS voert een origin-signatuurcontrole uit aan serverzijde). Friendly Captcha is self-hosted onder assets/js/vendor/.

4. IP-reputatie (optioneel)

Wanneer OW Shield geïnstalleerd en actief is, gebruikt OW Forms zijn IP-reputatiefeed om inzendingen te scoren:

• spam_owshield_iprep (standaard: true)
• spam_block_disposable_emails (standaard: true) — weigert @mailinator, @tempmail, en ~120 andere wegwerpdomeinen

Aanvullende heuristieken

• spam_min_words_per_text_area — vereist minstens N woorden in textareas
• spam_max_links_per_submission — weigert bij meer dan N URLs in payload
• spam_blocklist_emails, spam_blocklist_words, spam_blocklist_ips — je eigen lijsten

Logging

Elke spambeslissing wordt gelogd met reden. Check OW Forms → Inzendingen → filter "spam" om drempels af te stemmen zonder blind te varen.

---

AVG-functies

AVG-naleving is native. Standaardwaarden zijn conservatief; versoepel ze alleen als je daar juridisch advies voor hebt.

Toestemmingsvinkje

Een toestemmingsvinkje wordt automatisch onderaan elk formulier geïnjecteerd wanneer gdpr_consent_required true is (standaard). De tekst is configureerbaar:

'gdpr_consent_text' => __(
    'I agree that my data will be processed to respond to my inquiry, in accordance with the privacy policy.',
    'ow-forms'
)

Als gdpr_auto_link_privacy aanstaat (standaard), worden de woorden "privacy policy" / "privacybeleid" automatisch gelinkt aan de OW Consent privacybeleid-URL wanneer die plugin actief is, of anders aan je in WP geconfigureerde privacypagina.

Modi voor IP-opslag

store_ip-instelling:

User-agent opslag

store_user_agent-instelling:

Retentie & purge

Een dagelijkse cron purget inzendingen ouder dan gdpr_retention_days (standaard: 1095 dagen — de CNIL-standaard voor prospectdata). Zet op 0 om automatisch purgen uit te schakelen.

Als gdpr_auto_delete_after_response true is, verwijdert het markeren van een inzending als "afgehandeld" deze onmiddellijk samen met alle geüploade bestanden.

DSAR — Toegang / Wissing van betrokkenen

Formulier-e-mails worden bij opslag gehasht met wp_salt(). Wanneer OW Consent actief is en een DSAR-wissing wordt verwerkt voor een e-mailadres, verwijdert OW Forms automatisch overeenkomstige inzendingen op basis van email_hash en triggert:

do_action( 'owf_gdpr_erased_for_email', $hash, $count );

Zonder OW Consent kun je de wissing handmatig aanroepen:

OWF_GDPR::erase_by_email( 'user@example.com' );  // returns int count

---

E-mailmeldingen

Templates

Zowel admin-melding als gebruikers-auto-reply ondersteunen {{token}}-substitutie:

Instellingen

Override per formulier

Het formulierschema kan globals overschrijven:

{
  "mail": {
    "recipient": "sales@example.com",
    "subject": "New lead — {{name}}",
    "body": "Lead: {{name}}\\nEmail: {{email}}\\nMessage: {{message}}",
    "autoreply": true,
    "autoreply_subject": "Thanks, {{name}}!",
    "autoreply_body": "Hi {{name}},\\n\\nWe got your message."
  }
}

---

Webhooks

Wanneer webhook_url is ingesteld, triggert elke succesvolle inzending een HTTP POST.

Payload (JSON)

{
  "form_id": 1,
  "form_title": "Contact",
  "submission_id": 42,
  "received_at": "2026-05-13T14:32:18+00:00",
  "fields": { "name": "Jane", "email": "jane@example.com", "message": "Hi" },
  "site": "https://example.com"
}

HMAC-signatuur

Als webhook_secret is ingesteld, bevat het verzoek:

X-OWF-Signature: sha256=<hex digest of HMAC-SHA256(body, secret)>

Verificatie aan ontvangerszijde (Node-voorbeeld):

const expected = crypto
  .createHmac('sha256', SECRET)
  .update(rawBody)
  .digest('hex');
const provided = req.headers['x-owf-signature'].replace(/^sha256=/, '');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided))) {
  return res.status(401).end('bad sig');
}

Retries

Als de ontvanger 5xx retourneert of een time-out heeft, probeert OW Forms opnieuw met exponentiële backoff (60 s → 5 min → 30 min). Na 3 mislukkingen wordt de webhook gelogd als permanent mislukt maar blokkeert de inzending niet.

---

Bestandsuploads

Wanneer allow_file_uploads aanstaat (standaard true), wordt elk veld van type file geaccepteerd. De pijplijn:

1. Serverzijde validatie — bestandsgrootte (max_file_size_mb, standaard 8 MB), extensie-allowlist (allowed_file_types), en een finfo MIME-check gekruist met wp_get_mime_types().
2. Opslag — wp-content/uploads/owf-uploads/YYYY/MM/<sha256>.<ext> met een deny-all .htaccess (Apache) en lege index.php (Nginx/IIS).
3. Database-register — bestandsmetadata + SHA-256-hash in {prefix}_owf_files, gekoppeld aan de bovenliggende submission-ID.
4. Opruiming — wanneer een inzending wordt verwijderd (handmatig, door retentie of door DSAR) worden alle gekoppelde bestanden verwijderd.

Belangrijk: OW Forms gebruikt een aangepast geïsoleerd uploadpad, niet de WordPress mediatheek, dus geüploade bestanden zijn niet vindbaar via het standaard /wp-json/wp/v2/media endpoint en er worden geen thumbnails gegenereerd. Dit is bewust — formulierbijlagen zijn privé voor de eigenaar van het formulier.

Toegestane bestandstypes (standaard)

pdf, jpg, jpeg, png, webp, doc, docx, xls, xlsx, csv, txt

Uitbreiden:

add_filter( 'owf_settings', function( $s ) {
    $s['allowed_file_types'] = array_merge(
        (array) $s['allowed_file_types'],
        array( 'odt', 'ods', 'zip' )
    );
    return $s;
} );

---

Rendering

Shortcode

[owf_form id="42"]
[owf_form slug="contact"]

id (numeriek post-ID) of slug (post-slug) — één van beide is vereist.

Gutenberg-block

Zoek in de blok-editor naar "OW Forms" in de block-inserter en kies je formulier uit de dropdown.

PHP

echo OWF_Form::render( 42 );
// or
echo do_shortcode( '[owf_form id="42"]' );

REST

Het formulier kan ook programmatisch worden ingediend — zie REST API.

---

CF7-importer

Als Contact Form 7 geïnstalleerd is of was, levert OW Forms een één-klik importer mee.

OW Forms → Tools → Importeren vanuit Contact Form 7

De importer:

1. Scant elk wpcf7_contact_form-bericht in je database
2. Parseert elk shortcode-gebaseerd CF7-formulier en bouwt het equivalente OW Forms-schema
3. Behoudt ontvanger, onderwerp, succes-/foutmeldingen en veldtypes
4. Herschrijft elke [contact-form-7 id="..."] shortcode in al je post_content (pagina's, berichten, custom post types) naar [owf_form id="..."]
5. Logt resultaten: gevonden, geïmporteerd, overgeslagen (al geïmporteerd)

De CF7-plugin kan vervolgens worden gedeactiveerd en verwijderd.

De importer is idempotent: twee keer uitvoeren maakt geen duplicaten. Al geïmporteerde CF7-formulieren worden gemarkeerd via een _owf_imported_from_cf7 meta-key en bij volgende runs overgeslagen.

---

Instellingenreferentie

Alle instellingen staan in één option-key, owf_settings. Je kunt ze programmatisch lezen of overschrijven:

$value = OWF_Core::setting( 'spam_timetrap_min_seconds' );
OWF_Core::update_settings( array( 'spam_timetrap_min_seconds' => 3 ) );

Complete defaults

array(
    // General
    'default_recipient_email'        => '',     // empty = admin_email
    'from_name'                      => '',
    'from_email'                     => '',
    'sender_uses_dpo'                => true,

    // Anti-spam
    'spam_honeypot_enabled'          => true,
    'spam_timetrap_enabled'          => true,
    'spam_timetrap_min_seconds'      => 2,
    'spam_captcha_provider'          => 'none',
    'spam_captcha_site_key'          => '',
    'spam_captcha_secret_key'        => '',
    'spam_owshield_iprep'            => true,
    'spam_block_disposable_emails'   => true,
    'spam_min_words_per_text_area'   => 0,
    'spam_max_links_per_submission'  => 3,
    'spam_blocklist_emails'          => array(),
    'spam_blocklist_words'           => array(),
    'spam_blocklist_ips'             => array(),

    // GDPR
    'gdpr_consent_required'          => true,
    'gdpr_consent_text'              => '...',
    'gdpr_auto_link_privacy'         => true,
    'gdpr_retention_days'            => 1095,
    'gdpr_auto_delete_after_response' => false,

    // Storage
    'store_submissions'              => true,
    'store_ip'                       => 'pseudonymized',
    'store_user_agent'               => 'hashed',
    'allow_file_uploads'             => true,
    'max_file_size_mb'               => 8,
    'allowed_file_types'             => array( 'pdf', 'jpg', 'jpeg', 'png',
                                                'webp', 'doc', 'docx', 'xls',
                                                'xlsx', 'csv', 'txt' ),

    // Notifications
    'mail_html'                      => true,
    'mail_admin_subject'             => '[{{site_name}}] New message via {{form_title}}',
    'mail_admin_body'                => '',
    'mail_user_autoreply_enabled'    => true,
    'mail_user_subject'              => 'We have received your message',
    'mail_user_body'                 => '',
    'mail_failed_alert_email'        => '',
    'webhook_url'                    => '',
    'webhook_secret'                 => '',

    // Rendering
    'style_preset'                   => 'auto',
    'button_label_default'           => 'Send',
    'success_message_default'        => 'Your message has been sent. We will reply within 24 hours.',
    'error_message_default'          => 'An error occurred. Please try again or contact us directly.',
    'inherit_theme_tokens'           => true,

    // Analytics (opt-in)
    'track_conversions'              => false,
    'conversion_event_name'          => 'generate_lead',
    'conversion_value'               => 0,
    'conversion_currency'            => 'EUR',
);

---

REST API

Alle endpoints leven onder de namespace owf/v1.

Publiek endpoint

Body:

{
  "form_id": 1,
  "fields": { "name": "Jane", "email": "jane@example.com", "message": "Hi" },
  "_owf_nonce": "<from wp_create_nonce('owf_submit_form')>",
  "_owf_time": 1736780000,
  "_owf_hp": ""
}

Response (200):

{ "ok": true, "id": 42, "message": "Your message has been sent." }

Response (422) wanneer validatie mislukt:

{
  "ok": false,
  "errors": { "email": "Please enter a valid email" },
  "message": "Please review the fields in error."
}

Admin endpoints (vereisen manage_options)

Alle admin-endpoints vereisen zowel de manage_options-capability als een geldige WP REST nonce.

---

Hooks (filters & actions)

Actions

/**
 * Fires after a submission has been processed and stored.
 *
 * @param int   $submission_id  Database ID (0 if not stored)
 * @param int   $form_id        Form ID
 * @param array $cleaned        Sanitized field payload
 * @param array $schema         Full form schema
 */
do_action( 'owf_submission_received', $submission_id, $form_id, $cleaned, $schema );

/**
 * Fires after a DSAR erasure has deleted matching submissions by email hash.
 *
 * @param string $email_hash   SHA-256(email + wp_salt())
 * @param int    $deleted_count
 */
do_action( 'owf_gdpr_erased_for_email', $email_hash, $deleted_count );

Filters

/**
 * Filter the resolved settings array (merged defaults + saved + per-request).
 */
apply_filters( 'owf_settings', array $settings );

/**
 * Whitelist of trusted reverse proxy IPs that may set X-Forwarded-For.
 * Without this OW Forms ignores proxy headers (to prevent IP spoofing).
 */
apply_filters( 'owf_trusted_proxies', array $proxies );

/**
 * List of disposable email domains rejected when `spam_block_disposable_emails`
 * is on.
 */
apply_filters( 'owf_disposable_domains', array $domains );

Aanbevolen patroon — wegwerpdomeinlijst uitbreiden

add_filter( 'owf_disposable_domains', function( $list ) {
    return array_merge( $list, array(
        'example-throwaway.com',
        'company-blocked-domain.net',
    ) );
} );

Aanbevolen patroon — inzendingen naar CRM pushen

add_action( 'owf_submission_received', function( $sid, $form_id, $cleaned ) {
    if ( $form_id !== 7 ) return;  // only the "Sales" form
    wp_remote_post( 'https://crm.example.com/leads', array(
        'headers' => array( 'Authorization' => 'Bearer ' . CRM_TOKEN ),
        'body'    => wp_json_encode( array(
            'email'   => $cleaned['email'],
            'name'    => $cleaned['name'],
            'message' => $cleaned['message'],
            'source'  => 'website-form',
        ) ),
        'headers' => array( 'Content-Type' => 'application/json' ),
    ) );
}, 10, 3 );

---

Integraties

OW Canvas (thema)

Wanneer het OW Canvas-thema actief is, erft OW Forms zijn CSS custom properties (--owc-ink, --owc-paper, --owc-accent, etc.) voor visuele consistentie. Schakel uit met inherit_theme_tokens = false.

OW Consent

Wanneer OW Consent actief is:

• De link in het AVG-toestemmingsvinkje wordt automatisch gericht op je OW Consent privacybeleid-URL
• Inzendingen worden gekoppeld aan OW Consent-records (wanneer de bezoeker een consent-ID cookie heeft)
• DSAR-wissingsflows van OW Consent purgen automatisch OW Forms-inzendingen voor dezelfde e-mailhash

OW Shield

Wanneer OW Shield actief is en spam_owshield_iprep aanstaat, wordt het IP van elke inzending gescoord tegen de reputatiefeed van OW Shield voordat het wordt geaccepteerd.

---

Internationalisatie

De brontaal is Engels. Een Franse vertaling wordt meegeleverd onder languages/ow-forms-fr_FR.po.

Voor vertalers

Het .pot-template staat in languages/ow-forms.pot. Dien vertalingen in via translate.wordpress.org/projects/wp-plugins/ow-forms zodra de plugin is goedgekeurd op WP.org. Voor lokale distributie, plaats ow-forms-<locale>.mo in de map languages/.

.mo lokaal compileren

msgfmt languages/ow-forms-fr_FR.po -o languages/ow-forms-fr_FR.mo

---

Probleemoplossing

Formulier wordt ingediend maar er komt geen e-mail

1. Controleer of je site überhaupt mail kan versturen — probeer een test vanuit het contactformulier van een andere plugin of met Mail Tester
2. Check OW Forms → Inzendingen om te bevestigen dat de inzending is binnengekomen (zo ja, dan is het probleem aflevering, niet OW Forms)
3. Stel mail_failed_alert_email in op je eigen adres — OW Forms zal je een e-mail sturen wanneer wp_mail() false retourneert
4. Installeer een SMTP-plugin (Fluent SMTP, WP Mail SMTP, etc.) — de standaard PHP mail() wordt door 95 % van de ontvangende servers geweigerd

CAPTCHA verschijnt niet

• Controleer of zowel spam_captcha_site_key als spam_captcha_secret_key zijn ingesteld
• Open de pagina in DevTools — de script-URL van de leverancier moet met een 200 laden
• Voor reCAPTCHA moet het domein van je site geregistreerd zijn in de Google-admin
• Voor Turnstile moet de widget-modus in de Cloudflare-admin "Managed" of "Non-interactive" zijn

Bestanden worden geüpload maar admin kan ze niet downloaden

Dit is by design — geüploade bestanden worden geserveerd door een geauthenticeerde PHP-handler, niet rechtstreeks. Controleer of je bent ingelogd als gebruiker met manage_options.

CF7-importer zegt "0 formulieren gevonden"

De importer scant het post type wpcf7_contact_form. Als CF7 al gedeactiveerd is en de posts verwijderd zijn, is er niets meer om te importeren. Heractiveer CF7 alleen voor de import en deactiveer daarna opnieuw.

Submissions-tabel is enorm

• Verlaag gdpr_retention_days (standaard 1095 / 3 jaar)
• Schakel store_submissions uit als je alleen e-maillevering nodig hebt, geen database- audit trail
• Stel gdpr_auto_delete_after_response = true in om te verwijderen bij "afgehandeld"

---

FAQ

Is OW Forms gratis? Ja. GPL-2.0-or-later. Er is geen Pro-versie, geen licentiesleutel, geen functie achter betaling vergrendeld.

Werkt het op WordPress Multisite? Ja — elke site heeft eigen tabellen en formulierbibliotheek, geïsoleerd zoals verwacht.

Ondersteunt het multi-step formulieren? Basale volgende/vorige-navigatie werkt via veldgroepering in het schema. Een eersteklas wizard-UX staat op de v1.1-roadmap.

Hoe exporteer ik inzendingen? OW Forms → Inzendingen → CSV exporteren. De export respecteert de huidige filters (formulier, datumbereik, status).

Kan ik mijn formulieren achter een paywall of login hosten? Ja — wikkel de shortcode in de gating-logica van een membership-plugin, of render via PHP binnen een is_user_logged_in()-check.

Integreert het met e-mailmarketing- / CRM-tools? Out of the box: webhooks (HMAC-getekende POST naar een willekeurig endpoint), en e-mailontvangers per formulier. Voor Brevo / Mailchimp / HubSpot / Pipedrive, hook owf_submission_received en roep de REST API van de leverancier aan — zie de Hooks-sectie.

Is de plugin AVG-gecertificeerd? De defaults van de plugin zijn afgestemd op CNIL / AVG best practices, maar certificering is een juridisch proces specifiek voor je verwerkingsverantwoordelijke- setup. Wij leveren de technische tooling; jouw DPO bevestigt het beleid.

Waar is de support?

• Supportportaal: https://optionweb.dev/nl/addons/support/
• E-mail: support@optionweb.dev
• Documentatie: https://optionweb.dev/nl/addons/ow-forms/

---

Gebouwd door OptionWeb — Julien Daniel, Châtelet, België.