﻿=== Help Metric Article Helpful Feedback ===
Contributors: josevarghese
Tags: feedback, helpful, rating, user experience, documentation
Requires at least: 5.0
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Donate link: https://buymeacoffee.com/josevarghese

Add a "Was this page helpful?" feedback widget to your WordPress site - with icon styles, analytics dashboard, email alerts, and GDPR tools.

== Description ==

**Help Metric Article Helpful Feedback** lets your visitors tell you instantly whether your content is hitting the mark. A clean "Was this page helpful?" widget appears at the bottom of your posts, pages, or WooCommerce products. Visitors click Yes or No - optionally leaving a written comment - and you get a real-time picture of what's working and what isn't, right inside your WordPress dashboard.

No third-party services, no tracking scripts, no bloat. All data stays in your own database.

= Why use Help Metric Article Helpful Feedback? =

Most feedback plugins are either too simple (just a vote counter) or too complex (full survey tools). This plugin sits in the sweet spot: it's quick for visitors to use, gives you genuinely useful data, and has the professional features - GDPR tools, rate limiting, email alerts, analytics charts - that serious sites need without paying for a SaaS platform.

= Key Features =

**Widget & Placement**

* **Easy Setup** - works out of the box with sensible defaults; no configuration required to get started
* **Gutenberg Block** - insert the widget anywhere using the native block editor
* **Shortcode** - place the widget manually with `[hmahf_widget]` in any classic editor, page builder, or text widget
* **Content Type Selection** - choose which post types display the widget (posts, pages, custom post types, WooCommerce products)
* **Per-Post Disable Toggle** - hide the widget on individual posts from the editor sidebar without touching global settings
* **Auto-Hide on Old Posts** - optionally stop showing the widget on posts older than a set number of days
* **WooCommerce Support** - display the widget on product pages

**Appearance**

* **5 SVG Icon Styles** - choose from Thumbs, Stars, Hearts, Faces, or Arrows with a live visual picker in Settings; icons update across the widget, feedback form, dashboard cards, and admin bar
* **Customizable Text** - change every text element (title, subtitle, button labels, success messages, form text) to match your brand voice
* **Clean Design** - professional, minimal layout that fits any theme without CSS conflicts
* **Mobile Responsive** - touch-friendly buttons, stacked layouts on small screens
* **Accessibility Ready** - full keyboard navigation and ARIA screen reader support

**Feedback Collection**

* **Optional Written Comments** - visitors who click "Not helpful" can explain why in a short text field
* **Vote Change / Retraction** - a "Changed your mind?" link lets visitors update their vote after submitting
* **Duplicate Submission Prevention** - cookie-based, IP-based, or open (your choice)
* **Rate Limiting** - server-side protection against spam (max 5 submissions per IP per hour)
* **AJAX Powered** - smooth experience with no page reloads

**Analytics & Reporting**

* **Analytics Dashboard** - overview cards showing total, positive, negative, and ratio stats; cards use your selected icon style
* **30-Day Trend Chart** - pure CSS bar chart showing daily positive and negative counts over the last 30 days (no external libraries)
* **Distribution Chart** - CSS conic-gradient donut showing your overall positive/negative split
* **Statistics Page** - per-post feedback breakdown with sortable columns and date/post-type filters
* **Feedback List** - browse, filter, and search all individual feedback entries and comments with pagination
* **CSV Export** - export your statistics data with one click
* **Admin Bar Stats** - today's feedback counts shown in the WP admin bar with your selected icons, visible to administrators at all times

**Notifications & Privacy**

* **Email Notifications** - get an email alert (including the visitor's comment) whenever negative feedback is submitted; configurable recipient address
* **GDPR Tools** - configurable data retention period (auto-purge entries older than N days) and one-click deletion of all collected data
* **IP Anonymization** - IP addresses are masked in the admin feedback display

**Developer-Friendly**

* **Three Action/Filter Hooks** - `hmahf_widget_html`, `hmahf_before_feedback_submit`, `hmahf_after_feedback_submit`
* **Translation Ready** - fully internationalized with proper text domains
* **No External Dependencies** - no CDN calls, no third-party APIs, no tracking

= Perfect For =

* Documentation and knowledge base sites
* Blog posts and tutorials
* Help centre articles
* WooCommerce product pages
* Any content where knowing what resonates helps you improve

= Customization Options =

* Enable/disable the feedback widget globally
* Select which content types show the widget
* Choose from 5 SVG icon styles via a visual picker
* Customize all widget and form text to match your brand
* Choose duplicate-submission prevention method (cookie, IP, or none)
* Set cookie expiration in days
* Auto-hide widget on posts older than N days
* Per-post disable toggle from the editor sidebar
* Configure data retention period for GDPR compliance
* Set a custom email address for negative-feedback notifications

Feedback data is stored as WordPress post meta in your own database - nothing is ever sent to an external service.

== Installation ==

1. Upload the plugin files to the `/wp-content/plugins/help-metric-article-helpful-feedback` directory, or install the plugin through the WordPress plugins screen directly.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Navigate to **Settings > Helpful Feedback** to configure the plugin.
4. Choose your icon style, customize the text, and select which content types show the widget.
5. The feedback widget will automatically appear on your selected content types.
6. View results under the **Helpful Feedback** menu in the WordPress admin sidebar.

== Frequently Asked Questions ==

= Does this plugin work with any theme? =

Yes. The widget uses clean, minimal styling that blends with any properly coded WordPress theme. No theme-specific overrides needed.

= Can I customize the appearance? =

Yes. Choose from 5 SVG icon styles (Thumbs, Stars, Hearts, Faces, Arrows) via a visual picker in Settings, and customize all text elements. Additional layout options are planned for future releases.

= Where is the feedback data stored? =

All data is stored as WordPress post meta in your own database. Nothing is sent to any external service.

= Is the plugin translation ready? =

Yes. The plugin is fully internationalized with proper text domains and translation functions throughout.

= Does it work on mobile devices? =

Yes. The widget is fully responsive with touch-friendly buttons and stacked layouts on small screens.

= Can I see feedback statistics? =

Yes. Navigate to **Helpful Feedback > Statistics** to see per-post feedback counts, ratios, and trends. Filter by post type and date range, sort any column, and export to CSV. The main dashboard also shows a 30-day trend bar chart and a distribution donut chart.

= How does duplicate submission prevention work? =

Choose from three methods in Settings:
- **Cookie** (recommended): A browser cookie is set after submission, expiring after your configured number of days.
- **IP Address**: The visitor's IP is recorded and checked on future submissions.
- **None**: Multiple submissions are allowed (useful for open polls).

= Can visitors change their vote? =

Yes. After submitting, a "Changed your mind? Update your vote." link appears below the success message. Clicking it re-shows the widget so the visitor can select a different option.

= How do the SVG icon styles work? =

Go to **Settings > Helpful Feedback > Icon Style** and click any of the five icon pairs shown (Thumbs, Stars, Hearts, Faces, Arrows). Save settings and the icon you chose will appear on the widget buttons, the feedback form, the dashboard cards, and the admin bar stats - everywhere consistently.

= Is there spam protection? =

Yes. The plugin enforces a server-side rate limit of 5 submissions per IP address per hour, regardless of the duplicate-submission setting.

= Is it GDPR compliant? =

Yes. You can set an automatic data retention period (entries older than N days are purged on retrieval) and use the "Delete All Feedback Data" button in Settings to permanently remove all collected feedback. IP addresses shown in the admin are anonymized.

= Will this slow down my site? =

No. The plugin is lightweight and only loads its CSS/JS on pages where the widget is displayed. Admin scripts are only loaded on the plugin's own pages. Dashboard queries use object caching and are scoped to posts that actually have feedback data.

= Can I disable the widget on a specific post? =

Yes. Open any post or page in the editor and look for the **Helpful Feedback** panel in the right sidebar. Check "Disable feedback widget on this post" to hide it on that individual post without affecting global settings.

= Can I place the widget manually? =

Yes. Use the `[hmahf_widget]` shortcode in any classic editor or page builder, or insert the **Helpful Feedback Widget** block from the Gutenberg block inserter.

= Does it work with WooCommerce products? =

Yes. Select "Products" under Content Types in Settings and the widget will appear on your WooCommerce product pages automatically.

= How do email notifications work? =

Enable notifications under **Settings > Helpful Feedback > Email Notifications**. You will receive an email whenever a visitor submits negative feedback, including any comment they left. Leave the address blank to use the WordPress admin email, or enter a custom address.

= What are the admin bar stats? =

When logged in as an administrator, today's positive and negative feedback counts are shown in the WordPress admin bar using your chosen icon style. Clicking the stat takes you directly to the dashboard.

= Can developers extend the plugin? =

Yes. Three hooks are available:
- `apply_filters('hmahf_widget_html', $html, $settings, $post_id)` - modify the widget output
- `do_action('hmahf_before_feedback_submit', $post_id, $feedback, $comment)` - fires before data is stored
- `do_action('hmahf_after_feedback_submit', $post_id, $feedback, $comment)` - fires after data is stored

== Screenshots ==

1. Admin dashboard with overview cards, trend chart, and distribution chart
2. Settings page - General Settings with the visual icon style picker
3. Settings page - Text customization options for all text
4. Settings page - Form settings and GDPR
5. Settings page - Admin display and Email notifications option
6. Feedback list with search, type filter, and pagination

== Changelog ==

= 1.0.0 =
* Initial release
* Full customization options for all text elements
* Content type selection (posts, pages, custom post types)
* AJAX-powered feedback submission
* Duplicate submission prevention (cookie and IP methods)
* Mobile responsive design
* Accessibility features (ARIA labels, keyboard navigation)
* Added Gutenberg block - insert the "Helpful Feedback Widget" block anywhere in the block editor
* Added `[hmahf_widget]` shortcode for manual widget placement in classic content and page builders
* Added per-post disable toggle - hide the widget on individual posts via the editor sidebar metabox
* Added WooCommerce product page support - enable the widget on product pages via Content Type settings
* Added vote change/retraction - visitors can update their vote after submitting via a "Changed your mind?" link
* Added full analytics dashboard with overview cards (total, positive, negative, ratio)
* Added Statistics page with sortable columns and post type / date range filters
* Added Feedback List page with search, type filter, and pagination
* Added CSV export for statistics data
* Added GDPR data retention setting - automatically purge entries older than N days
* Added "Delete All Feedback Data" button with confirmation for full data removal
* Added IP anonymization in admin feedback display
* Added server-side rate limiting (max 5 submissions per IP per hour)
* Option to hide the admin bar stats widget via Settings > Notifications > Admin Bar Stats
* Updated Tested up to: 6.9
* Added SVG icon styles - choose from Thumbs, Stars, Hearts, Faces, or Arrows via a visual icon picker in Settings

== Upgrade Notice ==
= 1.0.0 =
Initial release.
