=== Stunning Related for Posts, Products, Pages and widgets ===
Contributors: wp-buy
Donate link: https://www.wp-buy.com/
Tags: related posts, related products, relevant, recommendations, similar
Requires at least: 5.4
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Rule-based related content for posts, pages, WooCommerce products and any custom post type. Unlimited displays, 12 templates, CTR analytics.

== Description ==

Most related-content plugins give you one global settings page and one block at the bottom of the article. This one is built around a different idea: you create **Displays**, and every display answers three separate questions.

* **WHAT** should be shown — content selection.
* **WHERE** should it appear — the placement engine.
* **HOW** should it look — layout, template and styling.

That separation runs all the way through the architecture:

`Content Provider → Relation Engine → Filters / Exclusions → Ranking → Cache → Placement Engine → Layout Renderer → Template`

= Unlimited independent displays =

One article can run several displays at once, each with its own content rules, position, design and priority — and the same item is never repeated twice on the page:

* "Read Next" — 1 related post after paragraph 4.
* "You May Also Like" — 3 posts after 65% of the article.
* "More From This Category" — 6 posts in 3 columns at the end.

Displays are ordered by a **priority** value, can be activated or deactivated individually, duplicated, and exported to JSON for another site.

= Weighted relation engine =

Instead of "same category", candidates are scored and ranked:

`related_score = primary category + categories + tags + custom taxonomies + product attributes + same author + recency`

Every weight is adjustable from 0 to 100, so two posts sharing a category and three tags naturally outrank one sharing only a category. The primary category set by **Yoast SEO** or **Rank Math** is recognised and weighted separately. A **Basic** engine mode is included when you want plain term matching where every shared term counts the same.

Other content controls:

* **Related by** — choose exactly which taxonomies create relatedness.
* **Recency window** — how recent an item must be to earn the recency bonus (0–3650 days).
* **Fallback** when relationships are thin — most recent, random, most-commented, or simply show fewer items.
* **Order** — relevance score, newest first, recently updated, title A→Z, or random.
* **Total items** — 1 to 60, independent of the column count.

= Selection modes =

* **Automatic** — the engine chooses.
* **Manual** — only your picks, in your order.
* **Manual + automatic** — your picks first, the remaining slots filled by the engine.

= HTML-aware in-content placement =

In-content insertion is resolved with a DOM pass. A block is only ever placed **between** top-level elements, so lists, tables, blockquotes, galleries and shortcodes are never split — content is never cut on `</p>` with a string function.

Available positions: before content, after title, after content, after paragraph X, before paragraph X, after X% of the article, middle of the article, before the first heading, after the first heading, before the last heading, before the conclusion, every X paragraphs, and every X words — the repeating positions with a maximum block count.

= WooCommerce placements =

24 product, shop, cart, checkout and order hooks:

* **Product page** — before product, before/after title, after rating, after price, before/after short description, before/after variations, before/after Add to Cart, after product summary, before/after product tabs, after product page.
* **Shop and archives** — before or after the product loop.
* **Cart** — before cart, cart collaterals, after cart, empty cart.
* **Checkout** — before or after the checkout form.
* **Order received** — after the order.

Cart, checkout and order-received recommendations are derived from what is actually in the cart or in the completed order, and never recommend a product the customer already has.

= Cross-content recommendations =

The engine is not hard-coded to post → post. Set a source and a target and a blog article can recommend products, while a product page recommends the guides that explain it. Cross-content matching links the two by matching term slugs across the taxonomies of the target post types.

= Display conditions =

A display runs only where you want it:

* Post types it is generated from.
* Taxonomy rules — "only when the post has …" and "never when the post has …", combined with **AND** or **OR** logic.
* Specific items to include or exclude by ID.
* WooCommerce product price range.
* Visitor state — everyone, logged-in only, or logged-out only.

= Per-post overrides =

Inside the post or product editor, a **Related Content** metabox can override the global behaviour for that item: use global settings, automatic, custom only, custom first then automatic, or disabled entirely — plus its own always-recommend and never-recommend lists with an AJAX search picker.

= Layouts, templates and responsive columns =

Layout controls the structure, the template controls the visual DNA, and the two are independent.

* **8 layouts** — grid, list, inline, carousel, masonry, compact, single recommendation, horizontal cards.
* **12 templates** — 01 Minimal, 02 Editorial, 03 Image Card, 04 Horizontal, 05 Magazine Grid, 06 Numbered, 07 Glass Cards, 08 Featured Recommendation, 09 Compact Pills, 10 Product Cards, 11 Product Minimal, 12 Carousel.
* Desktop / tablet / mobile **columns are core settings**, not advanced ones, and the item count is separate from the column count.
* Adjustable grid gap.

= Design controls =

* Heading text, tag (H2–H5, div, span) and alignment.
* Fields to show: image, title, excerpt, category or term, date, author, reading time, read-more button — plus price, rating, Add to Cart and sale badge when WooCommerce is active. Fields a template does not support are ignored.
* Excerpt length in words, image ratio (16:9, 4:3, 3:2, 1:1, 3:4, 2:3 or original), link target and button text.
* **Customize template**: accent, card background, title, text, meta and border colours; corner radius, image radius, card padding, title size, text size; and shadow depth. Everything is emitted as CSS custom properties on the block wrapper, so nothing leaks into the rest of the page.

= Live preview =

The editor renders a real preview from real content on your site while you work, with desktop, tablet and mobile device toggles, a full-screen preview overlay and a template navigator for stepping through all 12 templates without leaving the screen.

= Performance =

* Resolved recommendation IDs are cached per post and regenerated automatically when the post, its terms or the display change. Cache lifetime is selectable per display: disabled, 1 hour, 1 day, 1 week, 1 month.
* Scoring happens in one grouped SQL query, not one query per candidate.
* Nothing is enqueued globally. The stylesheet loads only when a display will actually render, and the carousel script only when a carousel is really on the page.
* Optional lazy loading for recommendation images.

= Analytics =

Impressions and clicks are aggregated per day, so you can see click-through rate per template, per placement, per display and per recommended item — which recommendation strategy actually works, not just which one looks nice. Aggregated counters only: no cookies and no personal data. A retention window (0–1825 days) prunes old rows automatically.

= Manual placement =

* Shortcode: `[smart_related id="5"]`
* Gutenberg block: **Related Content**
* Widget: **Related Content (Stunning Related)**
* PHP: `<?php srpp_the_related_content( 5 ); ?>` (the older `smart_related_content()` still works)

= Tools =

Clear the recommendation cache, reset statistics, and export or import displays as JSON to move a configuration between staging and production.

= Exclusions =

Never recommend the current item, password-protected content, private content, content marked noindex by Yoast SEO or Rank Math, or out-of-stock products — plus excluded terms, excluded authors, excluded item IDs, and a guard against showing the same item twice on one page.

= Privacy =

The plugin sends nothing to any external service. Analytics rows contain a display ID, a source post ID, a target post ID, a template key, a placement key, a date and two counters — no IP addresses, no cookies, no visitor identifiers.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/`, or install the ZIP from **Plugins → Add New → Upload Plugin**.
2. Activate it. A starter display, "Blog recommendations", is created for you.
3. Go to **Related Content → Displays** and click **+ Add Related Content**.
4. Answer the four questions — how it looks, what to show, where it appears, how many items — and save.

Optional: **Related Content → Settings** holds the global switches (cache, stylesheet, lazy images, analytics, retention, delete-on-uninstall), and **Related Content → Tools** holds cache clearing, statistics reset and JSON export/import.

== Frequently Asked Questions ==

= Does it work with custom post types? =

Yes. Every public post type registered on the site is detected automatically — courses, documentation, portfolio, downloads, jobs, events and so on. The same applies to public taxonomies, which can all be used for relatedness.

= Does it need WooCommerce? =

No. WooCommerce is optional. When it is active, the product placements, the product fields (price, rating, Add to Cart, sale badge), the product templates and the price-range condition appear automatically.

= Will it break my article markup? =

No. In-content insertion uses a DOM pass and only places blocks between top-level elements. Lists, tables, blockquotes, galleries and shortcodes are never split.

= Can several displays run on the same article? =

Yes, that is the point. Each one has its own priority, and the duplicate guard stops the same item appearing in two blocks on one page.

= Can I change the templates? =

Yes. Copy any file from `advanced-css3-related-posts-widget/templates/` into `your-theme/advanced-css3-related-posts-widget/` and it will be used instead. The template helper functions (`srpp_tpl_image()`, `srpp_tpl_title()`, `srpp_tpl_meta()`, …) are available there, and `$context`, `$display` and `$items` are in scope. Custom templates can also be registered with the `srpp_templates` filter.

= Which shortcode attributes are supported? =

`id`, `post_id`, `items`, `template`, `layout`, `columns`, `tablet`, `mobile` and `heading`. For example: `[smart_related id="5" items="4" columns="4" template="tpl-07"]`.

= Which hooks are available for developers? =

`srpp_related_ids`, `srpp_item_data`, `srpp_render`, `srpp_templates`, `srpp_conditions_pass`, `srpp_post_types`, `srpp_taxonomies`, `srpp_fields`, `srpp_image_size`, `srpp_placeholder_image` and `srpp_words_per_minute`.

= Is it slow on large sites? =

Relationship resolution is the expensive part of any related-content plugin, so it is done once per post and cached, and scoring runs as a single grouped SQL query. Front-end assets are conditional, so pages without recommendations load nothing at all.

= What happens when I uninstall it? =

Nothing is deleted unless you first enable **Delete all plugin data on uninstall** in Settings. With that switch on, displays, cached recommendation lists, per-post overrides, the statistics table and the plugin options are removed.

== Screenshots ==

1. The template library.
2. The editor with live preview and device toggles.
3. The collabsed tabs contains every control for a display.
4. The first admin page.

== Changelog ==

= 2.1 =
* Display-based architecture: unlimited independent recommendation rules, each with its own content, placement, layout and design, ordered by priority.
* Weighted relation engine with adjustable weights, primary-term detection for Yoast SEO and Rank Math, and a Basic term-matching mode.
* Selection modes: automatic, manual, and manual first with automatic fill.
* Cross-content recommendations between post types by matching term slugs.
* HTML-aware in-content placement with 13 positions, repeat-every-X-paragraphs/words and a maximum block count.
* 24 WooCommerce placements, with cart, checkout and order-received recommendations derived from the actual cart or order contents.
* Display conditions: post types, taxonomy include/exclude with AND/OR logic, specific items, product price range and visitor login state.
* Per-post and per-product override metabox with its own always/never recommend lists.
* 8 layouts and 12 templates, with independent desktop/tablet/mobile columns, image ratios and a full colour, radius, spacing, typography and shadow customiser emitted as CSS custom properties.
* Live preview with device toggles, a full-screen overlay and a template navigator.
* Per-post recommendation cache with automatic invalidation and a selectable lifetime, single-query scoring, and conditional asset loading.
* Daily-aggregated impression and click analytics with CTR per template, placement, display and item, plus a retention window.
* Output anywhere: `[smart_related]` shortcode, Related Content block, widget and `srpp_the_related_content()`.
* Tools: cache clearing, statistics reset, and JSON export/import of displays.
* Text domain is now `advanced-css3-related-posts-widget`. Theme template overrides load from `your-theme/advanced-css3-related-posts-widget/`; the previous folder keeps working.

= 1.2 = 
* Fixed Error in activation
* Added Default Image For non thumbnail posts
* Made the Plugin work in wordpress latest version

= 1.0 =
* CSS table and td fixed
* 3.3.1 compatibility fix
* Added hooks and filters for displaying posts in the side bar
* Added new 12 modern styles with easy control panel
* More advanced control on css3 functions
* Minor bug fixes

= 0.8 =
* changing priority of results order
* css style more compatibility fix with most themes
* Update sql code to get more equivalent results
* abbility to extract images from post content if there is no featured image set!

= 0.7 =
* CSS Style fixing
* Image display Fix
* New way of calculating image views

= 0.5 =
* CSS Style fixing
* New listing views

== Upgrade Notice ==
= 2.1 =
Version 2.1 introduces the display-based architecture, the weighted relation engine, WooCommerce placements and CTR analytics. Template overrides now live in your-theme/advanced-css3-related-posts-widget/ — the previous folder still works.
