BuddyLists

Introduction

BuddyLists is a powerful extension for BuddyPress and BuddyBoss platforms that allows users to create, manage, and share custom friend lists. Similar to Twitter’s list functionality, BuddyLists enables users to organize their connections, view activity streams from list members, and share their lists via unique URLs.

This developer documentation provides comprehensive guidance for developers looking to extend, customize, or integrate with the BuddyLists plugin.

Key Features:

Create and manage custom friend lists
Add/remove members with intuitive interface
Public or private list visibility options
Activity feeds filtered by list members
Follow/unfollow list functionality
Direct messaging to list members
Integration with existing BuddyPress/BuddyBoss components

Plugin Architecture

The plugin follows a modular architecture to facilitate maintenance and extensibility:

buddylists/
├── admin/                   # Admin-related files
│   ├── buddylist-admin-hooks-filters.php
│   ├── css/                 # Admin CSS files
│   ├── js/                  # Admin JavaScript files
│   ├── partials/            # Admin page templates
│   └── wbcom/               # WBCom admin framework
├── assets/                  # Frontend assets
│   ├── css/                 # Frontend CSS
│   ├── css-rtl/             # RTL CSS support
│   └── js/                  # Frontend JavaScript files
├── edd-license/             # EDD licensing system
├── includes/                # Core plugin functionality
│   ├── buddylists-functions.php  # Main functions
│   ├── buddylists-hooks-filters.php  # Hooks and filters
│   ├── db-schema.php        # Database structure
│   └── hooks.php            # Core hooks
├── languages/               # Translation files
├── templates/               # Frontend templates
└── widgets/                 # Widget components

Key Files

File	Description
`buddylists.php`	Main plugin file with initialization
`includes/buddylists-functions.php`	Core functions
`includes/db-schema.php`	Database table definitions
`includes/hooks.php`	Primary hooks initialization
`includes/buddylists-hooks-filters.php`	Hooks and filters implementation
`templates/single-list.php`	Single list view template
`templates/all-lists.php`	Lists overview template

Database Schema

BuddyLists creates three custom tables in the WordPress database:

bp_lists

Stores list information:

Column	Type	Description
`id`	BIGINT(20)	Primary key
`user_id`	BIGINT(20)	User ID of list creator
`name`	VARCHAR(255)	List name
`description`	TEXT	List description
`slug`	VARCHAR(6)	Unique slug for URL
`cover_image`	VARCHAR(255)	URL to cover image
`visibility`	ENUM(‘private’, ‘public’)	List visibility
`created_at`	DATETIME	Creation timestamp

bp_list_members

Maps members to lists:

Column	Type	Description
`id`	BIGINT(20)	Primary key
`list_id`	BIGINT(20)	Foreign key to bp_lists.id
`member_id`	BIGINT(20)	User ID of member
`added_at`	DATETIME	When member was added

bp_list_relation

Stores list follow relationships:

Column	Type	Description
`id`	BIGINT(20)	Primary key
`list_id`	BIGINT(20)	Foreign key to bp_lists.id
`follower_id`	BIGINT(20)	User ID of follower
`followed_at`	DATETIME	When follow relationship was created

Tables are created during plugin activation via the buddylists_create_tables() function defined in includes/db-schema.php.

Core API

BuddyLists provides a comprehensive API for interacting with lists and members.

List Management

/**
 * Creates a new list
 *
 * @param int    $user_id         User ID of list creator
 * @param string $list_name       List name
 * @param string $list_desc       List description
 * @param string $slug            URL slug for the list
 * @param string $cover_image_url URL to cover image
 * @param string $visibility      'public' or 'private'
 * @return array Status and response data
 */
buddylists_list_insert($user_id, $list_name, $list_desc, $slug, $cover_image_url, $visibility = 'public');

/**
 * Updates an existing list
 *
 * @param int    $list_id         List ID to update
 * @param int    $user_id         User ID of list owner
 * @param string $list_name       Updated list name
 * @param string $list_desc       Updated list description
 * @param string $slug            URL slug for the list
 * @param string $cover_image_url Updated cover image URL
 * @param string $visibility      Updated visibility ('public'|'private')
 * @return array Status and response data
 */
buddylists_list_update($list_id, $user_id, $list_name, $list_desc, $slug, $cover_image_url, $visibility = 'public');

/**
 * Deletes a list and its members
 *
 * @param int $list_id List ID to delete
 * @return bool True on success, false on failure
 */
buddylists_delete_list_data($list_id);

/**
 * Retrieves list data by ID
 *
 * @param int $list_id List ID
 * @return array List data
 */
buddylists_fetch_list_data_by_id($list_id);

/**
 * Retrieves list data by slug
 *
 * @param string $list_slug List slug
 * @return object List data
 */
buddylists_fetch_list_by_slug($list_slug);

/**
 * Retrieves complete list data including members
 *
 * @param int $list_id List ID
 * @return array Complete list data
 */
buddylists_fetch_list_all_data($list_id);

Member Management

/**
 * Adds a member to a list
 *
 * @param int $list_id   List ID
 * @param int $member_id User ID to add as member
 * @return array Status and response data
 */
buddylists_insert_members($list_id, $member_id);

/**
 * Removes a member from a list
 *
 * @param int $list_id   List ID
 * @param int $member_id User ID to remove
 * @return array Status and response data
 */
buddylists_delete_members($list_id, $member_id);

/**
 * Removes all members from a list
 *
 * @param int $list_id List ID
 * @return bool True on success, false on failure
 */
buddylists_delete_all_members($list_id);

/**
 * Retrieves all members of a list
 *
 * @param int $list_id List ID
 * @return array Array of member user IDs
 */
buddylists_fetch_member_data_by_list_id($list_id);

/**
 * Gets the number of members in a list
 *
 * @param int $list_id List ID
 * @return int Member count
 */
buddylists_fetch_member_count($list_id);

Following System

/**
 * Follow a list or user
 *
 * @param int    $user_id User ID of follower
 * @param int    $list_id List ID or User ID to follow
 * @param string $type    'list' or 'user'
 * @return bool Success status
 */
buddylists_follow_list($user_id, $list_id, $type = 'list');

/**
 * Unfollow a list or user
 *
 * @param int    $user_id User ID of follower
 * @param int    $list_id List ID or User ID to unfollow
 * @param string $type    'list' or 'user'
 * @return bool Success status
 */
buddylists_unfollow_list($user_id, $list_id, $type = 'list');

/**
 * Check if user is following a list or another user
 *
 * @param int    $user_id User ID of potential follower
 * @param int    $list_id List ID or User ID to check
 * @param string $type    'list' or 'user'
 * @return bool True if following, false otherwise
 */
buddylists_is_following_list($user_id, $list_id, $type = 'list');

/**
 * Get all lists followed by a user
 *
 * @param int $user_id User ID
 * @return array Array of list IDs
 */
buddylists_get_followed_lists($user_id);

/**
 * Get all followers of a list
 *
 * @param int $list_id List ID
 * @return array Array of user IDs
 */
buddylists_get_followers($list_id);

Utility Functions

/**
 * Get number of lists created by a user
 *
 * @param int $user_id User ID (defaults to current user)
 * @return int List count
 */
buddylists_list_count($user_id = 0);

/**
 * Check if user is in a list
 *
 * @param int $list_id List ID
 * @param int $user_id User ID (defaults to current user)
 * @return string|bool 'author', 'member', or false
 */
buddylists_is_user_in_list($list_id, $user_id = 0);

/**
 * Get paginated lists for a user
 *
 * @param int $user_id  User ID
 * @param int $page     Page number
 * @param int $per_page Items per page
 * @return array List data with pagination info
 */
buddylists_get_paginated_lists($user_id, $page = 1, $per_page = 10);

/**
 * Get URL for a list
 *
 * @param string $list_slug List slug
 * @return string URL to the list
 */
buddylists_list_link($list_slug = '');

/**
 * Check if a user can create lists
 *
 * @return bool True if user can create lists
 */
buddylists_create_list_permission();

/**
 * Get user profile URL
 *
 * @param int $user_id User ID
 * @return string User profile URL
 */
buddylists_get_user_url($user_id);

Hooks and Filters

BuddyLists provides numerous hooks and filters for extending functionality.

Action Hooks

/**
 * Fires after a member is added to a list
 *
 * @param array $response Insert response
 * @param int   $list_id  List ID
 * @param int   $member_id Member user ID
 */
do_action('buddylists_insert_members', $response, $list_id, $member_id);

/**
 * Fires after a member is removed from a list
 *
 * @param array $response Delete response
 * @param int   $list_id  List ID
 * @param int   $member_id Member user ID
 */
do_action('buddylists_delete_members', $response, $list_id, $member_id);

/**
 * Fires before the list banner on single list page
 */
do_action('buddylist_before_single_list_banner');

/**
 * Fires after the list banner on single list page
 */
do_action('buddylist_after_single_list_banner');

/**
 * Fires inside the list banner
 */
do_action('buddylist_single_list_banner');

/**
 * Fires after the direct message modal
 */
do_action('buddylist_after_direct_message_modal');

/**
 * Fires inside user info popup content
 *
 * @param int $user_id User ID
 */
do_action('buddylist-user-info-popup', $user_id);

Filters

/**
 * Filters list count
 *
 * @param int $count   List count
 * @param int $user_id User ID
 * @return int Modified list count
 */
apply_filters('buddylists_list_count', $count, $user_id);

/**
 * Filters list insertion result
 *
 * @param array $response Insert response
 * @return array Modified response
 */
apply_filters('buddylists_list_insert', $response);

/**
 * Filters list update result
 *
 * @param array $response Update response
 * @return array Modified response
 */
apply_filters('buddylists_list_update', $response);

/**
 * Filters member insertion result
 *
 * @param array $response Insert response
 * @param int   $list_id  List ID
 * @param int   $member_id Member user ID
 * @return array Modified response
 */
apply_filters('buddylists_insert_members', $response, $list_id, $member_id);

/**
 * Filters member deletion result
 *
 * @param array $response Delete response
 * @param int   $list_id  List ID
 * @param int   $member_id Member user ID
 * @return array Modified response
 */
apply_filters('buddylists_delete_members', $response, $list_id, $member_id);

/**
 * Filters list data
 *
 * @param array $list_data List data
 * @return array Modified list data
 */
apply_filters('buddylists_fetch_list_data_by_id', $list_data);

/**
 * Filters member data
 *
 * @param array $members_data Member data
 * @param int   $list_id      List ID
 * @return array Modified member data
 */
apply_filters('buddylists_fetch_member_data_by_list_id', $members_data, $list_id);

/**
 * Filters all list data
 *
 * @param array $response_data List data
 * @return array Modified list data
 */
apply_filters('buddylists_fetch_list_all_data', $response_data);

/**
 * Filters list URL
 *
 * @param string $list_url  List URL
 * @param string $list_slug List slug
 * @return string Modified URL
 */
apply_filters('buddylists_list_link', $list_url, $list_slug);

/**
 * Filters suggested members
 *
 * @param array $friends_data Friend data
 * @param int   $user_id      User ID
 * @return array Modified friend data
 */
apply_filters('buddylists_get_suggestions', $friends_data, $user_id);

/**
 * Filters template path
 *
 * @param string $template_part Template path
 * @param string $file_name     File name
 * @return string Modified template path
 */
apply_filters('buddylists_locate_template', $template_part, $file_name);

Settings Filters

/**
 * Filters general settings
 *
 * @param array $settings General settings
 * @return array Modified settings
 */
apply_filters('buddylists_general_settings', $settings);

/**
 * Filters visibility settings
 *
 * @param array $settings Visibility settings
 * @return array Modified settings
 */
apply_filters('buddylists_visibility_settings', $settings);

/**
 * Filters activity settings
 *
 * @param array $settings Activity settings
 * @return array Modified settings
 */
apply_filters('buddylists_activity_settings', $settings);

/**
 * Filters notification settings
 *
 * @param array $settings Notification settings
 * @return array Modified settings
 */
apply_filters('buddylists_notification_settings', $settings);

/**
 * Filters color settings
 *
 * @param array $settings Color settings
 * @return array Modified settings
 */
apply_filters('buddylists_color_settings', $settings);

Templates

BuddyLists follows the WordPress/BuddyPress template hierarchy system, allowing for theme overrides:

Template Loading

Templates are loaded using buddylists_locate_template() with the following hierarchy:

Child theme: /buddylists/template-name.php
Parent theme: /buddylists/template-name.php
Plugin: /templates/template-name.php

Core Templates

Template	Description
`all-lists.php`	Lists overview page in user profile
`buddylists-followed-lists.php`	Followed lists page
`single-list.php`	Single list view with activity stream
`public-list.php`	Public list display

Overriding Templates

To override any template:

Create a /buddylists/ directory in your theme
Copy the template file from the plugin’s /templates/ directory
Paste it into your theme’s /buddylists/ directory
Modify as needed

Template Function

/**
 * Locates and loads a template file
 *
 * @param string $file_name Template file name
 * @param bool   $load      Whether to load the template
 * @param array  $args      Template arguments
 * @return string Path to the template file
 */
buddylists_locate_template($file_name, $load = false, $args = array());

JavaScript Components

BuddyLists includes several JavaScript components to handle the dynamic functionality.

Frontend JavaScript

buddylists-user-profile.js

Handles user profile list management:

Function	Description
`reset_list_popup()`	Resets list creation/edit popup
`member_li_html()`	Generates HTML for member list items
`member_tab_count()`	Updates member tab count
`suggested_li_html()`	Generates HTML for suggested members
`suggested_tab_count()`	Updates suggested tab count
`loadMoreUsers()`	AJAX loading of more suggested users

buddylists-single-lists.js

Handles single list view functionality:

Function	Description
Direct messaging	Handles member selection and messaging
List following	Toggle follow/unfollow status
Member popups	Shows member preview on hover
Share functionality	Copy link and social sharing
Activity loading	Load more activity items

Admin JavaScript

The admin settings use modular JavaScript to handle settings UI interactions, including color pickers, tab navigation, and form validations.

Settings API

BuddyLists provides a comprehensive settings API to customize the plugin behavior:

General Settings

$buddylists_general_settings = buddylists_general_settings();

Setting	Description	Default
`buddylists_show_lists`	Show Lists tab in profiles	‘yes’
`lists_label`	Custom label for Lists	‘Lists’
`lists_slug`	URL slug for lists	‘lists’
`buddylists_user_role`	Roles that can create lists	All roles
`buddylists_member_type`	Member types excluded from list creation	[]
`lists_limit`	Maximum lists per user	10
`lists_member_limit`	Maximum members per list	10
`profile_view_popup`	Enable profile popup	‘yes’
`direct_message_button`	Enable direct messaging	‘yes’

Visibility Settings

$buddylists_visibility_settings = buddylists_visibility_settings();

Setting	Description	Default
`member_permission`	Who can add members	‘only_me’
`suggested_members`	Which users can be added	‘only_me’
`buddylists_member_roles`	Roles for suggested members	All roles
`buddylists_suggested_type`	Member types for suggestions	[]
`lists_visibility`	Default list visibility	1 (Public)
`buddylists_visibility_after_creation`	Can change visibility after creation	‘yes’
`private_lists_message`	Message for private lists	Custom message

Activity Settings

$buddylists_activity_settings = buddylists_activity_settings();

Setting	Description	Default
`list_visible`	Show list activities	‘yes’
`lists_visibility`	Activity visibility	‘everyone’
`enable_follow`	Enable follow button	‘yes’

Notification Settings

$buddylists_notification_settings = buddylists_notification_settings();

Setting	Description	Default
`added_member_notification`	Notify when added to list	‘yes’
`remove_member_notification`	Notify when removed from list	‘yes’

Color Settings

$buddylists_color_settings = buddylists_color_settings();

Setting	Description	Default
`primary_color`	Primary accent color	‘#003EDE’
`background_color`	Content background color	‘#ffffff’
`border_color`	Border color	‘#E7E7E7’

Widgets

BuddyLists provides two widgets for enhanced functionality:

Active Members Widget

Displays recently active members from the current list:

class Buddylists_Active_Members_Widget extends WP_Widget {
    // Implementation details
}

Title: Configurable widget title
Display: Avatar grid of active members
Context: Typically used in single list sidebar

Members List Widget

Displays detailed information about list members:

class Buddylists_Members_Lists_Widget extends WP_Widget {
    // Implementation details
}

Title: Configurable widget title
Display: Member avatars, names, and last activity time
Context: Typically used in single list sidebar

function register_custom_buddylists_widgets() {
    register_widget('My_Custom_Buddylists_Widget');
}
add_action('widgets_init', 'register_custom_buddylists_widgets');

Integration Points

BuddyLists provides several integration points with other plugins:

BuddyPress Integration

Profile tabs for lists management
Activity stream integration
Member directory integration
Notification system integration

BuddyBoss Integration

Full compatibility with BuddyBoss Platform
Seamless UI integration with BuddyBoss theme
Integration with BuddyBoss messaging system

BP-Follower Integration

If BP-Follower is active:

if (buddylists_is_follow_plugin_active()) {
    // Follow functionality is available
}

Adds follow buttons to list members
Shows follower/following counts
Integrates with follower activity streams

Custom Integration Example

/**
 * Add custom content to single list view
 */
function my_custom_list_content() {
    $list_data = buddylists_fetch_list('', true);

    if (!empty($list_data)) {
        echo '<div class="my-custom-list-content">';
        // Custom content here
        echo '</div>';
    }
}
add_action('buddylist_after_single_list_banner', 'my_custom_list_content');

Customization Guide

Adding Custom List Features

/**
 * Add custom meta to lists
 */
function add_custom_list_meta($list_id, $meta_key, $meta_value) {
    global $wpdb;

    // Create custom meta table if needed
    $wpdb->insert(
        "{$wpdb->prefix}bp_lists_meta",
        array(
            'list_id' => $list_id,
            'meta_key' => $meta_key,
            'meta_value' => $meta_value
        )
    );
}

/**
 * Display custom list meta
 */
function display_custom_list_meta() {
    $list_data = buddylists_fetch_list('', true);
    $list_id = $list_data['list_id'];

    // Get and display custom meta
    global $wpdb;
    $meta = $wpdb->get_results($wpdb->prepare(
        "SELECT * FROM {$wpdb->prefix}bp_lists_meta WHERE list_id = %d",
        $list_id
    ));

    // Output meta data
    if ($meta) {
        echo '<div class="custom-list-meta">';
        foreach ($meta as $item) {
            echo '<div class="meta-item">';
            echo '<span class="meta-key">' . esc_html($item->meta_key) . ':</span> ';
            echo '<span class="meta-value">' . esc_html($item->meta_value) . '</span>';
            echo '</div>';
        }
        echo '</div>';
    }
}
add_action('buddylist_single_list_banner', 'display_custom_list_meta');

Custom List Types

/**
 * Register custom list type
 */
function register_custom_list_type() {
    // Register in options or custom table
    $types = get_option('buddylists_custom_types', array());
    $types['special'] = array(
        'label' => 'Special List',
        'icon' => 'dashicons-star-filled',
        'capabilities' => array('create_special_lists')
    );
    update_option('buddylists_custom_types', $types);
}
add_action('init', 'register_custom_list_type');

/**
 * Add list type selector to creation form
 */
function add_list_type_selector() {
    $types = get_option('buddylists_custom_types', array());
    if (!empty($types)) {
        echo '<div class="buddylists-field">';
        echo '<label for="list_type">' . esc_html__('List Type', 'buddylists') . '</label>';
        echo '<select name="list_type" id="list_type">';
        echo '<option value="default">' . esc_html__('Default List', 'buddylists') . '</option>';

        foreach ($types as $key => $type) {
            echo '<option value="' . esc_attr($key) . '">' . esc_html($type['label']) . '</option>';
        }

        echo '</select>';
        echo '</div>';
    }
}
add_action('buddylists_form_before_submit', 'add_list_type_selector');

Custom Activity Types

/**
 * Register custom activity type for lists
 */
function register_custom_list_activity_type() {
    bp_activity_set_action(
        'buddylists',
        'custom_list_action',
        esc_html__('Custom List Action', 'buddylists'),
        'buddylists_format_custom_activity',
        esc_html__('Custom List Activities', 'buddylists'),
        array('member', 'member_groups')
    );
}
add_action('bp_register_activity_actions', 'register_custom_list_activity_type');

/**
 * Format the custom activity type
 */
function buddylists_format_custom_activity($action, $activity) {
    $list_id = bp_activity_get_meta($activity->id, 'list_id', true);
    $list = buddylists_fetch_list_data_by_id($list_id);

    return sprintf(
        esc_html__('%s performed a custom action on list %s', 'buddylists'),
        bp_core_get_userlink($activity->user_id),
        '<a href="' . esc_url(buddylists_list_link($list['slug'])) . '">' . esc_html($list['name']) . '</a>'
    );
}

Troubleshooting

Common Issues

Lists Not Appearing in Profiles

Check:

“Show Lists Tab” setting is enabled
User has permission to create/view lists
BuddyPress components are active

Solution:

// Force enable lists tab for specific user
function force_enable_lists_tab_for_user($enable, $user_id) {
    if ($user_id === 123) { // Specific user ID
        return true;
    }
    return $enable;
}
add_filter('buddylists_show_tab', 'force_enable_lists_tab_for_user', 10, 2);

Member Suggestions Not Working

Check:

Visibility settings for suggested members
User roles and member types configuration

Solution:

// Debug member suggestions
function debug_member_suggestions($suggestions, $user_id) {
    error_log('User ID: ' . $user_id);
    error_log('Suggestion count: ' . count($suggestions['friends']));
    return $suggestions;
}
add_filter('buddylists_get_suggestions', 'debug_member_suggestions', 10, 2);

Activity Stream Issues

Check:

BuddyPress activity component is active
List has members
Activity settings allow visibility

Solution:

// Force specific user IDs into activity query
function force_activity_visibility($query_args) {
    // Add specific user IDs if list view
    if (get_query_var('list_slug')) {
        $query_args['user_id'] = array_merge(
            (array) $query_args['user_id'],
            array(123, 456, 789) // Specific user IDs
        );
    }
    return $query_args;
}
add_filter('bp_after_has_activities_parse_args', 'force_activity_visibility');

Debugging Functions

/**
 * Debug list data
 */
function buddylists_debug_list($list_id) {
    $list_data = buddylists_fetch_list_all_data($list_id);
    error_log('List Data: ' . print_r($list_data, true));
    return $list_data;
}

/**
 * Debug list members
 */
function buddylists_debug_members($list_id) {
    $members = buddylists_fetch_member_data_by_list_id($list_id);
    error_log('List Members: ' . print_r($members, true));
    return $members;
}

/**
 * Debug settings
 */
function buddylists_debug_settings() {
    error_log('General Settings: ' . print_r(buddylists_general_settings(), true));
    error_log('Visibility Settings: ' . print_r(buddylists_visibility_settings(), true));
    error_log('Activity Settings: ' . print_r(buddylists_activity_settings(), true));
}

/**
 * Track list operations
 */
function buddylists_track_operations() {
    add_action('buddylists_list_insert', function($response) {
        error_log('List Created: ' . print_r($response, true));
    });

    add_action('buddylists_list_update', function($response) {
        error_log('List Updated: ' . print_r($response, true));
    });

    add_action('buddylists_insert_members', function($response, $list_id, $member_id) {
        error_log("Member $member_id added to list $list_id");
    }, 10, 3);
}

Support

Getting Help

If you encounter issues or need assistance with customization:

Documentation: Refer to this developer documentation
Support Forum: Visit the WBCom Designs Support Forum
GitHub Issues: Report bugs on the GitHub repository

BuddyLists – Developer Documentation

Introduction

Plugin Architecture

Key Files

Database Schema

bp_lists

bp_list_members

bp_list_relation

Core API

List Management

Member Management

Following System

Utility Functions

Hooks and Filters

Action Hooks

Filters

Settings Filters

Templates

Template Loading

Core Templates

Overriding Templates

Template Function

JavaScript Components

Frontend JavaScript

buddylists-user-profile.js

buddylists-single-lists.js

Admin JavaScript

Settings API

General Settings

Visibility Settings

Activity Settings

Notification Settings

Color Settings

Widgets

Active Members Widget

Members List Widget

Integration Points

BuddyPress Integration

BuddyBoss Integration

BP-Follower Integration

Custom Integration Example

Customization Guide

Adding Custom List Features

Custom List Types

Custom Activity Types

Troubleshooting

Common Issues

Lists Not Appearing in Profiles

Member Suggestions Not Working

Activity Stream Issues

Debugging Functions

Support

Getting Help