Custom profile field types

This page is for developers who create custom profile field types for BuddyPress, and wish to make them searchable by BP Profile Search (version 4.7.8 or later) using a simple action hook.

All the previously used hooks and codes have been removed in version 4.8.1. If you have questions or suggestions, please use my Contact page.

Quick summary

Register your field with BP Profile Search using a single action hook. See the full example at the bottom of this page.

1. Always register the field format: text, integer, decimal, date, set or location.

2. Only if your field has options AND they are not stored in bp_xprofile_fields, register the field options.

3. Only if your field values are not stored in bp_xprofile_data, register your search function.

Overview

BP Profile Search needs information on profile fields in order to:

1. Display the available search modes (filter types) in the Edit Form page
2. Display the fields in the search form(s)
3. Display the active filters in the search results page
4. Query the database to get the search results

While the information about the built-in profile field types is hard-coded, if you create a custom profile field type (CPFT) you need to provide that information at run time. See below for details.

1. Display the available search modes

For a given field type, the available search modes (filter types) depend on the field format. For instance, if a field contains text, the available filter types are contains, is, and is like. If a field contains a number, the available filter types are is and range. For a detailed explanation of the available search modes, see the Search Modes page.

To submit the format of your CPFT, use the bps_custom_field hook. The formats are:

* text: the field contains text, e.g. John Silver
* integer: the field contains an integer number, e.g. 4567
* decimal: the field contains a decimal number, e.g. 128.35
* date: the field contains a date, e.g. 2017-03-31 or 2017-05-27 15:29:02
* set: the field contains a set of values (like the built-in Checkboxes and Multi Select Box types)
* location: the field contains a location (a text address and its lat-long coordinates)

If the format of your CPFT is not listed, please let me know (use my Contact page).

If your field has options, and if they are not stored in the standard (wp_)bp_xprofile_fields table, submit those options too.

add_action ('bps_custom_field', 'my_hook01');
function my_hook01 ($f)
{
    if ($f->type != 'my_custom_type')  return;

    // submit the format of my_custom_type
    $f->format = 'text';

    // submit the field options, if they are not stored in
    // the standard (wp_)bp_xprofile_fields table
    $f->options = array (0 => 'Male', 1 => 'Female');
}

2. Display the fields in a search form

No further action is required to properly display your CPFT in a search form. BP Profile Search selects the right display based on the format of your CPFT, and on the search mode chosen by the admin who created the search form.

For instance, if your CPFT’s format is integer, and the chosen search mode is is, the search form will display an input box. If the chosen search mode is range, the search form will display two input boxes, to enter the min and max values of the range.

3. Display the active filters

No further action is required. BP Profile Search selects the right display based on the search mode chosen by the admin who created the search form.

4. Query the database

If your field values are stored in the standard (wp_)bp_xprofile_data table, you can stop reading, your CPFT will be compatible with BP Profile Search as soon as you add the code explained in 1. If something doesn’t work for you, please let me know (use my Contact page).

If your field values are not stored in the standard (wp_)bp_xprofile_data table, you have to provide your own search function. The search function receives the search mode and the value(s) to search for, and returns an array of matching user IDs.

add_action ('bps_custom_field', 'my_hook02');
function my_hook02 ($f)
{
    if ($f->type != 'my_custom_type')  return;

    // submit the format of my_custom_type
    $f->format = 'text';

    // submit the field options, if they are not stored in
    // the standard (wp_)bp_xprofile_fields table
    $f->options = array (0 => 'Male', 1 => 'Female');

    // submit the search function, if the field values are not
    // stored in the standard (wp_)bp_xprofile_data table
    $f->search = 'my_search_function';
}

function my_search_function ($f)
{
    $filter = $f->filter;    // the current search mode
    $value = $f->value;      // the value(s) POSTed by the search form

    $results = ...           // array of matching user IDs
    return $results;
}

Conclusions

I hope that, with the simple interface presented above, BP Profile Search will be able to support all the CPFT you may create. If you have questions or suggestions, please feel free to use my Contact page.