Add WPUF post form fields reference documentation #1695
Conversation
Introduces a comprehensive Markdown reference for all available WPUF (WordPress User Frontend) post form fields, including field types, properties, options, Pro vs Free distinctions, validation rules, templates, and usage guidelines for AI-driven form creation
WalkthroughAdds a new Markdown prompt/reference file for an AI Form Builder under includes/AI, detailing WPUF form field taxonomy (Free/Pro), standardized CREATE/MODIFY JSON formats, validation rules, templates, error handling, and form settings. No code or exported/public entities were modified. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Assessment against linked issues
Assessment against linked issues: Out-of-scope changes
Suggested labels
Poem
✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (6)
includes/AI/wpuf-post-form-fields-reference.mdc (6)
1219-1225: Out-of-scope “User Registration Form” in a Post Form reference.This section introduces
passwordand user registration semantics, which belong to registration/profile forms, not post forms. Remove or relocate to a separate Registration Forms reference.-#### User Registration Form - - `text_field` (First Name, required) - - `text_field` (Last Name, required) - - `email_address` (Email, required) - - `password` (Password, required) - - `checkbox_field` (Terms & Conditions, required)
441-448: Meta key rules may be overly restrictive.“Only letters and underscores allowed” and JS-style
/\W/greplacement may not reflect how WPUF/PHP generates meta keys. Consider aligning with actual generation logic and allow digits. Otherwise the AI may reject valid keys or create incompatible ones.
756-765: SVG and archive formats note.Allowing
svgand executable archive formats can be a security risk. At minimum, add a caution and recommend server-side hardening or disable by default.
332-344: Add a “Versioning and source of truth” preface.State the WPUF version(s) this reference targets and how to update when fields/settings change. Reduces drift and contradictions like those noted above.
345-358: Taxonomy Free/Pro wording.“Taxonomy | Free (basic), Pro (custom)”—clarify precisely which capabilities need Pro (custom taxonomies? hierarchical UI? AJAX?). Ambiguity causes mis-scaffolding by the AI.
171-185: Validation rules: enforce uniqueness and casing once.Great to have naming rules; add explicit conflict handling (rename-on-collision strategy) to avoid silent duplicates when the AI autogenerates fields.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
includes/AI/wpuf-post-form-fields-reference.mdc(1 hunks)
🔇 Additional comments (7)
includes/AI/wpuf-post-form-fields-reference.mdc (7)
84-87: Inconsistent Free vs Pro classification for multiple fields.Examples:
- multiple_select: PRO (Lines 84-87) vs Free (Lines 370-371)
- column_field: PRO (Lines 104-106) vs Free (Lines 378-379)
- recaptcha: PRO (Lines 95-97) vs Free (Lines 389-391)
Please reconcile to a single truth and update all examples accordingly.
Would you like me to run a verification pass against the codebase and official docs to produce a canonical Free/Pro matrix?
Also applies to: 104-106, 389-391, 95-97, 370-371, 378-379
588-597: Overclaiming nesting support.“Nesting repeat_field within repeat_field” and “nested columns” are often unsupported or fragile in form builders. Confirm actual WPUF capabilities before instructing AI to use them; otherwise forms will break.
If unsupported, add an explicit “not supported” note and remove the nested examples.
Also applies to: 626-655
330-358: Free/Pro settings and payments need verification.Claims like “Basic payment options (pay-per-post) available in Free” and “Advanced payment options in Pro” must match actual product tiers. Incorrect guidance will mislead users.
Do you want me to compile a definitive matrix of form settings vs. editions (Free/Pro) based on the current code and docs?
Also applies to: 564-579, 1334-1367
188-206: Linked issue #1084 (AJAX category blank on edit) is not addressed.This PR adds docs only and won’t fix the edit-time prefill bug. Either:
- include the actual code fix in this or a separate PR, or
- keep #1084 open and add a “Troubleshooting: AJAX taxonomy prefill on edit” note here (symptoms, expected behavior, config checklist, known versions affected, and link to the fix once merged).
Minimal doc add (if you choose to document):
+### Taxonomy (Category) – AJAX and Edit Prefill +- Use the `taxonomy` field bound to the correct taxonomy slug (e.g., `category`). +- When editing existing posts, previously selected terms should auto-populate. +- If values appear blank on edit: + - Ensure the edit page loads the same form used to create the post. + - Verify the field is configured for the same taxonomy and selection mode (AJAX vs non-AJAX). + - Confirm no custom code filters are clearing term values. + - Test on WPUF >= version X.Y.Z once the fix for issue #1084 is released.Also applies to: 245-273
1369-1403: Notification placeholders need validation.Placeholders such as
{author_bio}and{custom_FIELD_NAME}may not be supported. Please verify and list only supported tokens.
393-406: Address/country/phone field names.Confirm
country_list_fieldexists separately fromaddress_field. If country is only a subfield ofaddress_field, removecountry_list_fieldto avoid confusion.
1-36: Scope/invalid-request policy is solid.Clear boundaries and error shape look good.
| ### PRO FIELDS (Require WPUF Pro) | ||
| **IMPORTANT**: When users request these fields, inform them these require WPUF Pro: | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Contradictory guidance on PRO fields (warn vs. silent use).
You state to inform users that PRO fields require WPUF Pro (Lines 68-70), but later instruct to use them “without any fallbacks or warnings” (Lines 107-109). Pick one consistent rule.
Suggested fix:
-### HANDLING PRO FIELD REQUESTS
-When a user requests a PRO field, use the PRO field directly without any fallbacks or warnings.
+### HANDLING PRO FIELD REQUESTS
+When a user requests a PRO field, clearly indicate it requires WPUF Pro and proceed only if the user confirms Pro is available; otherwise, suggest a free alternative when feasible.Also applies to: 107-109
🤖 Prompt for AI Agents
In includes/AI/wpuf-post-form-fields-reference.mdc around lines 68-70 and
107-109 there is contradictory guidance: the header tells authors to inform
users that PRO fields require WPUF Pro, while later text says to use them
“without any fallbacks or warnings.” Pick one consistent policy and make the
copy consistent across both places: either change the header (68-70) to allow
silent use and remove the warning language, or change the later section
(107-109) to add the same explicit warning and recommend handling (e.g., feature
gate, messaging or graceful fallback). Update both locations so the document
consistently instructs authors to either always warn or always allow silent use,
and adjust the example wording to match the chosen policy.
| - `recaptcha` - Google reCAPTCHA (PRO) | ||
| - `ratings` - Star rating field (PRO) | ||
| - `linear_scale` - 1-10 scale rating (PRO) | ||
| - `qr_code` - QR code generator (PRO) | ||
| - `embed` - oEmbed content (PRO) | ||
| - `shortcode` - WordPress shortcode (PRO) | ||
| - `action_hook` - Custom action hook (PRO) | ||
| - `toc` - Terms and conditions checkbox with full text display (PRO) |
There was a problem hiding this comment.
Likely unsupported/incorrect field types present.
These look non-existent or misnamed for WPUF post forms: qr_code, linear_scale, multiple_choice_grid, checkbox_grid, embed (oEmbed?), math_captcha. Keeping them will cause the AI to generate invalid forms.
Action: remove or clearly mark as “not supported by WPUF”. If some are add-on specific, denote the exact add-on and version.
Apply this minimal cleanup (remove clearly non-WPUF items):
- - `checkbox_grid` - Checkbox grid layout (PRO)
- - `multiple_choice_grid` - Radio button grid (PRO)
- - `linear_scale` - 1-10 scale rating (PRO)
- - `qr_code` - QR code generator (PRO)
- - `math_captcha` - Math CAPTCHA (PRO)Also applies to: 408-418
| ### For CREATE requests | ||
| ```json | ||
| { | ||
| "action": "create", | ||
| "form_title": "Descriptive Form Title", | ||
| "form_description": "Brief form description", | ||
| "fields": [ | ||
| { | ||
| "id": "unique_id", | ||
| "type": "WPUF_FIELD_TYPE", | ||
| "label": "Field Label", | ||
| "name": "field_name", | ||
| "required": true/false, | ||
| "placeholder": "Optional placeholder", | ||
| "help_text": "Optional help text", | ||
| "default": "Optional default value", | ||
| "options": [ | ||
| {"value": "val1", "label": "Label 1"} | ||
| ] | ||
| } | ||
| ], | ||
| "settings": { | ||
| "submit_button_text": "Submit", | ||
| "success_message": "Thank you for your submission!", | ||
| "redirect_url": "", | ||
| "form_template": "default" | ||
| }, | ||
| "conversation_context": { | ||
| "form_id": "form_123", | ||
| "created_at": "timestamp", | ||
| "modifications": [] | ||
| } | ||
| } |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Schema drift: type vs template, boolean vs "yes"/"no", options array vs map, and wrong field keys.
The doc mixes:
type(Response Format) vstemplate(Templates)required: true/false vs "yes"/"no"options: array [{value,label}] vs map {key: "Label"}- Uses non-existent
phone_numbertype in examples
Unify to one canonical schema to avoid broken AI output. Suggested to standardize on WPUF export-style:
- key:
template required: "yes" | "no"options: object map
Edits:
@@ For CREATE requests (Lines ~116-146)
- "type": "WPUF_FIELD_TYPE",
+ "template": "WPUF_FIELD_TYPE",
"label": "Field Label",
"name": "field_name",
- "required": true/false,
+ "required": "yes"|"no",
- "help_text": "Optional help text",
+ "help": "Optional help text",
- "options": [
- {"value": "val1", "label": "Label 1"}
- ]
+ "options": {
+ "val1": "Label 1"
+ }
@@ MODIFY example (Lines ~279-286)
- "required": true
+ "required": "yes"
@@ Contact Form example (Lines ~214-218)
- {"type": "phone_number", "name": "phone", "label": "Phone", "required": false},
+ {"template": "phone_field", "name": "phone", "label": "Phone", "required": "no"},
@@ “Add a phone number field” (Lines ~296-304)
- "type": "phone_number",
+ "template": "phone_field",
- "required": false,
+ "required": "no",Also applies to: 151-166, 811-828, 832-843, 845-859, 210-219, 291-307
🤖 Prompt for AI Agents
In includes/AI/wpuf-post-form-fields-reference.mdc around lines 114 to 146 (and
also apply the same changes to ranges 151-166, 210-219, 291-307, 811-828,
832-843, 845-859), the examples mix inconsistent field schema variants (using
both type and template, boolean true/false vs "yes"/"no", options as arrays vs
maps, and a non-existent phone_number type). Standardize all examples to the
canonical WPUF export-style: replace any "type" keys with "template", make
"required" use string values "yes" or "no", convert options arrays into object
maps {key: "Label"}, remove or replace invalid field templates like phone_number
with supported templates, and ensure field key names match actual WPUF export
keys; update every affected example block accordingly so they all follow the
same schema.
| ### Contact Form | ||
| ```json | ||
| { | ||
| "fields": [ | ||
| {"type": "text_field", "name": "full_name", "label": "Full Name", "required": true}, | ||
| {"type": "email_address", "name": "email", "label": "Email", "required": true}, | ||
| {"type": "phone_number", "name": "phone", "label": "Phone", "required": false}, | ||
| {"type": "textarea_field", "name": "message", "label": "Message", "required": true} | ||
| ] | ||
| } |
There was a problem hiding this comment.
Fix “phone_number” type to phone_field.
Non-existent type will break AI output. See unified schema comment for diffs.
Also applies to: 291-307
🤖 Prompt for AI Agents
In includes/AI/wpuf-post-form-fields-reference.mdc around lines 210 to 219, the
Contact Form JSON uses an invalid field type "phone_number" which will break AI
output; change the type to the correct "phone_field" for that entry, and make
the same replacement for the other occurrence noted at lines 291–307 so both
snippets use "phone_field" consistently with the unified schema.
| | `shortcode` | Shortcode | Insert WordPress shortcodes | Any valid WordPress shortcode, custom shortcodes, dynamic content | | ||
| | `action_hook` | Action Hook | Execute custom PHP actions | Custom PHP functions, WordPress hooks, form processing actions | | ||
| | `toc` | Table of Contents | Generate table of contents | Auto-generated from headings, customizable styling, scroll navigation | | ||
| | `ratings` | Ratings | Star rating system | 1-10 stars, customizable icons, average calculation, user voting | | ||
| | `step_start` | Multi-Step | Multi-step form navigation | Unlimited steps, progress bar, step validation, conditional navigation | |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Mislabeling of toc field.
You correctly describe toc earlier as “Terms and conditions” (Lines 193-199, 222-231) but later list it as “Table of Contents” (Lines 410-414). Rename to “Terms and Conditions” everywhere.
-| `toc` | Table of Contents | Generate table of contents | Auto-generated from headings, customizable styling, scroll navigation |
+| `toc` | Terms and Conditions | Captures acceptance of terms text | Checkbox with full terms text (`toc_text`) |Also applies to: 193-199, 222-231
🤖 Prompt for AI Agents
In includes/AI/wpuf-post-form-fields-reference.mdc around lines 410-414 (and
also update occurrences at 193-199 and 222-231), the `toc` field is mislabeled
as "Table of Contents"; change the display name/label to "Terms and Conditions"
and update any short description text to match that meaning so all three
locations consistently describe `toc` as Terms and Conditions (ensure casing and
phrasing match the earlier occurrences).
| ### File Upload Options | ||
| - **max_size**: Maximum file size in bytes | ||
| - **allowed_extensions**: Allowed file extensions | ||
| - **max_files**: Maximum number of files | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Duplicate “File Upload Options” section.
You define file upload options twice with different defaults. Keep one canonical list.
-### File Upload Options
-- **max_size**: Maximum file size in bytes
-- **allowed_extensions**: Allowed file extensions
-- **max_files**: Maximum number of filesRetain the later, more complete section (Lines 519-527) and adjust defaults there if needed.
Also applies to: 519-527
🤖 Prompt for AI Agents
In includes/AI/wpuf-post-form-fields-reference.mdc around lines 481-485 there is
a duplicate "File Upload Options" block that conflicts with the canonical
version at lines 519-527; remove the earlier duplicate block (lines 481-485) so
only the later, more complete section remains, then verify and if necessary
update the defaults in the canonical block at 519-527 to the intended values to
ensure consistency.
fixes #1084
Introduces a comprehensive Markdown reference for all available WPUF (WordPress User Frontend) post form fields, including field types, properties, options, Pro vs Free distinctions, validation rules, templates, and usage guidelines for AI-driven form creation
Summary by CodeRabbit