Skip to main content

Add custom user settings

Every member has a Settings screen in the messenger, opened from their own photo at the bottom of the messenger. It holds their personal choices: email notifications, sounds, who may start a conversation with them, how Enter sends a message and so on. A plugin or a snippet can add its own options to that screen, and Better Messages saves what the member picks through the same request as its own options.

It takes two hooks:

Better Messages does not store your options for you. Keep them where your code reads them, usually in user meta.

REQUIREMENTS

To be able to implement this guide, you need to learn how to insert PHP snippets to your website.

You can find guide here: WP Beginner

A complete example#

The snippet adds two options for members:

  • Daily digest, a checkbox: whether the member wants a daily email of unread messages. Your own digest code reads it
  • Message text size, a choice of Small, Normal and Large: the text size of the messages, applied on the next page load
<?php

// 1. Show the options on the member's settings screen.
add_filter( 'better_messages_user_config', 'my_bm_user_settings', 10, 2 );
function my_bm_user_settings( $settings, $user_id ) {
// Members only: guests have no WordPress user meta.
if ( $user_id <= 0 ) {
return $settings;
}

$settings[] = array(
'id' => 'my_digest',
'title' => 'Daily digest',
'type' => 'checkboxes',
'options' => array(
array(
'id' => 'my_digest_email',
'label' => 'Email me a daily digest of unread messages',
'value' => 'yes',
'checked' => get_user_meta( $user_id, 'my_digest_email', true ) === 'yes',
'desc' => 'Sent once a day, only when you have unread messages',
),
),
);

$current = my_bm_text_size( $user_id );
$options = array();

foreach ( my_bm_text_sizes() as $value => $label ) {
$options[] = array(
'id' => $value,
'label' => $label,
'value' => $value,
'checked' => $current === $value,
'desc' => '',
);
}

$settings[] = array(
'id' => 'my_text_size',
'title' => 'Message text size',
'type' => 'radio',
'options' => $options,
);

return $settings;
}

// 2. Store what the member picked.
add_action( 'better_messages_user_setting_saved', 'my_bm_user_setting_saved', 10, 3 );
function my_bm_user_setting_saved( $option, $value, $user_id ) {
if ( $user_id <= 0 ) {
return;
}

// A checkbox is saved under its own id, as 'true' or 'false'.
if ( $option === 'my_digest_email' ) {
update_user_meta( $user_id, 'my_digest_email', $value === 'true' ? 'yes' : 'no' );
}

// A radio group is saved under the group id, with the value of the chosen option.
if ( $option === 'my_text_size' && array_key_exists( $value, my_bm_text_sizes() ) ) {
update_user_meta( $user_id, 'my_text_size', $value );
}
}

function my_bm_text_sizes() {
return array(
'small' => 'Small',
'normal' => 'Normal',
'large' => 'Large',
);
}

function my_bm_text_size( $user_id ) {
$size = get_user_meta( $user_id, 'my_text_size', true );

return array_key_exists( $size, my_bm_text_sizes() ) ? $size : 'normal';
}

// 3. Use the value: set the messenger's message text size for this member.
add_action( 'wp_head', 'my_bm_text_size_css' );
function my_bm_text_size_css() {
if ( ! is_user_logged_in() ) {
return;
}

$sizes = array( 'small' => '13px', 'large' => '18px' );
$size = my_bm_text_size( get_current_user_id() );

if ( isset( $sizes[ $size ] ) ) {
echo '<style>html:root{--bm-font-size-base:' . esc_attr( $sizes[ $size ] ) . '}</style>';
}
}

The two groups appear on the settings screen after the options of Better Messages, with the current choice of the member already marked. A change is saved the moment the member clicks it, and the messenger shows its usual "Saved successfully" notice.

The text size uses the token --bm-font-size-base, the same one as Settings → Appearance → Typography (see Change text size). html:root is a little more specific than :root, so the choice of the member wins over the size set in Appearance.

To find the members who want the digest, query the user meta:

$members = get_users( array(
'meta_key' => 'my_digest_email',
'meta_value' => 'yes',
'fields' => 'ID',
) );

How a group is described​

Each item you add to $settings is one group on the screen, with a title and its options.

KeyWhat it is
idThe group id. Unique on the screen, so prefix it with your plugin name
titleThe heading of the group
typecheckboxes, radio or raw_html (below)
optionsThe options of the group, for checkboxes and radio
htmlThe HTML to show, for raw_html

Each option of a checkboxes or radio group:

KeyWhat it is
idThe option id. For a checkbox it is also the name the change is saved under
labelThe text beside the checkbox or radio button
valueFor a radio button, the value saved when it is chosen. For a checkbox, any text
checkedtrue when the option is on now. Read it from where you stored it
descA line under the option, or an empty string

What the save action receives#

The messenger sends one change at a time, and better_messages_user_setting_saved gets it as three arguments:

Group type$option$value
checkboxesThe option id'true' when checked, 'false' when unchecked
radioThe group idThe value of the chosen option

$value is always text, cleaned with sanitize_text_field(). Better Messages answers "Saved successfully" for any option, including one your code refuses, so check the value yourself before storing it, as the example does with array_key_exists().

The action runs for the options of Better Messages too (email_notifications, sound_notifications, enter_to_send, online_status and the rest), so compare $option with your own ids and leave the others alone.

A group of your own HTML#

A raw_html group shows HTML under its title and saves nothing. Use it when an option is too rich for checkboxes or radio buttons, to link the member to a page of your plugin where they set it:

$settings[] = array(
'id' => 'my_profile_link',
'title' => 'Message templates',
'type' => 'raw_html',
'html' => '<a href="' . esc_url( home_url( '/account/templates/' ) ) . '">Edit your message templates</a>',
);

Guests#

Guests of Guest Access open the same settings screen, and their $user_id is negative. The example leaves them out because a guest has no WordPress user, so get_user_meta() and update_user_meta() do nothing for them.

To offer an option to guests too, return it for any $user_id that is not 0, and store it with the user meta functions of Better Messages, which keep the values of a guest in the record of that guest:

Better_Messages()->functions->update_user_meta( $user_id, 'my_digest_email', 'yes' );
Better_Messages()->functions->get_user_meta( $user_id, 'my_digest_email', true );

Good to know#

  • Hide an option the member should not see by not adding it: the filter runs for every member each time the screen opens, so you can check their role, a membership level or a setting of your plugin.
  • The order: your groups come after the groups of Better Messages. To put one first, add it to the start of the array with array_unshift().
  • The other group types you may see in $settings (checkboxes_radio, settings_group, blocked_users, app_devices) are drawn for the options of Better Messages only.
  • Your options are not shown when the site turns off User settings in Settings → Appearance, as the options of Better Messages are not. Use checkboxes, radio or raw_html for yours.
  • Changes apply from the next page load unless your own script reads them earlier. The messenger does not tell the rest of the page that a custom option changed.
  • A part drawn by your own script goes after all the groups with the JavaScript filter better_messages_user_settings_after.