Skip to main content

Proxy link updater (standalone)

Overview​

The proxy link updater is a small frontend utility that corrects anchor href values when the app is served behind a proxy (e.g., EZproxy). It preserves the original hostname replacement rules via insideProxy() and matchOrigin() from resources/js/helpers.js and also listens for proxy-navigate events to open URLs with a fixed origin.

This document explains how to use the standalone bundle.

When to use​

  • Pages where links generated server-side may include the tenant origin and need to be adjusted to the current origin behind a proxy.
  • Places where we want to trigger navigation programmatically with a fixed URL using proxy-navigate.

Usage​

Include it where needed using defer so it does not block rendering and executes after the DOM is parsed:

<script src="{{ mix('js/proxy-link-updater.js') }}" data-parent-selector="#main-content" defer></script>
  • data-parent-selector: Required. CSS selector defining the scope where anchors will be normalized. If omitted, the script is not activated and logs a warning.
  • The script runs on DOMContentLoaded and updates all a[href] within the scope if insideProxy() is true.
  • It registers a proxy-navigate listener to open fixed URLs computed with matchOrigin().

Event navigation example​

<script>
  // Open a fixed URL (with origin adjusted if behind proxy)
  window.dispatchEvent(new CustomEvent('proxy-navigate', {
    detail: { url: 'https://tenant.example.com/reader/book#p=1', target: '_blank' }
  }));
  </script>

Using Livewire​

If you need to trigger navigation from a Livewire component, dispatch the same browser event. Use the syntax matching your Livewire version:

// Livewire v2
$this->dispatchBrowserEvent('proxy-navigate', [
    'url' => 'https://tenant.example.com/reader/book#p=1',
    'target' => '_blank',
]);
// Livewire v3
$this->dispatch('proxy-navigate', url: 'https://tenant.example.com/reader/book#p=1', target: '_blank');

The standalone script listens globally via window.addEventListener('proxy-navigate', ...), so no extra JavaScript glue is required beyond including the script tag with data-parent-selector.

Notes and constraints​

  • Do not include the Alpine component proxyLinkUpdater() on pages where the standalone script is used to avoid duplicate work.
  • Always pass a data-parent-selector to enable the script. This keeps activation explicit and avoids unintended global rewrites.
  • Use defer to respect non‑blocking rendering and ensure DOM readiness.
  • farfalla/resources/js/standalone/proxy-link-updater.js
  • farfalla/resources/js/helpers.js (insideProxy, matchOrigin)
X

Graph View