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

Show every WooCommerce product review in one place: a front-end shortcode with rating summary and filters, plus a filterable admin screen with bulk moderation and CSV export. Includes the photos your customers attached to their reviews.

== Description ==

WooCommerce only shows reviews on the single product page. This plugin collects **all** of them in one list, with two ways to use it:

**1. Front-end shortcode**

Add the shortcode to any page, post or widget:

`[all_reviews]`

What it renders:

* A rating summary with an average score and a clickable 1–5 star distribution.
* Every approved review, newest first, with avatar, author, star rating, "Verified owner" badge, product link and date.
* The photos and videos customers attached to their review, as thumbnails that open in a lightbox.
* A filter bar (rating, sort order, verified owners, photos, optional search) that works without JavaScript and auto-submits when JavaScript is available.
* Pagination as numbered pages, a "Load more" button (AJAX, no page reload), or no pagination at all.

Designs:

* `customer-stories` – warm paper page: a two column hero with a photo and a floating quote, a dark band of real numbers, one featured story, quote first cards and a gallery of customer photos with captions.
* `journal` – long form magazine page: a dispatcher masthead, one featured story with a pull quote, a drop cap, a wax seal byline and a product panel, then a grid of editorial notes.
* `lookbook` – dark visual wall of customer photos, each tagged with its product category, a headline and a Shop button with the price.
* `stories` – warm editorial page: serif hero with a badge and a stat strip, category chips, cream review cards with customer photos, a photo gallery and a dark closing band.
* `testimonials` – testimonials page: hero with a section intro and photo, a row of highlight stats, review cards in a grid and a closing quote band.
* `list` – classic single column list with the most detail per review.

Pick a design once on **WooCommerce → Review Page**; every `[all_reviews]` then uses it. Individual shortcodes can still override it with the `layout` attribute.

Shortcode attributes:

* `layout` – `testimonials` or `list`. Defaults to the saved setting.
* `columns` – 1 to 4 columns for the card grid. Default `3`.
* `rows` – how many rows of reviews to show per page. Rows times columns sets the reviews per page, and it overrides `per_page` when set.
* `title`, `eyebrow`, `intro` – the section heading, the small label above it and the paragraph under it.
* `hero_image` – image URL used as the photo behind the testimonials hero.
* `grid_title` – heading above the card grid, e.g. `grid_title="Stories of Warmth"`.
* `closing_quote`, `closing_byline` – the Testimonials closing band: a quote and a byline. Without a quote the band shows the real rating numbers instead.
* `gallery_title` – heading above the customer photo gallery (Stories, Customer Stories).
* `gallery_note` – the short note beside that heading (Customer Stories).
* `cta_label`, `cta_url` – the Customer Stories hero button. Without a URL the hero renders without a button.
* `show_categories` – `yes`/`no` to show product category chips. Defaults to on for the Stories design and off elsewhere.
* `masonry` – `yes`/`no` for the staggered card wall. Defaults to on for the card designs.

Style, adjusted for one shortcode or block at a time. Leave a value out and the design keeps its own:

* `accent_color`, `bg_color`, `surface_color`, `text_color`, `heading_color`, `muted_color`, `line_color`, `star_color`, `button_color`, `button_text_color`, `badge_color`, `badge_text_color`, `chip_color`, `chip_text_color`, `overlay_color` – hex colours for the accent, the page background, the cards, the headings, the body text, the muted text (dates, counts, hints), the borders, the stars, the buttons and their labels, the verified badge and its text, the chips and pill labels with their text, and the dark overlay behind photo captions.
* `text_size` – `s`, `m` or `l`.
* `spacing` – `compact`, `comfortable` or `spacious`.
* `radius`, `photo_size`, `photo_height`, `avatar_size` – pixel sizes for the corner radius, the photo thumbnails, the tall photo panels and the avatars.
* `accent` – hex colour for stars, buttons, active filters and links. Defaults to the saved setting.
* `per_page` – reviews per page. Default `10`.
* `product_id` – limit to one or more product IDs (comma separated), or use `current` on a product page.
* `category` – limit to one or more product category slugs or IDs (comma separated).
* `rating` – only show a specific star rating (1–5).
* `verified` – `yes` or `no` to filter by verified owners.
* `photos` – `yes` to only show reviews that have photos, `no` for reviews without photos.
* `orderby` – `date`, `rating` or `random`.
* `seed` – a number that fixes a random order, so the same shuffle can be shared or repeated. Default `date`.
* `order` – `DESC` or `ASC`. Default `DESC`.
* `status` – comment status to include. Default `approve`. Set by the site owner only; it can never be changed from the URL.
* `search` – pre-filled search term.
* `include_replies` – `yes` to include review replies. Default `no`.
* `show_summary` – `yes`/`no`. Default `yes`.
* `show_filters` – `yes`/`no`. Default `yes`.
* `show_photo_filter` – `yes` to add a "With photos only" checkbox to the filter bar. Default `no`.
* `show_search` – `yes`/`no` to show the search box in the filter bar. Default `no`.
* `show_product` – `yes`/`no` to show which product a review belongs to. Default `yes`.
* `show_avatar` – `yes`/`no`. Default `yes`.
* `show_date` – `yes`/`no`. Default `yes`.
* `pagination` – `numbers`, `loadmore` or `none`. Default `numbers`.
* `title` – optional heading above the list.
* `eyebrow` – optional small label rendered above the heading, e.g. `eyebrow="Customer stories"`.
* `empty_message` – text shown when there are no reviews.

Examples:

`[all_reviews per_page="20" pagination="loadmore"]`

`[all_reviews category="coffee,tea" orderby="rating" order="DESC"]`

`[all_reviews product_id="current" show_summary="no" per_page="5"]`

`[all_reviews photos="yes" show_photo_filter="yes" title="Customer photos"]`

`[all_reviews layout="customer-stories" per_page="7" title="Loved in every stitch." intro="Hand knit in Nepal and worn somewhere warm." hero_image="https://example.com/hero.jpg" grid_title="Worn well, from every corner of the world" gallery_title="From your wardrobe to ours" gallery_note="Add yours and it may be featured next." closing_quote="Have a story of your own?" cta_label="Read the stories"]`

`[all_reviews layout="journal" per_page="7" eyebrow="The Kathmandu Dispatch" title="Stories Knit in Pure Himalayan Wool" intro="From the high pastures to cold winter evenings." grid_title="Customer Vignettes & Field Notes"]`

`[all_reviews layout="lookbook" per_page="8" eyebrow="#WoolmanduInTheWild" title="Community Lookbook Wall" intro="Open a card to shop the exact piece." grid_title="Latest from the community"]`

`[all_reviews layout="stories" columns="3" per_page="9" eyebrow="Happy customers" title="Real Stories of Pure Wool" intro="Every review below comes from a real order." grid_title="Latest stories" gallery_title="In the wild" closing_quote="Share your warmth" cta_label="Shop the collection" cta_url="https://example.com/shop"]`

`[all_reviews layout="testimonials" columns="3" per_page="9" eyebrow="Testimonials" title="Real People. Real Stories. Happy Customers." intro="Here is what our customers say." hero_image="https://example.com/hero.jpg" grid_title="Stories of Warmth &amp; Satisfaction" closing_quote="Customer happiness is the warmth that keeps us going." closing_byline="The Support Team"]`

Theme authors can call the template tag instead of using the shortcode:

`echo awr_get_reviews_html( array( 'per_page' => 5 ) );`

or in a template:

`awr_reviews( array( 'per_page' => 5 ), array( 'show_filters' => 'no' ) );`

**2. Blocks**

The same designs are available as blocks, so a page can be built visually:

* **Customer Reviews** – the full list with summary, filters and pagination.
* **Review Rating Summary** – just the average score and the star distribution.
* **Review Rating** – a compact line such as "Excellent 4.8 ★★★★★ based on 132 reviews".

Every design and option is in the block sidebar, including the visual design picker. Left on "Site default", a block follows the settings from WooCommerce → Review Page; change anything in the sidebar and that block wins. Blocks also support wide and full alignment, anchors, custom class names and spacing controls.

**3. Admin screen: WooCommerce → All Reviews**

* Summary cards for all / approved / pending / spam / trash reviews and the average rating.
* Filters for search text, product, product ID, category, rating, status, verified owners, sorting and reviews per page.
* Bulk actions: approve, set to pending, spam, not spam, trash, restore, delete permanently.
* Per-review row actions, including a link to the native comment editor.
* Photo thumbnails for every review that has them, and a Photos filter (with photos / without photos).
* CSV export of the current filter selection (up to 20,000 rows per download), including the photo URLs.

== Styling a block or shortcode ==

Every design can be restyled per block without touching CSS. Select the block and use the **Layout**, **Colours** and **Size & spacing** panels, or pass the same options to the shortcode:

`[all_reviews layout="stories" columns="2" rows="3" accent_color="#3D5A45" bg_color="#F4F1EA" surface_color="#FFFFFF" heading_color="#1F2A22" text_color="#37423A" line_color="#D8D2C4" star_color="#E0A33E" radius="6" photo_size="110" avatar_size="64" text_size="l" spacing="compact"]`

How the values behave:

* An empty colour or a size of `0` means "keep the design default", so a block only changes what you actually set. The colour pickers have a **Clear** button for exactly that.
* Colours must be hex. Anything else (a colour name, `rgb()`, or an attempt to inject CSS) is ignored and the design default stays, so a style value can never escape its declaration.
* Sizes are clamped to sensible ranges: radius 1-48px, photo thumbnails 32-240px, photo panels 120-800px, avatars 24-120px.
* `rows` multiplies by `columns` to set the reviews per page, which keeps the grid full. Without `rows`, the reviews per page value is used.
* Presets scale the type and the spacing instead of every individual value: `text_size="l"` scales the type by 15%, `spacing="compact"` tightens padding and gaps.
* Colours are grouped in the editor: brand and surfaces (accent, background, cards, borders, the photo overlay), text (headings, body, muted), buttons (background and label), badges and chips (background and label each) and stars. **Reset every colour** clears them all in one go.

Themes and plugins can hook the same system. Each block writes standard custom properties on its wrapper — `--awr-user-accent`, `--awr-user-bg`, `--awr-user-surface`, `--awr-user-text`, `--awr-user-heading`, `--awr-user-line`, `--awr-user-star`, `--awr-user-radius`, `--awr-user-photo`, `--awr-user-photo-height`, `--awr-user-avatar`, `--awr-user-text-scale`, `--awr-user-space` and `--awr-cols` — and the bundled CSS reads them with the design value as the fallback.

== Show or hide any component ==

Every part of the output has its own switch, in the **Show or hide** panel of the block, or as a shortcode attribute. All of them default to on, so nothing disappears until you ask.

**Page sections**

| Shortcode attribute | Hides |
| --- | --- |
| `show_hero="no"` | The design hero: heading, eyebrow, intro and its photo. Also the plain heading on the List design. |
| `show_stats="no"` | The stat row, strip or dark band of numbers. |
| `show_grid_head="no"` | The small heading that sits above the cards. |
| `show_featured="no"` | The wide featured story the Journal and Customer Stories open with: those reviews become ordinary cards. |
| `show_gallery="no"` | The customer photo wall below the cards. |
| `show_summary="no"` | The rating summary panel. |
| `show_filters="no"` | The whole filter bar. |
| `show_categories="no"` | Just the category chips. |
| `show_search="no"` | Just the search field. |
| `show_photo_filter="no"` | Just the "with photos only" checkbox. |
| `pagination="none"` | The pagination or load more control. |

**Each review**

| Shortcode attribute | Hides |
| --- | --- |
| `show_rating="no"` | The star rating. |
| `show_content="no"` | The review text. |
| `show_photos="no"` | The customer photos attached to a review. |
| `show_verified="no"` | The verified buyer badge. |
| `show_avatar="no"` | The customer avatar. |
| `show_date="no"` | The review date. |
| `show_product="no"` | The product name, thumbnail and link. |
| `show_permalink="no"` | The "view on product page" link. |
| `show_count="no"` | The "showing 1-6 of 8 reviews" line, and the "based on N reviews" line in the summary. |

**The summary block** has its own four: `showScore`, `showBars`, `showReset` and `showCount` in the editor, or `show_score`, `show_bars`, `show_reset` and `show_count` in a shortcode. With both the score and the bars off the block renders nothing at all rather than an empty panel.

For example, a bare list of quotes with no chrome at all:

`[all_reviews show_summary="no" show_filters="no" show_hero="no" show_stats="no" show_featured="no" show_gallery="no" show_avatar="no" show_rating="no" show_permalink="no"]`

== Random sorting ==

The sort control offers **Random** next to newest, oldest and the rating sorts, and `orderby="random"` works in a shortcode.

A random order is shuffled with a seed, so it behaves the way shoppers expect: a fresh visit reshuffles, but paging through a shuffled list does not repeat or skip reviews. The seed is kept in the paging and load more links, and you can pin it yourself with `seed="1234"` to share or repeat an exact order.

Two notes on how it works. The shuffle happens in PHP over the matching review IDs rather than in SQL, because WordPress keys its comment query cache on the query vars it knows about, so a database side seed would hand the next visitor the previous visitor's cached shuffle. And a shuffled list opts out of that query cache, since a cache that ignores the seed is worse than no cache.

== The four UI states ==

Every state a shopper can land in is designed, not left to chance.

* **Empty.** With no reviews at all the panel shows your message (the `empty_message` attribute, "No reviews found." by default). When a filter or a search matches nothing it says so, suggests what to try, and offers a **Clear filters** button that keeps everything except the review filters. The counts footer and the pagination are hidden when there is nothing to count or page through.
* **Loading.** Load more disables the button, marks the list `aria-busy`, and shows a loading label. Submitting the filter bar gives the same instant feedback and blocks a second submit.
* **Error.** If the request fails, the button says so and restores itself after a few seconds, and the failure is written into the live region for screen readers.
* **Success.** The list is announced when more reviews arrive ("More reviews loaded."), and the count line updates.

Screen readers follow along through a polite live region, so nothing happens silently.

The rating summary and the stat rows always describe the whole set: they ignore the filters a shopper narrows with (a star, a search, verified only) and keep the product or category scope. A search that matches nothing therefore still shows your real rating instead of "0.0 from 0 reviews".

== Screen sizes ==

Every design is audited from 320px phones to 2560px displays, in portrait and landscape, and at three container widths, then again with the browser's default font size raised to 150% (WCAG 1.4.4).

What that covers, and what it caught:

* **No horizontal scrolling**, at any width, in any design, including inside a wide 1400px content column.
* **Touch targets stay 44px** on touch widths: the category chips, the Lookbook "Shop" pill, the pagination, the filters and the lightbox controls including its close button, which used to be 40px on desktop.
* **Text never clips or squeezes.** At 150% text on a 320px screen the flex rows used to squeeze a customer name down to 19px and push the page 60px wide. Long strings now break instead of overflowing (`overflow-wrap: anywhere` on the wrapper, which also lets flex and grid children shrink below their longest word), those rows wrap, and the photo galleries drop to a single column below a 420px container so captions stay readable.
* The masonry wall and the featured story still lay out correctly at every step.

== Layout and loading behaviour ==

Two things are handled for you, because they matter for both looks and speed.

**Masonry.** The card designs (Testimonials, Stories, Journal and Customer Stories) lay their reviews out as a masonry wall: reviews are different lengths, so each column packs independently instead of leaving the ragged gaps an aligned row grid produces. It is pure CSS column layout, so there is no scroll listener, no reflow on resize and no layout shift, and it falls back to one column on a phone and two on a tablet. The first story in the Journal and Customer Stories designs spans the full width. Turn it off per block with the **Card layout** setting (`masonry="no"` in a shortcode) for aligned rows.

**Lazy loading.** Every review image below the fold lazy loads and decodes off the main thread, while the hero photo is served eagerly with `fetchpriority="high"` so the largest paint is not delayed. The hero is a real `img` element, not a CSS background, so the browser can prioritise it. Photos stored as attachments also get a `srcset` with a `sizes` hint and their intrinsic `width` and `height`, so a small slot downloads a small file and the box is reserved before the bytes arrive. Avatars are lazy too: WordPress stopped adding a loading attribute to them, which meant a page of twelve reviews fetched twelve gravatars immediately.

== Hero and Featured Review blocks ==

Two blocks build the testimonial hero and the big single quote from your real reviews.

**Reviews Hero** – the rating line, headline, intro and photo with a floating quote card:

* The rating line is real: "3.8 from 8 reviews". Add the **Who the customers are** field to read "3.8 from 8 knitwear lovers".
* The floating quote card quotes your strongest review and names them. Write your own quote and attribution in the **Floating quote** panel, or switch the card off.
* The photo is optional. Pick one from the media library, or leave it empty and the block uses the customer's own photo, then the product image. It is served eagerly with `fetchpriority="high"` because it is the largest thing on screen.
* The second action is off unless you fill in both the **Text link label** and the **Text link URL**, so nothing invites customers to submit anything until you ask for it.

**Featured Review** – one customer story shown large, photo beside a big serif quote:

* It picks the strongest review: a verified purchase that has a photo, then a verified one, then the newest. Narrow it down under **Query** (product, category, rating, or only reviews with photos).
* Every part switches off in **Show or hide**: the quote mark, the stars, the product and the date.
* The photo is the customer's own, and can be replaced from the media library.
* WooCommerce has no customer location field, so where the design shows a city the card shows the review date and the product category instead.

== Blocks ==

Add the blocks from the inserter (search for "reviews") or by typing `/reviews` in the editor:

* **Customer Reviews** – the complete list. Sidebar panels: Design (layout, columns, accent colour), Content (heading, reviews per page, pagination, and which parts to show) and Filters (rating, verified owners, photos, product IDs, categories, pre-filled search, sorting).
* **Review Rating Summary** – the average score and 1–5 star distribution, for a hero area or sidebar.
* **Review Rating** – one compact line with an optional label such as "Excellent".

The block preview is rendered by the server, so what you see in the editor is exactly what the page renders. The attributes are declared once in each block's `block.json`, which is also what the editor receives.

The editor script is a plain script with no build step: there is no npm, webpack or compiled bundle to keep in sync.

== Choosing a design ==

**WooCommerce → Review Page** is where the design is chosen. It offers six designs, each shown with a small preview and a note on when to use it:

* **Customer Stories** – a warm paper page with a tight 8px radius, espresso and gold on oatmeal: a two column hero (a star rating line, a serif headline, the intro, a button and a "share yours" link) with a photo and a floating quote card from your strongest review, a dark band of real numbers, one featured story shown wide, then the rest as quote first cards with the customer's avatar, name, date, category and product. Below that a gallery of customer photos with captions.
* **Journal** – for stores with long, worth-reading reviews. The page opens with a masthead and one featured story: the plugin picks the strongest real candidate (a verified purchase that has a photo, then a verified one, then the newest). The featured review's opening sentence becomes the pull quote, the rest becomes the drop cap body, and the customer's avatar is set in a wax seal. Customer photos are attached to the vignettes: the featured story gets a labelled "Photos uploaded by ... (click to enlarge)" panel and each note leads with the customer's photo. Below it, every other review becomes a short editorial note with a monospaced date and category line and the star score. Nothing is truncated or invented: a single short sentence is never pulled out of its own text.
* **Lookbook** – a photo wall for stores that collect customer pictures. Only reviews that have photos are listed, so the counts and pagination always match what is on screen. Each tile shows the photo with the product category tag, the star rating, the customer's opening sentence, who wrote it, and a footer that links to the product with its price.
* **Stories** – a warm editorial page for a dedicated reviews or about page: a serif heading with an eyebrow badge and an intro, a stat strip (average rating, number of stories, share rated 4 or 5 stars, share from verified buyers), a row of product category chips that filter the list through the URL, cream review cards with the customer avatar, name, product category, a felt "Verified" badge, stars, date, the review, the customer's photos and a footer with the product thumbnail, and finally a customer photo gallery plus a dark closing band with a button.
* **Testimonials** – a full page for a dedicated reviews or about page: a hero with the section intro, a row of highlight stats, review cards (avatar, stars, quote, customer, product thumbnail and verified badge) and a closing quote band. The stat row is built from your real reviews: the average rating, the number of reviews, the share rated 4 or 5 stars, and the share from verified buyers. Rename any of them with the `awr_highlights_items` filter.
* **List** – the classic single column list with the most detail per review and the safest choice for any number of reviews.

The same screen sets the number of columns, the accent colour, reviews per page, pagination style, and which parts appear (rating summary, filter bar, search box, "With photos only" filter, product name, avatars, dates). Everything there is a default: a shortcode attribute always wins, so you can use one design site-wide and a different one on a specific page.

Customer Stories uses Fraunces for its display type and Work Sans for body text. The Journal adds Cormorant Garamond for its standfirst and drop caps. The Stories, Journal and Lookbook designs use Playfair Display for their headings and Plus Jakarta Sans for body text. Both are named with system fallbacks, so no third party request is made: if your theme already loads them, the design picks them up. To load them from Google Fonts, opt in:

`add_filter( 'awr_enqueue_design_fonts', '__return_true' );`

Two notes on the data. WooCommerce reviews have no customer location and no review headline, so the Stories cards show the product category, the review date and the verified state instead of inventing them. There is also no "helpful" counter, so the cards link to the review on the product page rather than showing a vote button.

Both page designs adapt to the width they are given using CSS container queries, so it looks right inside a narrow theme content column as well as on a full width page. For the full width look, use the block with "Full width" alignment.

== Review photos ==

If you collect photos with a photo-review plugin that stores media in the `reviews-images` comment meta, this plugin picks them up automatically. No configuration needed: it reads that comment meta.

* Each review shows its photos as thumbnails under the review text; clicking one opens a lightbox with previous/next navigation, keyboard support (arrow keys, Escape) and focus handling.
* Images, videos and YouTube/Vimeo links are all supported. Reviews imported from marketplaces, where the image is a plain URL instead of a media library attachment, work too.
* The enlarged image prefers the review-photo size a photo-review plugin generates when it exists, then falls back to `medium_large`, `large` and the original.
* Use `[all_reviews photos="yes"]` to show only the reviews that have photos, and `show_photo_filter="yes"` to let visitors toggle "With photos only".
* Photo URLs are validated before they are rendered, and unsupported or malformed entries are skipped.

Using a different photo review plugin? Filter `awr_review_images_meta_key` to point at its comment meta key; the value may be an array of attachment IDs or URLs.

== Installation ==

1. Upload the `all-woocommerce-reviews` folder to `/wp-content/plugins/`, or install the ZIP through *Plugins → Add New → Upload Plugin*.
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 `awr_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-woocommerce-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 links. For any other plugin, filter `awr_review_images_meta_key` to return its meta key.

== Screenshots ==

1. The front-end review page: rating summary, filter bar, review cards and the reviews' product links.
2. The **All Reviews** admin screen under WooCommerce, with summary cards, filters and bulk moderation.
3. The **Review Page** settings screen, where the site-wide design and its defaults are chosen.
4. A review block in the editor, with its Order, Design and Filter panels open.
5. The review page on a phone.

== Changelog ==

= 1.17.1 =
* Fixed the summary's star links writing an invalid `awr_sort=random-desc`, which quietly dropped a random sort back to newest first. Random links now carry `awr_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 `awr_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 `awr_enqueue_design_fonts`.

= 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 `awr_get_review_form_url()` helper and `awr_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 (`AWR_Reviews::get_categories()`) and the `awr_category` URL filter behind the chips.
* Design fonts are opt-in through the `awr_enqueue_design_fonts` filter instead of being loaded from a third party by default.

= 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.17.1 =
Fixes the random-sort links on the rating summary and removes a no-op query argument. No configuration changes needed.
