Sharp 4.1.3 and its new features

There is new on commands and filters

Photo by Tyler Nix on Unsplash

The 4.1 version of Sharp for Laravel was released a few weeks ago, with important new features, listed here. But there was a few missing, and that’s the purpose of this version 4.1.3.

If Sharp is new to you, please start here for a tour.

Commands in dashboards

Dashboards are much more powerful since the 4.1.0 version (generalization and filters). They gain another feature with the 4.1.3 version: the ability to handle Commands, just like Entity Lists. Nothing to really add here, it will work exactly like regular Commands, with 2 exceptions:

• A Dashboard Command must extend Code16\Sharp\Dashboard\Command\DashboardCommand which expose the same API as Entity List Commands
• And a Dashboard Command can not return the refresh() action, since there is no instance to refresh.

The Command is “Export as PDF” here.

Retained filters

This first new feature brings a huge simplification in a common process. Say you manage a sports team, with entities like matches, players, injuries, salaries, … When displaying injuries or salaries, you’ll want to have a “player filter” to display data only for him (or, let’s say, them: we’ll use a multiple filter here, because why not). Easy enough, and nothing new here:

class PlayerFilter implements EntityListMultipleFilter
{
    public function values()
    {
        return Player::orderBy("name")
            ->pluck("name", "id")
            ->all();
    }
}

The user can now filter the list on players. But a common need is to keep this filter while navigating: otherwise, coming back to the “injuries” Entity List, or even switching from “injuries” to “salaries” will reset this filter. Implementing this before Sharp 4.1.3 would mean handing a session store, maybe with filter callbacks, which could be tricky. But with the new retained filters feature, we just need to add a method on our filter:

class PlayerFilter implements EntityListMultipleFilter
{
    public function values()
    {
        return Player::orderBy("name")
            ->pluck("name", "id")
            ->all();
    }
    public function retainValueInSession()
    {
        return true;
    }
}

And that’s it! This will work with all types of filters, for Entity Lists and Dashboards.

Global filters

Let’s continue on this sports team example: we now want to “scope” all our data with a global “championship” filter. We can of course do this adding a filter on every Entity List which needs it, and with the retained filter feature, we can keep the chosen value across navigation.

But there is now a better solution: defining this filter on a global level, in the configuration, like this:

// sharp.php

return [
    [...]

    "global_filters" => [
        "championship" => ChampionshipGlobalFilter::class
    ],
    
    [...]
];

This ChampionshipGlobalFilter class is a regular filter, except on one point: instead of implementing ListFilter, ListRequiredFilter or ListMultipleFilter it must implement GlobalFilter, GlobalRequiredFilter or GlobalMultipleFilter.

class ChampionshipGlobalFilter implements GlobalRequiredFilter
{

    public function values()
    {
        return Championship::orderBy("name")
            ->pluck("name", "id")
            ->all();
    }

    public function defaultValue()
    {
        return Championship::first()->id;
    }
}

The Global Filter will appear over the menu, like this:

Closed, and opened. OK, that’s not championships, but you feel the idea…

Finally, to get the actual value of the filter on your Entity List or Form classes, you may use `SharpContext`(as documented here):

app(SharpContext::class)->globalFilterFor('championship')

Note that you could define more that one Global Filter (they will stack), and that Global Filter is a good way to scope data by user, maybe in a multi-clients app handled by Sharp.

That’s it for this 4.1.3 version, which brings three little but (hopefully) useful features. Sharp repo is open source on Github, there is more to learn about it on Medium, and you can find me on twitter to keep in touch.