Documentation for B7 Feedback Engine WP

General Tab

• Enable Feedback for Post Types: Select the post types (e.g., Posts, Pages) where the feedback form should be available or automatically inserted.
• Auto Insert Feedback Form: Check this to automatically add the feedback form to the end of the content for the selected post types. If unchecked, you'll need to use the [b7_feedback_wp] shortcode.
• Taxonomy Condition (Optional): Display the form *only* on posts belonging to specific taxonomy terms. Format: taxonomy_slug:::term_slug1, term_slug2. Example for category 'News': category:::news. Example for tag 'Tutorial': post_tag:::tutorial. Leave empty to disable this condition.
• Feedback Form Template: Choose the visual layout for the feedback form:
  • Default: Standard layout with title above buttons.
  • Center Title: Centers the form title and feedback buttons.
  • Sticky Bottom: Fixes the form (title and buttons) to the bottom of the viewport. Comment area appears above when triggered.
  • Flat: Places the title and buttons inline within a header section.
• Feedback Comment Display: Control when the comment textarea appears:
  • Always Show: The comment area is always visible.
  • Show on Dislike: Only appears after clicking the Dislike button (Default).
  • Show on Like: Only appears after clicking the Like button.
  • Show on Any Feedback: Appears after clicking either Like or Dislike.
  • Never Show: The comment area is completely hidden. Feedback is submitted immediately upon clicking Like/Dislike.
• Feedback Comment Character Limit: Set the maximum number of characters allowed in the feedback comment textarea.
• Display Stats Position: Choose where to automatically display feedback statistics (using the settings below) within the content of selected post types. Options: Disable, Top of content, Before first H2, After first Paragraph. This only applies if 'Auto Insert Feedback Form' is enabled and stats are configured below. Requires the [b7_feedback_wp_stats] shortcode otherwise.
• Stats Type to Display: Select which type of statistics to show when using the automatic display position: Submission Stats (actual likes/dislikes) or Custom Stats (manually set in post editor).
• Stat Template: Choose the visual template for the displayed stats: Default Bar or Versus Bar.
• Minimum Feedback Count to Show: Only display the stats block if the total number of feedback submissions (or custom stats total) meets or exceeds this number. Set to 0 to always show (if available).

Text Customization Tab

• Like Button Text: Customize the text displayed on the "Like" button (Default: Like).
• Dislike Button Text: Customize the text displayed on the "Dislike" button (Default: Dislike).
• Comment Label Text: Customize the label displayed above the comment textarea (Default: Feedback comment (optional)).
• Submit Button Text: Customize the text on the button used to submit the comment (Default: Submit).
• Cancel Button Text: Customize the text on the button used to close the comment area (Default: Cancel).
• Pre-defined Comment 1/2/3: Add up to three quick-reply buttons that appear below the comment textarea. Clicking these inserts the predefined text into the textarea. Leave blank to disable.
• Submission Stats Label: Customize the label displayed above the feedback statistics when showing submission stats (Default: Feedback Stats:).
• Custom Stats Label: Customize the label displayed above the feedback statistics when showing custom stats (Default: Custom Feedback Stats:).
• Thank You Message: The message shown to the user after successfully submitting feedback.
• Enable Icons: Toggle the display of Dashicons next to the Like/Dislike button text.
• Like Button Icon: Enter the CSS class for the Dashicon to use for the Like button (e.g., dashicons-thumbs-up, dashicons-heart). Browse available icons on the WordPress developer site.
• Dislike Button Icon: Enter the CSS class for the Dashicon to use for the Dislike button (e.g., dashicons-thumbs-down, dashicons-no-alt).

Email Notification Tab

• Enable Email Notification: Check this box to enable email notifications for new feedback.
• Notification Triggers: Choose when to send notifications: For all feedback, Only for Like, Only for Dislike, Only with feedback comment, or Disable notifications entirely.
• Notification Email Address: The email address where notifications will be sent (Defaults to the site admin email).

Spam Prevention Tab

• Enable Spam Prevention by IP: Activate IP-based submission limiting to prevent abuse.
• Max Feedback Submissions per IP: The maximum number of times a single IP address can submit feedback for the *same post* within the selected time range.
• Time Range for IP Limit: The duration for the IP limit (Per Hour, Per Day, Per Week).
• Feedback Delay Timer (seconds): Enter the number of seconds a user must wait on the page before the feedback buttons become active. Set to 0 to disable the delay. Useful for preventing quick, non-genuine feedback.

Note: The plugin also includes hidden honeypot fields (b7_feedback_hp_name, b7_feedback_hp_email) to catch simple bots. These should remain empty for valid submissions.

Styling Tab

Customize the visual appearance of the feedback form. These styles are applied only if 'Enable Custom Styling' is turned on.

• Enable Custom Styling: Toggle switch to activate/deactivate all custom styles defined below. If off, the plugin relies solely on its default CSS (public-style.css).
• Form Container Background Color: Set the background color of the main feedback form container.
• Form Padding: Set the padding inside the form container (e.g., 20px, 15px 25px).
• Form Margin: Set the margin outside the form container (e.g., 20px 0, 30px auto).
• Form Title Color: Set the text color of the form's title (e.g., "Was this helpful?").
• Form Title Font Size: Set the font size of the form's title (e.g., 1.3em, 18px).
• Like Button Background Color: Set the background color of the Like button.
• Dislike Button Background Color: Set the background color of the Dislike button.
• Like Button Text Color: Set the text color of the Like button.
• Dislike Button Text Color: Set the text color of the Dislike button.
• Comment Area Background Color: Set the background color of the comment textarea section.
• Comment Area Text Color: Set the text color inside the comment textarea.
• Submit Button Text Color: Set the text color of the Submit button.
• Submit Button Font Size: Set the font size of the Submit button text (e.g., 1em, 14px).
• Cancel Button Text Color: Set the text color of the Cancel button.
• Cancel Button Font Size: Set the font size of the Cancel button text (e.g., 0.9em, 13px).
• Reset Styling: A button to revert all styling options on this tab back to their default values.

Tools Tab

• Reset Feedback for Posts: Enter comma-separated Post IDs to target specific posts for feedback reset.
• Reset Feedback Type: Choose which type of feedback data to reset for the specified posts (All, Only Likes, Only Dislikes, Only Comments). Click the "Run Reset" button to execute. Use with caution! This action cannot be undone.
• Open Shortcode Builder: Click this button to open a modal window that helps you generate the [b7_feedback_wp_stats] shortcode with various options.
• Demo Mode: If enabled, the feedback form will only be visible to site administrators. Spam prevention (IP limits) is also bypassed for admins in this mode. Useful for testing without affecting regular users or collecting test data.

Membership Management Tab

• User Submission Limit: Set a maximum number of feedback submissions allowed per logged-in user across the entire site. Set to 0 for unlimited submissions. This limit does not apply to non-logged-in users.
• Allowed User Roles: Select specific user roles that are permitted to submit feedback. If no roles are selected, all logged-in users (subject to the submission limit) and non-logged-in users can submit feedback. Administrators are always allowed, regardless of this setting.

Import / Export Tab

• Import Settings: Upload a JSON file (previously exported from this plugin) to restore settings.
• Export Settings: Download a JSON file containing all current plugin settings. Useful for backups or migrating settings between sites.

Privacy Tab

• Anonymize IP Addresses: If checked, stored IP addresses will be partially anonymized (e.g., the last octet replaced with 0 like 192.168.1.0) in the database and data views.
• Anonymize Usernames: If checked, usernames associated with feedback (for logged-in users) will be displayed as 'Anonymous User' in the Feedback Data table, though the User ID is still stored.
• Keep Feedback Data (Days): Specify the number of days to retain feedback data. Data older than this period will be automatically deleted daily via a scheduled cron job. Set to 0 to disable automatic deletion. (Default: 90 days).

Automatic Insertion

If you have enabled "Auto Insert Feedback Form" in the General settings, the form will automatically appear at the end of the content for posts matching the selected post types and (if configured) taxonomy conditions.

If you've configured automatic stats display under General Settings, the corresponding stats block will appear in the selected position (e.g., Top of Content).

You can disable the form on a specific post using the "B7 Feedback Options" metabox in the post editor.

Using Shortcodes

You can manually place the feedback form or statistics anywhere within your content using shortcodes:

• Feedback Form: Use [b7_feedback_wp] to insert the feedback form.
• Feedback Statistics: Use [b7_feedback_wp_stats] to display feedback statistics. Customize its behavior using attributes generated by the Shortcode Builder (Tools tab) or manually:
  • id="123": Specify the post ID (optional, defaults to current post).
  • submission_stat="on": Show stats based on actual likes/dislikes.
  • custom_stat="on": Show stats based on values set in the post editor.
  • stat_template="default" or stat_template="versus": Choose the display template.
  • min_show="5": Set the minimum total feedback count required to display the stats.

  Example: Display versus bar submission stats for post ID 456, only if it has at least 10 feedbacks:

  [b7_feedback_wp_stats id="456" submission_stat="on" stat_template="versus" min_show="10"]

  Example: Display default bar custom stats for the current post:

  [b7_feedback_wp_stats custom_stat="on" stat_template="default"]

Viewing Feedback Data

Navigate to B7 Feedback > Feedback Data in the admin menu.

This page displays a table of all feedback submissions, including:

• Submission ID
• Post ID (linked to the post editor) & Title Snippet
• Feedback Type (Like/Dislike)
• Comment (if provided)
• IP Address (potentially anonymized based on Privacy settings)
• User ID & Username (potentially anonymized based on Privacy settings, 'Guest' for non-logged-in)
• Timestamp

From this page, you can also:

• Clear all feedback data: Permanently removes all entries from the feedback table.
• Export All Feedback Data to CSV: Generates and provides a download link for a CSV file containing all feedback data. The link is temporary (5 minutes).

Using the Feedback Report

Navigate to B7 Feedback > Feedback Report.

This page provides aggregated insights:

• Filters: Filter the report by Start Date, End Date, and selected Post Types.
• Basic Summary: Shows total feedback, likes, dislikes, comments, and like/dislike percentages for the filtered period/post types.
• Top & Bottom Posts: Lists the top 5 most liked and top 5 most disliked posts based on the filtered data. Post titles link to their respective edit screens.

Post Editor Metaboxes

When editing a post type for which feedback is enabled, you'll find metaboxes in the editor sidebar:

• B7 Feedback Options:
  • Checkbox to Disable Feedback Form on this post, overriding the auto-insert setting.
  • Displays the current Like/Dislike counts and percentages for this specific post.
• Custom Feedback Stats:
  • Fields to manually enter Custom Likes and Custom Dislikes counts.
  • These values are used when displaying stats with the custom_stat="on" shortcode attribute or if 'Custom Stats' is selected for automatic display.

Actions and Filters

The plugin provides some hooks for customization:

• Action: b7_feedback_submitted - Fires after a feedback entry is successfully saved to the database. Passes $post_id, $feedback_type, $feedback_comment, $ip_address.
• Filter: b7_feedback_form_output - Allows modification of the generated feedback form HTML before it's displayed. Passes the $output HTML string.
• Filter: b7_feedback_stats_shortcode_output - Allows modification of the generated feedback stats HTML before it's displayed by the shortcode. Passes $output, $atts, $post_id.

// Example: Add custom content after feedback form
add_filter('b7_feedback_form_output', 'my_custom_content_after_feedback', 10, 1);
function my_custom_content_after_feedback($output) {
    $output .= '
Thank you for helping us improve!
';
    return $output;
}

// Example: Do something after feedback is submitted
add_action('b7_feedback_submitted', 'my_feedback_logging', 10, 4);
function my_feedback_logging($post_id, $feedback_type, $feedback_comment, $ip_address) {
    // Log feedback to a custom log file or external service
    error_log("Feedback on Post {$post_id}: Type={$feedback_type}, IP={$ip_address}, Comment={$feedback_comment}");
}

AJAX Actions

The plugin uses WordPress AJAX for various operations:

• wp_ajax_b7_submit_feedback / wp_ajax_nopriv_b7_submit_feedback: Handles feedback form submissions.
• wp_ajax_b7_run_feedback_reset: Executes the feedback reset tool.
• wp_ajax_b7_reset_styling_settings: Resets styling options to default.
• wp_ajax_b7_get_shortcode_preview: Generates the live preview for the Shortcode Builder.
• wp_ajax_b7_import_settings: Handles importing settings from a JSON file.
• wp_ajax_b7_export_settings: Handles exporting settings to a JSON file.
• wp_ajax_b7_feedback_download_csv: Handles the download request for the exported CSV data.

Database Table

The plugin creates one custom database table:

• {$wpdb->prefix}b7_feedback_data: Stores individual feedback submissions.
  • id (mediumint, PK, AI)
  • post_id (mediumint)
  • feedback_type (varchar: 'like' or 'dislike')
  • feedback_comment (text, nullable)
  • user_id (mediumint, 0 for guests)
  • ip_address (varchar)
  • timestamp (datetime)

The plugin also uses standard WordPress options (wp_options table) to store its settings under the option name b7_feedback_settings.