Widgets

Dokumentasi ini merupakan referensi untuk seluruh class di dalam PandaPanel\Widgets:

base Widget;
empat concrete widget type;
value object yang digunakan Widget untuk membangun payload;
serta mekanisme registration dan resolution di sekitarnya.

Gunakan halaman ini ketika Anda sudah memahami apa itu Widget dan membutuhkan detail seperti:

signature yang tepat;
default value;
serialized key;
lifecycle;
atau behavior internal.

Untuk pembahasan konsep seperti:

kapan menggunakan masing-masing Widget;
kapan sebuah Widget sebaiknya dibuat lazy;

lihat:

Widgets Overview

Sebuah Widget menghitung seluruh datanya di server kemudian mengirim serialized description ke Vue:

text

scalar
array
null

Tidak ada:

Closure;
executable PHP;
class name;

yang dikirim ke frontend.

Contoh minimal yang berfungsi

Buat Stats Widget:

bash

php artisan make:panel-widget UserStats --panel=Admin --type=stats

Kemudian:

php

<?php

declare(strict_types=1);

namespace App\Panels\Admin\Widgets;

use App\Models\User;
use PandaPanel\Widgets\Enums\StatColor;
use PandaPanel\Widgets\StatsWidget;
use PandaPanel\Widgets\Support\Stat;

final class UserStats extends StatsWidget
{
    protected static int $sort = 10;

    protected static ?string $heading = 'Accounts';

    /** @return list<Stat> */
    public function stats(): array
    {
        return [
            Stat::make(
                'Total users',
                User::query()->count()
            )
                ->icon('users'),

            Stat::make(
                'Verified',
                User::query()
                    ->whereNotNull(
                        'email_verified_at'
                    )
                    ->count()
            )
                ->icon('shield')
                ->color(
                    StatColor::Success
                ),
        ];
    }
}

Aktifkan discovery pada Panel:

php

use PandaPanel\Core\Panel;

public function panel(
    Panel $panel
): Panel {
    return $panel
        ->path('admin')
        ->discoverWidgets(
            app_path(
                'Panels/Admin/Widgets'
            )
        );
}

Sekarang:

text

GET /admin

akan merender Dashboard dengan Widget tersebut.

`PandaPanel\Widgets\Widget`

Widget merupakan abstract base class dari keempat tipe Widget.

Class ini mengimplementasikan:

php

PandaPanel\Contracts\WidgetContract

Static configuration

Property	Type	Default	Dibaca melalui
`$sort`	`int`	`0`	`sort()`
`$columnSpan`	`int\|string\|array<string, int\|string>`	`1`	`columnSpan()`
`$lazy`	`bool`	`false`	`isLazy()`
`$heading`	`?string`	`null`	`heading()`
`$description`	`?string`	`null`	`description()`
`$pollingInterval`	`?int`	`null`	`pollingInterval()`

Contoh:

php

use PandaPanel\Widgets\StatsWidget;

final class QueueDepth extends StatsWidget
{
    protected static int $sort = 5;

    protected static int|string|array
        $columnSpan = [
            'default' => 1,
            'md' => 2,
            'lg' => 3,
            'xl' => 4,
        ];

    protected static bool $lazy = true;

    protected static ?string $heading =
        'Queue';

    protected static ?string $description =
        'Jobs waiting, by connection.';

    protected static ?int $pollingInterval =
        30;

    // ...
}

Widget diurutkan berdasarkan:

text

[sort(), id()]

Jadi jika dua Widget memiliki $sort yang sama, urutannya fallback ke id secara alfabetis, bukan registration order.

Methods

Method	Signature	Catatan
`type()`	`abstract public static function type(): WidgetType`	Diimplementasikan oleh masing-masing base Widget type
`data()`	`abstract public function data(): array`	Payload yang diterima renderer
`id()`	`public static function id(): string`	`Str::kebab(class_basename(static::class))`
`sort()`	`public static function sort(): int`
`isLazy()`	`public static function isLazy(): bool`
`heading()`	`public static function heading(): ?string`
`description()`	`public static function description(): ?string`
`pollingInterval()`	`public static function pollingInterval(): ?int`	Dalam detik
`canView()`	`public static function canView(): bool`	Default `true`
`columnSpan()`	`public static function columnSpan(): array`	Dinormalisasi per breakpoint
`filterSchema()`	`public function filterSchema(): ?FormSchema`	Default `null`
`filtersInModal()`	`public static function filtersInModal(): bool`	Default `false`
`withPageContext()`	`public function withPageContext(PageContext $context): static`	Dipanggil oleh Page
`withFilters()`	`public function withFilters(array $filters): static`	Dipanggil oleh Page
`context()`	`protected function context(): PageContext`	Throw jika context tidak tersedia
`filter()`	`protected function filter(string $name, mixed $default = null): mixed`
`filters()`	`protected function filters(): array`
`toDefinition()`	`public function toDefinition(): array`	Serialized Widget
`toArray()`	`public function toArray(): array`	Alias dari `toDefinition()`

`id()`

php

public static function id(): string;

Id dibuat dari kebab-case basename class.

Contoh:

php

UserStats::id();
// 'user-stats'

RecentUsers::id();
// 'recent-users'

Id ini stabil antar-run sehingga:

urutan Widget;
key deferred data;
filter namespace;

semuanya menggunakan identifier yang sama.

`canView()`

php

public static function canView(): bool;

Method ini diperiksa oleh:

php

WidgetCollection

sebelum Widget di-construct.

Artinya Widget yang tidak diizinkan:

text

canView()
↓
false
↓
tidak di-construct
↓
data() tidak dipanggil
↓
query tidak berjalan

Contoh:

php

use Illuminate\Support\Facades\Auth;

public static function canView(): bool
{
    return Auth::user()
        ?->can(
            'viewRevenue'
        )
        ?? false;
}

`columnSpan()`

php

/**
 * @return array{
 *     default: int|string,
 *     md: int|string,
 *     lg: int|string,
 *     xl: int|string
 * }
 */
public static function columnSpan(): array;

Method ini menjalankan $columnSpan melalui:

php

ColumnSpan::normalize()

Contoh:

php

protected static int|string|array
    $columnSpan = 'full';

UserStats::columnSpan();

Hasil:

php

[
    'default' => 'full',
    'md' => 'full',
    'lg' => 'full',
    'xl' => 'full',
]

`withFilters()` dan `filter()`

php

/**
 * @param array<string, mixed> $filters
 */
public function withFilters(
    array $filters
): static;

protected function filter(
    string $name,
    mixed $default = null
): mixed;

/**
 * @return array<string, mixed>
 */
protected function filters(): array;

filter() mengembalikan default jika value:

php

null

atau empty string:

text

''

Dengan demikian control yang sudah dibersihkan dibaca sebagai:

text

absent

bukan sebagai empty string literal.

Contoh:

php

$widget =
    (new UserGrowth)
        ->withFilters([
            'months' => '12',
        ]);

// Di dalam Widget:
$months =
    (int)
    $this->filter(
        'months',
        6
    );

// 12

Value yang diterima Widget sudah dibatasi oleh schema yang mendeklarasikannya.

Key yang tidak pernah dideklarasikan schema tidak akan tersedia, apa pun isi query string.

`filterSchema()` dan `filtersInModal()`

php

public function filterSchema():
    ?FormSchema;

public static function filtersInModal():
    bool;

Contoh:

php

use PandaPanel\Forms\Components\Select;
use PandaPanel\Forms\FormSchema;

public function filterSchema():
    FormSchema
{
    return FormSchema::make()
        ->schema([
            Select::make('months')
                ->label('Window')
                ->options([
                    '6' =>
                        'Last 6 months',

                    '12' =>
                        'Last 12 months',
                ])
                ->default('6'),
        ]);
}

public static function filtersInModal():
    bool
{
    return true;
}

State filter disimpan di query string dengan bentuk:

text

widgets[{id}][{field}]

Contoh:

text

?widgets[user-growth][months]=12

State juga dipersist per Page di session.

Lihat:

Widget Filters

`withPageContext()` dan `context()`

php

public function withPageContext(
    PageContext $context
): static;

/**
 * @throws LogicException
 */
protected function context():
    PageContext;

Hanya Resource Page yang memberikan Page Context.

context() melempar exception daripada mengembalikan empty context.

Alasannya:

Widget yang mencoba membaca record tetapi tidak pernah diberikan record berarti berada pada Page yang salah.

Contoh:

php

public function stats(): array
{
    return [
        Stat::make(
            'Rows on this tab',
            $this
                ->context()
                ->count()
        ),
    ];
}

`toDefinition()`

php

/**
 * @return array<string, mixed>
 */
public function toDefinition(): array;

Serialized Widget memiliki key berikut:

Key	Type	Value
`id`	`string`	`static::id()`
`type`	`string`	`static::type()->value`
`sort`	`int`
`columnSpan`	`array{default, md, lg, xl}`
`lazy`	`bool`
`heading`	`?string`
`description`	`?string`
`polling`	`?int`	Detik, dari `pollingInterval()`
`filters`	`?array{inModal: bool, form: array}`	`null` jika tidak ada `filterSchema()`
`data`	`?array`	`null` untuk lazy Widget
`component`	`string`	Hanya `CustomWidget`

Contoh:

php

(new UserStats)
    ->toDefinition()['id'];

// 'user-stats'

`PandaPanel\Widgets\StatsWidget`

API:

php

public static function type():
    WidgetType;
// WidgetType::Stats

/** @return list<Stat> */
abstract public function stats():
    array;

/**
 * @return array{
 *     stats: list<array<string, mixed>>
 * }
 */
public function data():
    array;

Contoh:

php

use App\Models\Order;
use PandaPanel\Widgets\Enums\StatColor;
use PandaPanel\Widgets\StatsWidget;
use PandaPanel\Widgets\Support\Stat;

final class OrderStats extends StatsWidget
{
    /** @return list<Stat> */
    public function stats(): array
    {
        return [
            Stat::make(
                'Orders',
                Order::query()->count()
            )
                ->icon('receipt'),

            Stat::make(
                'Revenue',
                (float)
                Order::query()
                    ->sum('total')
            )
                ->format(
                    prefix: '£',
                    decimals: 2
                )
                ->color(
                    StatColor::Success
                ),
        ];
    }
}

Lakukan aggregation di database.

Contohnya:

php

Order::query()->count();

Bukan:

php

Order::query()
    ->get()
    ->count();

Meng-hydrate seluruh collection hanya untuk menghitung jumlah adalah salah satu cara paling umum membuat Dashboard menjadi Page paling lambat di application.

`PandaPanel\Widgets\TableWidget`

Defaults:

php

protected static int|string|array
    $columnSpan = [
        'default' => 1,
        'md' => 2,
        'lg' => 2,
        'xl' => 2,
    ];

protected static string $emptyMessage =
    'Nothing to show yet.';

protected static int $perPage = 5;

API:

php

public static function type():
    WidgetType;
// WidgetType::Table

abstract public function table(
    TableSchema $table
): TableSchema;

/**
 * @return Builder<covariant Model>
 */
abstract public function query():
    Builder;

public static function stateNamespace():
    string;

Contoh:

php

use App\Models\User;
use Illuminate\Database\Eloquent\Builder;
use PandaPanel\Tables\Columns\DateTimeColumn;
use PandaPanel\Tables\Columns\TextColumn;
use PandaPanel\Tables\Enums\SortDirection;
use PandaPanel\Tables\TableSchema;
use PandaPanel\Widgets\TableWidget;

final class RecentUsers extends TableWidget
{
    protected static string
        $emptyMessage =
            'No one has signed up yet.';

    protected static int
        $perPage = 5;

    public function table(
        TableSchema $table
    ): TableSchema {
        return $table
            ->columns([
                TextColumn::make('name')
                    ->searchable()
                    ->sortable(),

                TextColumn::make('email')
                    ->searchable(),

                DateTimeColumn::make(
                    'created_at'
                )
                    ->label('Joined')
                    ->relative()
                    ->sortable(),
            ])
            ->defaultSort(
                'created_at',
                SortDirection::Descending
            );
    }

    /** @return Builder<User> */
    public function query(): Builder
    {
        return User::query()
            ->select([
                'id',
                'name',
                'email',
                'created_at',
            ]);
    }
}

data() menjalankan schema melalui:

php

PandaPanel\Tables\TableQuery

yang sama dengan yang digunakan Resource Index.

Hasilnya:

Key	Type	Catatan
`columns`	`array`	Dari `TableSchema::toArray()['columns']`
`rows`	`list<array>`	Satu `TableSchema::toRow()` per record
`emptyMessage`	`string`	`static::$emptyMessage`
`state`	`array`	Search, sort, direction, perPage, filters, columns, group
`pagination`	`array{page, perPage, total, lastPage, from, to}`
`namespace`	`string`	`static::stateNamespace()`
`searchable`	`bool`	`TableSchema::isSearchable()`

stateNamespace() menghasilkan:

php

'widgets.'
. Str::kebab(
    class_basename(
        static::class
    )
)

Contoh:

php

RecentUsers::stateNamespace();

// 'widgets.recent-users'

Sehingga state Table berada di:

text

?widgets[recent-users][page]=2

Namespacing inilah yang memungkinkan beberapa Table Widget berada di satu Dashboard tanpa state saling bertabrakan.

Per-page options dipaksa menjadi:

php

[
    $perPage,
]

Artinya Table Widget tidak memiliki page-size control.

Table Widget merupakan ringkasan yang dapat:

dicari;
disortir;
dipaginate;

bukan Resource Index kedua.

Karena itu Table Widget tidak memiliki:

Bulk Actions;
Column Manager;
Filter Tabs.

`PandaPanel\Widgets\ChartWidget`

Defaults:

php

protected static int|string|array
    $columnSpan = [
        'default' => 1,
        'md' => 2,
        'lg' => 2,
        'xl' => 2,
    ];

protected static ChartVariant
    $variant =
        ChartVariant::Bar;

protected static int
    $maxHeight = 220;

API:

php

public static function type():
    WidgetType;
// WidgetType::Chart

/** @return list<string> */
abstract public function labels():
    array;

/** @return list<ChartSeries> */
abstract public function series():
    array;

public function options():
    ChartOptions;

Contoh:

php

use PandaPanel\Widgets\ChartWidget;
use PandaPanel\Widgets\Enums\ChartVariant;
use PandaPanel\Widgets\Enums\StatColor;
use PandaPanel\Widgets\Support\ChartOptions;
use PandaPanel\Widgets\Support\ChartSeries;

final class UserGrowth extends ChartWidget
{
    protected static ChartVariant
        $variant =
            ChartVariant::Area;

    protected static int
        $maxHeight = 200;

    /** @return list<string> */
    public function labels(): array
    {
        return [
            'Mar',
            'Apr',
            'May',
            'Jun',
            'Jul',
            'Aug',
        ];
    }

    /** @return list<ChartSeries> */
    public function series(): array
    {
        return [
            ChartSeries::make(
                'Sign-ups',
                [
                    4,
                    9,
                    7,
                    12,
                    18,
                    21,
                ]
            )
                ->color(
                    StatColor::Info
                ),
        ];
    }

    public function options():
        ChartOptions
    {
        return ChartOptions::make()
            ->legend(false)
            ->curved()
            ->filled();
    }
}

data() menghasilkan:

text

variant
labels
series
options
maxHeight

Setiap point pada seluruh series menggunakan daftar label yang sama.

Chart digambar menggunakan dependency-free inline SVG yang sudah di-compile.

Yang dikirim ke frontend adalah deskripsi Chart, bukan configuration tree untuk third-party chart library.

Jika kebutuhan Chart tidak dapat diekspresikan oleh:

php

ChartOptions

gunakan:

php

CustomWidget

`PandaPanel\Widgets\CustomWidget`

API:

php

/**
 * Path di bawah resources/js/pages/,
 * misalnya:
 * Panels/Admin/Widgets/ServerHealth
 */
protected static string
    $component = '';

public static function type():
    WidgetType;
// WidgetType::Custom

/**
 * @throws RuntimeException
 * jika $component kosong
 */
public static function component():
    string;

public function toDefinition():
    array;
// parent definition + component

Contoh:

php

use Illuminate\Foundation\Application;
use PandaPanel\Widgets\CustomWidget;

final class SystemInfo extends CustomWidget
{
    protected static string
        $component =
            'Panels/Admin/Widgets/SystemInfo';

    /**
     * @return array<string, mixed>
     */
    public function data(): array
    {
        return [
            'laravel' =>
                Application::VERSION,

            'php' =>
                PHP_VERSION,

            'environment' =>
                app()->environment(),
        ];
    }
}

Vue:

vue

<script setup lang="ts">
defineProps<{
    data: {
        laravel: string
        php: string
        environment: string
    }
}>()
</script>

<template>
    <dl class="space-y-1 text-sm">
        <div>
            <dt>Laravel</dt>
            <dd>{{ data.laravel }}</dd>
        </div>

        <div>
            <dt>PHP</dt>
            <dd>{{ data.php }}</dd>
        </div>

        <div>
            <dt>Environment</dt>
            <dd>{{ data.environment }}</dd>
        </div>
    </dl>
</template>

Component harus berada di:

text

resources/js/pages/Panels/**/Widgets/*.vue

Frontend me-resolve component menggunakan build-time:

import.meta.glob

Jadi component name yang tidak ikut di-compile tidak dapat diakses, apa pun string yang diterima runtime.

Unknown component:

merender neutral fallback;
memberikan warning sekali di development.

Lihat:

Custom Vue Widgets

`PandaPanel\Widgets\Support\Stat`

Stat merupakan:

php

final readonly

Fluent method-nya menghasilkan instance baru.

Jadi Stat tidak dimutasi setelah diserahkan Widget.

Constructor:

php

public function __construct(
    public string $label,

    public string|int|float $value,

    public ?string $description = null,

    public ?string $icon = null,

    public StatColor $color =
        StatColor::Default,

    public ?array $trend = null,

    public array $chart = [],

    public ?string $url = null,

    public ?string $prefix = null,

    public ?string $suffix = null,

    public ?int $decimals = null,
) {}

API:

Method	Signature
`make()`	`public static function make(string $label, string\|int\|float $value): self`
`description()`	`public function description(string $description): self`
`icon()`	`public function icon(string $icon): self`
`color()`	`public function color(StatColor $color): self`
`trend()`	`public function trend(string $direction, float $value): self`
`chart()`	`public function chart(array $values): self`
`url()`	`public function url(string $url): self`
`format()`	`public function format(?string $prefix = null, ?string $suffix = null, ?int $decimals = null): self`
`display()`	`public function display(): string`
`toArray()`	`public function toArray(): array`

Contoh:

php

use App\Panels\Admin\Resources\Users\UserResource;
use PandaPanel\Widgets\Enums\StatColor;
use PandaPanel\Widgets\Support\Stat;

Stat::make(
    'Revenue',
    12045
)
    ->format(
        prefix: '£',
        decimals: 2
    )
    // display: "£12,045.00"

    ->icon('receipt')

    ->color(
        StatColor::Success
    )

    ->trend(
        'up',
        12.4
    )
    // 'up' | 'down' | 'neutral'

    ->chart([
        4,
        9,
        7,
        12,
        18,
        21,
    ])

    ->url(
        UserResource::url()
    );

display() melakukan format di server karena server mengetahui arti angka tersebut.

Contoh:

php

Stat::make(
    'Revenue',
    1204.5
)
    ->format(
        prefix: '£',
        decimals: 2
    )
    ->display();

// '£1,204.50'

String tidak diubah:

php

Stat::make(
    'Uptime',
    '99.9%'
)
    ->display();

// '99.9%'

String dibiarkan persis seperti yang diberikan Widget.

Tanpa decimals:

text

float
→ 2 decimal

int
→ 0 decimal

toArray() mengirim:

text

label
value
display
description
icon
color
trend
chart
url

Property berikut tidak diserialisasi secara terpisah:

text

prefix
suffix
decimals

Ketiganya hanya digunakan untuk menghasilkan:

text

display

`PandaPanel\Widgets\Support\ChartSeries`

ChartSeries juga merupakan:

php

final readonly

Constructor:

php

/**
 * @param list<int|float> $values
 */
public function __construct(
    public string $label,

    public array $values,

    public StatColor $color =
        StatColor::Default,
) {}

Factory:

php

/**
 * @param list<int|float> $values
 */
public static function make(
    string $label,
    array $values
): self;

Color:

php

public function color(
    StatColor $color
): self;

Serialization:

php

/**
 * @return array{
 *     label: string,
 *     values: list<int|float>,
 *     color: string
 * }
 */
public function toArray():
    array;

Contoh:

php

use PandaPanel\Widgets\Enums\StatColor;
use PandaPanel\Widgets\Support\ChartSeries;

ChartSeries::make(
    'Sign-ups',
    [
        4,
        9,
        7,
    ]
)
    ->color(
        StatColor::Info
    )
    ->toArray();

Hasil:

php

[
    'label' =>
        'Sign-ups',

    'values' => [
        4,
        9,
        7,
    ],

    'color' =>
        'info',
]

`PandaPanel\Widgets\Support\ChartOptions`

ChartOptions merupakan closed set configuration.

Bukan arbitrary options tree.

Object ini mutable dan fluent.

Setiap method mengembalikan instance yang sama.

Method	Signature	Default
`make()`	`public static function make(): self`
`legend()`	`public function legend(bool $legend = true): self`	`true`
`grid()`	`public function grid(bool $grid = true): self`	`true`
`stacked()`	`public function stacked(bool $stacked = true): self`	`false`
`filled()`	`public function filled(bool $filled = true): self`	`false`
`curved()`	`public function curved(bool $curved = true): self`	`false`
`labels()`	`public function labels(bool $labels = true): self`	`false`
`range()`	`public function range(?float $min, ?float $max): self`	`null`, `null`
`format()`	`public function format(?string $prefix = null, ?string $suffix = null): self`	`null`, `null`
`toArray()`	`public function toArray(): array`

Contoh:

php

use PandaPanel\Widgets\Support\ChartOptions;

ChartOptions::make()
    ->legend(false)
    ->stacked()
    ->range(
        0,
        100
    )
    ->format(
        suffix: '%'
    )
    ->toArray();

Hasil:

php

[
    'legend' =>
        false,

    'grid' =>
        true,

    'stacked' =>
        true,

    'filled' =>
        false,

    'curved' =>
        false,

    'labels' =>
        false,

    'min' =>
        0.0,

    'max' =>
        100.0,

    'prefix' =>
        null,

    'suffix' =>
        '%',
]

range() berguna jika Chart dibaca terhadap target tetap, bukan relatif terhadap datanya sendiri.

Misalnya:

text

0–100%

Tanpa fixed range, axis yang terus menyesuaikan diri terhadap data dapat membuat setiap minggu terlihat memiliki bentuk yang hampir sama walaupun skala sebenarnya berubah.

`PandaPanel\Widgets\Support\ColumnSpan`

API:

php

/**
 * @param int|string|array<string, int|string> $span
 *
 * @return array{
 *     default: int|string,
 *     md: int|string,
 *     lg: int|string,
 *     xl: int|string
 * }
 */
public static function normalize(
    int|string|array $span,
    string $context = 'A widget'
): array;

Breakpoint yang tersedia:

text

default
md
lg
xl

Maximum span:

text

Value:

text

full

dibiarkan sebagai:

text

full

Contoh:

php

use PandaPanel\Widgets\Support\ColumnSpan;

ColumnSpan::normalize(2);

Hasil:

php

[
    'default' => 2,
    'md' => 2,
    'lg' => 2,
    'xl' => 2,
]

Partial breakpoint:

php

ColumnSpan::normalize([
    'default' => 1,
    'lg' => 2,
]);

Hasil:

php

[
    'default' => 1,
    'md' => 1,
    'lg' => 2,
    'xl' => 2,
]

md mewarisi:

text

default

Nilai terlalu besar:

php

ColumnSpan::normalize(99);

menjadi:

php

[
    'default' => 4,
    'md' => 4,
    'lg' => 4,
    'xl' => 4,
]

Karena maximum grid span adalah empat.

Dua kondisi menghasilkan:

php

PandaPanel\Exceptions\PanelSchemaException

Typo span:

php

ColumnSpan::normalize(
    'ful'
);

Secara konsep error-nya:

text

declares a column span of [ful],
which is neither a number nor "full"

Unknown breakpoint:

php

ColumnSpan::normalize([
    'default' => 1,
    'sm' => 2,
]);

Error:

text

declares a column span at [sm]
...
It has:
default, md, lg, xl

Angka di luar range dianggap permintaan untuk menggunakan lebih banyak Column daripada yang tersedia.

Framework dapat menjawab secara aman dengan:

text

Namun string tidak valid seperti:

text

ful

kemungkinan besar merupakan typo.

Fallback diam-diam ke 1 akan membuat Widget tampil seperempat lebar tanpa memberi tahu mengapa.

`PandaPanel\Widgets\Support\WidgetFilters`

WidgetFilters merupakan:

php

final readonly

Object ini dibuat oleh:

php

Page::resolveFilters()

Sebuah Widget hanya menerima bagian filter miliknya melalui:

php

withFilters()

API:

php

public static function none():
    self;

/**
 * @param array<string, FormSchema>
 * $widgetSchemas
 * keyed by widget id
 */
public static function fromRequest(
    Request $request,
    ?FormSchema $dashboardSchema = null,
    array $widgetSchemas = [],
    ?string $sessionKey = null,
): self;

/**
 * @return array<string, mixed>
 */
public function for(
    string $widgetId
): array;

/**
 * @return array<string, mixed>
 */
public function dashboard():
    array;

Contoh:

php

use PandaPanel\Forms\Components\Select;
use PandaPanel\Forms\FormSchema;
use PandaPanel\Widgets\Support\WidgetFilters;

$filters =
    WidgetFilters::fromRequest(
        request(),
        // ?filters[months]=6
        // &widgets[user-growth][months]=24

        FormSchema::make()
            ->schema([
                Select::make('months')
                    ->options([
                        '6' => '6',
                    ])
                    ->default('6'),
            ]),

        [
            'user-growth' =>
                FormSchema::make()
                    ->schema([
                        Select::make(
                            'months'
                        )
                            ->options([
                                '24' =>
                                    '24',
                            ]),
                    ]),
        ],

        'panel.admin.page.dashboard',
    );

Dashboard filter:

php

$filters->dashboard();

// ['months' => '6']

Widget-specific filter:

php

$filters->for(
    'user-growth'
);

// ['months' => '24']

Widget yang tidak memiliki override:

php

$filters->for(
    'recent-users'
);

// ['months' => '6']

Widget-specific filter memiliki prioritas terhadap Page filter.

Rules yang digunakan resolver:

Situasi	Hasil
Key tidak dideklarasikan schema	Dibuang
Parameter group tidak ada, session memiliki value	Gunakan stored value
Parameter group tidak ada, session kosong	Gunakan field default
Parameter group ada, tetapi field tidak dikirim	`null` — filter yang sudah dibersihkan tetap kosong

`PandaPanel\Widgets\PageContext`

PageContext merupakan:

php

final

Object ini menentukan informasi Page apa yang boleh diketahui Widget pada Resource Page.

API:

php

public static function forRecord(
    Model $record
): self;

/**
 * @param Closure():
 * Builder<covariant Model> $query
 */
public static function forQuery(
    Closure $query
): self;

public function record():
    ?Model;

/**
 * @return Builder<covariant Model>|null
 */
public function query():
    ?Builder;

public function count():
    int;

Contoh:

php

use PandaPanel\Widgets\PageContext;

PageContext::forRecord(
    $order
);

PageContext::forQuery(
    static fn () =>
        OrderResource::query()
);

count() di-memoize.

Jika tidak ada query:

php

dikembalikan.

Artinya Page dengan empat Widget yang tidak pernah memanggil:

php

context()->count()

tidak menjalankan query count tambahan.

Jika tiga Widget memanggilnya, query count tetap hanya berjalan sekali.

Context per Page:

Page	Context yang diberikan
`ListRecords`	`forQuery()`, sudah di-scope ke active Tab
`ViewRecord`, `EditRecord`	`forRecord()`
`ManageRelatedRecords`	`forRecord()` terhadap owner record
`CreateRecord`	Tidak ada
`Page`, `Dashboard`	Tidak ada

`PandaPanel\Pages\WidgetCollection`

WidgetCollection merupakan:

php

final readonly

Object ini me-resolve daftar Widget class sebuah Page menjadi props.

Authorization dilakukan:

text

lebih dulu
dan
sekali

API:

php

/**
 * @param list<class-string<Widget>> $classes
 */
public static function for(
    array $classes,
    ?PageContext $context = null,
    ?WidgetFilters $filters = null,
): self;

public function merge(
    self $other
): self;

/**
 * @param list<class-string<Widget>> $classes
 *
 * @return array<string, FormSchema>
 */
public static function filterSchemas(
    array $classes
): array;

/**
 * @return list<
 *     array<string, mixed>
 * >
 */
public function definitions():
    array;

public function deferred():
    mixed;

Contoh:

php

use PandaPanel\Pages\WidgetCollection;

$collection =
    WidgetCollection::for([
        UserStats::class,
        RecentUsers::class,
    ]);

$collection
    ->definitions();

// [
//     ['id' => 'recent-users', ...],
//     ['id' => 'user-stats', ...],
// ]

Jika tidak ada Widget lazy:

php

$collection->deferred();

// null

deferred() menghasilkan:

php

Inertia::defer()

dengan shape:

text

{
    widgetId: data
}

untuk Widget lazy.

Jika tidak ada lazy Widget:

php

null

dikembalikan sehingga Page tidak mengiklankan second request yang sebenarnya tidak diperlukan.

`PandaPanel\Core\WidgetRegistry`

WidgetRegistry merupakan:

php

final

Satu registry dibuat per Panel dan di-key berdasarkan Widget id.

API:

php

/**
 * @param class-string<WidgetContract> $widget
 */
public function register(
    string $widget
): void;

public function has(
    string $id
): bool;

/**
 * @return class-string<WidgetContract>|null
 */
public function byId(
    string $id
): ?string;

/**
 * @return list<
 *     class-string<WidgetContract>
 * >
 */
public function all():
    array;

public function count():
    int;

Contoh:

php

use PandaPanel\Core\PanelManager;

$registry =
    app(
        PanelManager::class
    )
        ->widgets(
            panel('admin')
        );

Seluruh Widget:

php

$registry->all();

Class names sudah diurutkan.

Lookup:

php

$registry->byId(
    'user-stats'
);

// 'App\Panels\Admin\Widgets\UserStats'

Check:

php

$registry->has(
    'nope'
);

// false

Jika dua Widget class pada Panel yang sama memiliki id sama:

php

PanelRegistrationException::duplicateWidgetId()

dilempar.

Karena id berasal dari basename class, maka:

text

Admin\Widgets\UserStats

dan:

text

Reports\UserStats

pada Panel yang sama akan bertabrakan.

Registration dan placement

Pada Panel

API:

php

/**
 * @param list<class-string> $widgets
 */
public function widgets(
    array $widgets
): self;

public function discoverWidgets(
    string ...$paths
): self;

/**
 * @return list<class-string>
 */
public function getWidgets():
    array;

/**
 * @return list<string>
 */
public function getWidgetDiscoveryPaths():
    array;

/**
 * @param class-string<Page> $page
 */
public function dashboard(
    string $page
): self;

/**
 * @param array<
 *     array-key,
 *     class-string<Page>
 * > $pages
 */
public function dashboards(
    array $pages
): self;

Contoh:

php

use App\Panels\Admin\Pages\AccountsDashboard;
use App\Panels\Admin\Widgets\RevenueChart;
use PandaPanel\Core\Panel;
use PandaPanel\Pages\Dashboard;

return $panel
    ->widgets([
        RevenueChart::class,
    ])
    ->discoverWidgets(
        app_path(
            'Panels/Admin/Widgets'
        )
    )
    ->dashboards([
        Dashboard::class,
        AccountsDashboard::class,
    ]);

Registration eksplisit digabungkan dengan discovery.

Jika class yang sama muncul pada keduanya:

text

hanya satu kali

dashboards() menjadikan entry pertama sebagai root Panel.

Entry sisanya diregistrasikan sebagai ordinary Pages.

Contoh:

php

[
    Dashboard::class,
    AccountsDashboard::class,
]

berarti:

text

Dashboard
→ Panel root

AccountsDashboard
→ own route
→ own navigation item
→ own filters

Jika dashboards() menerima empty array:

php

[]

Dashboard yang sudah ada tidak diubah.

Pada Page

API:

php

/**
 * @return list<class-string<Widget>>
 */
public function widgets():
    array;

public function filterSchema():
    ?FormSchema;

protected function filterSessionKey():
    string;

protected function resolveFilters():
    WidgetFilters;

protected function resolveWidgets(
    ?WidgetFilters $filters = null
): WidgetCollection;

PandaPanel\Pages\Dashboard::widgets() mengoverride default dan mengembalikan seluruh Widget di Panel registry.

filterSessionKey():

text

panel.{panelId}.page.{slug}

Contohnya:

text

panel.admin.page.dashboard

Dengan demikian dua Dashboard menyimpan filter masing-masing secara terpisah.

Contoh custom Page:

php

use PandaPanel\Pages\Page;
use PandaPanel\Widgets\Widget;

final class Reports extends Page
{
    /**
     * @return list<
     *     class-string<Widget>
     * >
     */
    public function widgets():
        array
    {
        return [
            RevenueChart::class,
            TopProducts::class,
        ];
    }
}

Sebuah Page merender props:

text

widgets
widgetData
filters

Pada Resource Page

API pada Resource:

php

public static function getWidgets():
    array;

public static function getHeaderWidgets(
    string $page
): array;

public static function getFooterWidgets(
    string $page
): array;

API pada Page instance:

php

/**
 * @return list<class-string<Widget>>
 */
public function headerWidgets():
    array;

/**
 * @return list<class-string<Widget>>
 */
public function footerWidgets():
    array;

/**
 * @return array<string, mixed>
 */
protected function widgetProps(
    ?PageContext $context = null
): array;

Contoh:

php

use PandaPanel\Resources\Pages\ListRecords;
use PandaPanel\Resources\Resource;
use PandaPanel\Widgets\Widget;

final class OrderResource extends Resource
{
    /**
     * @return list<
     *     class-string<Widget>
     * >
     */
    public static function getWidgets():
        array
    {
        return [
            OrderStats::class,
        ];
    }
}

final class ListOrders extends ListRecords
{
    /**
     * @return list<
     *     class-string<Widget>
     * >
     */
    public function headerWidgets():
        array
    {
        return [
            ...parent::headerWidgets(),
            RevenueChart::class,
        ];
    }
}

widgetProps() mengirim:

text

headerWidgets
footerWidgets
widgetData

widgetData merupakan satu shared deferred prop yang mencakup header dan footer Widget.

Filter Resource Page Widget di-resolve dari:

text

widgets[{id}]

dan disimpan per:

text

Panel
Resource
Page
Record Key

Discovery

API:

php

/**
 * @return list<
 *     class-string<WidgetContract>
 * >
 */
public function widgets(
    Panel $panel
): array;

Contoh:

php

use PandaPanel\Discovery\PanelDiscoverer;

app(
    PanelDiscoverer::class
)
    ->widgets(
        panel('admin')
    );

Discovery men-scan:

php

getWidgetDiscoveryPaths()

untuk class yang mengimplementasikan:

php

WidgetContract

Yang dilewati:

abstract base class;
Support/ value objects;
enums;

karena mereka tidak mengimplementasikan contract secara concrete.

Enums

php

enum PandaPanel\Widgets\Enums\WidgetType:
    string
{
    case Stats =
        'stats';

    case Table =
        'table';

    case Chart =
        'chart';

    case Custom =
        'custom';
}

enum PandaPanel\Widgets\Enums\StatColor:
    string
{
    case Default =
        'default';

    case Success =
        'success';

    case Warning =
        'warning';

    case Danger =
        'danger';

    case Info =
        'info';
}

enum PandaPanel\Widgets\Enums\ChartVariant:
    string
{
    case Bar =
        'bar';

    case Line =
        'line';

    case Area =
        'area';

    case Doughnut =
        'doughnut';
}

Ketiganya merupakan closed set karena frontend memetakan masing-masing case ke:

literal class;
atau renderer yang sudah di-compile.

Arbitrary color name dapat menghasilkan CSS class yang tidak pernah masuk bundle.

`PandaPanel\Contracts\WidgetContract`

Contract:

php

interface WidgetContract
{
    public static function id():
        string;

    public static function type():
        WidgetType;

    public static function canView():
        bool;

    /**
     * @return array<string, mixed>
     */
    public function toArray():
        array;
}

Contract ini diimplementasikan oleh:

php

PandaPanel\Widgets\Widget

Discovery dan registry melakukan type-hint terhadap contract ini.

Untuk penggunaan normal, extend salah satu base Widget daripada mengimplementasikan contract langsung.

Artisan

Command:

bash

php artisan make:panel-widget {name} --panel=Admin [--type=stats] [--force]

Options:

Option	Value	Default
`--panel`	Nama directory Panel	Wajib
`--type`	`stats`, `table`, `chart`, `custom`	`stats`
`--force`	Overwrite file yang sudah ada	Off

Contoh:

bash

php artisan make:panel-widget RecentOrders --panel=Admin --type=table

Custom:

bash

php artisan make:panel-widget ServerHealth --panel=Admin --type=custom

Class dibuat pada:

text

app/Panels/{Panel}/Widgets/{Name}.php

Untuk:

text

--type=custom

matching Vue component juga dibuat pada:

text

resources/js/pages/Panels/{Panel}/Widgets/{Name}.vue

Property:

php

$component

otomatis diisi:

text

Panels/{Panel}/Widgets/{Name}

Custom Widget tanpa component akan merender fallback.

Exceptions

Exception	Dilempar ketika
`PanelSchemaException::unusableColumnSpan()`	`$columnSpan` berupa string yang bukan numeric dan bukan `'full'`
`PanelSchemaException::unknownBreakpoints()`	`$columnSpan` menggunakan breakpoint di luar `default`, `md`, `lg`, `xl`
`PanelRegistrationException::duplicateWidgetId()`	Dua Widget class pada satu Panel memiliki id sama
`RuntimeException`	`CustomWidget::component()` dipanggil ketika `$component` kosong
`LogicException`	`Widget::context()` dipanggil pada Widget yang dirender tanpa Page Context

Gotchas

canView() dijalankan sebelum construction.
WidgetCollection::for() melewati class sepenuhnya jika authorization gagal. Karena itu data() tidak pernah berjalan dan tidak ada query yang dieksekusi. Menyembunyikan Widget hanya di frontend tetap akan membayar biaya query.
widgetData tidak bernilai null pada response pertama — key-nya belum ada.
Deferred prop belum tersedia sampai follow-up request selesai. Vue component yang membaca prop tersebut harus membuatnya optional, atau Vue dapat memberi warning karena required prop belum tersedia pada first paint.
Filter dan Page Context tidak digunakan bersama.
Dashboard atau standalone Page memberikan filter kepada Widget tetapi tidak memberikan context. Resource Page memberikan context tetapi tidak memberikan filter. context() pada Dashboard Widget akan throw, sedangkan filter() pada Resource Page Widget mengembalikan default.
Widget id berasal dari basename class.
Jika class:
text
```
UserGrowth
```
1
diganti nama, URL tersimpan seperti:
text
```
?widgets[user-growth][...]
```
1
tidak lagi cocok. Filter yang tersimpan di session di bawah id lama juga menjadi orphaned state.
Table Widget tidak memiliki page-size control.
data() mengunci:
php
```
perPageOptions([
    $perPage,
])
```
1
2
3
Jadi jika ingin jumlah row lebih banyak, ubah:
php
```
$perPage
```
1
Polling melakukan reload props milik Page, bukan hanya satu Widget.
Data Widget merupakan prop dari Page yang menampungnya. Karena itu $pollingInterval menyebabkan partial reload terhadap Page pada setiap interval untuk setiap browser tab yang sedang terbuka.
Definition Lazy Widget tetap dikirim langsung.
Yang ditunda hanya:
text
```
data
```
1
Sedangkan berikut tetap tersedia pada first paint:
text
```
heading
columnSpan
filters
polling
```
1
2
3
4
Stat::display() membiarkan string apa adanya.
format() hanya diterapkan pada:
text
```
int
float
```
1
2
Jika Widget sudah membuat formatted string sendiri, framework menghormati value tersebut.
Column span class ditulis lengkap di frontend.
Dynamic interpolation seperti:
text
```
md:col-span-${n}
```
1
belum tentu tersedia di compiled bundle.
Karena itu vocabulary span bersifat closed dan nilai numeric di luar range di-clamp.

Widgets ​

Contoh minimal yang berfungsi ​

PandaPanel\Widgets\Widget ​

Static configuration ​

Methods ​

id() ​

canView() ​

columnSpan() ​

withFilters() dan filter() ​

filterSchema() dan filtersInModal() ​

withPageContext() dan context() ​

toDefinition() ​

PandaPanel\Widgets\StatsWidget ​

PandaPanel\Widgets\TableWidget ​

PandaPanel\Widgets\ChartWidget ​

PandaPanel\Widgets\CustomWidget ​

PandaPanel\Widgets\Support\Stat ​

PandaPanel\Widgets\Support\ChartSeries ​

PandaPanel\Widgets\Support\ChartOptions ​

PandaPanel\Widgets\Support\ColumnSpan ​

PandaPanel\Widgets\Support\WidgetFilters ​

PandaPanel\Widgets\PageContext ​

PandaPanel\Pages\WidgetCollection ​

PandaPanel\Core\WidgetRegistry ​

Registration dan placement ​

Pada Panel ​

Pada Page ​

Pada Resource Page ​

Discovery ​

Enums ​

PandaPanel\Contracts\WidgetContract ​

Artisan ​

Exceptions ​

Gotchas ​

Lihat juga ​

Widgets

Contoh minimal yang berfungsi

`PandaPanel\Widgets\Widget`

Static configuration

Methods

`id()`

`canView()`

`columnSpan()`

`withFilters()` dan `filter()`

`filterSchema()` dan `filtersInModal()`

`withPageContext()` dan `context()`

`toDefinition()`

`PandaPanel\Widgets\StatsWidget`

`PandaPanel\Widgets\TableWidget`

`PandaPanel\Widgets\ChartWidget`

`PandaPanel\Widgets\CustomWidget`

`PandaPanel\Widgets\Support\Stat`

`PandaPanel\Widgets\Support\ChartSeries`

`PandaPanel\Widgets\Support\ChartOptions`

`PandaPanel\Widgets\Support\ColumnSpan`

`PandaPanel\Widgets\Support\WidgetFilters`

`PandaPanel\Widgets\PageContext`

`PandaPanel\Pages\WidgetCollection`

`PandaPanel\Core\WidgetRegistry`

Registration dan placement

Pada Panel

Pada Page

Pada Resource Page

Discovery

Enums

`PandaPanel\Contracts\WidgetContract`

Artisan

Exceptions

Gotchas

Lihat juga