Kindly Forms developer reference
Storage, permissions, PHP functions, REST routes, every hook and filter, and how to add field types and connections.
This page is for developers: how Kindly Forms stores forms and entries, its permission words, its REST routes, the PHP functions worth calling, every hook and filter, and how to add a field type or a connection. The source is includes/forms/ in the plugin. The builder and hub are plain JavaScript in assets/forms/ with no build step.
Storage#
A form is a post of type kindly_form. It is never public on its own address: it shows through the [kindly_form] shortcode, a page's Form element, or its landing page.
| Where | Holds |
|---|---|
| Post title and status | The form's name. publish is open to visitors, draft is closed, trash is in the trash |
Meta _kf_live |
The published definition, as JSON |
Meta _kf_draft |
The builder's unpublished version, when there is one |
Meta _kf_history |
Earlier versions for History (20 by default, filter kindly_forms_history_size) |
Option kindly_forms_settings |
Site-wide settings (Kindly Edit > Forms > Settings). Read with kindly_forms_setting( 'dot.path', $default ) |
Option kindly_forms_connections |
Site-wide connection keys and accounts, per provider. Secrets never leave the server: REST answers show them as __kept__ |
Option kindly_forms_inventory |
Shared stock items |
A definition is one JSON object: title, fields (a tree: columns, sections and groups hold their own fields), settings, notifications (emails) and feeds (connections). Every field is { id, type, name, ...settings }. Anything left out takes its default when read.
Entries and everything about them live in custom tables, named with the site's prefix plus kf_. kindly_forms_table( 'entries' ) returns the full name.
| Table | Holds |
|---|---|
kf_entries |
One row per entry: form, serial number, status, favorite, user, source address, IP, browser, device, country, payment status and total, the answers as JSON, dates |
kf_values |
Each answer again as its own row, indexed for filters and reports |
kf_meta |
Entry notes, status changes, connection results and other entry history |
kf_logs |
Activity and API logs, with secrets removed |
kf_queue |
Connections waiting to be sent or tried again |
kf_drafts |
Saved progress and partial entries |
kf_views |
Daily views, starts and sends per form |
kf_transactions, kf_subscriptions, kf_coupons |
Payments |
kf_stock |
Stock held and used per entry |
The tables are created and upgraded with dbDelta when the schema version (option kindly_forms_db) changes.
Permissions#
Every REST route, ability and screen checks kindly_forms_can( $what, $form_id ). The words and the WordPress capability each needs by default:
| Word | Allows | Default capability |
|---|---|---|
manage |
Opening Kindly Edit > Forms and the forms list | edit_others_pages |
edit |
Building and changing forms | edit_others_pages |
entries |
Reading entries and logs | edit_others_pages |
entries_edit |
Changing entries: status, notes, answers, approval, resending | edit_others_pages |
entries_delete |
Deleting entries | edit_others_pages |
reports |
Reports | edit_others_pages |
settings |
Site-wide settings and connections | manage_options |
payments |
Payments, refunds, coupons and payment settings | manage_options |
Settings > Managers gives named people chosen rights without changing their role. It never grants settings, so a manager can't widen anyone's access. The kindly_forms_can filter receives ( $ok, $what, $form_id, $user_id ) for your own rules.
PHP functions#
| Function | Does |
|---|---|
kindly_forms_get( $id, $draft = false ) |
A form's definition with id, title, status, pending (has a draft) and modified. With $draft, the builder's unpublished version when there is one. null if missing |
kindly_forms_create( $def, $status = 'publish' ) |
Makes a form from a definition. Returns its ID or a WP_Error |
kindly_forms_save( $id, $def, $live = false, $label = '' ) |
Saves a definition as the draft, or straight live with $live. Adds a history entry |
kindly_forms_publish( $id ), kindly_forms_discard( $id ) |
Puts the draft live, or drops it |
kindly_forms_render( $id, $o = [] ) |
The form's HTML, as the shortcode prints it |
kindly_forms_submit( $form_id, $in ) |
Runs the whole sending pipeline (checks, spam, entry, emails, connections, payment) for input shaped like a visitor's send. Returns { ok, message, ... } |
kindly_forms_smart( $text, $ctx ) |
Replaces smartcodes such as {inputs.email} and {all_data}. See the smartcode reference |
kindly_forms_entry_get( $id ), kindly_forms_entry_create( $row ), kindly_forms_entry_update( $id, $changes ) |
Read, add and change entries |
kindly_forms_entries_query( $q ) |
A page of entries: [ $rows, $total ]. Keys: form, status, search, from, to, page, per, orderby, order, filters |
kindly_forms_entry_note( $entry_id, $key, $value, $form_id ) |
Adds a note or history line to an entry |
kindly_forms_log( $form, $entry, $kind, $component, $status, $title, $message ) |
Writes a line to the logs. $kind is activity or api; $status is success, failed or info |
kindly_forms_setting( 'dot.path', $default ) |
A site-wide setting |
kindly_forms_can( $what, $form_id ) |
The permission check above |
Shortcodes and addresses#
| Shortcode | Shows |
|---|---|
[kindly_form id="12"] |
The form. title="yes" shows its title above it |
[kindly_forms_results form="12" field="color" labels="yes" counts="yes"] |
Survey results of a published form, for one field or all of them |
[kindly_forms_receipt] |
A payment receipt, on the receipt page a payment links to |
[kindly_forms_payments] |
The signed-in person's own payments and subscriptions |
[gravityform id="12"], [gravityforms id="12"] and the gravityforms/form block |
The Kindly form imported from Gravity form 12 with Show for [gravityform] shortcodes and blocks on (since 0.12.0). While Gravity Forms is active it still draws every form nobody imported |
The site also answers a few addresses of its own: landing pages (a base path plus the form's slug, see Quizzes, landing pages and post forms), the answers page, signed PDF download links (kindly_pdf), save-and-continue links (?kf_resume=), a confirmation page opened with Fill smartcodes on that page (?kf_entry=, signed, never cached and not indexed; since 0.12.0), and admin-post.php actions for sending without JavaScript (kindly_forms_submit), email confirmation (kindly_forms_confirm), private file downloads (kindly_forms_file, kindly_forms_cloud_file), account verification (kindly_forms_verify_user), service sign-in (kindly_forms_oauth_start, kindly_forms_oauth) and canceling a subscription (kindly_forms_sub_cancel).
REST routes#
Everything the builder and hub show comes from these routes, under /wp-json/kindly-forms/v1. Signed-in requests use WordPress cookie authentication with the X-WP-Nonce header, or an application password. A form on a page sends as the signed-in person: for someone signed in, its script gets a nonce from the kindly_forms_nonce admin-ajax action (never cached, readable only by the site's own pages; a visitor gets an empty one) and renews it there if it expires while the page is open. No nonce is printed in the page, so cached pages are safe, and /token never hands one to a request that isn't already authenticated. "Who" names the permission word checked, for the form the request touches.
For visitors#
| Method and route | Who | Does |
|---|---|---|
GET /token?form=ID |
anyone | A fresh anti-spam token for the form, and counts a start when asked (start=1) |
POST /count?form=ID |
anyone | Counts a view of a published form. The form's script sends it when analytics are on (count in data-kf-config), so cached pages count too; the server decides whether this visitor counts (not someone who can edit the form, not a bot) |
POST /submit |
anyone | Sends a form. Answers 200 when accepted, 422 with errors, 429 when rate limited |
POST /upload |
anyone | Uploads one file for an upload field before sending |
POST /resume |
anyone | Saves progress for save and continue, and emails the link when asked |
POST /coupons/check |
anyone | Checks a coupon against the form's order |
POST /payments/webhook/{gateway} |
anyone | A payment service's notice, verified by that service's signature |
GET /payments/return |
anyone | The return from a hosted checkout (signed) |
POST /payments/confirm |
anyone | The browser finished an on-page payment step (signed) |
The token, send, upload and save answers are never cached. Nothing from the browser is believed about amounts or payment status: the payment service is asked.
Forms and the builder#
| Method and route | Who | Does |
|---|---|---|
GET /schema |
edit | Field types and their settings, smartcodes, presets, countries, taxonomies, roles and pages, for the builder |
GET /forms |
manage | The forms list with entry, unread and view counts and the pages using each form. status, search |
POST /forms { title?, template?, definition?, status? } |
edit | A new form, blank, from a template or from a definition |
GET /forms/{id} |
edit | The form, with its draft when there is one |
PUT /forms/{id} { definition?, live?, label?, modified?, force?, status? } |
edit | Saves the draft (or live). With modified, refuses with 409 when someone else saved since |
DELETE /forms/{id} |
edit | Moves it to the trash. With force, deletes it and its entries (needs entries_delete) |
POST /forms/{id}/publish, /discard, /duplicate, /restore, /untrash |
edit | Publish the draft, drop it, copy the form, restore a version (at), or take it out of the trash |
GET /forms/{id}/history |
edit | Saved versions with who and when |
POST /render |
edit | The form's HTML for the builder's canvas or a preview |
GET /templates |
edit | The templates, flat and by category |
GET /forms/export?ids= |
manage | Form definitions as a JSON download |
POST /forms/import |
edit | A Kindly Forms, Fluent Forms or Gravity Forms JSON file. See Import and templates |
GET /gravity/forms |
edit | The site's own Gravity Forms forms (id, title, active, entry count, already imported), for From Gravity Forms (since 0.12.0) |
POST /gravity/import { ids, shortcode?, entries? } |
edit | Imports those Gravity forms with their add-on feeds. shortcode (on unless false) lets [gravityform] show the Kindly form; entries also copies their entries, only for people with entries_edit whom Gravity Forms lets view entries. 404 when Gravity Forms isn't on the site (since 0.12.0) |
Entries, reports and logs#
| Method and route | Who | Does |
|---|---|---|
GET /entries?form=ID |
entries | A page of entries with counts by status. status, search, from, to, page, per, orderby, order, payment, filters |
GET /entries/{id} |
entries | One entry with readable answers, notes, payments and the next and previous IDs. payments.subscriptionLive is true while one of its subscriptions hasn't ended. Marks it read unless peek |
PUT /entries/{id} { status?, favorite?, values? } |
entries_edit | Changes status or star, or edits answers (files and passwords stay as they were) |
DELETE /entries/{id} |
entries_delete | Deletes it for good. Its payments and subscriptions are kept and nothing is canceled with the payment service |
POST /entries/{id}/note, /resend, /approve, /decline, /confirm |
entries_edit | Adds a note, sends an email again, approves, declines, or confirms an unconfirmed entry by hand |
POST /entries/bulk { ids, action } |
entries_edit | read, unread, spam, trashed, restore, favorite, unfavorite, approve, decline, delete (needs entries_delete), feeds (runs connections again) |
GET /export |
entries | Entries as CSV, XLSX, ODS, JSON or a print page (a download) |
POST /entries/import |
entries_edit | A CSV or JSON file into a form's entries: a preview step, then a run with a column mapping |
GET /reports |
reports | Views, starts and sends per day, conversion, answers per choice, averages and payments |
GET /logs, GET /logs/{id}, DELETE /logs |
entries, entries_delete | Activity and API logs, secrets removed |
GET /unfinished, DELETE /unfinished |
entries, entries_delete | Saved progress and partial entries |
GET /queue, POST /queue/{id}/retry, POST /queue/retry |
entries, entries_edit | Connections waiting or failed, and trying them again |
GET /prefs, PUT /prefs |
manage | The person's own entries columns and page size per form |
GET /users |
settings | People to choose in Settings > Managers |
GET /settings, PUT /settings |
settings | Site-wide settings. Secrets show as __kept__ and keep their value when sent back that way |
Connections#
| Method and route | Who | Does |
|---|---|---|
GET /connections |
settings | Every provider and whether it is connected (no secrets) |
GET /connections/{provider} |
settings | Its values with secrets as __kept__, and sign-in links |
PUT /connections/{provider}, DELETE /connections/{provider} |
settings | Save and check, or disconnect |
POST /connections/{provider}/test |
settings | Check the saved connection again |
GET /connections/{provider}/lists |
edit | Choices from the service (lists, tags, boards), kept for 10 minutes |
GET /connections/{provider}/map |
edit | Mapping rows fetched from the service |
POST /connections/{provider}/sample |
edit | Sends made-up answers through one connection |
GET /connections/{provider}/oauth |
settings | The sign-in address to open |
Stock, documents and payments#
| Method and route | Who | Does |
|---|---|---|
GET /inventory, POST /inventory |
edit | Shared stock items with where they are used, and adding one |
PUT /inventory/{slug} |
edit | Renames it or changes its total |
DELETE /inventory/{slug}, POST /inventory/{slug}/reset |
settings | Removes it, or starts its count again |
GET /forms/{id}/inventory |
edit | What this form uses |
GET /forms/{id}/pdf/setup |
edit | What the Documents tab needs: starting points, fonts, paper sizes, defaults and recent entries |
POST /forms/{id}/pdf/preview |
edit | A preview of a document |
GET /forms/{id}/entries/{entry}/pdf/{doc} |
entries | One entry's document |
POST /forms/{id}/entries/pdf |
entries | Documents of several entries in one zip (up to 100, filter kindly_forms_pdf_zip_limit) |
GET /payments/settings, PUT /payments/settings |
payments | Payment settings, secrets as __kept__ |
GET /transactions, GET /subscriptions |
payments | Lists |
POST /payments/{tx}/refund, POST /payments/{tx}/status |
payments | Refund, or change a payment's status by hand |
POST /subscriptions/{id}/cancel |
payments | Cancels a subscription |
GET /coupons, POST /coupons, PUT /coupons/{id}, DELETE /coupons/{id} |
payments | Coupons |
Moving a page form#
GET and POST /wp-json/cantata-edit/v1/forms/{post}/{form}/convert turn an old page Form into a Kindly form. They need permission to edit the page and manage. See Moving an old page form.
AI abilities#
The kindly-forms/* abilities run through WordPress's own abilities routes, not this namespace. See AI and Kindly Forms.
Hooks and filters#
Every literal kindly_forms_ hook, by area. A name ending in {type}, {provider} or {event} is built from that value. Arguments are listed in order.
Forms, permissions and settings#
| Hook | Type | Arguments | Use |
|---|---|---|---|
kindly_forms_can |
filter | $ok, $what, $form_id, $user_id |
Grant or refuse a permission word |
kindly_forms_normalize |
filter | $clean, $def |
The cleaned definition before it is stored |
kindly_forms_clean_feed_{provider} |
filter | $clean, $feed |
Clean one provider's connection settings when a form is saved |
kindly_forms_created |
action | $id, $def |
A form was made |
kindly_forms_saved |
action | $id, $def, $live |
A form was saved (draft, or live) |
kindly_forms_published |
action | $id |
A draft went live |
kindly_forms_history_size |
filter | 20 |
How many versions History keeps |
kindly_forms_settings_saved |
action | $settings |
Site-wide or payment settings were saved |
kindly_forms_schema |
filter | $schema |
What GET /schema gives the builder |
kindly_forms_canvas_css |
filter | $urls |
Stylesheets the builder's canvas loads (the theme's, Kindly's element styles, the forms styles) |
kindly_forms_templates_dirs |
filter | $dirs |
Folders of template files |
kindly_forms_templates |
filter | $list |
The templates offered |
kindly_forms_template |
filter | $def, $key, $template |
The definition a template makes |
kindly_forms_import_fluent_field |
filter | null, $element, $ctx |
Return a Kindly field (or a list) for a Fluent Forms element |
kindly_forms_import_fluent_definition |
filter | $def, $item, $notes |
A Fluent Forms form after conversion |
kindly_forms_import_gravity_definition |
filter | $def, $form, $notes |
A Gravity Forms form after conversion (since 0.12.0) |
kindly_forms_gravity_addons_on |
filter | $registered |
Gravity add-ons counted as switched on, keyed by slug. A feed whose add-on isn't listed comes over switched off (since 0.12.0) |
kindly_forms_import_max |
filter | 20000 |
Most rows an entries import takes, also the most Gravity entries copied per form |
kindly_forms_legacy_converted |
action | $form_id, $post_id, $old_form |
An old page form was moved to Kindly Forms |
kindly_forms_mcp_on |
filter | $on |
Whether the AI abilities work |
Fields and showing the form#
| Hook | Type | Arguments | Use |
|---|---|---|---|
kindly_forms_field_types |
filter | $types |
Add or change field types (see below) |
kindly_forms_render_{type} |
filter | null, $field, $ctx |
Return HTML to draw a field type yourself |
kindly_forms_field_render |
filter | $field, $ctx |
Change a field before it is drawn, or return a non-array to hide it |
kindly_forms_field_choices |
filter | $choices, $field, $ctx |
A field's choices, manual or dynamic |
kindly_forms_source_rows |
filter | $rows, $source, $ctx |
Rows a dynamic source found, before they become choices |
kindly_forms_presets |
filter | $presets |
Ready-made choice lists (US states, months, ages and more) |
kindly_forms_countries |
filter | $countries |
The country list |
kindly_forms_file_groups |
filter | $groups |
Upload file type groups. Executables are never accepted |
kindly_forms_public_user_meta |
filter | [ 'description', 'nickname' ] |
User meta a user source may show |
kindly_forms_render_options |
filter | $options, $id |
Options for drawing a form |
kindly_forms_before_render |
filter | $def, $options |
The definition about to be drawn |
kindly_forms_rendered |
filter | $html, $def, $options |
The finished HTML |
kindly_forms_public_config |
filter | $config, $def |
Settings handed to the visitor's browser |
kindly_forms_enqueue |
action | $needs |
Scripts and styles the page needs (date picker, phone, captcha) |
kindly_forms_button_class |
filter | $class |
The send button's class (the theme's button class by default) |
kindly_forms_closed |
filter | null, $def, $ctx |
Return [ code, message ] to close a form |
kindly_forms_page_definition |
filter | $def |
The form shown on its landing page or answers page |
kindly_forms_webmcp |
filter | true, $def |
Whether the form describes itself to visitors' AI assistants |
Sending and entries#
| Hook | Type | Arguments | Use |
|---|---|---|---|
kindly_forms_submit_definition |
filter | $def, $input |
The definition a send is checked against |
kindly_forms_collect_{type} |
filter | null, $value, $field, $raw |
Return the cleaned value of a field type |
kindly_forms_values |
filter | $values, $def, $input |
All cleaned answers |
kindly_forms_validate_{type} |
filter | null, $value, $field, $values, $def |
Return an error message for a field type |
kindly_forms_validate |
filter | $errors, $values, $def, $input |
All errors, keyed by field name |
kindly_forms_is_spam |
filter | $spam, $def, $values, $input |
Mark a send as spam (kept quietly as spam) |
kindly_forms_token_min_age |
filter | 2 |
Seconds a token must be old before a send counts |
kindly_forms_ip_headers |
filter | [] |
Proxy headers to trust for the visitor's IP. None by default, since headers can be forged |
kindly_forms_entry_row |
filter | $row, $def, $input |
The entry about to be stored |
kindly_forms_before_insert |
action | $row, $def, $input |
Just before it is stored |
kindly_forms_submitted |
action | $entry, $def, $input |
An entry was stored (not for spam) |
kindly_forms_refused |
action | $def, $values, $reason |
A send was refused after its answers were read (spam when Akismet's answer is set to refuse); nothing was stored |
kindly_forms_event |
action | $event, $entry, $def |
Emails and connections ran for an event: submit, payment, confirmed, approved, declined, pending |
kindly_forms_event_{event} |
action | $entry, $def |
The same, for one event |
kindly_forms_submit_result |
filter | $result, $def, $entry |
What the visitor's browser gets back. For an entry waiting for an email confirmation or approval, $result['gate'] is unconfirmed or pending |
kindly_forms_entry_status |
action | $id, $new, $old |
An entry's status changed |
kindly_forms_entry_deleting |
action | $entry |
An entry is about to be deleted |
kindly_forms_smartcode |
filter | null, $group, $key, $ctx |
Return a value for your own smartcode |
kindly_forms_report_choices |
filter | $types |
Field types reported as counts per choice |
kindly_forms_report_numbers |
filter | $types |
Field types reported as averages |
Emails#
| Hook | Type | Arguments | Use |
|---|---|---|---|
kindly_forms_send_notification |
filter | true, $email, $def, $entry |
Return false to skip one email |
kindly_forms_notification_attachments |
filter | $files, $email, $def, $entry |
Files attached to an email |
kindly_forms_mail |
filter | $message, $def, $entry, $kind |
A message about to be sent in the site's email layout: to, subject, body, from, reply-to, copies, attachments |
kindly_forms_email_html |
filter | null, $body, $subject, $def |
Return your own email layout |
kindly_forms_notification_to_visitor |
filter | $to_visitor, $email |
Whether an email goes to the person who filled in the form (it is then sent in their language) |
Connections and file storage#
| Hook | Type | Arguments | Use |
|---|---|---|---|
kindly_forms_feed_providers |
filter | $providers |
Register a connection (see below) |
kindly_forms_feed_failed |
action | $feed, $entry, $def, $result |
A connection failed for good after its tries |
kindly_forms_queue_spawn |
filter | true |
Whether to start WordPress cron at once when a connection is queued |
kindly_forms_notion_version |
filter | '2026-03-11' |
The Notion API version sent |
kindly_forms_openai_model |
filter | '' |
The OpenAI model used by that connection |
kindly_forms_clearout_message |
filter | $message |
The message when an email address fails the Clearout check |
kindly_forms_storage_ops |
filter | $ops |
Each storage service's upload and link steps |
kindly_forms_storage_chunk_size |
filter | 8 MB, $provider |
Upload piece size |
kindly_forms_storage_single_max |
filter | $bytes, $provider |
Largest file sent in one request |
kindly_forms_storage_s3_min_part |
filter | 5 MB |
Smallest S3 part |
kindly_forms_storage_time_budget |
filter | $seconds |
Time one background run may spend uploading |
kindly_forms_storage_open_seconds |
filter | 300 |
How long a cloud file link made for a person works |
Payments and stock#
| Hook | Type | Arguments | Use |
|---|---|---|---|
kindly_forms_payments_on |
filter | $on |
Whether payments are on for the site |
kindly_forms_payment_gateways |
filter | $gateways |
Register a payment gateway |
kindly_forms_payment_conf |
filter | $conf, $gateway |
A gateway's settings |
kindly_forms_payment_form_settings |
filter | $settings, $def |
A form's payment settings |
kindly_forms_currencies |
filter | $list |
Currencies offered |
kindly_forms_payment_prepare |
filter | [], $def, $values, $input |
The payment worked out before the entry is stored |
kindly_forms_payment_order |
filter | $payment, $def, $values |
The order: items, totals, coupons |
kindly_forms_payment_start |
filter | null, $def, $entry, $payment, $input |
The next step for the browser: a checkout or a card to confirm |
kindly_forms_payment_result |
filter | $result, $tx, $def, $entry |
What the browser gets after a payment step |
kindly_forms_payment_paid |
action | $entry, $tx, $def |
A payment succeeded |
kindly_forms_payment_status |
action | $tx, $status, $was |
A payment's status changed |
kindly_forms_payment_refunded |
action | $tx, $refund, $full |
A refund was made |
kindly_forms_payment_reversed_statuses |
filter | [ 'refunded', 'partially-refunded', 'canceled' ] |
Statuses a late success never overwrites |
kindly_forms_payment_abandon_hours |
filter | 24 |
Hours before an unfinished payment counts as abandoned |
kindly_forms_payment_card_tries |
filter | 10 |
Cards one network address may try in an hour on cards typed on the page |
kindly_forms_payment_smart_custom |
filter | '', $key, $ctx, $tx, $subscription |
Your own payment smartcodes |
kindly_forms_subscription_payment |
action | $subscription, $tx, $entry |
A subscription was charged again |
kindly_forms_subscription_status |
action | $subscription, $status |
A subscription's status changed |
kindly_forms_payments_reset |
action | none | Payment settings were saved; cached gateway details should be dropped |
kindly_forms_coupon_ok |
filter | true, $coupon, $def, $subtotal |
Whether a coupon applies |
kindly_forms_coupon_message |
filter | $message, $reason, $coupon, $def, $subtotal |
The message when it doesn't |
kindly_forms_stripe_shipping_countries |
filter | $countries |
Countries Stripe Checkout asks shipping for |
kindly_forms_square_notification_url |
filter | $url |
Square's notification address |
kindly_forms_authnet_arb_tries |
filter | 6 |
Tries from cron to set up an Authorize.Net subscription that Authorize.Net wasn't ready to bill (E00040) before it is marked failing (since 0.12.0) |
kindly_forms_authnet_arb_wait |
filter | 5 |
Seconds between the tries made during the payment itself (since 0.12.0) |
kindly_forms_inventory_release |
action | $entry_id, $reason |
Gives an entry's stock back (fired on a failed payment) |
kindly_forms_inventory_restore |
action | $entry_id, $reason |
Takes it again (fired when a payment succeeds after all) |
PDF documents#
| Hook | Type | Arguments | Use |
|---|---|---|---|
kindly_forms_pdf_starters |
filter | $starters, $def |
Starting points in the Documents tab |
kindly_forms_pdf_fonts |
filter | $fonts |
Fonts offered |
kindly_forms_pdf_fallback_fonts |
filter | [] |
Extra fonts for characters the bundled fonts lack, such as Chinese, Japanese or Korean |
kindly_forms_pdf_papers |
filter | $sizes |
Paper sizes, in points |
kindly_forms_pdf_options |
filter | $options |
The PDF engine's options |
kindly_forms_pdf_html |
filter | $html, $def, $doc, $entry |
The document's HTML before it becomes a PDF |
kindly_forms_pdf_bytes |
filter | $bytes, $def, $doc, $entry |
The finished PDF |
kindly_forms_pdf_link_ttl |
filter | $seconds, $def, $doc |
How long a download link works (the site's setting, 7 days by default) |
kindly_forms_pdf_zip_limit |
filter | 100 |
Most entries in one zip |
Translation#
| Hook | Type | Arguments | Use |
|---|---|---|---|
kindly_forms_i18n_engine |
filter | $engine |
Which translation plugin is used |
kindly_forms_lang_current, kindly_forms_lang_default |
filter | $lang |
The current and default language |
kindly_forms_lang_list |
filter | $languages |
Languages offered |
kindly_forms_lang_locale |
filter | $locale, $lang |
The locale for a language |
kindly_forms_i18n_field_keys |
filter | $keys |
Field settings that are translated |
kindly_forms_i18n_strings |
filter | $strings, $def |
A form's words registered for translation |
kindly_forms_i18n_registered |
action | $form_id, $registered, $before |
They were registered |
kindly_forms_translate |
filter | $text, $context, $name, $form_id, $lang |
One translated text |
kindly_forms_texts_in_page |
filter | $on |
Whether the browser's words are written into the page (on with TranslatePress or Weglot) |
kindly_forms_page_texts |
filter | $texts, $def |
Those words |
See Multilingual forms.
Posts and accounts#
| Hook | Type | Arguments | Use |
|---|---|---|---|
kindly_forms_meta_key_allowed |
filter | $ok, $key, $kind |
Whether an entry may write a post or user meta key. Protected and site-internal keys never are |
kindly_forms_post_create_terms |
filter | $create, $taxonomy |
Whether a post form may make new terms (tags yes, categories no, by default) |
kindly_forms_registration_roles |
filter | $roles |
Roles a registration form may give |
kindly_forms_verify_email |
filter | $body, $user, $link |
The account verification email |
kindly_forms_user_registered |
action | $user_id, $entry, $def, $feed |
A form made an account |
kindly_forms_user_updated |
action | $user_id, $entry, $def, $feed |
A form changed an account |
kindly_forms_user_verified |
action | $user_id |
Someone verified their account |
Scheduled events#
| Event | Runs | Does |
|---|---|---|
kindly_forms_queue |
Once, right after a connection is queued | Sends what is due, 25 at a time |
kindly_forms_queue_retry |
Every 5 minutes | Sends what is due and tries failed connections again; also sets up waiting Authorize.Net subscriptions |
kindly_forms_authnet_arb_retry |
Once, a minute after Authorize.Net wasn't ready to bill a new subscription's card (since 0.12.0) | Sets up the waiting Authorize.Net subscriptions, one try each |
kindly_forms_daily |
Daily | Deletes entries past a form's "delete after" days, unconfirmed entries past the site's "delete unconfirmed" days, old logs (60 days by default) and saved progress older than the form's "keep saved answers" days (30 by default); removes unclaimed temporary uploads and left-over PDF files; ends abandoned payments; sends the weekly summary on its day |
Add a field type#
A field type is one definition that drives the builder's palette and settings, the drawing and the checking. Register it with kindly_forms_field_types:
add_filter( 'kindly_forms_field_types', function ( $types ) {
$types['member_number'] = [
'label' => __( 'Member number', 'my-plugin' ),
'group' => 'advanced', // general, choice, advanced, layout, payment or post
'icon' => 'id-card',
'tags' => 'member club id card', // words the palette search finds it by
'value' => true, // it submits an answer
'logic' => true, // offer Show when
'defaults' => [ 'label' => __( 'Member number', 'my-plugin' ), 'prefix' => 'M-' ],
// shared settings by key, in order; the type's own ones come from 'own'
'settings' => [ 'label', 'prefix', 'help', 'required', 'adminLabel', 'name', 'logic' ],
'own' => [
'prefix' => [ 'label' => __( 'Starts with', 'my-plugin' ), 'control' => 'text' ],
],
];
return $types;
} );
Set the flags your type needs: value (it submits an answer), choices, composite (an object of parts), children (it holds fields), logic (offer Show when), repeatable (it may sit in a repeating group) and one (only one per form). Any flag you leave out is filled in after the filter runs: value and logic default to on, the others to off, and group to advanced. Set 'value' => false for a type that only shows something. Then draw it, clean it and check it with the per-type filters:
add_filter( 'kindly_forms_render_member_number', function ( $html, $f, $ctx ) {
$id = kindly_forms_input_id( $f, $ctx );
return kindly_forms_wrap_open( $f, $ctx )
. kindly_forms_label( $f, $ctx, $id )
. '<input type="text"' . kindly_forms_input_attrs( $f, $ctx, $id ) . '>'
. kindly_forms_help( $f, $ctx, $id ) . kindly_forms_error( $f, $ctx, $id )
. '</div>';
}, 10, 3 );
add_filter( 'kindly_forms_collect_member_number', fn( $value, $v ) => strtoupper( sanitize_text_field( is_scalar( $v ) ? (string) $v : '' ) ), 10, 2 );
add_filter( 'kindly_forms_validate_member_number', function ( $error, $v, $f ) {
return '' === $v || str_starts_with( $v, $f['prefix'] ?? 'M-' ) ? null : __( 'Member numbers start with M-.', 'my-plugin' );
}, 10, 3 );
Return null from a per-type filter to leave that step to Kindly. A field type registered this way is in the builder for everyone: nothing is gated.
Add a connection#
A connection is a provider registered with kindly_forms_feed_providers. Its site-wide keys (connect) appear under Connections; each form's feeds get its settings. Feeds run after the entry is stored. By default they go through the queue: the visitor isn't kept waiting, and a failure is tried again every 5 minutes, up to 4 times. Every call is logged with its request and response, secrets removed.
add_filter( 'kindly_forms_feed_providers', function ( $p ) {
$p['club_desk'] = [
'label' => 'Club Desk',
'group' => 'crm', // crm, email, messaging, automation, data, payments, accounts or other
'icon' => 'users',
'description' => __( 'Add new members to Club Desk.', 'my-plugin' ),
'connect' => [ 'key' => [ 'label' => __( 'API key', 'my-plugin' ), 'type' => 'password', 'required' => true ] ],
'settings' => [
'email' => [ 'label' => __( 'Email', 'my-plugin' ), 'control' => 'text', 'required' => true, 'smart' => true ],
'name' => [ 'label' => __( 'Name', 'my-plugin' ), 'control' => 'text', 'smart' => true ],
],
'test' => fn( $c ) => '' !== ( $c['key'] ?? '' ) ? true : new WP_Error( 'key', __( 'Add the API key.', 'my-plugin' ) ),
'send' => function ( $feed, $entry, $def, $c ) {
$r = wp_safe_remote_post( 'https://api.example.org/members', [
'headers' => [ 'Authorization' => 'Bearer ' . $c['key'], 'Content-Type' => 'application/json' ],
'body' => wp_json_encode( [ 'email' => $feed['map']['email'], 'name' => $feed['map']['name'] ] ),
] );
if ( is_wp_error( $r ) ) return $r;
$code = wp_remote_retrieve_response_code( $r );
return [ 'ok' => $code < 300, 'message' => 'Answered ' . $code, 'request' => [ 'email' => $feed['map']['email'] ], 'response' => wp_remote_retrieve_body( $r ) ];
},
];
return $p;
} );
Settings marked smart take smartcodes; by the time send runs, $feed['map'] holds them filled in from the entry. send returns true, a WP_Error (an error with the code final is not tried again), or [ ok, message, request, response ] for the log. Other keys: map (a list of fields to fill, or a callable that fetches them from the service), lists (a callable for remote choices such as lists or tags), oauth, and async (false sends during the visitor's request).