Link Box Registry Multilingual

Link Box Registry (Multilingual): The Simple Way to Build a Shared Blogroll Network in WordPress.
Link Box Registry (Multilingual) lets you display five random partner sites from a shared registry using the linkbox shortcode. It works as Server or Client, supports EN, FR, DE, RO, ES, IT, PT, RU, JA, uses a Shadow DOM UI, and refreshes every five minutes.

What You’ll Learn

You will learn what the plugin does, how to install it, and how to use it as a Server or Client. You will also see how to customize the box title, translate the interface, and integrate the REST API. Finally, you will discover performance tips, security best practices, and AdSense-friendly usage ideas.

---

Why a Link Box Registry?

A classic blogroll is static. It gets stale, and you must update it manually.
This plugin fixes that. It pulls five random links from a shared registry and shows them inside a self-contained UI. It works across many sites. It is multilingual. And it refreshes every five minutes, so the list stays fresh without extra work.

---

How the Plugin Works (High Level)

The plugin runs in two modes:

• Server (registry): One site hosts the registry. Other sites can register themselves through REST endpoints. The server returns a random list of links on request.
• Client: A client site does not store the registry. Instead, it calls the server’s endpoint and proxies the list locally, caching it for five minutes.

You display the box anywhere with a simple shortcode:

[linkbox]

The UI mounts in a Shadow DOM. Therefore, its CSS does not leak to your theme, and your theme styles do not break the widget. This is crucial for reliability and for Publisher Program friendliness.

---

Key Features at a Glance

• Multilingual UI: English, French, German, Romanian, Spanish, Italian.
• Shadow DOM Widget: Safe, isolated styles.
• Shortcode-based: Use [linkbox] in posts, pages, or widgets.
• Server or Client: Pick the role per site.
• Five Random Links: Rotates on each refresh; cached for five minutes.
• Heartbeat & Cleanup: Clients can send periodic heartbeats. The server prunes inactive sites.
• REST Endpoints: /register, /heartbeat, /links, and /proxy_links.
• AdSense-friendly: No auto-clicking, no deceptive UI, and clean markup.

---

What the Code Actually Does

The code registers settings, a settings screen, a shortcode, REST endpoints, and two scheduled tasks.

Settings and Options

• linkbox_settings_ml stores mode, server endpoint, box title, and whether to include the current site.
• linkbox_registry_ml stores the registry (Server only).
• Five-minute cache: linkbox_ml_cached_links transient for quick responses.

REST Endpoints

• POST /wp-json/linkbox/v1/register
  Registers a site: { url, name? }. The server stores or updates last_seen.
• POST /wp-json/linkbox/v1/heartbeat
  Renews last_seen so the server knows the client is still active.
• GET /wp-json/linkbox/v1/links?count=5&random=1&exclude=...
  Returns an array of { url, name } from the local registry. Works on the Server.
• GET /wp-json/linkbox/v1/proxy_links?...
  Clients call their configured server to proxy the list locally. If the server fails, the plugin gracefully falls back to the current site’s own link.

Shadow DOM UI

The frontend script (assets/linkbox.js, enqueued as linkbox-js-ml) attaches a component to a <div class="linkbox-host" ...>. The script fetches the links from the local rest_url('linkbox/v1/...'), injects clean markup, and styles it inside a Shadow Root. Your theme stays unaffected.

Scheduled Events

• Daily purge: Removes registry entries that have not been seen in 30 days.
• Weekly heartbeat sender (Client): Re-registers and pings the server, keeping the registry healthy.

---

Installation (Step-by-Step)

1. Download or copy the plugin folder into wp-content/plugins/.
   Folder name example: linkbox-registry-ml.
2. Check file structure:
   • linkbox-registry-ml.php (main file with the code you provided)
   • assets/linkbox.js (frontend widget script)
   • readme.txt (optional but recommended)
3. Activate the plugin in Plugins → Installed Plugins.
4. Open Settings: Settings → Link Box (ML).
5. Choose a Role:
   • Server if this site will host the registry.
   • Client if this site should fetch from a central server.
6. If Client, set Registry endpoint to the server’s base path, for example: https://example.com/wp-json/linkbox/v1
7. Set a Box Title (optional).
   You can rename the display title to match your branding. If you leave it blank, the plugin will use the localized fallback (e.g., “Our Network”).
8. Include current site or not.
   If you run a hub, you may include the current site. If not, uncheck it to avoid showing your own URL.
9. Save your settings.
10. Add the Shortcode wherever you want: [linkbox]

[linkbox]

Donate & Get Plugin

After donating, you will be redirected back and receive a download link (valid for 10 minutes).

---

Server Mode: Getting Other Sites to Join

When your site is the Server, other sites can register themselves in two easy ways:

1. Automatic (Client mode)
   When a Client site saves its settings with your endpoint set in Registry endpoint, it will call your /register route and add itself.
2. Manual (cURL or Postman)
   Any Admin can send: POST https://YOUR-SERVER/wp-json/linkbox/v1/register Body: url=https://site-to-add.com name=Nice Site The server saves { url, name, last_seen }. Clients should also ping /heartbeat weekly.

Tip: Keep your server endpoint public. The plugin uses permission_callback => __return_true for simple registries. If you need to restrict who can join, place the server behind a firewall rule or add a custom token check in the register route.

---

Client Mode: Simple and Hands-Off

As a Client, you only need the server endpoint. The plugin fetches links, caches them for five minutes, and refreshes automatically. It also re-registers and sends a heartbeat weekly. If the server goes down, the widget falls back to your own site link, so the layout never breaks.

---

Using the Shortcode

Place the shortcode in any of these:

• A post or page content area.
• A widget that supports shortcodes.
• A block using a Shortcode block in Gutenberg.
• A template part via do_shortcode('[linkbox]').

The plugin outputs a single placeholder:

<div class="linkbox-host" data-endpoint=".../linkbox/v1/links" data-exclude=""></div>

The JS then mounts the Shadow DOM widget, fetches links, and renders the UI with a localized title and meta line. The meta line already includes a Download Page link, which you can point to your own page for sharing the plugin with partners.

---

Multilingual UI and Localization

The plugin auto-detects the WordPress locale (determine_locale()), then maps it to one of six languages:

• English (en)
• Français (fr)
• Deutsch (de)
• Română (ro)
• Español (es)
• Italiano (it)
• Português (pt)
• Русский (ru)
• 日本語 (ja)

You can switch the site language in Settings → General → Site Language. The widget updates its title, labels, and meta text accordingly. This is ideal for multi-region networks.

---

Customizing the Box Title

Visit Settings → Link Box (ML) and edit Box title.
You can set different titles per language by combining this with multilingual plugins that manage per-language options screens, or by running separate language sites as clients of the same server.

---

Excluding Your Own Site from the List

If you do not want to show your own URL in the five random links, uncheck Include current site link in settings. The widget will pass your site to the endpoint’s exclude parameter under the hood. The server or proxy will filter it out before returning the list.

---

Performance and Caching

• Five-minute transient: Results are cached per site for five minutes using set_transient().
• Fast calls: Endpoints return a compact array of { url, name }.
• Graceful fallback: On network issues, clients show your own link to avoid an empty box.
• Shadow DOM CSS: Styles load once and do not compete with your theme.

This is light enough for most shared hosts and highly compatible with page caching and CDNs. The REST calls can be excluded from cache if you want the five-minute refresh to remain accurate.

---

Security Considerations

• URL sanitation: The plugin normalizes and sanitizes URLs with filter_var() and wp_parse_url().
• Open endpoints: The default permission_callback allows public registration. For private networks, restrict access at the server level or add a token.
• Escaping: Output uses esc_html(), esc_url(), and wp_specialchars_decode() correctly.
• Cron tasks: Purge removes stale entries. Heartbeat keeps records fresh.

For AdSense compliance, keep the box descriptive and avoid deceptive labels. Do not encourage clicks. Use clear titles like “Our Network”.

---

Styling Notes (Shadow DOM)

Because the widget renders inside a Shadow Root, its CSS:

• Does not affect your theme.
• Is not affected by your theme.
• Can be updated safely in the plugin script without breaking layouts.

If you want custom theming, extend assets/linkbox.js to accept CSS variables from attributes on .linkbox-host, and use them inside the Shadow Root. This keeps the isolation while allowing brand tweaks.

---

Shortcode Examples

Default usage

[linkbox]

Inside a column layout
Add a Shortcode block inside a Group or Columns block. The widget will size to the container width.

In a PHP template

echo do_shortcode('[linkbox]');

---

Troubleshooting

The box shows only my site.
Your server may be empty. Register more client sites, or switch this site to Client and point it to a populated server.

The box never changes.
Remember, the list caches for five minutes. Clear your cache, or wait five minutes and refresh.

The UI looks unstyled.
Confirm that assets/linkbox.js loads in the front end. Check the console for 404 errors. Make sure you activated the plugin and did not block JS in performance plugins.

Registration fails on the server.
Verify the server’s REST base: https://server-site.tld/wp-json/linkbox/v1. Try registering using Postman or cURL to confirm connectivity.

I do not want public registration.
Restrict by IP, add a secret token, or implement a custom permission_callback that checks a header.

---

AdSense-Friendly Usage Ideas

• Add the box below your content as “Our Network” or “Partner Sites”.
• Do not place it too close to ad units to avoid accidental clicks.
• Keep labels clear. Do not incentivize clicks.
• Use it to broaden discovery across your own projects and trusted partners.

Donate & Get Plugin

After donating, you will be redirected back and receive a download link (valid for 10 minutes).

---

How to Create Your Own “Download Page” Link

By default, the meta line includes a localized Download Page link. Point it to a page on your site with:

• A short description of the plugin.
• Instructions for Server and Client setup.
• Your registry endpoint (if public).
• A ZIP download of the plugin.

You can keep this page updated as your network grows.

---

Example REST Calls (For Admins and Developers)

Register a site

POST /wp-json/linkbox/v1/register
url=https://partner1.com
name=Partner 1

Heartbeat

POST /wp-json/linkbox/v1/heartbeat
url=https://partner1.com

Get links from Server

GET /wp-json/linkbox/v1/links?count=5&random=1

Get links from Client (proxy)

GET /wp-json/linkbox/v1/proxy_links?count=5&random=1

---

Benefits of Link Box Registry

• Easy cross-promotion without manual list management.
• Fresh rotation keeps discovery high.
• Multilingual UI fits global audiences.
• Shadow DOM prevents design conflicts.
• Lightweight and fast with smart caching.
• Scalable: Add dozens or hundreds of sites to the registry.
• Fail-safe: Fallback ensures the box never breaks the layout.

---

Best Practices for a Healthy Network

• Run one stable Server on a reliable host.
• Encourage Clients to enable heartbeat by keeping Client mode active.
• Prune dead links automatically with the daily purge.
• Monitor the registry page in the WordPress admin.
• Publish a public Download Page with clear guidelines and a ZIP.

---

Step-By-Step Quick Start (Two-Site Demo)

On Site A (Server):

1. Install and activate the plugin.
2. Go to Settings → Link Box (ML).
3. Set Role = Server. Save.

On Site B (Client):

1. Install and activate the plugin.
2. Go to Settings → Link Box (ML).
3. Set Role = Client.
4. Paste Site A’s endpoint: https://site-a.com/wp-json/linkbox/v1 Save.

On both sites, add [linkbox] to a page.
Site A shows random links from its local registry. Site B proxies Site A’s list every five minutes.

---

Frequently Asked Questions

---

Practical Implementation Checklist

• Choose your hub site to act as the Server.
• Publish a Download Page with the ZIP and setup steps.
• Point Client sites to your server endpoint.
• Add [linkbox] to the footer or sidebar of each site.
• Check the widget rotates links every five minutes.
• Monitor the registry weekly. Remove broken or unwanted links.

---

Developer Tips

• Add a REST nonce or token if you require private registration.
• Extend tr_map() to support more languages.
• Add CSS variable support for brand colors inside assets/linkbox.js.
• Expose a filter for the number of visible items if you want three or six.
• Write a small admin UI to view and prune the registry from the dashboard.

---

Final Thoughts

This plugin gives you a safe, fast way to build cross-site discovery without messing with theme CSS. It scales from two sites to entire networks. It is simple to install, easy to manage, and friendly to users, search engines, and ad policies.

---

---

Fresh Ways to Grow a Network

Partnerships grow with trust and visibility. This lightweight Link Box gives both. Start with one Server. Invite a few friends. Keep it tidy. As new sites join, everyone benefits from rotating exposure without clutter, without risk, and without time-consuming maintenance.