=== Relatedly ===
Contributors:      iamkingsleyf, kraftysprouts
Tags:              related posts, related content, related articles, content recommendation, post suggestions
Requires at least: 5.0
Tested up to:      7.0
Requires PHP:      7.4
Stable tag:        2.0.7
License:           GPLv2 or later
License URI:       https://www.gnu.org/licenses/gpl-2.0.html

Advanced related posts engine with inline display, end-of-content lists, RSS integration, and multiple themes.

== Description ==

Relatedly automatically displays related posts to keep readers engaged and reduce bounce rate. It matches posts by categories, tags, or both, and offers multiple display styles to fit any theme.

**Key Features:**

* **Inline related posts** — insert related posts between paragraphs at a configurable interval
* **End-of-content related posts** — append a related posts section after post content
* **8 inline themes** — Simple, Minimal, Featured, Quote, Badge, Callout, Gradient, Card
* **6 end-of-content themes** — List, Simple List, Masonry, Carousel, Timeline, Compact
* **RSS feed integration** — add related posts to your RSS feed with UTM tracking
* **Click & impression tracking** — built-in analytics dashboard
* **Email reports** — scheduled weekly or monthly performance reports
* **Floating sidebar** — optional floating related posts widget
* **CSS custom properties** — all colours are user-configurable without touching code
* **Performance-first** — pool-based queries ordered by date (no `ORDER BY RAND()`), transient caching, conditional asset loading
* **Developer-friendly** — PSR-4 autoloading, template override system, action/filter hooks

**Developer Filters:**

* `relatedly_inline_labels` — modify the inline label pool
* `relatedly_end_content_labels` — modify the end-content label pool
* `relatedly_excluded_elements` — add custom HTML elements to exclude from inline insertion
* `relatedly_rss_utm_parameters` — modify UTM parameters for RSS links
* `relatedly_rss_output_format` — customise RSS inline post HTML
* `relatedly_rss_end_content_format` — customise RSS end-content post HTML
* `relatedly_register_themes` — register custom themes via ThemeRegistry

**Template Overrides:**

Place template files in `your-theme/relatedly/inline/simple.php` (etc.) to override any theme template without modifying plugin files.

== Installation ==

1. Upload the `relatedly` folder to `/wp-content/plugins/`
2. Activate the plugin through the **Plugins** menu in WordPress
3. Go to **Relatedly → Settings** to configure display options
4. Related posts will appear automatically on single post pages

== Frequently Asked Questions ==

= Does this plugin slow down my site? =

No. Relatedly uses a pool-based query strategy — it fetches 30 posts ordered by date (using the database index), caches the pool per post with a configurable TTL, and shuffles in PHP. This avoids the expensive `ORDER BY RAND()` pattern used by many related post plugins.

= Can I customise the look of related posts? =

Yes. Each theme's colours are configurable via CSS custom properties in the settings. Use **Appearance → Customize → Additional CSS** in WordPress for site-wide styling beyond the built-in colour options.

= Can I override templates in my theme? =

Yes. Create a `relatedly/` folder in your theme directory and place template files there. For example, `your-theme/relatedly/inline/simple.php` will override the Simple inline theme template.

= Does it work with custom post types? =

Yes. Go to **Settings → General** and select which post types to enable.

= Does it work with RSS feeds? =

Yes. Enable RSS integration in **Settings → RSS Feed**. Related posts are added inline and at the end of each feed item, with configurable UTM parameters for tracking.

= Is click tracking GDPR compliant? =

The plugin stores IP addresses and user agents in a custom database table. This is disclosed in the Privacy section below. You can disable tracking entirely in **Settings → General**. The plugin integrates with WordPress's built-in personal data export and erasure tools.

= How do I disable related posts on specific posts? =

Use the `relatedly_excluded_elements` filter or disable the plugin for specific post types in Settings → General.

== Screenshots ==

1. Settings page — General tab
2. Inline related post — Simple theme
3. End-of-content related posts — List theme
4. Floating sidebar widget
5. Statistics dashboard
6. Theme customization options

== Changelog ==

= 2.0.7 =
* Fix UTF-8 BOM in Floating Variant class files (rewritten through editor with proper file header docblocks)
* Fix MissingTranslatorsComment — phpcs:ignore moved above the translators comment so it sits directly before printf()
* Fix InterpolatedNotPrepared warnings — SQL extracted to $sql variable so phpcs:ignore lands on the flagged line
* Fix NoCaching false positives — phpcs:ignore extended to cover the query call lines in DataProvider
* Fix OutputNotEscaped in floating sidebar variant label
* Fix PreparedSQL.NotPrepared in DataProvider query calls

= 2.0.6 =
* Fix UTF-8 BOM in Floating Variant class files — rewritten through editor, also adds proper file header docblocks
* Fix MissingTranslatorsComment — move phpcs:ignore above the translators comment so it sits directly before printf()
* Fix InterpolatedNotPrepared warnings — extract SQL strings to $sql variable so phpcs:ignore lands on the correct line
* Fix NoCaching false positives — extend phpcs:ignore to cover the query call lines in DataProvider

= 2.0.5 =
* Fix stable tag mismatch between readme.txt and plugin header
* Fix str_ends_with() replaced with substr() for PHP 7.4 / WordPress 5.0 compatibility
* Fix table name escaping in all direct DB queries (esc_sql())
* Add targeted phpcs:ignore for false-positive nonce/escaping/prefix sniffs in templates and stream-wrapper file ops
* Normalize mixed line endings in Floating Variant class files

= 2.0.4 =
* Fix escaping compliance: replace pre-built HTML attribute strings with individual scalar values escaped at output time across all 19 templates

= 2.0.3 =
* Remove languages/.gitkeep and dev markdown files from distribution package
* Include composer.json when vendor/ is bundled

= 2.0.2 =
* Restore Plugin URI to https://kraftysprouts.com/portfolio/relatedly/

= 2.0.1 =
* WordPress.org review compliance: wire email report scheduling, remove custom CSS field, update premium upsell copy
* Remove bundled jQuery — use WordPress core jQuery for DataTables
* Upgrade SweetAlert2 to a privacy-safe release
* Remove load_plugin_textdomain() — translations load automatically on WordPress.org
* Update Plugin URI and contributors list

= 2.0.0 =
* Complete rebuild — PSR-4 architecture, no CDN dependencies, pool-based queries
* All third-party libraries bundled locally (Choices.js, Tippy.js, SweetAlert2, Flatpickr, Chart.js, DataTables)
* Declarative options schema replaces 360-line procedural sanitizer
* CSS custom properties replace inline styles on every element
* PHP template files replace HTML string concatenation
* PHPUnit test suite added
* GDPR data export/erasure hooks added
* Batched impression tracking (one AJAX request per container)
* Monthly tracking data pruning cron added

= 1.9.15 =
* Namespace refactor completed (ksm_relatedly → relatedly)
* Table schema version tracking added

= 1.9.13 =
* Option and hook prefix changed from ksm_relatedly_ to relatedly_

= 1.8.8 =
* Critical fix: boolean options no longer reset to defaults on page load

= 1.8.5 =
* Label management system — disable individual default labels from admin UI

= 1.8.4 =
* RSS end-content related posts added
* UTM parameter customization added

= 1.8.3 =
* Floating sidebar added (5 variants)

= 1.7.0 =
* Statistics dashboard, click tracking, email reports added

= 1.0.0 =
* Initial release

== Upgrade Notice ==

= 2.0.0 =
Major rebuild. Settings and tracking data are preserved. Deactivate v1.x and activate v2.0.0 — no manual migration needed.

== Support ==

* [Documentation](https://kraftysprouts.com/docs/relatedly/)
* [Support Forum](https://wordpress.org/support/plugin/relatedly/)
* [Contact](https://kraftysprouts.com/contact/)

== Credits ==

Built by [Krafty Sprouts Media, LLC](https://kraftysprouts.com).

Third-party libraries included in this plugin:
* [Choices.js](https://github.com/Choices-js/Choices) — MIT License
* [Tippy.js](https://github.com/atomiks/tippyjs) — MIT License
* [Popper.js](https://github.com/floating-ui/floating-ui) — MIT License
* [SweetAlert2](https://github.com/sweetalert2/sweetalert2) — MIT License
* [Flatpickr](https://github.com/flatpickr/flatpickr) — MIT License
* [Chart.js](https://github.com/chartjs/Chart.js) — MIT License
* [DataTables](https://github.com/DataTables/DataTables) — MIT License

== Privacy ==

This plugin collects the following data when click tracking is enabled:

* Source post ID (the post the visitor was reading)
* Clicked post ID (the related post that was clicked)
* Display type (inline, end_content, or floating)
* Event type (click or impression)
* IP address
* User agent string
* Timestamp

This data is stored in the `wp_relatedly_clicks` table in your WordPress database. It is used solely for the statistics dashboard and email reports. It is never transmitted to external servers.

**To disable data collection:** Go to Relatedly → Settings → General and uncheck "Enable Click Tracking".

**Data retention:** Rows older than 90 days are automatically deleted by a monthly scheduled task. The retention period is configurable in Settings.

**GDPR:** This plugin integrates with WordPress's built-in personal data tools (Tools → Export Personal Data / Erase Personal Data).
