Custom Macro UI Enhancer Runs Only Once — Fails on Reopen (Confluence Server/DC Plugin)

Confluence Development
1

I’m developing a custom Confluence macro (for Server/Data Center) that enhances the macro editor UI by injecting additional fields and behaviors when editing the macro parameters in the macro editor dialog (like tab configuration, label selectors, etc.).

I’m using JavaScript with AJS.toInit() and a MutationObserver to detect when the macro editor dialog opens and then apply custom UI logic.

:white_check_mark: Current Behavior (First Time):

  • On the first time the macro editor dialog opens, the JS logic successfully:
    • Detects the macro dialog visibility.
    • Locates inputs using querySelector.
    • Injects custom DOM elements (like a sortable table for selected pages or a label picker).
    • Works perfectly.

:cross_mark: Problem (Subsequent Opens):

  • On second or third attempt to open the same macro editor:
    • The macro dialog UI appears stuck with a loading spinner.
    • The browser console logs show that my setup logic (setupCustomUI()) runs multiple times (sometimes infinitely).
    • The macro fails to load completely or hangs.

:detective: Debugging Observations:

  • I use MutationObserver to monitor #macro-browser-dialog and detect when it becomes visible.
  • However, re-opening the macro editor does not reset the DOM cleanly, causing my injected DOM or handlers to accumulate or conflict.
  • Even though I attempt to prevent multiple initializations with flags like isInitializationInProgress, it doesn’t fully avoid recursive triggers due to DOM mutations.

:light_bulb: What I’ve Tried:

  • Added macroDialogOpen flag to allow UI setup only once per open.
  • Cleaned up existing DOM before reinserting UI elements.
  • Wrapped DOM setup in visibility checks (dialog.style.display !== "none").
  • Ensured I remove previously injected elements (removeChild or replaceChild).
  • Tried setTimeout, requestAnimationFrame, and debounce around initialization.

:bullseye: What I Need Help With:

  • What’s the best practice to detect and respond to macro dialog open/close events in a stable and repeatable way?
  • How can I safely inject UI enhancements on each open without side effects or leaks from the previous instance?
  • Is there a lifecycle hook or documented pattern for safely extending the macro editor UI?