ProofPulse

A modern, developer-first WordPress testimonial plugin. It ships — for free — the layout, collection, and styling features that competing plugins typically gate behind a pro license (Strong Testimonials, Real Testimonials, Testimonial Widgets, Testimonial Free).

Topics: wordpress · testimonials · reviews · gutenberg · block-editor · star-ratings · slider · carousel · masonry · rtl · wpml · polylang · rest-api · media-uploads · video-recording · storybook · typescript · lit-element · dark-mode · responsive · form-builder · schema-org

Quick facts:

• Testimonials render through Lit 2 web components (Shadow DOM) hydrated from a REST API
• Authored with a Gutenberg block or shortcodes
• Server-rendered markup fallback when JavaScript is disabled
• 5 responsive layouts: slider, carousel, grid, masonry, list
• 10+ layout-style variants (card, gradient, glass, minimal, border-left, outline, classic, modern, rounded, bordered)
• Advanced features: filtering, search, sorting, pagination, lazy-load images, read-more truncation, half-star ratings
• Slider/carousel UX: pause-on-hover, drag + touch swipe, adaptive height, transition speed, top-right nav
• RTL support, per-display color theming, avatar size + initials fallback, responsive columns/gap, section title
• Video testimonials: embeds or in-browser recording (MediaRecorder → validated upload); inline or lightbox
• Frontend submission form with honeypot + reCAPTCHA v3, multiple form presets, optional popup/lightbox
• Email: admin notification, submitter auto-responder, publish-approval notice; optional auto-publish by rating
• JSON-LD Review schema (toggle) + AggregateRating SEO markup
• Admin: Google Fonts, custom CSS/JS, JSON and CSV import/export, shortcode generator
• Integrations: Elementor widget, Polylang/WPML multilingual

Tech stack & tools used

Build & develop

npm install
npm run build      # production build → assets/js, assets/css
npm run dev        # Vite dev server (HMR for component work)

Build outputs (committed):

• assets/js/block.js — Gutenberg block registration + all Lit display components + API client. Loaded in both the editor and the frontend.
• assets/js/frontend.js — standalone JavaScript for frontend (lazy-loaded separately).
• assets/css/frontend.css — global design tokens (CSS custom properties) + light-DOM fallback layout styles + component styles.
• src/styles/frontend.ts — TypeScript styles file (imported in components).

Storybook

The Lit layout components render in isolation in Storybook — no WordPress install or live REST API needed. Stories set testimonials directly from mock fixtures (src/stories/fixtures.ts), so all 10 layout styles can be previewed and tweaked with hot reload.

npm run storybook        # dev server at http://localhost:6006
npm run build-storybook  # static build → storybook-static/ (git-ignored)

Stories live in src/stories/. Layouts.stories.ts covers every layout (card, minimal, modern, outline, classic, border-left, gradient, glass, bordered, rounded) plus single-item, video, hidden-rating, and empty states. The Gutenberg block editor (React/@wordpress/*) is intentionally out of scope — only the framework-agnostic Lit display layer is storied.

Features implemented

Core data model

• Testimonial CPT (proofpulse_tstml) with category & tag taxonomies
• Manual moderation via pending status
• Meta: rating (half-star, 0.5–5), video URL, author website URL, photo (featured image)
• Extended identity fields: company, job title, location, country, reviewer avatar, company logo, social profiles (Facebook, X/Twitter, LinkedIn, Instagram, YouTube, GitHub)
• Unlimited custom fields (admin visual repeater builder + per-testimonial values)
• Admin list columns (photo, rating, category, tags, video) with sortable rating

Frontend display

• Layouts: slider, carousel, grid, masonry, list
• Layout styles: card, minimal, border-left, outline, gradient, glass, classic, modern, rounded, bordered
• Element ordering: drag-to-sort content, rating, author, video, custom fields, and category (global default + per-block override)
• Slider / carousel UX: pause-on-hover, mouse drag + touch swipe, slider adaptive height, configurable transition speed, arrows/dots toggles, top-right nav option
• RTL (right-to-left) across every layout
• Per-display colors: card background, text, accent, star (CSS custom properties that pierce the Shadow DOM)
• Avatar: size control + initials fallback when no photo
• Responsive: per-device columns (tablet/mobile) + gap (grid); optional section title heading
• Video: YouTube/Vimeo embeds or direct <video> files; inline or lightbox playback
• Pagination, lazy-loaded images & video, half-star ratings (including 0.5-star increments)
• Read-more / content truncation (character or word limit with expand button)
• Controls bar: instant search, category filter chips, rating filter, multi-field sorting (grid / masonry / list)
• Category/tag filtering, multiple instances per page, sidebar widgets (display + average rating)
• Server-rendered fallback inside every custom element (works when JS is disabled)
• RatingSummary element: average rating, total reviews, 1–5 star breakdown

Authoring

• Gutenberg block with inspector controls (layout, style picker, columns, slider/carousel options, element order)
• Shortcodes (see below)

Submission & collection

• Frontend submission form (Lit) via REST POST
• Fields: name, email, content, rating, video URL, website, category, tags, custom fields
• In-browser video recording (MediaRecorder) → POST /upload-video (strict type/size validation, stored as attachment)
• Multiple form presets — each with its own name, button text, and custom-field subset ([proofpulse_form id="..."])
• Optional popup / lightbox form (trigger button + native <dialog>)
• Drag-sortable custom-field builder (admin)
• Honeypot + reCAPTCHA v3, admin notification + submitter auto-responder
• Publish-approval email to the reviewer (on pending → publish); optional auto-publish by star-rating threshold (gated on a passed reCAPTCHA)

Settings (admin)

• Spam protection (reCAPTCHA v3 keys)
• Custom form fields (drag-sortable visual builder) + global field order
• Forms tab (multiple form presets)
• Display & Code: schema on/off, auto-publish threshold, Google Font, custom CSS + custom JS
• Shortcode generator with live output + copy button
• Import / Export: JSON and CSV (CSV-safe export, auto-detected import)

Rating aggregation

• Average rating, total reviews, 1–5 star breakdown
• Custom <proofpulse-rating-summary> element, rating block layout, and [proofpulse_rating] shortcode
• AggregateRating JSON-LD schema emitted alongside the summary

SEO / data

• JSON-LD Review schema output (toggleable) + AggregateRating
• REST listing + filtering; JSON and CSV import/export

Integrations

• Elementor: a ProofPulse Testimonials widget (registered only when Elementor is active) reusing the shared renderer
• Polylang / WPML: translatable CPT + taxonomies, registered strings, and a shipped wpml-config.xml

Shortcodes

All tags are namespaced with proofpulse_ to avoid collisions with other testimonial plugins.

Back-compat: the old un-namespaced tags ([testimonials], [testimonials_grid], [testimonial_form], [testimonial_rating], …) still work, but only when no other active plugin has claimed the same tag. Prefer the proofpulse_* tags.

Common attributes (kebab-case, mirror the block attributes):

[proofpulse_grid category="clients" tags="vip,2024" limit="6" columns="3"
  style="gradient" show-rating="true" paginate="true" class="my-wrap"]

Shortcodes share the exact same renderer as the Gutenberg block, so output, defaults, and sanitization stay identical.

REST API

Namespace proofpulse/v1:

• GET /testimonials — category, tag, tags, per_page, page, search, orderby (newest/oldest/highest/lowest/random), min_rating; returns items + X-WP-Total / X-WP-TotalPages headers
• POST /testimonials — public submission (honeypot + optional reCAPTCHA), saved as pending (or publish when auto-publish + reCAPTCHA pass)
• POST /upload-video — public recorded-video upload; strict type (webm/mp4/mov) + 25 MB cap, stored as an attachment, returns { id, url }
• GET /categories — non-empty testimonial categories (slug, name, count) for the filter chips
• GET /rating-summary — category, tags; returns average, total, count, and a 1–5 breakdown
• GET /settings — public config for the submission form; form param scopes to a preset (reCAPTCHA site key, custom-field definitions, button + success text)

Architecture & conventions (followed strictly)

These rules are intentional and must be kept when extending the plugin:

1. Prefixing. Everything is namespaced/prefixed proofpulse / ProofPulse\ — post type, taxonomies, meta keys, option names, REST namespace, CSS classes, custom-element tags, script/style handles.

2. Class loading. PSR-style namespace ProofPulse\… resolved by a flat autoloader against src/php/<ShortClassName>.php. One class per file; init via a static init() called from proofpulse.php.

3. Rendering pipeline. The browser upgrades a server-printed custom element (e.g. <proofpulse-grid>) that fetches via REST and renders into Shadow DOM. The server also prints a styled light-DOM fallback inside the element for the no-JS case. Never duplicate display logic — block and shortcodes both call the single shared render_testimonial_block().

4. Single bundle, no un-versioned sub-imports. block.js inlines the components; it must not split into relative ES imports (those aren't cache-busted and serve stale code). Assets are cache-busted with filemtime() as the version.

5. Shadow-DOM styling + design tokens. Component styles live in the component (static styles), reusing shared css fragments (layout-styles, stars, pagination). Visual values come from --proofpulse-* custom properties (defined in frontend.css, they pierce the shadow boundary) with literal fallbacks so components survive even if the global sheet is missing. The card-variant styles consume:

   • --proofpulse-bg-card — card background (minimal, outline, glass, classic)
   • --proofpulse-color-primary — accent border (border-left, modern)
   • --proofpulse-text-color — card text (gradient)
   • --proofpulse-spacing-sm, --proofpulse-font-size-sm, --proofpulse-bg-muted — shared spacing/typography

   The PHP renderer also emits --proofpulse-text-color (and --proofpulse-grid-gap) inline on the wrapper so per-display color controls propagate into Shadow DOM without an extra stylesheet.

6. BEM-ish class names. proofpulse-{component}__{element}--{modifier}; layout-style modifier is always proofpulse-card--{style}.

7. Security. Escape on output (esc_*), sanitize on input (sanitize_*, wp_kses_post), nonce + capability checks on admin writes, permission_callback on every REST route, honeypot + reCAPTCHA on public submission.

8. i18n. All user-facing strings wrapped with the proofpulse text domain.

9. Field-order contract. Order flows: global Settings default → per-instance override → applied identically across every layout and the server fallback.

Project layout

proofpulse.php          Bootstrap: constants, autoloader, hooks, block + shortcode render,
                        custom CSS/JS + Google Font output, color sanitizer
wpml-config.xml         WPML translatable types/taxonomies + admin strings
src/php/                CPT, REST_API, Settings, CustomFields, Forms, ImportExport, Schema,
                        Shortcodes, TestimonialWidget, RatingSummaryWidget, Compat,
                        ElementorIntegration, ElementorTestimonialWidget, Timber
src/components/         Lit display components (Slider, Grid, Masonry, Carousel, List,
                        SubmissionForm, RatingSummary) + shared helpers (author,
                        controls, read-more, video) + css/render utilities
src/layouts/            Layout-style definitions (card, gradient, glass, …)
src/block/              Gutenberg block (edit/save/index, block.json, editor.scss, templates)
src/styles/             Design tokens (frontend.ts), layout styles, component styles
src/api/                REST client and service layer
src/stories/            Storybook stories + mock fixtures
src/templates/          Twig templates (Timber)
admin/                  Settings page assets (admin.php, admin.js, admin.css)

Roadmap

See IMPLEMENTATION-TRACKER.md (status against the codebase), IMPLEMENTATION-TRACKER-2.md (full feature spec), and FEATURE-GAP-VS-REAL-TESTIMONIALS.md (parity vs. the Real Testimonials plugin — now complete except retina images, which needs an attachment-ID media rework).

Done: shortcodes · read-more · AJAX filter/search/sort · rating summary · extended data fields · pre-designed templates · slider UX (hover/drag/swipe/adaptive/speed/nav) · RTL · per-display colors · Google Fonts · avatar size + fallback · responsive columns/gap · section title · video lightbox + in-browser recording · multiple forms + popup · auto-publish + approval email · CSV import/export · schema toggle · custom CSS/JS · shortcode generator · standalone rating widget · Elementor · Polylang/WPML.

License

GPL-2.0+