1. Developer Tutorials
  2. Migrating Custom Notifications to Modern Notifications API

Migrating Custom Notifications to Modern Notifications API

In this tutorial, you will learn how to register your own BuddyBoss Platform notifications that will trigger based on the criteria you specify. Once registered, you’ll be able to enable and disable them in the “Notification Types” section of the WordPress Admin Dashboard > BuddyBoss > Settings > Notifications page and the “Notification Preferences” section on the Account Settings > Notification Preferences page.

Note: The tutorial is intended for registering and migrating custom notifications to Modern Notifications API (currently available in the BuddyBoss Labs feature only) from the Legacy Notifications API & Legacy Email Preferences API.


To start, you will need to extend our abstract class by following these steps:

1. Create one class file and extend BP_Core_Notification_Abstract

class BP_Custom_Notification extends BP_Core_Notification_Abstract {
​
	/**
	 * Instance of this class.
	 *
	 * @var object
	 */
	private static $instance = null;
​
	/**
	 * Get the instance of this class.
	 *
	 * @return null|BP_Custom_Notification|Controller|object
	 */
	public static function instance() {
		if ( is_null( self::$instance ) ) {
			self::$instance = new self();
		}
​
		return self::$instance;
	}
}

2. Extend two abstract methods into the newly created class from Step 1.

/**
 * Set up the Custom notification class.
 */
class BP_Custom_Notification extends BP_Core_Notification_Abstract {

	/**
	 * Instance of this class.
	 *
	 * @var object
	 */
	private static $instance = null;

	/**
	 * Get the instance of this class.
	 *
	 * @return null|BP_Custom_Notification|Controller|object
	 */
	public static function instance() {
		if ( is_null( self::$instance ) ) {
			self::$instance = new self();
		}

		return self::$instance;
	}

	/**
	 * Constructor method.
	 */
	public function __construct() {
		$this->start();
	}

	/**
	 * Initialize all methods inside it.
	 *
	 * @return mixed|void
	 */
	public function load() {}

	/**
	 * Format the notifications.
	 *
	 * @param string $content               Notification content.
	 * @param int    $item_id               Notification item ID.
	 * @param int    $secondary_item_id     Notification secondary item ID.
	 * @param int    $action_item_count     Number of notifications with the same action.
	 * @param string $component_action_name Canonical notification action.
	 * @param string $component_name        Notification component ID.
	 * @param int    $notification_id       Notification ID.
	 * @param string $screen                Notification Screen type.
	 *
	 * @return array
	 */
	public function format_notification( $content, $item_id, $secondary_item_id, $action_item_count, $component_action_name, $component_name, $notification_id, $screen ) {

		return $content;
	}
}

3. Register a group for your platform notifications. This will help manage similar kinds of notifications in one section on the Settings screen.

/**
 * Register Notification Group.
 *
 * @param string $group_key         Group key.
 * @param string $group_label       Group label.
 * @param string $group_admin_label Group admin label.
 * @param int    $priority          Priority of the group.
 */
$this->register_notification_group(
	'custom',
	esc_html__( 'Custom Notification Frontend', 'buddyboss' ), // For the frontend.
	esc_html__( 'Custom Notifications Admin', 'buddyboss' ) // For the backend.
);

4. Once a group has been registered, Register the Platform Notification Type into the created group using this method:

/**
 * Register Notification Type.
 *
 * @param string $notification_type        Notification Type key.
 * @param string $notification_label       Notification label.
 * @param string $notification_admin_label Notification admin label.
 * @param string $notification_group       Notification group.
 * @param bool   $default                  Default status for enabled/disabled.
 */
$this->register_notification_type(
	'notification_custom',
	esc_html__( 'Custom Notification title', 'buddyboss' ),
	esc_html__( 'Custom Notification admin title', 'buddyboss' ),
	'custom'
);

5. Register the Platform Email Type and attach it to the Registered Platform Notification Type using this method.

/**
 * Add email schema.
 *
 * @param string $email_type        Type of email being sent.
 * @param array  $args              Email arguments.
 * @param string $notification_type Notification Type key.
 */
$this->register_email_type(
	'custom-at-message',
	array(
		'email_title'         => __( 'email title', 'buddyboss' ),
		'email_content'       => __( 'email content', 'buddyboss' ),
		'email_plain_content' => __( 'email plain text content', 'buddyboss' ),
		'situation_label'     => __( 'Email situation title', 'buddyboss' ),
		'unsubscribe_text'    => __( 'You will no longer receive emails when custom notification performed.', 'buddyboss' ),
	),
	'notification_custom'
);

6. Register a Platform Notification and attach it to the Registered Platform Notification Type using the following method.

/**
 * Register notification.
 *
 * @param string $component         Component name.
 * @param string $component_action  Component action.
 * @param string $notification_type Notification Type key.
 * @param string $icon_class        Notification Small Icon.
 */
$this->register_notification(
	'custom',
	'custom_action',
	'notification_custom'
);

7. If you want to show notification registered above into the notification filter on the member’s notification list use the following method:

/**
 * Register Notification Filter.
 *
 * @param string $notification_label    Notification label.
 * @param array  $notification_types    Notification types.
 * @param int    $notification_position Notification position.
 */
$this->register_notification_filter(
	__( 'Custom Notification Filter', 'buddyboss' ),
	array( 'notification_custom' ),
	5
);

8. You can load your custom notification class from your child theme using the below hooks.

// Include custom notification file.
require_once trailingslashit( get_template_directory() ) . 'class-bp-custom-notification.php';

add_action(
   'bp_init',
   function () {
      // Register custom notification in preferences screen.
      if ( class_exists( 'BP_Custom_Notification' ) ) {
         BP_Custom_Notification::instance();
      }
   }
);

9. In the next step you need to provide the support for rendering of notification registered above inside a method called format_notification see the example below.

Tip: Make use the of $screen variable to return different content for notifications that are displayed on different devices or screens.

$screen variables is an enum of

  1. web refers to the notifications list page or notifications popup on the site.
  2. web_push refers to the browser’s native push notifications popup.
  3. app_push refers to the mobile device’s native notification center.
public function format_notification( $content, $item_id, $secondary_item_id, $action_item_count, $component_action_name, $component_name, $notification_id, $screen ) {

		if ( 'custom' === $component_name && 'custom_action' === $component_action_name ) {

			$text = esc_html__( 'Custom Notification text.', 'buddyboss' );
			$link = get_permalink( $item_id );
    
            /**
             * Change the text for Push Notifications  
             */
            if($screen == "app_push" || $screen == "web_push") {
                $text = esc_html__( 'Custom Push Notification Text Only.', 'buddyboss' );
            }
    
			return array(
				'title' => "", // (optional) only for push notification & if not provided no title will be used.
				'text' => $text,
				'link' => $link,
			);
		}

		return $content;
	}

Note: Make sure to add a comparison of $component_name & $component_action_name before returning any alteration of $content as wrongly handling this method can affect the issues on other notification rendering on the user’s notifications list page.

Tip: Make use of $screen argument to provide a different modified content for web & push interface by returning the alternate versions comparing variable with (web, app_push, web_push).

Tip: To support title inside a push notification you need to profile the title inside $content array variable which is optional.

Note: For Push Notifications, the maximum number of characters for the title is 26 and message content is 354.


Full Example Code

// Include custom notification file.
require_once trailingslashit( get_template_directory() ) . 'class-bp-custom-notification.php';

add_action(
   'bp_init',
   function () {
      // Register custom notification in preferences screen.
      if ( class_exists( 'BP_Custom_Notification' ) ) {
         BP_Custom_Notification::instance();
      }
   }
);

Example class file for custom notification:

class-bp-custom-notification.php

This file also goes into your plugin folder. This contains most of the functional code for registering and migrating your custom notifications to Modern Notifications API.

<?php
/**
 * BuddyBoss Custom Notification Class.
 */

defined( 'ABSPATH' ) || exit;

if ( ! class_exists( 'BP_Core_Notification_Abstract' ) ) {
	return;
}

/**
 * Set up the Custom notification class.
 */
class BP_Custom_Notification extends BP_Core_Notification_Abstract {

	/**
	 * Instance of this class.
	 *
	 * @var object
	 */
	private static $instance = null;

	/**
	 * Get the instance of this class.
	 *
	 * @return null|BP_Custom_Notification|Controller|object
	 */
	public static function instance() {
		if ( is_null( self::$instance ) ) {
			self::$instance = new self();
		}

		return self::$instance;
	}

	/**
	 * Constructor method.
	 */
	public function __construct() {
		$this->start();
	}

	/**
	 * Initialize all methods inside it.
	 *
	 * @return mixed|void
	 */
	public function load() {

		/**
		 * Register Notification Group.
		 *
		 * @param string $group_key         Group key.
		 * @param string $group_label       Group label.
		 * @param string $group_admin_label Group admin label.
		 * @param int    $priority          Priority of the group.
		 */
		$this->register_notification_group(
			'custom',
			esc_html__( 'Custom Notification Frontend', 'buddyboss' ), // For the frontend.
			esc_html__( 'Custom Notifications Admin', 'buddyboss' ) // For the backend.
		);

		$this->register_custom_notification();
	}

	/**
	 * Register notification for user mention.
	 */
	public function register_custom_notification() {
		/**
		 * Register Notification Type.
		 *
		 * @param string $notification_type        Notification Type key.
		 * @param string $notification_label       Notification label.
		 * @param string $notification_admin_label Notification admin label.
		 * @param string $notification_group       Notification group.
		 * @param bool   $default                  Default status for enabled/disabled.
		 */
		$this->register_notification_type(
			'notification_custom',
			esc_html__( 'Custom Notification title', 'buddyboss' ),
			esc_html__( 'Custom Notification admin title', 'buddyboss' ),
			'custom'
		);

		/**
		 * Add email schema.
		 *
		 * @param string $email_type        Type of email being sent.
		 * @param array  $args              Email arguments.
		 * @param string $notification_type Notification Type key.
		 */
		$this->register_email_type(
			'custom-at-message',
			array(
				'email_title'         => __( 'email title', 'buddyboss' ),
				'email_content'       => __( 'email content', 'buddyboss' ),
				'email_plain_content' => __( 'email plain text content', 'buddyboss' ),
				'situation_label'     => __( 'Email situation title', 'buddyboss' ),
				'unsubscribe_text'    => __( 'You will no longer receive emails when custom notification performed.', 'buddyboss' ),
			),
			'notification_custom'
		);

		/**
		 * Register notification.
		 *
		 * @param string $component         Component name.
		 * @param string $component_action  Component action.
		 * @param string $notification_type Notification Type key.
		 * @param string $icon_class        Notification Small Icon.
		 */
		$this->register_notification(
			'custom',
			'custom_action',
			'notification_custom'
		);

		/**
		 * Register Notification Filter.
		 *
		 * @param string $notification_label    Notification label.
		 * @param array  $notification_types    Notification types.
		 * @param int    $notification_position Notification position.
		 */
		$this->register_notification_filter(
			__( 'Custom Notification Filter', 'buddyboss' ),
			array( 'notification_custom' ),
			5
		);
	}

	/**
	 * Format the notifications.
	 *
	 * @param string $content               Notification content.
	 * @param int    $item_id               Notification item ID.
	 * @param int    $secondary_item_id     Notification secondary item ID.
	 * @param int    $action_item_count     Number of notifications with the same action.
	 * @param string $component_action_name Canonical notification action.
	 * @param string $component_name        Notification component ID.
	 * @param int    $notification_id       Notification ID.
	 * @param string $screen                Notification Screen type.
	 *
	 * @return array
	 */
	public function format_notification( $content, $item_id, $secondary_item_id, $action_item_count, $component_action_name, $component_name, $notification_id, $screen ) {

		if ( 'custom' === $component_name && 'custom_action' === $component_action_name ) {

			$text = esc_html__( 'Custom Notification text.', 'buddyboss' );
			$link = get_permalink( $item_id );
    
            /**
             * Change the text for Push Notifications  
             */
            if($screen == "app_push" || $screen == "web_push") {
                $text = esc_html__( 'Custom Push Notification Text Only.', 'buddyboss' );
            }
    
			return array(
				'title' => "", // (optional) only for push notification & if not provided no title will be used.
				'text' => $text,
				'link' => $link,
			);
		}

		return $content;
	}
}

Questions?

We're always happy to help with questions you might have! Search our documentation, contact support, or connect with our sales team.