Control Panel#

You can add your own pages and dashboard widgets to Waterhole's Control Panel.

Pages#

Adding Routes#

The Control Panel is accessible under /cp by default (configurable in config/waterhole/cp.php), and all routes are named with the waterhole.cp. prefix. To register your own routes with these attributes, use the CpRoutes extender and define routes directly inside the extender callback using the Route facade:

use Illuminate\Support\Facades\Route;
use Waterhole\Extend;

$this->extend(function (Extend\Routing\CpRoutes $routes) {
    Route::get('my-route', MyController::class) // Path: /cp/my-route
        ->name('my-route');                     // Name: waterhole.cp.my-route
});

See Routes for more information.

Adding a Navigation Link#

The CpNav extender is a list of components that make up the CP navigation. You can add any component or view you want; typically you'll want to use a closure returning a NavLink component instance:

use Waterhole\View\Components\NavLink;
use Waterhole\Extend;

$this->extend(function (Extend\Ui\CpNav $nav) {
    $nav->add(
        key: 'resources',
        content: fn() => new NavLink(
            label: 'Resources',
            icon: 'tabler-star',
            route: 'waterhole.cp.resources',
        ),
    );
});

Rendering the CP Layout#

Use the <x-waterhole::cp> component to render your views inside the CP layout:

<x-waterhole::cp title="My Page">
    <!-- content -->
</x-waterhole::cp>

Adding Assets#

To add styles or scripts to the Control Panel (without adding them to the global bundle), use the Stylesheet and Script extenders and specify cp as the bundle name.

use Waterhole\Extend;

$this->extend(function (Extend\Assets\Stylesheet $stylesheets) {
    $stylesheets->add(__DIR__.'/../resources/less/test.css', 'cp');
});

$this->extend(function (Extend\Assets\Script $scripts) {
    $scripts->add(__DIR__.'/../resources/dist/test.js', 'cp');
});

See Assets for more information about how Waterhole manages assets.

Widgets#

Extensions can make widgets available to be displayed on the CP Dashboard.

Defining a Widget#

Widgets are just Blade components. So, to make a new widget available, define a new component:

namespace App\Widgets;

use Illuminate\View\Component;

class LatestResources extends Component
{
    public function render()
    {
        return view('widgets.latest-resources');
    }
}

Typically the widget view will contain a card beginning with a <h3> element:

<div class="card">
    <h3>Latest Resources</h3>
    <!-- ... -->
</div>

Widget Configuration#

Each Waterhole project can configure its widget layout in config/waterhole/cp.php – refer to the Dashboard customization documentation.

Any extra configuration options will be passed in when the widget is instantiated. For example, you could accept a limit configuration option (with a default value) like so:

class LatestResources extends Component
{
    public function __construct(public int $limit = 3)
    {
    }

    // ...
}

And then consumers can override it:

'widgets' => [
    [
        'component' => App\Widgets\LatestResources::class,
        'width' => 1 / 2,
        'limit' => 5,
    ],
]

Lazy Loading#

If your widget is a bit resource intensive – if it makes a HTTP request, or runs an expensive database query, for example – you can indicate that it should be loaded lazily, so as to not slow down the whole Dashboard loading.

Set a static $lazy property to true on your component, and Waterhole will take care of the rest:

class LatestResources extends Component
{
    public static bool $lazy = true;
}