BP Discovery Feed

An Instagram-style discovery feed for BuddyPress communities

🎯 Overview

The BP Discovery Feed plugin adds an Instagram-style "Explore" page to your BuddyPress-powered community. It displays trending posts from all users based on engagement metrics (likes, comments, shares, views), helping users discover popular content beyond their immediate connections.

Key Features:

• 📈 Trending Algorithm - Intelligent content ranking based on engagement
• 🎨 Modern UI - Responsive grid layout with smooth animations
• 🚀 High Performance - Caching, lazy loading, and optimized queries
• ♿ Accessible - WCAG AA compliant with keyboard navigation
• 🔧 Customizable - Shortcodes, widgets, and extensive settings
• 🔒 Secure - Nonce-verified AJAX, input sanitization, and permission checks
• 🌐 REST API - Full API access for custom integrations

📦 Installation

Requirements

• WordPress: 5.8 or higher
• PHP: 7.4 or higher
• BuddyPress: 7.0 or higher

Quick Install

1. Download the plugin from the WordPress repository
2. Upload to your WordPress plugins directory
3. Activate via WordPress Admin → Plugins
4. Configure settings at Settings → BP Discovery Feed

Manual Install

# Via WP-CLI
wp plugin install bp-discovery-feed --activate

# Or manually:
# 1. Download bp-discovery-feed.zip
# 2. Extract to /wp-content/plugins/
# 3. Activate via admin dashboard

Verification

After activation, you'll see:

• ✅ New "BP Discovery" admin menu
• ✅ /discovery/ page created automatically
• ✅ Database table wp_bp_trending_metrics created
• ✅ No activation errors

⚙️ Configuration

Admin Settings

Access settings at Settings → BP Discovery Feed or BP Discovery → Settings

General Settings

• Enable Discovery Feed: Toggle plugin on/off
• Items Per Page: Activities shown per page (1-50)
• Cache Duration: Result caching time (seconds)
• Enable Filters: Category, time, and location filters
• Grid Columns: Responsive layout columns (1-4)

Algorithm Configuration

Trending scores calculated using:

Score = (Likes × 3.0) + (Comments × 2.0) + (Shares × 4.0) + (Views × 0.5) × Time Decay

Adjustable Weights:

• Like Weight: 0-10 (default: 3.0)
• Comment Weight: 0-10 (default: 2.0)
• Share Weight: 0-10 (default: 4.0)
• View Weight: 0-5 (default: 0.5)
• Time Decay: Hours before score decays (default: 24)

Display Options

• Card Style: Compact or Expanded layout
• Show Trending Badges: 🔥 score indicators
• Show Engagement Metrics: Like/comment counts
• Enable Location Tracking: Geographic discovery

Shortcode Usage

// Basic discovery feed
[bp_discovery_feed]

// Advanced usage
[bp_discovery_feed per_page="15" show_filters="yes" columns="3"]

// Trending sidebar widget
[bp_trending_widget limit="8" show_score="yes"]

Widget Integration

1. Go to Appearance → Widgets
2. Add "BP Trending Widget" to any sidebar
3. Configure display options and save

🔌 API Usage

REST API Endpoints

# Get trending activities
GET /wp-json/bp-discovery/v1/trending?page=1&per_page=20&category=all&date_range=7_days

# Get specific activity metrics
GET /wp-json/bp-discovery/v1/metrics/123

JavaScript Integration

// Load activities programmatically
$.post(ajaxurl, {
    action: 'bpdf_get_trending_activities',
    nonce: bpdfData.nonce,
    page: 1,
    per_page: 20
}, function(response) {
    if (response.success) {
        // Handle activities
        console.log(response.data.activities);
    }
});

🎨 Frontend Features

Discovery Page Layout

• Responsive Grid: 1-4 columns based on screen size
• Filter Bar: Category, time, and location filters
• Infinite Scroll: Automatic content loading
• Loading States: Smooth animations and feedback

Activity Cards

• User Info: Avatar, name, and timestamp
• Content Preview: Smart excerpts with media support
• Engagement Stats: Like, comment, and view counts
• Action Buttons: Favorite, comment, and view links
• Trending Badges: 🔥 score indicators
• Accessibility: Full keyboard and screen reader support

Responsive Design

• Desktop: Multi-column grid layout
• Tablet: 2-column responsive
• Mobile: Single column stack
• Touch-friendly: Large tap targets and spacing

🛠️ Development

Hooks & Filters

// Customize trending algorithm
add_filter('bpdf_algorithm_weights', function($weights) {
    $weights['like_weight'] = 4.0; // Increase like importance
    return $weights;
});

// Add custom activity categories
add_filter('bpdf_activity_categories', function($categories) {
    $categories['videos'] = __('Videos', 'bp-discovery-feed');
    return $categories;
});

// Modify query parameters
add_filter('bpdf_query_args', function($args) {
    $args['meta_query'][] = array(
        'key' => 'featured_post',
        'value' => '1',
        'compare' => '='
    );
    return $args;
});

WP-CLI Commands

# Recalculate trending scores
wp bpdf recalculate

# Clear all caches
wp bpdf clear-cache

# View statistics
wp bpdf stats

# Reset plugin data
wp bpdf reset

Database Tables

• wp_bp_trending_metrics: Engagement tracking data
• wp_options: Plugin settings and transients

🔧 Troubleshooting

Common Issues

Plugin won't activate:

• Ensure BuddyPress 7.0+ is installed and active
• Check PHP version (7.4+ required)
• Verify WordPress 5.8+ compatibility

No trending content:

• Wait for WP-Cron to run (hourly updates)
• Check activity privacy settings
• Manually recalculate via WP-CLI: wp bpdf recalculate

Slow performance:

• Increase cache duration in settings
• Reduce items per page
• Clear caches: wp bpdf clear-cache

Discovery page not found:

• Check if page was created during activation
• Manually create page with shortcode: [bp_discovery_feed]
• Verify permalink settings

Debug Mode

Enable debugging in wp-config.php:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

Check /wp-content/debug.log for errors.

Reset Plugin

To completely reset:

# Deactivate plugin
wp plugin deactivate bp-discovery-feed

# Remove database table
wp db query "DROP TABLE IF EXISTS wp_bp_trending_metrics"

# Remove options
wp db query "DELETE FROM wp_options WHERE option_name LIKE 'bpdf_%'"

# Reinstall
wp plugin install bp-discovery-feed --activate

📊 Performance

Optimization Features

• Caching: Query results cached for configurable duration
• Lazy Loading: Images load as they enter viewport
• Database Indexing: Optimized queries with proper indexes
• WP-Cron: Automated metric updates and cleanup

Monitoring

• Query Performance: Monitor database query times
• Cache Hit Rates: Track caching effectiveness
• Memory Usage: Monitor PHP memory consumption
• Page Load Times: Track frontend performance

🔒 Security

Security Measures

• ✅ Input Sanitization: All inputs validated and sanitized
• ✅ Output Escaping: User data properly escaped
• ✅ Nonce Verification: AJAX requests nonce-protected
• ✅ Permission Checks: User capabilities verified
• ✅ SQL Injection Protection: Prepared statements used
• ✅ XSS Protection: Content properly escaped

Security Headers

The plugin respects WordPress security headers and doesn't override them.

♿ Accessibility

WCAG AA Compliance

• ✅ Keyboard Navigation: Full keyboard support
• ✅ Screen Reader Support: Proper ARIA labels
• ✅ Color Contrast: WCAG AA compliant colors
• ✅ Focus Management: Clear focus indicators
• ✅ Reduced Motion: Respects user preferences
• ✅ Semantic HTML: Proper heading hierarchy

Accessibility Features

• ARIA labels on interactive elements
• Keyboard shortcuts for common actions
• High contrast focus indicators
• Screen reader announcements
• Reduced motion support
• Touch-friendly interface

📄 License

This plugin is licensed under the GPL v2 or later.

Copyright (C) 2024 WBCom Designs

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

🤝 Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Development Setup

# Clone repository
git clone https://github.com/your-org/bp-discovery-feed.git
cd bp-discovery-feed

# Install dependencies (if any)
composer install
npm install

# Run tests
phpunit

📞 Support

Getting Help

1. Documentation: Check this README and Guide.md first
2. WordPress.org: Post in the plugin support forum
3. GitHub Issues: Report bugs and request features
4. Debug Logs: Enable WP_DEBUG for detailed error logs

Professional Support

For custom development, premium support, or consulting:

• Visit: WBCom Designs
• Email: support@wbcomdesigns.com

📈 Changelog

Version 1.0.0 (Current)

• 🎉 Initial release
• ✅ Full BuddyPress Nouveau integration
• ✅ Responsive grid layout
• ✅ Advanced trending algorithm
• ✅ REST API endpoints
• ✅ Comprehensive admin settings
• ✅ Accessibility compliance
• ✅ Performance optimizations
• ✅ Security hardening

Planned Features

• 🔄 Real-time trending updates
• 📱 Mobile app API endpoints
• 🤖 AI-powered content recommendations
• 📊 Advanced analytics dashboard
• 🎨 Custom theme templates
• 🌍 Multi-language support
• 🔍 Advanced search filters

BP Discovery Feed - Transform your BuddyPress community with Instagram-style content discovery! 🚀