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.

You register the embed runtime and the inline script bundle (human-interaction signal and optional phone masking for fields named wf_phone). Call wckd_form_init() once in <head> after requiring wckd-form.php (or rely on wckd_form() in the body, which calls init as a fallback). Without init, submissions can fail with NO_HUMAN_INTERACTION.

<?php
require_once __DIR__ . '/wckd-forms/wckd-form.php';
wckd_form_init();
?>
  1. Adjust the require_once path so it resolves from the current PHP file’s directory to wckd-forms/wckd-form.php.
  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.

Screenshot. Show your shared layout or header file with the require line above added (and the multi-email line when applicable).

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 key that exists in wckd-forms/forms/registry.php.
  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 a signing secret exists in wf_config/private.php. 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 require_once …/wckd-form.php, wckd_form_init();, and then wckd_form_init('multi-email'); on these pages (the second call loads wf_load_app_config(), the mint helper, and related includes). installer.php already pulls in forms/lib/forms.php for wf_get_form_config().

<?php
require_once __DIR__ . '/wckd-forms/wckd-form.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'); ?>

Each placement keeps its own label while sharing one init.

  1. Keep a single require_once …/wckd-form.php and one wckd_form_init(); 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 rewrites to wckd-forms/submit.php 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 Leads in the dashboard for the placement label you used.
  • Unknown form schema: typo in the registry key or a missing file under wckd-forms/forms/schemas/; fix forms/registry.php, 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.