Cookbook: Modify Notification Before Display

Use the notifal/onpage/notification/content filter when you need to change notification settings before Notifal renders the template and builds the frontend payload.

The filter runs inside NotificationDataPreparer::prepareForFrontend() immediately after notification meta is loaded and before template rendering, retrigger variant building, and frontend JSON assembly.

Hook reference: Hooks: Notifications and Eligibility.

When to use this filter

For changing the final REST eligibility response after preparation, combine this filter with hooks documented under notifications and eligibility. This filter targets the pre-render notification array.

Filter signature

apply_filters(
    'notifal/onpage/notification/content',
    array $notificationData,
    array $context
);

Common $notificationData keys (from NotificationSaveService::getNotificationData()):

• template_id, template_content
• appearance_settings, behavior_settings, timing_settings
• content_source_settings, content_source_type
• display_rules_data, rule_combination_logic, display_rules_visibility_mode
• campaign_id, notif_title, post_id

Example: swap template on WooCommerce checkout

Register after Notifal boots so eligibility services exist when you debug, but the filter itself can be added on plugins_loaded because it only runs during eligibility/preparation requests.

<?php
/**
 * Plugin Name: My Notifal Notification Tweaks
 * Description: Example integration for notifal/onpage/notification/content.
 * Version: 1.0.0
 * Requires PHP: 7.4
 */

defined( 'ABSPATH' ) || exit;

use Notifal\Infrastructure\WordPress\Hooks\FilterHooks;

/**
 * Bootstrap notification content tweaks after WordPress loads plugins.
 *
 * @return void
 */
add_action( 'plugins_loaded', 'my_notifal_register_notification_content_filter' );

/**
 * Register the notification content filter callback.
 *
 * @return void
 */
function my_notifal_register_notification_content_filter(): void {
    // Bail when Notifal is not active.
    if ( ! defined( 'NOTIFAL_VERSION' ) ) {
        return;
    }

    // Attach the filter using the canonical FilterHooks constant.
    add_filter( FilterHooks::ONPAGE_NOTIFICATION_CONTENT, 'my_notifal_filter_notification_content', 10, 2 );
}

/**
 * Swap the linked template when the visitor is on the WooCommerce checkout page.
 *
 * @param array<string, mixed> $notificationData Loaded notification settings.
 * @param array<string, mixed> $context          Current page context from Notifal.
 * @return array<string, mixed> Modified notification settings.
 */
function my_notifal_filter_notification_content( array $notificationData, array $context ): array {
    // Read the current page ID from context (falls back to 0 when unknown).
    $page_id = isset( $context['page_id'] ) ? absint( $context['page_id'] ) : 0;

    // Only run on singular pages with a valid ID.
    if ( $page_id <= 0 ) {
        return $notificationData;
    }

    // Require WooCommerce and the checkout page helper.
    if ( ! function_exists( 'is_checkout' ) || ! is_checkout() ) {
        return $notificationData;
    }

    // Replace template when a checkout-specific template post exists.
    $checkout_template_id = absint( get_option( 'my_notifal_checkout_template_id', 0 ) );

    if ( $checkout_template_id > 0 && get_post_type( $checkout_template_id ) === 'notifal_template' ) {
        // Override the template used for rendering on checkout.
        $notificationData['template_id'] = $checkout_template_id;
    }

    // Return the (possibly modified) notification array.
    return $notificationData;
}

Example: append a custom flag for your JavaScript

Notifal does not expose arbitrary keys to the frontend automatically. Use this filter to prepare data your own layer reads, or pair with notifal/onpage/frontend/context if you need client-side context (see hook reference).

<?php

defined( 'ABSPATH' ) || exit;

use Notifal\Infrastructure\WordPress\Hooks\FilterHooks;

add_filter( FilterHooks::ONPAGE_NOTIFICATION_CONTENT, function ( array $notificationData, array $context ): array {
    // Sanitize a simple string flag from your site option.
    $variant = sanitize_key( (string) get_option( 'my_notifal_ab_variant', 'control' ) );

    // Store under content_source_settings so it persists through the prepare pipeline.
    if ( ! isset( $notificationData['content_source_settings'] ) || ! is_array( $notificationData['content_source_settings'] ) ) {
        $notificationData['content_source_settings'] = [];
    }

    // Add a namespaced key to avoid collisions with Notifal core keys.
    $notificationData['content_source_settings']['my_ab_variant'] = $variant;

    return $notificationData;
}, 10, 2 );

Important behavior notes

1. Runs before render , changes to template_id and content_source_settings affect tag resolution and pool selection in FrontendTemplateRenderer.
2. Returning invalid data can suppress the notification , if rendering finds no matching dynamic pool data, prepareForFrontend() returns null and the notification is omitted from the eligibility response.
3. Sanitize every value you write , use absint(), sanitize_key(), sanitize_text_field(), and typed checks before updating nested arrays.
4. Prefer FilterHooks::ONPAGE_NOTIFICATION_CONTENT over hard-coded strings so refactors stay compatible.

Related hooks

What to read next

Cookbook series

1. Cookbook: Modify Notification Before Display (you are here)
2. Cookbook: Add Custom Dynamic Tag
3. Cookbook: Customize Template Import
4. Cookbook: Extend Display Rules
5. Cookbook: Register a Custom HTML Builder Widget

Hook articles

• Hooks: Notifications and Eligibility
• Hook Reference Hub