How to Add Custom Notifications in SureDash

SureDash provides a flexible notification system that lets developers create their own custom notifications. These notifications can be shown to users, admins, or everyone inside the portal.

This guide explains the notification types and shows a full example of adding a custom notification step by step.

Notification Types in SureDash

SureDash supports three types of notifications. Each type is stored differently and serves a different purpose.

1. User Notifications

Best for: Notifications meant for a specific user only.

• Dataset filter: suredashboard_user_notifications_dataset
• Stored in: User Meta
• Meta key: suredashboard_user_notifications
• Common use cases:
  • Personal alerts
  • Activity related to one user

Helper functions used:

• sd_get_user_meta()
• sd_update_user_meta()

2. Admin Notifications

Best for: Notifications meant only for portal managers or admins.

• Dataset filter: suredashboard_admin_notifications_dataset
• Stored in: WordPress Options
• Option key: suredashboard_admin_notifications
• Visibility: Only portal managers

Functions used:

• get_option()
• update_option()

3. Common Notifications

Best for: Notifications visible to all users or a selected group of users.

• Dataset filter: suredashboard_common_notifications_dataset
• Stored in:
  • WordPress Options (global), or
  • User Meta (per user)
• Option key: suredashboard_common_notifications

This guide focuses on Common Notifications, since they are the most flexible.

Example: Add a Custom “Course Published” Notification

In this example, we will show a notification when a new course is published.

Step 1: Add the Custom Notification to the Dataset

First, register your notification in the common notifications dataset.

<?php
/**
 * Add custom notification to SureDash
 */

// Hook into the common notifications dataset
add_filter( 'suredashboard_common_notifications_dataset', 'my_custom_course_notification' );

function my_custom_course_notification( $dataset ) {
    $dataset['course_published'] = [
        'icon'                => 'BookOpen', // Icon from SureDash icon library
        'description'         => __( 'New course "{{COURSE}}" has been published!', 'your-textdomain' ),
        'trigger'             => 'my_custom_course_published', // Custom trigger hook
        'callback'            => 'my_course_published_callback',
        'formatting_callback' => 'my_course_published_format',
    ];

    return $dataset;
}

What this does:

• Registers a new notification type
• Defines how the notification is triggered
• Sets callbacks for saving and formatting the notification

Step 2: Create the Notification Callback

This function stores the notification data when the event happens.

/**
 * Callback when course is published
 * Stores the notification data
 */
function my_course_published_callback( $args ) {
    if ( empty( $args['course_id'] ) ) {
        return;
    }

    $course_id = absint( $args['course_id'] );

    // Make sure the course exists
    if ( ! get_post_status( $course_id ) ) {
        return;
    }

    $notifiable = [
        'trigger'   => 'course_published',
        'course_id' => $course_id,
    ];

    // Fetch existing notifications
    $option             = 'suredashboard_common_notifications';
    $notifications_data = get_option( $option, [] );

    if ( ! is_array( $notifications_data ) ) {
        $notifications_data = [];
    }

    // Use timestamp as the key
    $timestamp                        = ! empty( $args['timestamp'] ) ? $args['timestamp'] : suredash_get_timestamp();
    $notifications_data[ $timestamp ] = $notifiable;

    // Save notifications
    update_option( $option, $notifications_data );
}

What this does:

• Validates the course
• Prepares notification data
• Saves it using a timestamp so notifications stay ordered

Step 3: Create the Formatting Callback

This function controls how the notification looks on the frontend.

/**
 * Format the course published notification
 */
function my_course_published_format( $args, $value ) {
    $icon = ! empty( $args['icon'] ) ? $args['icon'] : 'BookOpen';

    ob_start();

    if ( ! is_array( $value ) || empty( $value ) ) {
        return ob_get_clean();
    }

    $course_id = ! empty( $value['course_id'] ) ? absint( $value['course_id'] ) : 0;

    // Ensure course still exists
    if ( ! get_post_status( $course_id ) ) {
        return ob_get_clean();
    }

    $description = ! empty( $args['description'] ) ? $args['description'] : '';

    // Create course link
    $course_title = '<a href="' . get_permalink( $course_id ) . '"><strong>' .
                    get_the_title( $course_id ) . '</strong></a>';

    // Replace placeholder with actual course title
    $description = str_replace( '{{COURSE}}', $course_title, $description );

    // Use SureDash base formatter
    $base = \SureDashboard\Core\Notifier\Base::get_instance();
    $base->format_notification( $icon, $description, $value );

    return ob_get_clean();
}

What this does:

• Builds the notification message
• Replaces placeholders with real data
• Uses SureDash’s built-in formatter for consistent UI

Step 4: Trigger the Notification

Finally, trigger the notification when the course is published.

/**
 * Trigger notification when a course is published
 */
function trigger_course_notification( $post_id, $post ) {
    // Only target specific post type
    if ( $post->post_type !== 'community-content' ) {
        return;
    }

    // Only when publishing
    if ( $post->post_status !== 'publish' ) {
        return;
    }

    // Dispatch the notification
    $base = \SureDashboard\Core\Notifier\Base::get_instance();
    $base->dispatch_common_notification(
        'my_custom_course_published',
        [
            'course_id' => $post_id,
        ]
    );
}

add_action( 'save_post', 'trigger_course_notification', 10, 2 );

What this does:

• Listens for post publishing
• Fires the custom notification trigger
• Sends data to SureDash for processing

Summary

To add a custom notification in SureDash:

1. Register the notification using a dataset filter
2. Create a callback to store notification data
3. Create a formatting callback to control display
4. Trigger the notification using a custom action

This approach works the same way for User, Admin, and Common notifications. Only the dataset filter and storage method change.