📚 pbMessage — Universal Message Display

pbMessage is a lightweight utility class for displaying success/error messages after pbFetch requests or any async operations.

✅ Why Use It?

• Automatically shows messages from JSON responses like { success: true|false, message: "..." }.
• Works out-of-the-box with pbFetch — no manual handling required.
• Controlled via pb:success and pb:error events — override auto-display if needed.
• Customizable: Set CSS classes, target containers, and cleanup behavior.

⚙️ How It Works

🚦 Core Logic

pbMessage.success(ctx, message)  
pbMessage.error(ctx, message)  
pbMessage.clear(ctx)

• ctx: Context element (e.g., a form, pb-target, or document) where messages are inserted.
• Checks for [pb-success-message] or [pb-error-message] within ctx.
• Falls back to [pb-message] if no dedicated containers exist.
• Silently skips if no target is found (log to console or handle manually).

🏷️ HTML Markup

1️⃣ Single Container

<div pb-message class="d-none"></div>

2️⃣ Dedicated Containers

<div pb-success-message class="d-none"></div>  
<div pb-error-message class="d-none"></div>

✔️ Best Practice: Place these inside forms or target elements for reliable context detection.

📌 Form Example

<form id="my-form">  
  <input type="text" name="name">  
  <button   
    type="submit"  
    pb-post="/api/submit"  
    pb-expect="json"  
    pb-include="#my-form input"  
  >  
    Submit  
  </button>  

  <!-- Inside the form -->  
  <p pb-success-message class="text-success d-none"></p>  
  <p pb-error-message class="text-danger d-none"></p>  
</form>

🧩 Auto-Integration with pbFetch

For responses like { success: true, message: "..." }:

• On success (response.ok), pbFetch calls:

pbMessage.success(ctx, data.message)

• On error (!response.ok), pbFetch calls:

pbMessage.error(ctx, data.message)

Override auto-display with:

document.addEventListener('pb:success', (e) => {  
  e.preventDefault(); // Blocks auto-message  
  // Your custom logic  
});

🎨 Configuring Classes via System Settings

By default, message styling classes are pulled from system settings:

• pageblocks_msg_success – CSS classes for success messages
• pageblocks_msg_error – CSS classes for error messages
• pageblocks_hidden_class – Class used to hide message blocks (e.g. d-none)

Sample System Settings:

pageblocks_msg_success = "text-success"
pageblocks_msg_error = "text-danger,text-error" 
pageblocks_hidden_class = "d-none"

These get automatically mapped to JS configuration:

pbMessage.config = {
  successClasses: ['text-success'], // or values from system settings
  errorClasses: ['text-danger', 'text-error'], 
  hiddenClass: 'd-none' // or pageblocks_hidden_class value
};

Manual Override:

You can dynamically reconfigure using setConfig():

pbMessage.setConfig({
  successClasses: ['alert', 'alert-success'],
  errorClasses: ['alert', 'alert-danger'],
  hiddenClass: 'hidden' // e.g. for TailwindCSS
});

💡 Important: System settings are automatically applied during pbMessage initialization. Use setConfig() only for runtime modifications.

🧹 Clearing Messages

Reset messages and remove classes:

pbMessage.clear(form);  
// or pbMessage.clear(targetElement);

🔥 Full API

Method	Description
pbMessage.success(ctx, message)	Show success message
pbMessage.error(ctx, message)	Show error message
pbMessage.clear(ctx)	Clear messages and reset classes
pbMessage.setSuccessHandler(fn)	Override default success handler
pbMessage.setErrorHandler(fn)	Override default error handler
pbMessage.setConfig({...})	Configure CSS classes (arrays) for messages

✔️ SweetAlert2 Integration

pbMessage.setSuccessHandler((ctx, message) => {  
    Swal.fire({  
        icon: 'success',  
        title: 'Success!',  
        text: message  
    });  
});  

pbMessage.setErrorHandler((ctx, message) => {  
    Swal.fire({  
        icon: 'error',  
        title: 'Error!',  
        text: message  
    });  
});