=== WP Testimonials & Social Proof ===
Contributors:      vetrisuriya
Donate link:       https://vetrisuriya.in/donate
Tags:              testimonials, reviews, star ratings, social proof, shortcode
Requires at least: 6.0
Tested up to:      6.7
Stable tag:        1.0.0
Requires PHP:      8.0
License:           GPL-2.0-or-later
License URI:       https://www.gnu.org/licenses/gpl-2.0.html

A complete testimonial management system with star ratings, front-end submission, AJAX filtering, REST API, and a sidebar widget. No page builders required.

== Description ==

**WP Testimonials & Social Proof** gives your site a professional testimonial system without the bloat of a page builder plugin. Manage testimonials from a dedicated admin area, display them anywhere with a shortcode, and let customers submit their own reviews directly from your website.

= Core Features =

* **Testimonials CPT** — dedicated post type with category taxonomy
* **Star Ratings** — 1–5 stars stored as post meta, shown in shortcode output
* **`[testimonials]` shortcode** — display testimonials anywhere with layout, columns, rating filter, and category filter attributes
* **`[testimonial_form]` shortcode** — front-end submission form with honeypot spam protection
* **AJAX filter** — visitors filter by star rating or category without a page reload
* **AJAX load more** — paginate testimonials without reloading the page
* **Moderation workflow** — new submissions go to Pending; admin approves before they go live. Optional auto-approve toggle in Settings.
* **Admin notification email** — receive an email with submission details when a new testimonial is submitted
* **Widget** — Featured Testimonials sidebar widget with configurable count and minimum rating
* **REST API** — `GET /wp-json/wptsm/v1/testimonials` for headless or mobile use
* **View counter** — tracks impressions per testimonial using post meta
* **Global stats** — site-wide submission counter using the Options API
* **Transient caching** — shortcode query results cached for 30 minutes, flushed on testimonial save
* **Schema.org** — `AggregateRating` JSON-LD injected on pages using the shortcode
* **Custom capability** — `moderate_testimonials` lets Editors approve reviews without `manage_options`

= Shortcode Examples =

Display a 3-column grid of all 5-star testimonials:
`[testimonials columns="3" rating="5" layout="grid"]`

Show 6 testimonials from the "services" category with a filter bar:
`[testimonials count="6" category="services" show_filter="true"]`

Show a carousel that auto-rotates every 4 seconds:
`[testimonials layout="carousel" autoplay="4"]`

Display the front-end submission form:
`[testimonial_form]`

= Shortcode Attributes — [testimonials] =

| Attribute      | Default   | Options                     | Description                          |
|----------------|-----------|-----------------------------|--------------------------------------|
| `layout`       | `grid`    | grid, list, carousel        | Display layout                       |
| `columns`      | `3`       | 1, 2, 3, 4                  | Columns in grid/carousel             |
| `count`        | `9`       | Any integer, -1 = all       | Posts per page                       |
| `rating`       | `0`       | 0–5 (0 = any)               | Minimum star rating filter           |
| `category`     | (empty)   | Taxonomy slug               | Limit to one category                |
| `featured`     | `false`   | true, false                 | Show only featured testimonials      |
| `show_filter`  | `false`   | true, false                 | Show rating + category filter bar    |
| `show_summary` | `false`   | true, false                 | Show aggregate rating summary bar    |
| `orderby`      | `date`    | date, rating, rand, views   | Sort order                           |
| `order`        | `DESC`    | DESC, ASC                   | Sort direction                       |
| `clamp`        | `0`       | Integer (0 = no limit)      | Lines of text before "Read more"     |
| `autoplay`     | `0`       | Seconds (0 = off)           | Carousel auto-rotate interval        |
| `schema`       | `true`    | true, false                 | Inject AggregateRating JSON-LD       |

= Shortcode Attributes — [testimonial_form] =

| Attribute        | Default   | Description                                           |
|------------------|-----------|-------------------------------------------------------|
| `title`          | (empty)   | Form heading text                                     |
| `subtitle`       | (empty)   | Subheading below the title                            |
| `show_company`   | `true`    | Show company name field                               |
| `show_role`      | `true`    | Show job title/role field                             |
| `redirect`       | (empty)   | URL to redirect to after successful submission        |
| `require_login`  | `false`   | Only logged-in users can submit                       |

= Who Is This For? =

* **Agencies** building sites for service businesses
* **SaaS products** showcasing customer success
* **E-commerce stores** collecting product reviews outside WooCommerce
* **Coaches and consultants** displaying client feedback
* **WordPress developers** who need a clean, standards-compliant starting point

= Privacy =

This plugin:
* Collects name, email (stored as post meta — not displayed publicly), company name, and testimonial content submitted via the front-end form.
* Stores a view/impression counter per testimonial as post meta.
* Does **not** use cookies.
* Does **not** share data with third parties.
* Sends one admin notification email per new submission. No subscriber lists are maintained.
* On uninstall, all plugin data is removed from the database (see Uninstall section in the plugin FAQ).

= Development =

* Source: https://github.com/vetrisuriya/wp-testimonials-social-proof
* Bug tracker: https://github.com/vetrisuriya/wp-testimonials-social-proof/issues
* Contributions welcome via pull request.

== Installation ==

= Automatic Installation (Recommended) =

1. Log in to your WordPress admin panel.
2. Go to **Plugins → Add New**.
3. Search for **WP Testimonials & Social Proof**.
4. Click **Install Now**, then **Activate**.

= Manual Installation =

1. Download the plugin `.zip` file.
2. Go to **Plugins → Add New → Upload Plugin**.
3. Choose the `.zip` file and click **Install Now**.
4. Click **Activate Plugin**.

= After Activation =

1. Go to **Testimonials → Settings** to configure the plugin.
2. Add the `[testimonials]` shortcode to any page or post.
3. Add the `[testimonial_form]` shortcode to a dedicated "Leave a Review" page.
4. Optionally add the **Featured Testimonials** widget to a sidebar under **Appearance → Widgets**.

== Frequently Asked Questions ==

= How do I display testimonials on a page? =

Add `[testimonials]` to any page, post, or widget that supports shortcodes. Use attributes to customise the output — see the Shortcode Attributes table above.

= Can visitors submit testimonials themselves? =

Yes. Add `[testimonial_form]` to any page. By default, new submissions go to "Pending" status and must be approved by an admin before they appear publicly. You can enable auto-approval under **Testimonials → Settings → Moderation**.

= How do I approve a submitted testimonial? =

Go to **Testimonials → All Testimonials**. Pending submissions appear in the list with a "Pending Review" status. Click the testimonial to edit it, then change its status to "Published" and click Update.

= Can I let Editors approve testimonials without giving them admin access? =

Yes. The plugin registers a custom `moderate_testimonials` capability. Assign this capability to the Editor role (using a plugin like User Role Editor, or programmatically with `get_role('editor')->add_cap('moderate_testimonials')`) to allow Editors to publish and manage testimonials without granting `manage_options`.

= How do I add a category to testimonials? =

Go to **Testimonials → Categories** to create categories. Then assign a category when editing a testimonial, just like assigning categories to a blog post.

= Does the plugin add Schema.org markup for Google rich snippets? =

Yes. When the `[testimonials]` shortcode is on a page, the plugin automatically injects an `AggregateRating` JSON-LD `<script>` block into the page `<head>`. This is compatible with Google's structured data requirements for star ratings in search results.

= Will the plugin slow down my site? =

No. Assets (CSS and JS) are loaded **only on pages that contain the shortcode** — not on every page. Shortcode query results are cached as transients for 30 minutes. The view counter and submission counter use `autoload = false` to avoid loading on every page request.

= How do I export my testimonials? =

Go to **Testimonials → Settings → Data** and click **Export CSV**. This downloads all published testimonials as a comma-separated file you can open in Excel or import into another system.

= What happens to my data if I uninstall the plugin? =

All plugin data is permanently removed: the `wptsm_testimonial` CPT posts and their meta, the `wptsm_category` taxonomy terms, all plugin options (`wptsm_settings`, `wptsm_total_submissions`), and all cached transients. The `moderate_testimonials` capability is removed from the Administrator role. This behaviour follows WordPress.org Plugin Directory guidelines for clean uninstallation.

= Can I use the testimonials in a headless WordPress setup? =

Yes. The plugin registers a REST API endpoint at `GET /wp-json/wptsm/v1/testimonials`. It supports `rating`, `category`, `per_page`, `page`, `orderby`, and `order` query parameters. A POST endpoint at `/wp-json/wptsm/v1/submit` accepts new testimonial submissions with Application Password or cookie authentication.

= Does the plugin work with caching plugins? =

Yes. The AJAX filter and form submission work via `admin-ajax.php`, which is excluded from page caching by most caching plugins (WP Super Cache, W3 Total Cache, LiteSpeed Cache, WP Rocket). The shortcode output itself is served from the page cache; the dynamic parts (filtering, submission) bypass it correctly.

= The star ratings do not appear in Google search results. =

Structured data can take several weeks to be indexed by Google. Use **Google's Rich Results Test** (https://search.google.com/test/rich-results) to verify the JSON-LD output is valid. The `schema` shortcode attribute must be `true` (the default), and the page must have at least one published testimonial.

= Can I customise the testimonial card appearance? =

Yes. The plugin uses CSS custom properties (variables) for all colours, spacing, and shadows. You can override them in your theme's stylesheet or via the WordPress Customizer (Additional CSS). For example: `body { --wptsm-primary: #e63946; --wptsm-star-filled: #f59e0b; }`.

= Is the plugin translation-ready? =

Yes. All user-visible strings are wrapped in `__()`, `_e()`, `_n()`, or `esc_html__()` with the text domain `wp-testimonials-social-proof`. A `.pot` template file is included in the `/languages/` folder.

== Screenshots ==

1. **Testimonials grid** — 3-column grid layout with star ratings, author photos, and category badges.
2. **Single testimonial card** — featured card with verified badge and company information.
3. **AJAX filter bar** — filter by star rating and category without a page reload.
4. **Front-end submission form** — interactive star picker, required fields, and honeypot spam protection.
5. **Admin list table** — custom columns showing star rating, company, view count, and quick-approve button.
6. **Settings page** — tabbed settings with moderation options, colour picker, and shortcode builder.
7. **Featured Testimonials widget** — sidebar widget configured from Appearance → Widgets.
8. **REST API response** — JSON output from `/wp-json/wptsm/v1/testimonials`.

== Changelog ==

= 1.0.0 =
*Release date: 2024-01-15*

* Initial release.
* Testimonials CPT with wptsm_category taxonomy.
* Star rating, company, role, and website custom meta fields.
* `[testimonials]` shortcode with grid, list, and carousel layouts.
* `[testimonial_form]` shortcode with honeypot spam protection.
* AJAX rating and category filter.
* AJAX load-more pagination.
* Front-end submission with moderation workflow.
* Admin notification email on new submission.
* Auto-approve toggle in Settings.
* Featured Testimonials sidebar widget.
* REST API endpoint: `GET /wptsm/v1/testimonials`, `POST /wptsm/v1/submit`.
* Schema.org AggregateRating JSON-LD injection.
* View/impression counter per testimonial.
* Transient caching with 30-minute TTL and save_post invalidation.
* `moderate_testimonials` custom capability for Editors.
* Settings API page with colour picker and shortcode builder.
* Admin list table: custom rating, company, and views columns.
* CSV export of all testimonials.
* Clean uninstall via uninstall.php.

== Upgrade Notice ==

= 1.0.0 =
Initial release. No upgrade steps required.