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>

TIP

The Dashboard name should be singular, in CamelCase and must end with the "Dashboard" suffix. For instance: ActivityDashboard.

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(), 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
            ->declareEntity(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(CompanyDashboardEntity::class, '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.