# 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](./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:**

```javascript
{
  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`):

```javascript
{
  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

```javascript
(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