Contents

Submission Form — Plugixa Testimonial

Let visitors submit testimonials directly from your frontend. The form supports inline and modal display modes, per-field real-time validation, photo upload, custom fields (Pro), multilingual passthrough, and reCAPTCHA v2 or v3 protection.

Enabling the form

The form is disabled by default.

  1. Go to Plugixa Testimonial → Settings → Submission.
  2. Toggle Enable Submission Form on.
  3. Configure required fields, reCAPTCHA, and photo upload.
  4. Save.

When disabled, [plugixa_testimonial_form] renders nothing on the frontend.

Submission settings tab

Place the shortcode

[plugixa_testimonial_form]

Or use inside a Gutenberg Shortcode block, a widget, or a PHP template:

<?php echo do_shortcode( '[plugixa_testimonial_form]' ); ?>

Display modes

Inline

Form renders directly on the page. All fields immediately visible, card layout with pill-button tabs for logical grouping.

[plugixa_testimonial_form form_style="inline"]

Use when the form is the primary content of the page (e.g., a dedicated “Share Your Testimonial” page).

Inline submission form

A button is rendered on the page. Clicking opens a modal dialog containing the form.

[plugixa_testimonial_form form_style="modal" button_text="Share Your Experience"]

The modal:

  • Uses a two-layer structure: fixed backdrop (z-index: 99998) + scrollable centering container (z-index: 99999, overflow-y: auto).
  • White rounded panel max-w-lg with close X button.
  • Dismisses on Escape key, close button, or click outside (backdrop click).
  • Locks body scroll while open.
  • Auto-closes on successful submission.

Use when you want to offer submissions alongside other content without taking up page space.

Modal submission form

Form fields

Field Type Default required Notes
Client Name Text ✓ Required by default.
Email Email ✓ Required. Stored in meta table under submitter_email key.
Role / Position Text — Optional.
Company Text — Optional.
Website URL URL — Validated format.
Testimonial Text Textarea ✓ Required. Char counter shown.
Rating Star selector — Interactive 1–5 star rating.
Photo File upload — Drag-and-drop style UI. Validated against max_photo_size + allowed_photo_types.
Custom fields PRO Varies Varies Fields with show_in_frontend = true. See Custom Fields.

Submissions default to pending status (configurable in Settings → Submission → Default Status).

Field validation

All fields use real-time validation:

  • On blur — the FormValidator class validates each field as the user moves away.
  • On input — errors clear as the user types (if previously shown).
  • On tab change (modal or multi-tab forms) — per-tab validation before advancing.
  • On submit — server-side validation; per-field errors are mapped back to the correct field.

Required, email, URL, number, and text-length validations are built in. Inline red border + error message appears under invalid fields.

Client-side validation is a UX aid — server-side validation is authoritative.

Photo upload

When photo_upload_enabled is on in settings:

  • A custom drag-and-drop area appears (dashed border, SVG upload icon, helper text).
  • Hidden <input type="file"> overlay catches drops and clicks.
  • On file select, FileReader generates an instant preview (.has-preview class swap).
  • Submissions with a photo use multipart/form-data; without a photo they use JSON.

Server-side checks

  • File type — must match the allowed_photo_types setting (JPEG/PNG/GIF/WebP).
  • File size — must be ≤ max_photo_size MB (default 2 MB).
  • Uses media_handle_upload() to create a WordPress Media Library attachment.
  • Stores the resulting attachment ID as client_photo_id on the testimonial.

reCAPTCHA

Two versions are supported:

Version Type Description
v2 Checkbox Visible “I’m not a robot” checkbox. User clicks before submit.
v3 Invisible Invisible Runs in the background; returns a score 0.0–1.0. No interaction required.

Setup

  1. Register your site at Google reCAPTCHA admin.
  2. Pick v2 or v3.
  3. Copy the Site Key and Secret Key.
  4. In Plugixa Testimonial → Settings → Submission:
    • Toggle Enable reCAPTCHA on.
    • Select the reCAPTCHA Version.
    • Paste the keys.
    • For v3, set the Score Threshold (default 0.5 — submissions scoring below this are rejected).
  5. Save.

Testing

  • v2 — visit a page with the form, verify the checkbox appears, complete and submit.
  • v3 — submit the form; verify success without visible reCAPTCHA UI. The v3 badge may appear in a corner.

If submissions fail:

  • The site key matches the reCAPTCHA version (v2 keys don’t work with v3 and vice versa).
  • Your domain is registered in the reCAPTCHA admin.
  • The secret key is correct.

Approval workflow

  1. Submission — visitor fills out and submits.
  2. Validation — required fields, reCAPTCHA, photo type/size.
  3. Storage — saved with default_submission_status (usually pending).
  4. Notification — if notification_enabled in Settings → Notifications, admin email sent.
  5. Confirmation — the configured success message renders (with a success animation for 1.5 seconds).
  6. Review — admin reviews in Plugixa Testimonial → Testimonials filtered by Pending.
  7. Approval or rejection — admin sets status to approved (makes it live) or rejected.

Changing the default submission status

In Settings → Submission → Default Status:

  • pending (recommended) — requires manual approval.
  • draft — saved but hidden; requires status change to approved.
  • approved — immediately visible on the frontend. Use only if you trust all submitters.

Multilingual passthrough

When WPML or Polylang is active:

  • The submission form automatically sends the current site language as language_code on submit.
  • The new testimonial is created with that language_code.
  • No UI change needed — the JS form reads the language from the page.

See Multilingual.

When a testimonial request link is visited (e.g., /share-testimonial/?pxt_request_token=...):

  • The submission form detects the token via URL query parameter.
  • Validates the token via REST API.
  • Pre-fills the name and email fields from the request record.
  • On submit, the request status changes from pending to submitted and links to the created testimonial.

See Testimonial Requests.

Success animation

On successful submission, the form:

  1. Shows a green success message with the configured thank-you text.
  2. Adds a brief success animation (1.5-second transition).
  3. Resets the form fields to blank (for inline mode) or auto-closes (for modal mode).

Custom fields on the form PRO

Pro custom fields with show_in_frontend = true appear automatically in the submission form, rendered by field type:

  • text / email / url / number / date — native input types.
  • textarea — multiline.
  • select — dropdown with defined options.
  • checkbox — option groups.
  • color — color picker.

Validation and required-field enforcement apply per-field.

See Custom Fields.

REST endpoint

The form submits to:

POST /wp-json/plugixatestimonial/v1/frontend/submit
Content-Type: application/json   (or multipart/form-data when a photo is attached)

{
  "client_name": "Jane",
  "client_role": "CEO",
  "client_company": "Acme",
  "testimonial_text": "...",
  "rating": 5,
  "submitter_email": "jane@example.com",
  "website_url": "https://...",
  "custom_fields": { ... },
  "language_code": "en",
  "pxt_request_token": "...",
  "g-recaptcha-response": "..."
}

Response is JSON with per-field validation errors on failure.

Troubleshooting

Form renders but doesn’t submit

  • Check browser console for JS errors.
  • Verify submission_enabled is on.
  • Test with other plugins deactivated to rule out conflicts.

“reCAPTCHA verification failed”

  • Site key and secret key match the selected version.
  • Domain is registered with Google reCAPTCHA.
  • For v3, try lowering the score threshold to 0.3 if legitimate users are being blocked.

Photo upload fails

  • File size ≤ max_photo_size MB (default 2 MB).
  • File type in allowed_photo_types list.
  • PHP upload_max_filesize and post_max_size are high enough.
  • Check for JS errors in the browser console.
  • Verify the modal trigger button has the class pxt-custom-open-modal-btn.

Quick Links

Plugin page Changelog