Create a Dashboard

A Dashboard is a good way to present synthetic data to the user, with graphs, stats, or personalized reminders for instance.

Generator

php artisan sharp:make:dashboard <class_name>

Write the class

The first step is to create a new class extending Code16\Sharp\Dashboard\SharpDashboard, and to implement three functions:

• buildWidgets(WidgetsContainer $widgetsContainer),
• buildDashboardLayout(DashboardLayout $dashboardLayout),
• and buildWidgetsData(DashboardQueryParams $params), for the actual Dashboard data

buildWidgets

This method is meant to host the code responsible for the declaration and configuration of each widget. This must be done by calling $widgetsContainer-⁠>addWidget():

class SalesDashboard extends SharpDashboard
{
    // [...]
    function buildWidgets(WidgetsContainer $widgetsContainer): void
    {
        $widgetsContainer
            ->addWidget(
                SharpLineGraphWidget::make('sales')
                    ->setTitle('Sales evolution')
            )
            ->addWidget(
                SharpFigureWidget::make('pendingOrders')
                    ->setTitle('Pending orders')
                    ->setLink(LinkToEntityList::make('orders')->addFilter(StateFilter::class, 'pending'))
            );
    }
}

As we can see in this example, we defined two widgets giving them a mandatory key and some optional properties.

Every widget has the optional following setters:

• setTitle(string $title) for the widget title displayed above it
• setLink(SharpLinkTo $sharpLinkTo) to make the whole widget linked to a specific page (see dedicated SharpLinkTo documentation)

And here's the full list and documentation of each widget available, for the specifics:

• Graph
• Panel
• Figure
• OrderedList

buildDashboardLayout

The layout API is a bit different from Forms or Show Pages here, because we think in terms of rows and not columns.

function buildDashboardLayout(DashboardLayout $dashboardLayout): void
{
    $dashboardLayout
        ->addSection('Posts', function (DashboardLayoutSection $section) {
            $section->addRow(function (DashboardLayoutRow $row) {
                $row->addWidget(6, 'draft_panel')
                    ->addWidget(6, 'online_panel');
            });
        })
        ->addSection('Stats', function (DashboardLayoutSection $section) {
            $section->addFullWidthWidget('visits_line');
        });
}

Note that:

• Sections are optional but useful to group related widgets; you can add rows directly to the layout if you don’t need them.
• Rows group widgets in a 12-based grid.

buildWidgetsData

Widget data is set with specific methods depending on their type. The documentation is therefore split:

• Graph
• Panel
• Figure
• OrderedList

Configure the Dashboard

A Dashboard must have his own Entity class, as documented here.

Once this class (CompanyDashboardEntity for instance) written, we have to declare it:

class SharpServiceProvider extends SharpAppServiceProvider
{
    protected function configureSharp(SharpConfigBuilder $config): void
    {
        $config
            ->addEntity('company_dashboard', CompanyDashboardEntity::class)
            // [...]
    }
}

In the menu, like an Entity, a Dashboard can be displayed anywhere.

class AppSharpMenu extends SharpMenu
{
    public function build(): self
    {
        return $this
            ->addEntityLink('company_dashboard', 'Dashboard')
            // ...
    }
}

Dashboard commands

Like Entity Lists, Commands can be declared in a Dashboard with getDashboardCommands() : see the Command documentation.

And like Show Pages, Commands can be visually attached to a specific section:

protected function buildDashboardLayout(DashboardLayout $dashboardLayout): void
{
    $dashboardLayout
        ->addSection('Posts', function (DashboardLayoutSection $section) {
            // ...
        })
        ->addSection('Stats', function (DashboardLayoutSection $section) {
            $section
                ->setKey('stats-section') // <- define a key here...
                ->addRow(function (DashboardLayoutRow $row) {
                    // ...
                });
        });
}

public function getFilters(): ?array
{
    return [
        'stats-section' => [
            PeriodRequiredFilter::class,
        ],
    ];
}

public function getDashboardCommands(): ?array
{
    return [
        'stats-section' => [ // <- use the section key here...
            ExportStatsAsCsvCommand::class,
        ],
    ];
}

Dashboard filters

Just like Entity Lists, Dashboard can display filters, as documented on the Filter page.

And very much like Commands, Filters can be visually attached to a specific section of the dashboard:

public function getFilters(): ?array
{
    return [
        'stats-section' => [ // <- must be a section key
            PeriodRequiredFilter::class,
        ],
    ];
}

Dashboard policy

You can define a Policy for a Dashboard; see the authorization documentation.