=== Init Recent Comments – Templated, Modern, Minimal ===
Contributors: brokensmile.2103
Tags: comments, recent comments, widget, shortcode, template
Requires at least: 6.9  
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Display recent comments with customizable templates, Block Editor blocks, Abilities API support, and clean CSS.

== Description ==

**Init Recent Comments** is a developer-friendly plugin that lets you display the latest comments anywhere via a simple shortcode. It uses clean HTML, minimal CSS, and fully customizable templates.

No widgets, no bloated options. Just lightweight, extendable code — made for real sites, with native Block Editor support and Abilities API integration for the next generation of automation tools.

Key design goals:

- Native Block Editor blocks, one per shortcode, with live preview
- Abilities API support (WordPress 6.9+) for AI agents and automation tools
- Templated rendering with override support from themes
- Clean CSS you can disable or replace
- REST-ready architecture (future-proof)
- No jQuery, no nonsense

Perfect for blogs, news sites, or anyone who wants a better way to show active discussions.

This plugin is part of the [Init Plugin Suite](https://en.inithtml.com/init-plugin-suite-minimalist-powerful-and-free-wordpress-plugins/) — a collection of minimalist, fast, and developer-focused tools for WordPress.

GitHub repository: [https://github.com/brokensmile2103/init-recent-comments](https://github.com/brokensmile2103/init-recent-comments)

== Features ==

- Block Editor (Gutenberg) blocks: Recent Comments, Recent Reviews, User Recent Comments, User Recent Reviews — each with a live server-side preview in the editor
- Abilities API (WordPress 6.9+): all 4 shortcodes' data exposed as discoverable, executable abilities via `wp_get_abilities()` and the `wp-abilities/v1` REST namespace
- Simple shortcode: `[init_plugin_suite_recent_comments]` (legacy alias: `[init_recent_comments]`)
- Shortcode for displaying recent reviews: `[init_plugin_suite_recent_reviews]` (legacy alias: `[init_recent_reviews]`)
- Shortcode for displaying recent comments of a specific user: `[init_plugin_suite_user_recent_comments]` (legacy alias: `[init_user_recent_comments]`)
- Shortcode for displaying recent reviews of a specific user: `[init_plugin_suite_user_recent_reviews]` (legacy alias: `[init_user_recent_reviews]`)
- Template-based rendering (`comment-item.php`, `wrapper.php`)
- CSS can be disabled to use your theme's design
- No widgets, no jQuery, no frontend bloat
- Developer-ready: extend with filters, REST, and lazy loading (planned)
- Translation-ready (`.pot` included)

== Block Editor (Gutenberg) ==

Four dynamic blocks are available under their own **Init Recent Comments** category in the block inserter — no shortcodes needed if you prefer working entirely in the editor:

- **Recent Comments** — equivalent to `[init_plugin_suite_recent_comments]`
- **Recent Reviews** — equivalent to `[init_plugin_suite_recent_reviews]`
- **User Recent Comments** — equivalent to `[init_plugin_suite_user_recent_comments]`
- **User Recent Reviews** — equivalent to `[init_plugin_suite_user_recent_reviews]`

Each block shares the exact same rendering code as its shortcode, so switching between the Block Editor and shortcodes never changes the output. Block settings map directly to shortcode attributes, and a live preview is shown right in the editor as you configure it.

== Abilities API (WordPress 6.9+) ==

On WordPress 6.9 and above, Init Recent Comments registers four read-only abilities under the `init-recent-comments` category — `get-recent-comments`, `get-recent-reviews`, `get-user-recent-comments`, and `get-user-recent-reviews` — mirroring the plugin's four shortcodes exactly. This plugin has no write actions at all (it's a pure display plugin), so all of its functionality is safely exposed. These abilities are discoverable and executable via PHP (`wp_get_abilities()`), and — for sites that opt in — the `wp-abilities/v1` REST namespace. This integration is fully optional: on WordPress versions older than 6.9, it silently does nothing and the rest of the plugin is unaffected.

== Usage ==

Prefer working in the Block Editor? Each shortcode below has an equivalent block — see the "Block Editor (Gutenberg)" section above.

Use the shortcode anywhere:

`[init_plugin_suite_recent_comments number="5" maxheight="400px"]`

Recent reviews:

`[init_plugin_suite_recent_reviews number="5"]`

Recent comments of a specific user:

`[init_plugin_suite_user_recent_comments user_id="123"]`

Recent reviews of a specific user:

`[init_plugin_suite_user_recent_reviews user_id="123"]`

The legacy tags `[init_recent_comments]`, `[init_recent_reviews]`, `[init_user_recent_comments]`, and `[init_user_recent_reviews]` still work exactly the same way, for backward compatibility with existing content.

Attributes:

- `number` – Total items to show (default: 5)
- `maxheight` – Optional max height with scroll and hidden scrollbar (example: `300px`)
- `paged` – Optional pagination
- `theme` – Light or dark (example: `theme="dark"`)
- For user shortcodes: `user_id`, `user_login`, or `user_email` can be used to target the user

To override templates, create the folder in your theme:

    your-theme/
    └── init-recent-comments/
        ├── wrapper.php
        ├── review-wrapper.php
        ├── comment-item.php
        └── review-item.php

== Filters for Developers ==

This plugin provides multiple filters to help developers customize caching behavior and performance for recent comments, reviews, and total comment count queries.

**By default, comment/review queries are NOT cached (TTL = 0)** so newly posted comments always show up immediately — this is intentional, since most sites using this plugin expect real-time freshness. If your site has heavy traffic and you're fine with a short delay before new comments appear, you can enable caching yourself using the filters below (a value like `60` for 60 seconds is a reasonable starting point). Total comment count queries default to a 5-minute TTL instead, since counts are less time-sensitive.

`init_plugin_suite_recent_comments_ttl`  
Control the cache TTL (in seconds) for recent comments.  
Applies to: Recent Comments Query  
Params: `int $ttl`

`init_plugin_suite_recent_comments_query_args`  
Allows developers to modify or extend the WP_Comment query arguments before the query runs.  
Applies to: Recent Comments Query  
Params: `array $args`

`init_plugin_suite_recent_reviews_ttl`  
Control the cache TTL (in seconds) for recent reviews.  
Applies to: Recent Reviews Query  
Params: `int $ttl`

`init_plugin_suite_user_recent_comments_ttl`  
Control cache TTL (in seconds) for recent comments by a specific user.  
Applies to: `[init_user_recent_comments]`  
Params: `int $ttl`, `array $args`

`init_plugin_suite_user_recent_reviews_ttl`  
Control cache TTL (in seconds) for recent reviews by a specific user.  
Applies to: `[init_user_recent_reviews]`  
Params: `int $ttl`, `array $args`

`init_plugin_suite_total_comments_ttl`  
Control the cache TTL (in seconds) for total approved comment counts by post type.  
Applies to: Total Comments Query  
Params: `int $ttl`, `array $post_types`

`init_plugin_suite_total_by_posts_ttl`  
Control the cache TTL (in seconds) for total approved comment counts across multiple post IDs.  
Applies to: Total by Post IDs Query  
Params: `int $ttl`, `array $post_ids`

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/`
2. Activate via **Plugins → Init Recent Comments**
3. Use the shortcode `[init_plugin_suite_recent_comments]` in any page or widget
4. Optional: Visit **Settings → Init Recent Comments** to disable built-in CSS

== Screenshots ==

1. Settings page with CSS toggle

== Frequently Asked Questions ==

= Can I disable the plugin’s CSS? =  
Yes! Go to **Settings → Init Recent Comments** and check the box to disable built-in styling.

= Can I customize the comment HTML? =  
Absolutely. Copy `templates/comment-item.php` and `templates/wrapper.php` to your theme to override the output.

= Will this plugin slow down my site? =  
No. It uses `get_comments()` with sane defaults, no extra queries, no JavaScript.

== Changelog ==

= 2.0.0 – August 4, 2026 =
- **New: Abilities API support (WordPress 6.9+)**: registers four read-only abilities under the `init-recent-comments` category — `get-recent-comments`, `get-recent-reviews`, `get-user-recent-comments`, and `get-user-recent-reviews` — mirroring all four shortcodes exactly. This plugin has no write actions, so all of its data is safely exposed. Discoverable and executable via PHP, `wp_get_abilities()`, and — when a site opts in — the `wp-abilities/v1` REST namespace. Fully optional and backward-compatible: on WordPress versions older than 6.9, the integration silently does nothing
- **New: Block Editor (Gutenberg) support**: four dynamic blocks, grouped under their own **Init Recent Comments** block category (instead of the generic "Widgets" category) — **Recent Comments**, **Recent Reviews**, **User Recent Comments**, and **User Recent Reviews**, matching the four existing shortcodes. Each block is registered via `block.json` (with a PHP `render.php` file wired through the `"render"` field, WP 6.1+) that calls the exact same shortcode function as its shortcode counterpart — no duplicated display logic, output always matches. The editor integration is a single, no-build-step vanilla JavaScript file using `wp.serverSideRender` for a live preview directly in the editor
- **Changed**: `Requires at least` raised from 5.5 to 6.9 to support the Abilities API integration. `Requires PHP` remains 7.4
- **Tested up to: 7.1**

= 1.5 – July 21, 2026 =
- Shortcode Builder in the admin settings page now generates the prefixed shortcodes (`[init_plugin_suite_recent_comments]`, `[init_plugin_suite_recent_reviews]`, `[init_plugin_suite_user_recent_comments]`, `[init_plugin_suite_user_recent_reviews]`) by default; legacy tags remain fully supported
- Updated documentation to use the prefixed shortcodes as the primary examples, with legacy tags noted as backward-compatible aliases
- Uninstall routine now reliably removes the plugin's settings option
- Documented the default caching behavior (TTL = 0 for comments/reviews) in the Filters for Developers section
- Internal code cleanup for readability and maintainability

= 1.4 – November 5, 2025 =
- Introduced new user-specific shortcodes:
  - `[init_plugin_suite_user_recent_comments]` — display recent comments made by a specific user
  - `[init_plugin_suite_user_recent_reviews]` — display recent reviews made by a specific user
  - Backward-compat maintained: `[init_user_recent_comments]` and `[init_user_recent_reviews]`
- Both shortcodes reuse existing template system (wrapper.php / review-wrapper.php), ensuring UI consistency
- Fully supports pagination, theme mode, max height, and query argument overriding through filters
- Added new helpers for fetching user data:
  - `init_plugin_suite_recent_comments_get_user_comments()`
  - `init_plugin_suite_recent_comments_get_user_reviews()`
- Implemented separate cache groups for user comments & user reviews
  - TTL fully customizable via filters (`init_plugin_suite_user_recent_comments_ttl`, `init_plugin_suite_user_recent_reviews_ttl`)
- Updated review item template:
  - Display reviewer name and avatar resolved from `user_id` instead of relying on non-existing `author_name`
  - Fallback support for anonymous reviewers
- Internal improvements and cleanup for code reliability and maintainability

= 1.3 – November 4, 2025 =
- Added new filter `init_plugin_suite_recent_comments_query_args` allows developers to modify or extend the comment query args before running `get_comments()`
- Improved recent comments retrieval function:
  - Supports overriding query parameters via filter (e.g., filter by `post_type`, change `number`, include `meta_query`, etc.)
  - Maintains full backward compatibility
- UI update for Reply-to context:
  - Recent comment items now display "Replying to {Author}" when the comment has a parent
  - Added minimal CSS styling (non-intrusive, inherits container background)
- Codebase refinements:
  - Minor internal cleanups for readability and maintainability
  - Consistent filter naming across features to match the plugin's prefix standard

= 1.2 – October 12, 2025 =
- Enhanced caching flexibility for existing functions:
  - Added TTL filter support to init_plugin_suite_recent_comments_get_comments()
  - Added TTL filter support to init_plugin_suite_recent_comments_get_reviews()
  - Added TTL filter support to init_plugin_suite_recent_comments_get_total_comments()
- Introduced new helper function init_plugin_suite_recent_comments_get_total_by_posts() for counting total approved comments across multiple post IDs
- Separated cache group for comment totals (`init_comment_totals`) to improve cache isolation and performance
- Developers can now customize cache durations via filters
- Default TTL values remain unchanged (0 for comments/reviews, 5 minutes for totals)
- Minor internal optimizations for stability and consistency

= 1.1 – October 1, 2025 =  
- Added new shortcode `[init_recent_reviews]` for displaying recent reviews  
- Introduced prefixed shortcodes `[init_plugin_suite_recent_comments]` and `[init_plugin_suite_recent_reviews]` for better naming consistency  
- Maintained backward compatibility: old shortcodes `[init_recent_comments]` and `[init_recent_reviews]` still work  
- Added template override support for review wrapper (`init-recent-comments/review-wrapper.php`)  
- Unified CSS handling and options across both comments and reviews shortcodes  

= 1.0 – June 16, 2025 =  
- Initial release  
- Static shortcode `[init_recent_comments]`  
- Basic settings page to toggle CSS  
- Template override support  
- Clean CSS with disable option

== License ==

This plugin is licensed under the GPLv2 or later.  
You are free to use, modify, and distribute it under the same license.
