Embed forms on your site

This guide is for a developer who places WCKD Forms into an existing PHP layout. You will add two PHP blocks: one loads the helper and shared scripts once per page; the other prints each form where it belongs in the HTML. A non-developer can copy the same snippets from Settings → Forms once a Manager has opened that tab.

Embedding on another site with the Lite package? Start with WCKD Forms Lite, then use the Other Sites snippets in Settings → Forms.

You register the embed runtime and the inline script bundle (human-interaction signal and optional phone masking for fields named wf_phone). Copy the In <head> snippet from Settings → Forms and place it once in your shared layout.

Why call init in the head? wckd_form() also calls wckd_form_init() if you omit the head snippet, but the human-interaction listeners attach when init runs. Loading init in <head> gives visitors time to move the mouse or touch the page before submit; otherwise a fast click can fail with NO_HUMAN_INTERACTION.

  1. Deploy the package where your PHP layout can load it, then use the dashboard-generated snippet for your install.
  2. For multi-email forward pages, add wckd_form_init('multi-email'); in <head> (after default wckd_form_init()) so PHP can mint a token in the body. The second call loads installer + directory routing once; it does not repeat the human-interaction script tag.

You output the HTML form for a registry key and set the placement label used in the database as form_name.

<?php wckd_form('default', 'Contact page hero'); ?>
  1. Replace default with a form key that exists in your dashboard.
  2. Replace Contact page hero with a placement label you will recognize in the inbox and performance filters (it becomes form_name).
  3. Omit the second argument only when you accept the registry key as the label.

Optional third argument: multi-email forward token

Use this only when Use multi-email forward is turned on for that registry template under Settings → Forms → Configure → Advanced settings and directory routing is configured. It sends the staff notification to a page-specific inbox without putting that address in the HTML. This is separate from department routing (the Department field Choices in the form builder); see Notifications — who gets the staff notification?

Your layout <head> must include the dashboard-generated head snippet, plus wckd_form_init('multi-email'); on these pages. The second call loads the helpers needed to mint the signed recipient token.

<?php wckd_form_init('multi-email'); ?>
<?php
$app = wf_load_app_config() ?? [];
$formSettings = wf_get_form_config('default')['settings'] ?? [];
$staffEmail = 'person@example.com'; // from your CMS, member record, etc.
$token = wf_directory_routing_mint_recipient_token($staffEmail, $app, is_array($formSettings) ? $formSettings : []);
wckd_form('default', 'Contact page hero', $token);
?>

If $token is an empty string, call wckd_form('default', 'Contact page hero'); with two arguments only; staff mail then follows department routing or Reply-To.

wckd() is an alias for wckd_form() with the same arguments (registry key, placement label, optional directory token).

<?php wckd('default', 'Footer'); ?>

Lite uses the same wckd_form() API, but it posts to the main dashboard intake URL instead of storing anything locally. Install and configure Lite first, then copy the Other Sites snippet from Settings → Forms.

For custom forms, copy the matching dashboard schema definition into Lite and add the key to the Lite form map. See WCKD Forms Lite.

Each placement keeps its own label while sharing one init.

  1. Keep the dashboard-generated head snippet once in the layout <head>. Add wckd_form_init('multi-email') only on pages that mint a directory token.
  2. Call wckd_form() (or wckd()) once per placement with a unique second argument so reports stay readable.

You prove the browser POST reaches intake and the submission row exists.

  1. Confirm /form-submit reaches the correct WCKD Forms route per Routing & URLs.
  2. Submit the form from a normal page load (not only from devtools).
  3. Expect a redirect to your thank-you URL and a new row under Inbox for the placement label you used.

Common mistakes

  • Unknown form schema: typo in the form key or a missing schema definition; fix the form mapping, deploy, hard-refresh.
  • Wrong require_once path: PHP fatals before output; fix the relative path from the layout file that runs first.
  • Redirect to not-sent with ?wckd=: see Troubleshooting for intake and abuse checks.

Related pages