Using the default form template

Template options

When you select the default form template in the Form Template meta box, you can set two template options:

1. jQuery UI Theme

With this option you can select no jQuery UI, or one of the available jQuery UI themes. If you wish to know how each theme looks like before choosing one, visit the jQuery UI ThemeRoller and, in the left sidebar, select Gallery.

If you select no jQuery UI, no jQuery UI styles and effects are applied to your form. If you select a jQuery UI theme, the theme style is applied and your form is enclosed in a jQuery UI accordion. The default value is the Base jQuery UI theme.

2. Collapsible Form

This option applies only if you’ve chosen a jQuery UI theme, and allows collapsing the accordion enclosing your form. If you select Yes, the accordion can be opened and closed, if you select No the accordion stays always open. The default value is Yes.

Customizations

The default form template can be customized using CSS, or using hooks.

As an example, let’s see how we can modify the integer-range display. By default, the range is displayed using two input boxes, but we can change that to two drop-down select boxes, adding this code to bp-custom.php:

add_action ('bps_field_before_search_form', 'change_display');
function change_display ($f)
{
    if ($f->code == 'field_4' && $f->display == 'integer-range')
    {
        $f->display = 'range-select';
        $range = range (18, 99);
        $f->options = array ('' => '') + array_combine ($range, $range);
    }
}

Replace field_4 with the actual field code of your field, and 18, 99 with the actual range you want to show in your drop-downs.

Modifying the default form template

If you are familiar with PHP programming, you can edit the template file to suit your needs.

Locate the file bp-profile-search/templates/members/bps-form-default.php, copy it to the buddypress/members directory in your theme’s root, then edit the new copy. If you edit the original file, your changes will be overwritten during the next BP Profile Search update.

Before starting to change your template, you may want to know more about the template structure and the data it uses.

As you can see, the template contains three sections:

// 1st section: set the default value of the template options
...

// 2nd section: display the form to select the template options

if (is_admin ())
{
    ...
    return 'end_of_options 4.9';
}

// 3rd section: display the search form

$F = bps_escaped_form_data ($version = '4.9');
...

return 'end_of_template 4.9';

While the first section runs in both the back-end and front-end, the second section runs only in the back-end and the third section runs only in the front-end.

In the third section, the form template calls bps_escaped_form_data to get the form data. This call returns a stdClass object $F containing all the form’s data, already escaped, so they can safely be used in the HTML code.

The default form template uses these form data:

$F->unique_id		: the form HTML id
$F->title		: the form title
$F->action		: the form action
$F->method		: the form method
$F->fields		: array of the form fields
$F->errors		: number of the field error messages

An element of the $F->fields array is a stdClass object $f containing all the field’s data, already escaped, so they can safely be used in the HTML code.

The default form template uses these field data:

$f->name		: the field name
$f->description		: the field description
$f->display		: the field display mode
$f->label		: the field label
$f->mode		: the field search mode
$f->unique_id		: the field HTML id
$f->html_name		: the field HTML name
$f->value		: the field value(s)
$f->error_message	: the field error message
$f->options		: array of the field options

If you don’t change the file name of your template, your customized version in your active theme folder will simply take precedence over the built-in version.

If you wish to to change the file name, you also need to add your new name to the template selection drop-down. Add this code to your bp-custom.php file:

add_filter ('bps_templates', 'add_template');
function add_template ($templates)
{
    $templates[] = 'members/new-template-file-name';
    return $templates;
}

Replace new-template-file-name with the actual file name of your new template, without the .php suffix.