my_openplace/frontend-backup/plugins/README.md

FurryPlace Plugins

This directory contains plugins that extend the FurryPlace UI using the FurryPlace SDK.

Quick Start

1. Create a plugin file in this directory (e.g., my-plugin.js)
2. Refresh the page - Plugins are automatically discovered and loaded!
3. Use the SDK to register buttons or add other functionality

✨ Auto-Loading: Plugins are automatically discovered from the frontend-backup/plugins/ directory. Any .js file you add here will be automatically loaded when the page loads. No need to manually edit HTML files!

Example Plugin

See example-button.js for a complete example showing how to:

• Add custom buttons with icons
• Handle click events
• Use conditional rendering
• Apply custom styling
• Open external links

FurryPlace SDK API

window.FurryPlaceSDK.registerButton(config)

Register a custom button in the UI.

Configuration Object:

{
  id: string,              // Required: Unique identifier
  title: string,           // Required: Tooltip text
  icon: string|HTMLElement, // Required: SVG string or DOM element
  onClick: Function,       // Required: (context, event) => {}
  position: string,        // Optional: 'top', 'bottom', 'before-leaderboard', 'after-leaderboard'
  className: string,       // Optional: Custom CSS classes (default: 'btn btn-square shadow-md')
  wrapperClass: string,    // Optional: Wrapper div CSS classes
  condition: Function,     // Optional: (context) => boolean
  disabled: boolean        // Optional: Whether button is disabled
}

Positions:

• 'top' - First button in the container
• 'bottom' - Last button in the container
• 'before-leaderboard' - Before the leaderboard button
• 'after-leaderboard' - After the leaderboard button (default)

Context Object (passed to onClick and condition):

{
  sdk: {
    version: string        // SDK version
  },
  user: {
    isLoggedIn: boolean    // User login status (not yet implemented)
  },
  map: {}                  // Map context (not yet implemented)
}

Other SDK Methods

• FurryPlaceSDK.unregisterButton(id) - Remove a registered button
• FurryPlaceSDK.getButtons() - Get list of all registered buttons
• FurryPlaceSDK.getContext() - Get current context object
• FurryPlaceSDK.init() - Manually initialize SDK (usually automatic)

Example Usage

(function() {
  'use strict';

  // Wait for SDK to load
  function waitForSDK(callback) {
    if (window.FurryPlaceSDK) {
      callback();
    } else {
      setTimeout(() => waitForSDK(callback), 100);
    }
  }

  waitForSDK(() => {
    // Register a button
    window.FurryPlaceSDK.registerButton({
      id: 'my-custom-button',
      title: 'My Button',
      position: 'bottom',
      icon: `
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960" fill="currentColor" class="size-5">
          <path d="M480-80q-83 0-156-31.5T197-197q-54-54-85.5-127T80-480q0-83 31.5-156T197-763q54-54 127-85.5T480-880q83 0 156 31.5T763-763q54 54 85.5 127T880-480q0 83-31.5 156T763-197q-54 54-127 85.5T480-80Z"/>
        </svg>
      `,
      onClick: (context) => {
        alert('Button clicked!');
        console.log('Context:', context);
      }
    });

    console.log('[My Plugin] Loaded!');
  });
})();

Finding SVG Icons

You can find Material Design icons at:

• https://fonts.google.com/icons

Copy the SVG code and use it as the icon parameter.

Tips

1. Wrap your plugin in an IIFE to avoid polluting the global scope
2. Wait for the SDK to be available before registering buttons
3. Use unique IDs to avoid conflicts with other plugins
4. Test button positions to find the best placement for your use case
5. Check the console for SDK loading messages and errors

How Auto-Loading Works

The SDK automatically:

1. Calls /api/plugins to get a list of all .js files in the plugins/ directory
2. Dynamically loads each plugin by creating <script> tags
3. Reports loading progress in the browser console

You can check which plugins are loaded by looking at the console:

[FurryPlace SDK] Auto-discovering plugins...
[FurryPlace SDK] Found 2 plugin(s): ['example-button.js', 'my-plugin.js']
[FurryPlace SDK] Loaded plugin: example-button.js
[FurryPlace SDK] Loaded plugin: my-plugin.js

Note: If you need to disable a plugin, either delete it or rename it to something other than .js (like .js.disabled)

Troubleshooting

Button not appearing?

• Check the browser console for errors
• Verify the SDK is loaded: console.log(window.FurryPlaceSDK)
• Ensure your button ID is unique
• Try different positions

Button appearing in wrong place?

• Try different position values
• Check if the button container has changed in the UI

Icon not showing?

• Verify your SVG has viewBox and fill="currentColor"
• Add class="size-5" to the SVG element
• Check for syntax errors in the SVG string