# WooCommerce Home Inbox Notifications Development Guide

This guide explains how to create and manage inbox notifications that appear in the WooCommerce Admin dashboard.

## Overview

The WooCommerce PayPal Payments plugin uses a structured system to create inbox notes through three main components: note definitions, note objects, and registration handling.

## Architecture

### 1. Define Inbox Notes

Inbox notes are defined as service configurations in `modules/ppcp-wc-gateway/services.php` (Service name: `wcgateway.settings.inbox-notes`). The system creates an array of `InboxNote` objects with the following properties:

- `title`: The note headline
- `content`: The note body text  
- `type`: Note type (e.g., `Note::E_WC_ADMIN_NOTE_INFORMATIONAL`)
- `name`: Unique identifier for the note
- `status`: Note status (e.g., `Note::E_WC_ADMIN_NOTE_UNACTIONED`)
- `is_enabled`: Boolean function to control visibility
- `actions`: `InboxNoteAction` objects for user interactions

### 2. Create Inbox Note Objects

Each inbox note is created using the `InboxNoteFactory` and `InboxNote` class. The constructor requires all the properties listed above.

### 3. Register Inbox Notes

The `InboxNoteRegistrar` handles the registration process by:
- Creating WooCommerce `Note` objects from `InboxNote` definitions
- Saving notes to display in the admin inbox
- Managing note lifecycle (creation/deletion based on conditions)

### 4. Registration Hook

Inbox notes are registered via the `register_woo_inbox_notes` method in `WCGatewayModule`, which hooks into the `admin_init` action.

## Implementation Example

```php
// In services.php
'inbox-note.example' => static function ( ContainerInterface $container ): InboxNote {
    return $container->get( 'inbox-note.factory' )->create_note(
        __( 'Example Note Title', 'woocommerce-paypal-payments' ),
        __( 'This is the note content that appears in the inbox.', 'woocommerce-paypal-payments' ),
        Note::E_WC_ADMIN_NOTE_INFORMATIONAL,
        'example-note-unique-name',
        Note::E_WC_ADMIN_NOTE_UNACTIONED,
        static function () use ( $container ): bool {
            // Conditional logic to determine when note should be shown
            return true; // or your condition
        },
        new InboxNoteAction(
            'apply_now',
            __( 'Apply now', 'woocommerce-paypal-payments' ),
            'http://example.com/',
            Note::E_WC_ADMIN_NOTE_UNACTIONED,
            true
        )
    );
},

```

## Content Limitations

WooCommerce inbox notes have several restrictions:

### Character Limit
- Content is automatically truncated at **320 characters** with "..."
- No expansion option available in the UI
- Reference: [WooCommerce Developer Blog ↗](https://developer.woocommerce.com/2021/11/10/introducing-a-320-character-limit-to-inbox-notes/)

### HTML Restrictions
Only basic HTML tags are allowed:
- `<strong>`, `<em>` for emphasis
- `<a>` for links (with `href`, `rel`, `name`, `target`, `download` attributes)
- `<br>`, `<p>` for formatting
- Tags like `<sup>`, `<sub>`, `<span>` are stripped

### Workarounds
- Use asterisks (*) for emphasis when HTML tags aren't supported
- Keep messages concise and prioritize essential information
- Place most important content within the first 320 characters

## Automatic Cleanup

The system includes automatic cleanup functionality:
- Notes are deleted when their `is_enabled` condition becomes `false` (`InboxNoteRegistrar.php`)
- This prevents stale notifications from persisting in the admin

## Actions

Notes can include user actions defined through the `InboxNoteAction` class. Actions appear as buttons in the inbox note and can:
- Navigate to specific admin pages
- Trigger custom functionality
- Dismiss or acknowledge the notification

## Best Practices

1. **Use descriptive, unique names** for note identification
2. **Implement proper conditional logic** in the `is_enabled` function
3. **Keep content concise** due to the 320-character limit
4. **Test note visibility conditions** thoroughly
5. **Provide clear, actionable next steps** through note actions
6. **Consider cleanup scenarios** when notes should be removed

## Existing Examples

The codebase includes several inbox note implementations:
- PayPal Working Capital note
- Settings migration notices
- Feature announcements

These examples demonstrate conditional logic based on feature flags, user settings, and other criteria.