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.

Quick summary

Register your field type with BP Profile Search using the bps_custom_field action hook:

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

2. Only if your field type has options and they are not stored in bp_xprofile_fields, register the options of your field type;

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

See a complete example at the bottom of this page.

Overview

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

1. Display the available search modes in the Edit Form page
2. Display the fields in the search form(s)
3. Display the active filters section in the target directory
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 depend on the field format. For instance, if a field contains text, the available search modes are contains, is, and is like. If a field contains a number, the available search modes are is and range. For a detailed explanation of the 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 serialized array 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 lower and upper 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 field

    $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.