UI Components

Create custom widgets and server tabs to extend the PteroCA interface.

Dashboard Widgets

Widgets are UI components displayed on the dashboard or other contexts.

Widget Interface

<?php
namespace Plugins\MyPlugin\Widget;

use App\Core\Widget\WidgetContext;
use App\Core\Widget\WidgetInterface;
use App\Core\Widget\WidgetPosition;

class MyWidget implements WidgetInterface
{
    public function __construct(
        private readonly MyService $myService,
    ) {}

    public function getName(): string
    {
        return 'my_widget';
    }

    public function getDisplayName(): string
    {
        return 'My Custom Widget';
    }

    public function getSupportedContexts(): array
    {
        return [
            WidgetContext::DASHBOARD,      // Main dashboard
            WidgetContext::SERVER_DETAIL,  // Server detail page
        ];
    }

    public function getPosition(): WidgetPosition
    {
        return WidgetPosition::RIGHT;  // LEFT, CENTER, RIGHT
    }

    public function getPriority(): int
    {
        return 50;  // Higher = appears first (0-100)
    }

    public function getColumnSize(): int
    {
        return 12;  // Bootstrap grid: 1-12 (12 = full width)
    }

    public function getTemplate(): string
    {
        return '@PluginMyPlugin/widgets/my_widget.html.twig';
    }

    public function getData(WidgetContext $context, array $contextData): array
    {
        // Prepare data for template
        $data = $this->myService->getWidgetData();

        return [
            'items' => $data,
            'count' => count($data),
            'last_updated' => new \DateTimeImmutable(),
        ];
    }

    public function isVisible(WidgetContext $context, array $contextData): bool
    {
        // Control widget visibility
        // Example: only show to admins
        return $this->security->isGranted('ROLE_ADMIN');
    }
}

Widget Template

{# templates/widgets/my_widget.html.twig #}
<div class="card">
    <div class="card-header">
        <h5 class="card-title">{{ 'widget.my_widget.title'|trans({}, 'plugin_my_plugin') }}</h5>
    </div>
    <div class="card-body">
        {% if items is empty %}
            <p class="text-muted">{{ 'widget.my_widget.no_data'|trans({}, 'plugin_my_plugin') }}</p>
        {% else %}
            <ul class="list-group">
                {% for item in items %}
                    <li class="list-group-item">
                        {{ item.name }} - {{ item.value }}
                    </li>
                {% endfor %}
            </ul>
        {% endif %}

        <div class="mt-3 text-muted small">
            {{ 'widget.my_widget.last_updated'|trans({}, 'plugin_my_plugin') }}:
            {{ last_updated|date('Y-m-d H:i:s') }}
        </div>
    </div>
</div>

Registering Widgets

In Resources/config/services.yaml:

services:
    Plugins\MyPlugin\Widget\MyWidget:
        tags: ['widget']

Important: Widgets MUST be tagged with widget.

Widget Contexts

• DASHBOARD: Main dashboard page

• SERVER_DETAIL: Individual server page

• USER_PROFILE: User profile page

• ADMIN_OVERVIEW: Admin overview page

Widget Positions

• TOP: Top of the page

• LEFT: Left column

• RIGHT: Right column

• BOTTOM: Bottom of the page

• FULL_WIDTH: Full width across all columns

• NAVBAR: Navigation bar area

Widget Best Practices

1. Keep widgets lightweight - avoid heavy computations

2. Use caching for expensive operations

3. Handle empty data gracefully

4. Use translations for all text

5. Make responsive - test at different screen sizes

6. Check permissions in isVisible()

Server Tabs

Add custom tabs to the server detail page.

Tab Interface

<?php
namespace Plugins\MyPlugin\Tab;

use App\Core\Tab\ServerTabContext;
use App\Core\Tab\ServerTabInterface;

class MyTab implements ServerTabInterface
{
    public function getId(): string
    {
        return 'my_tab';
    }

    public function getLabel(): string
    {
        return 'My Tab';
    }

    public function getPriority(): int
    {
        return 10;  // Higher = appears first
    }

    public function isVisible(ServerTabContext $context): bool
    {
        // Control tab visibility
        // Example: only show for specific game
        return $context->server->getGame() === 'minecraft';
    }

    public function isDefault(): bool
    {
        return false;  // Is this the default selected tab?
    }

    public function getTemplate(): string
    {
        return '@PluginMyPlugin/tabs/my_tab.html.twig';
    }

    public function getStylesheets(): array
    {
        return [];  // Optional: Add custom CSS files
    }

    public function getJavascripts(): array
    {
        return [];  // Optional: Add custom JS files
    }

    public function requiresFullReload(): bool
    {
        return false;  // Set to true if tab needs full page reload
    }
}

Tab Template

Templates receive the context variable which is a ServerTabContext object:

{# templates/tabs/my_tab.html.twig #}
<div class="server-tab-content">
    <h4>{{ 'tab.my_tab.title'|trans({}, 'plugin_my_plugin') }}</h4>

    <div class="card">
        <div class="card-body">
            <p><strong>Server ID:</strong> {{ context.server.id }}</p>
            <p><strong>Server Name:</strong> {{ context.server.name }}</p>
            <p><strong>Status:</strong> {{ context.serverData.status }}</p>

            {% if context.isAdminView %}
                <div class="alert alert-info">
                    <strong>Admin View:</strong> You're viewing as administrator
                </div>
            {% endif %}

            {% if context.isOwner %}
                <div class="alert alert-success">
                    <strong>You are the server owner</strong>
                </div>
            {% endif %}

            <a href="{{ path('plugin_my_plugin_server_action', {id: context.server.id}) }}"
               class="btn btn-primary">
                {{ 'tab.my_tab.action'|trans({}, 'plugin_my_plugin') }}
            </a>
        </div>
    </div>
</div>

Context Data Available

ServerTabContext provides these public properties:

• server (Server entity): Server object with id, name, game, pterodactylServerId, user (owner), etc.

• serverData (ServerData DTO): Server status, isInstalling, resources (CPU, RAM, disk), limits

• user (User entity): Current viewing user

• isAdminView (bool): Whether admin is viewing

• isOwner (bool): Whether current user is the server owner

ServerTabContext provides these methods:

• hasPermission(string $permission): bool - Check if user has specific permission

• hasAnyPermission(array $permissions): bool - Check if user has any of the permissions

• hasAllPermissions(array $permissions): bool - Check if user has all permissions

• getProductFeature(string $featureKey): mixed - Get product feature value

• hasConfigurableStartup(): bool - Check if server has configurable startup

Access properties directly in PHP: $context->server->getId() Access in Twig templates: {{ context.server.id }}

Registering Tabs

Use an Event Subscriber (see Event System):

namespace Plugins\MyPlugin\EventSubscriber;

use App\Core\Event\Server\Tab\ServerTabsCollectedEvent;
use Plugins\MyPlugin\Tab\MyTab;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class ServerTabSubscriber implements EventSubscriberInterface
{
    public function __construct(
        private readonly MyTab $myTab,
    ) {}

    public static function getSubscribedEvents(): array
    {
        return [
            ServerTabsCollectedEvent::class => 'onServerTabs',
        ];
    }

    public function onServerTabs(ServerTabsCollectedEvent $event): void
    {
        // Get the tab registry and register your tab
        $registry = $event->getRegistry();
        $registry->registerTab($this->myTab);
    }
}

Related Guides

• Event System - Subscribe to menu and tab events

• Translations - Multi-language UI

• Assets - Custom styles for widgets/tabs

• Best Practices - Performance tips