=== TillFoundry All Product Reviews for WooCommerce ===
Contributors: lijnam
Tags: woocommerce, reviews, product reviews, ratings, testimonials
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.24.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Show every product review in one place, with customer photos displayed, not collected, in a filterable shortcode and admin screen.

== Description ==

All Product Reviews is free, with no paid tier, licence key or upgrade prompt: every design, block, filter, the photo lightbox and the admin review screen ship in this build. Photos are displayed, not collected — the plugin renders the media a compatible photo-review tool has already stored, and adds no upload field of its own.

WooCommerce shows reviews on the single product page only. This plugin collects all of them in one place, three ways.

**1. The `[all_reviews]` shortcode**, on any page, post or widget. It renders a rating summary with a clickable 1–5 star distribution; every approved review with avatar, author, rating, "Verified owner" badge, product link and date; the photos and videos a compatible photo-review plugin has attached, as thumbnails that open in a lightbox; a filter bar (rating, sort, verified owners, photos, optional search) that works without JavaScript; and pagination as numbered pages, a "Load more" button or nothing at all.

**2. Blocks**, with the same designs and options: Customer Reviews (the full list), Reviews Hero, Featured Review, Review Rating Summary and Review Rating. Everything is in the block sidebar, including the visual design picker. Left on "Site default", a block follows the settings from WooCommerce → Review Page; anything set in the sidebar wins. Blocks support wide and full alignment, anchors, custom class names and spacing controls.

**3. The admin screen**, under WooCommerce → All Reviews: summary cards for every status and the average rating; filters for search text, product, product ID, category, rating, status, verified owners, sorting and reviews per page; bulk approve, pending, spam, trash, restore and permanent delete; per-review row actions including a link to the native comment editor; photo thumbnails with a photos filter; and a CSV export of the current selection (up to 20,000 rows per download, photo URLs included).

**Six designs**, chosen once for the review page and overridable per shortcode or block.

* `layout` — one of `customer-stories`, `journal`, `lookbook`, `stories`, `testimonials` or `list`. They range from a warm editorial page with customer photos to a classic single-column list with the most detail per review. The same six are in the block sidebar's design picker.

**Requirements.** WordPress 5.8 or higher, PHP 7.4 or higher and WooCommerce. The shortcode and blocks show the reviews WooCommerce holds. Without WooCommerce the plugin still activates and its admin review list still works, listing the reviews that are there with the product details it can resolve.

**Privacy.** Ratings, review text and photos stay in your own database. The plugin adds no tracking and makes no third-party request to load its own CSS, JS or fonts; see *External Services* for the one case where a review's own photo or video is loaded from the service that hosts it.

The full reference — every shortcode attribute, block option, template override and CSS hook — is at <https://tillfoundry.com/docs/>.

== Installation ==

1. Install the ZIP through *Plugins → Add New → Upload Plugin*, or upload the plugin folder to `/wp-content/plugins/`.
2. Activate the plugin through the *Plugins* screen.
3. A page called "Customer Reviews" containing the `[all_reviews]` shortcode is created automatically on activation (it can be disabled with the `tillapr_create_reviews_page_on_activate` filter).
4. Optionally add the shortcode to any other page, or use the admin screen under *WooCommerce → All Reviews*.

== Frequently Asked Questions ==

= Does it work with the WooCommerce High-Performance Order Storage (HPOS)? =

Yes. The plugin only reads product reviews, which are WordPress comments, and it declares HPOS compatibility to WooCommerce.

= Which reviews are counted? =

Product reviews stored as the WooCommerce `review` comment type, plus reviews stored as plain comments, which is what WooCommerce itself queries. Reviews on trashed or draft products are included in the admin screen but never on the front end.

= Can visitors see pending or spam reviews? =

No. The front end only ever queries approved reviews of published products, and that restriction is enforced server-side even for AJAX requests, regardless of the URL parameters.

= Are the results cached? =

The aggregate rating statistics are cached in a transient that is invalidated automatically whenever a review is added, edited, moderated or deleted.

= Why can the average rating card differ from the distribution bars? =

The "Average rating (approved)" card is store wide and counts approved reviews of published products only, so it always matches the rating customers see on the storefront. The distribution bars follow the filters you have selected, so with "All statuses" selected they also include pending reviews and reviews of draft products.

= Do the blocks work with my theme's editor styles? =

Yes. The blocks use the theme's editor styles for typography and the standard block wrapper, so alignment, spacing and custom class names behave like any other block. The review markup itself is styled by the plugin, with the accent colour set per block.

= Can I show fit, temperature or audio reviews? =
Only if you supply the data, because WooCommerce does not store it. A review records the customer, the rating, the text, the date, the verified flag and any photos or video: there is no field for wearer height and weight, "true to size" feedback, a tested temperature or an audio note, and the photo review plugin accepts images (plus video when enabled) but not audio. Designs built on that data would have to invent it, so this plugin does not ship them. If your store collects it elsewhere, copy the closest design into your theme and add the fields there: every design is a template, and the query layer hands you the reviews it selected.

= Can I override the templates? =

Yes. Copy any file from the plugin `templates/` folder into `your-theme/all-product-reviews/` and edit it there. The structure mirrors the plugin:

* `summary.php`, `filters.php`, `list.php`, `list-items.php` – the page around the reviews.
* `items/<layout>.php` – the markup of one review for a design, e.g. `items/testimonials.php`.
* `partials/head.php`, `partials/content.php`, `partials/photos.php`, `partials/product.php`, `partials/permalink.php` – the shared building blocks every design reuses, so overriding one of them changes all designs at once.

The pre-1.2 `review.php` item override is still honoured for the List design.

= Do the review photos work with my photo review plugin? =

The plugin reads the `reviews-images` comment meta used by photo-review plugins, which stores an array of attachment IDs or, for imported reviews, image URLs. Both forms are supported, along with videos and YouTube/Vimeo/Dailymotion links (each loads only when a visitor opens it; see *External Services*). For any other plugin, filter `tillapr_review_images_meta_key` to return its meta key.

== External Services ==

This plugin contacts two kinds of third-party service: WordPress's avatar service (Gravatar), which is contacted whenever a review avatar is displayed, and a third-party video player, which is loaded only when a visitor chooses to open a review video in the lightbox. Both requests are made directly by the visitor's browser. Nothing is sent to a video provider before the visitor clicks a video thumbnail.

**Avatars (WordPress Gravatar).** When avatars are shown — which is the default — the visitor's browser requests `https://secure.gravatar.com/avatar/<md5 hash of the review author's email address>`. As with any web request, that sends the provider the hashed email address together with the visitor's IP address and browser user agent. The request happens on every page that lists reviews, without any click by the visitor. The provider's privacy policy is at https://automattic.com/privacy/. The plugin itself does not receive, log or store that data. Avatars can be turned off with the `show_avatar` setting, in which case no Gravatar request is made.

When a video is opened, the browser asks the matching provider for its player and, as with any web request, sends the provider the visitor's IP address, the browser user agent and the address of the page the video was opened from (the referrer). The provider's own privacy policy explains any cookies it may set. The plugin itself does not receive, log or store that data.

The providers used by the lightbox are:

* **YouTube** — player loaded from `https://www.youtube.com/embed/` when a review contains a YouTube (`youtube.com`, `m.youtube.com`) or `youtu.be` link. Terms of Service: https://www.youtube.com/t/terms. Privacy Policy: https://policies.google.com/privacy.
* **Vimeo** — player loaded from `https://player.vimeo.com/video/` when a review contains a `vimeo.com` link. Terms of Service: https://vimeo.com/legal. Privacy Policy: https://vimeo.com/legal/privacy/policy.
* **Dailymotion** — player loaded from `https://www.dailymotion.com/embed/video/` when a review contains a `dailymotion.com` or `dai.ly` link. Terms of Use: https://legal.dailymotion.com/en/terms-of-use/. Privacy Policy: https://legal.dailymotion.com/en/privacy-policy/.

If a store would rather not contact these video services at all, it can leave video links out of reviews: the lightbox still displays images and uploaded video files without contacting these providers.

== Screenshots ==

1. The front-end review page: rating summary, distribution, the filter bar and the review cards.
2. The lookbook: customer photos collected from reviews, as a grid on the storefront.
3. The All Reviews admin screen under WooCommerce, with summary cards, filters and bulk moderation.
4. The Review Page settings, where the site-wide design and its defaults are chosen.

== Changelog ==

= 1.24.1 =
* Directory review response. No feature, setting or behaviour changed for a visitor.
* Every function, class, constant, hook, option, transient and meta key moved from the `awr_` / `AWR_` prefix to `tillapr_` / `TILLAPR_`, which the directory requires to be at least four characters. Existing settings and the reviews page survive the upgrade: the plugin copies the old keys on the first request after updating and only then removes them, and the comment and term cache-version meta are renamed in place.
* The text domain is now `tillfoundry-all-product-reviews-for-woocommerce`, the directory slug the plugin was submitted under, so community translations can be loaded.
* Removed `Tested up to` from the plugin header: the readme is the only supported place for it.
* The `[awr_reviews]` shortcode alias is now `[tillapr_reviews]`. `[all_reviews]` is unchanged.
* The readme description was rewritten to the directory's visible length; the full reference moved to the documentation site.

= 1.24.0 =
* Adopted the brand-first name and text domain for the WordPress.org directory. The display name is now "TillFoundry All Product Reviews for WooCommerce" and the text domain moved from all-product-reviews to tillfoundry-all-product-reviews-for-woocommerce in the plugin header and every i18n call. `Contributors` credits the publishing WordPress.org account, `lijnam`, and the installation steps no longer name the plugin folder, since the same readme ships in a directory tree and a store ZIP whose folders can differ. No feature or setting changes.

= 1.23.0 =
* Maintenance release with no feature or setting changes. Every design, block, filter, the photo lightbox, the admin All Reviews screen, bulk moderation and CSV export remain free, with no paywall, licence check or upgrade prompt.

= 1.22.0 =
* Maintenance release. Documentation and internal checks only; all existing features stay free and unchanged.

= 1.21.0 =
* Maintenance release. Documentation and internal checks only; all existing features stay free and unchanged.

= 1.20.0 =
* Removed the optional external webfont loader. The designs keep their preferred font stacks with system fallbacks, so a theme that already supplies those families still gets the intended type and other sites use the next font in the stack. No settings changes.

= 1.19.0 =
* Documentation only: a note on the Review Page explains that review photos and videos come from a compatible collection tool. No feature or setting changes.

= 1.18.0 =
* Version 1.18.0 was not released. The work that followed 1.17.1 shipped as 1.19.0; this entry records the gap so the version history does not silently skip a release.

= 1.17.1 =
* Fixed the summary's star links writing an invalid `tillapr_sort=random-desc`, which quietly dropped a random sort back to newest first. Random links now carry `tillapr_sort=random` and the shuffle seed, so filtering by rating keeps both.
* Removed a no-op `cache_results` argument: WordPress comment queries cannot opt out of their cache that way. Random ordering is unaffected, because the shuffle is computed in PHP from the seed on every render.

= 1.17.0 =
* Random sorting in the filter bar, in a shortcode (`orderby="random"`) and in the block sidebar. The shuffle is seeded, so paging through it never repeats or skips a review, and `seed="1234"` pins an exact order to share or repeat.
* Eight more colour controls, so a block can be matched to any brand: muted text, button background and label, verified badge background and text, chip background and text, and the photo overlay. The Colours panel is now grouped (brand and surfaces, text, buttons, badges and chips, stars) and has a **Reset every colour** button.
* The new colours are documented CSS variables (`--awr-user-muted`, `--awr-user-button`, `--awr-user-button-text`, `--awr-user-badge`, `--awr-user-badge-text`, `--awr-user-chip`, `--awr-user-chip-text`, `--awr-user-overlay`), so a theme can set them too.

= 1.16.0 =
* Accessibility and readability pass over every design: fixed 13 real contrast failures (gold and brick text on the warm backgrounds, the muted grey on cream, the verified badge, the photo expand pills). The warm designs gained `--awr-gold-ink` and `--awr-brick-bg` tokens so text always sits on a dark enough colour while stars and marks keep the bright accent.
* All four UI states are now designed: a useful empty state with a Clear filters action and the counts footer hidden, a busy state for load more and the filter bar, a failure message that is announced, and a live region that reports what loaded.
* The rating summary and stat rows no longer empty themselves when a search or filter matches nothing: they show the real rating for the product or category being viewed.
* A consistent visible keyboard focus ring on every control, a product thumbnail on the list design's "on <product>" line, and a slightly larger monospaced meta line on the Journal.
* New UX audit harness: `bash .plugin-test/ux-audit.sh` checks contrast, accessible names, alt text, heading order and the four states across every design at desktop and mobile. It is currently clean (45 page audits).

= 1.15.0 =
* New **Reviews Hero** block: a rating line built from real reviews, a large serif headline, an intro, a button, an optional text link, and a photo with a floating quote card overlapping its corner. The quote defaults to your strongest review and can be written by hand; the photo can be picked from the media library or falls back to the customer's own photo.
* New **Featured Review** block: one customer story shown large, with their photo beside a big serif quote, a quote mark, their name, the date and product category, the star rating and the product. It picks the strongest review and can be scoped by product, category, rating or photos.
* Both blocks share the Customer Stories palette and type, adapt to the width they are given, and expose every part through the Show or hide panel.

= 1.14.0 =
* Every component is now hideable from the block editor's new **Show or hide** panel, and from shortcode attributes: the hero, the stats, the section heading, the featured story, the photo gallery, the rating summary and the filter bar, plus the stars, review text, customer photos, verified badge, avatar, date, product, review link and count on each review. All default to visible.
* Fixed three components that had no working switch: `show_count` was mapped but missing from the block schema and was not honoured by the footer count at all, and the summary block's count line ignored it too.
* The summary block gained `show_score`, `show_bars`, `show_reset` and `show_count`. A summary with neither the score nor the bars now renders nothing instead of an empty panel.

= 1.13.0 =
* Removed the "share your story & photo" invitation from the Journal, Lookbook and Customer Stories designs, and the dark "Share your warmth" closing band from the Stories design. Nothing on the page asks the customer to submit anything now: WooCommerce's own review form is untouched and still reaches the pages it always did.
* Removed the `show_share` attribute and its editor toggle, and the `tillapr_get_review_form_url()` helper that only the invitation used.
* `closing_quote` and `closing_byline` now only drive the Testimonials closing band, and `cta_label` / `cta_url` only drive the Customer Stories hero button.

= 1.12.0 =
* Added a responsive audit (`bash .plugin-test/responsive.sh`): 572 page loads across 320px to 2560px, portrait and landscape, three container widths, 150% text and the lightbox. It is currently clean.
* Fixed the issues it found: the lightbox close button was 40px on desktop, category chips were 39-41px tall, and the Lookbook "Shop" pill and "Share yours" link were under 44px.
* Fixed large text overflow: long strings (customer names, hashtags, product titles) now break instead of pushing the page sideways, the identity and footer rows wrap instead of squeezing, buttons wrap their labels, and the photo galleries stack below a 420px container so captions stay readable.
* The browser suite now guards both cases, so a regression fails the normal run rather than only the audit.

= 1.11.0 =
* Masonry card walls for the Testimonials, Stories, Journal and Customer Stories designs, in pure CSS (no scroll listeners, no layout shift). The first story still spans the full width. Control it with the new **Card layout** setting or `masonry="yes|no"`.
* Performance: the hero photo is now a real image served eagerly with `fetchpriority="high"` instead of a CSS background, so the largest paint is prioritised.
* Performance: review avatars lazy load. WordPress stopped adding a loading attribute to avatars, so a page of reviews was requesting every gravatar up front.
* Performance: attachment photos carry a `srcset`, a `sizes` hint and intrinsic `width`/`height`, so a small slot downloads a small file and no space is left to shift.
* A real world example page ships in the test harness, with reviews of deliberately different lengths, and the suite now asserts the masonry packing, the eager hero and the lazy images.

= 1.10.0 =
* New Customer Stories design: a two column hero with a photo and a floating quote from the strongest review, a dark band of real numbers, one wide featured story, quote first cards and a gallery of customer photos with captions, closed by a "share your story" band.
* New `gallery_note` attribute for the note beside the gallery heading.
* The design fonts follow the design: Customer Stories loads Fraunces and Work Sans when you opt in with `tillapr_enqueue_design_fonts` (the opt-in and its external stylesheet were removed in 1.20.0; provide the families in your theme and the design picks them up).

= 1.9.0 =
* Style each block from the editor: new **Layout**, **Colours** and **Size & spacing** panels.
* Colours: accent, background, cards, headings, body text, borders and stars, each with the quick palette and a custom picker. Empty keeps the design default.
* Sizes: text size (smaller, normal, larger), spacing (compact, comfortable, spacious), corner radius, photo thumbnail size, tall photo panel height and avatar size.
* Layout: columns now accepts 1 to 4, and a new rows control sets the page size from the grid.
* The same options are available as shortcode attributes, and every value is sanitised: colours are hex only (anything else is ignored, so no value can escape its declaration) and sizes are clamped.
* The bundled CSS reads a documented custom property contract, so a theme can restyle a block the same way.

= 1.8.0 =
* Journal: customer photos now appear as vignettes. The featured story gets a labelled "Photos uploaded by ... (click to enlarge)" panel and each note leads with the customer's photo; both open the shared lightbox.
* New "share your story & photo" invitation on the Journal and Lookbook pages. It links to the real WooCommerce review form of the product being viewed (or the shop when the page covers many products) instead of reimplementing review submission, so your validation, spam checks and photo upload rules still apply. Turn it off with `show_share="no"` or the block toggle, and rename the heading, note and button with the existing `closing_quote`, `closing_byline` and `cta_label` attributes.
* New `tillapr_get_review_form_url()` helper and `tillapr_share_section` filter.

= 1.7.0 =
* New Journal design: a heritage masthead with a stat pair, one featured story with a pull quote taken from the review's opening sentence, a drop cap body, a wax seal byline and a product panel, then a grid of editorial notes.
* New Lookbook design: a dark visual wall of customer photos, each tile tagged with its category and a Shop button carrying the real price. The design lists only reviews that have photos.
* The content partial now accepts explicit text and an extra class, so designs can reuse it instead of duplicating markup.
* Fixed derived item templates (such as the Journal's featured story) not resolving, which made them silently fall back to the list item.

= 1.6.0 =
* New Stories design: warm editorial page with a serif hero and stat strip, product category chips that filter through the URL, cream review cards with a felt verified badge and customer photos, a customer photo gallery and a dark closing band with a call to action.
* New attributes: `gallery_title`, `cta_label`, `cta_url` and `show_categories`, in the shortcode and in the block sidebar (which now has a "Page sections" panel).
* New product category data (`TILLAPR_Reviews::get_categories()`) and the `tillapr_category` URL filter behind the chips.
* Design fonts are opt-in through the `tillapr_enqueue_design_fonts` filter instead of being loaded from a third party by default (removed in 1.20.0).

= 1.5.0 =
* New Testimonials design: a hero with an eyebrow, heading, intro paragraph and photo, a row of highlight stats built from your review data, review cards with avatar, stars, quote, customer, product thumbnail and verified badge, and a closing quote band.
* Removed the earlier designs (Cards, Photo wall, Carousel, Spotlight, Quote and Editorial). The List design remains as the classic fallback. Older ZIPs still contain them if you need one back.
* New attributes: `intro`, `hero_image`, `grid_title`, `closing_quote` and `closing_byline`, in the shortcode and in the block sidebar.
* The testimonials design uses container queries, so it adapts to the width its theme actually gives it rather than to the browser width.


= 1.4.0 =
* New Editorial design: magazine style customer stories with an eyebrow label, a display size quote, photos, a byline over a rule and alternating panels with an accent rule down the left edge. The rating summary is restyled as a stat banner for this design.
* New `eyebrow` attribute (shortcode and block) for a small label above the heading, and an eyebrow field in the block sidebar.

= 1.3.0 =
* Three blocks: Customer Reviews, Review Rating Summary and Review Rating, with a server rendered preview in the editor and the visual design picker in the block sidebar.
* Blocks follow the Review Page settings by default and can override design, columns, accent colour, content toggles and filters individually. They support wide/full alignment, anchors, custom class names and spacing.
* Editor assets are plain scripts with no build step, and block attributes are declared once in block.json.

= 1.2.0 =
* Six selectable review page designs: List, Cards, Photo wall, Carousel, Spotlight and Quote.
* New "Review Page" settings screen with a visual design picker, previews, columns, accent colour, pagination and display toggles. Settings act as the defaults for every shortcode.
* Template structure split into per design item templates plus shared partials, so a theme can override one design or one building block.
* Fixed the carousel making the whole page scroll sideways on some browsers.

= 1.1.1 =
* Accessibility and touch pass: every interactive control in the review list, the filter bar, the pagination and the photo lightbox now meets the 44x44px minimum touch target size on phones and tablets.
* Filter controls use explicit, visible labels associated with `for`/`id`, and each shortcode instance gets unique ids so two review lists on one page both stay accessible.
* Photo galleries are touch friendly: swipe left/right to move between photos, while the browser's own pinch-to-zoom keeps working.
* Fixed the rating summary leaving a large empty gap on narrow screens, where the flex basis was applied to the block height.

= 1.1.0 =
* Review photos: thumbnails under each review, a lightbox with keyboard navigation, a `photos` shortcode attribute and URL filter, a "With photos only" filter checkbox, admin photo thumbnails plus a Photos filter, and photo URLs in the CSV export. Integrates with the `reviews-images` comment meta used by photo-review plugins.

= 1.0.0 =
* First release: front-end shortcode with summary, filters, pagination and AJAX load more; admin screen with filtering, bulk moderation and CSV export.

== Upgrade Notice ==
= 1.24.0 =
Branding and WordPress.org directory name only. Every existing feature stays free, with no paywall, licence check or upgrade prompt. No settings changes; nothing to migrate.


= 1.23.0 =
Maintenance release. Every existing feature stays free, with no paywall, licence check or upgrade prompt. No settings changes; nothing to migrate.

= 1.22.0 =
Maintenance release. Every existing feature stays free and unchanged. Nothing to migrate.

= 1.21.0 =
Maintenance release. Every existing feature stays free and unchanged. Nothing to migrate.

= 1.20.0 =
Removes the optional external webfont loader. If you relied on it, add those font families to your theme. Nothing to migrate.

= 1.19.0 =
Adds a note explaining where review photos and videos come from. No settings changes; nothing to migrate.

= 1.17.1 =
Fixes the random-sort links on the rating summary and removes a no-op query argument. No configuration changes needed.
