How to use the new Sharp for Laravel Show page feature

A step-by-step guide

Photo by Rob Laughter on Unsplash

The 4.2 release of Sharp brought Show page, which was presented in a previous post; let’s look in this one at some code to understand how, why and when to use Show pages.

I’ll use Saturn code: Saturn is the demo project attached to Sharp used for development and demo purpose (it is NOT included in Sharp when imported as a dependency). Before the Show page implementation, we can list spaceships, and display for each of them a few data in a table:

An EntityList of spaceships—with seeded data.

Clicking on a row leads us to the Form, and in some cases it’s not ideal. Let’s fix this by inserting a Show page between the List and the Form. It begins with an implementation of Code16\Sharp\Show\SharpShow:

I think there’s nothing really new here: available Show fields are documented but it’s pretty straightforward, if you already know how to use Form fields.

A quick side note on Pictures: we use a built-in transformer in this example, which simplify the work when using the Sharp way of handing uploads, but you can use your custom transformer for that: simply return a valid thumbnail URL.

Then we have to report this new class in Sharp’s config file, as usual:

// In config/sharp.php
return [
    "entities" => [
        "spaceship" => [
            "list" => \App\Sharp\SpaceshipSharpList::class,
            "show" => \App\Sharp\SpaceshipSharpShow::class,
            "form" => \App\Sharp\SpaceshipSharpForm::class,
        ],
        [...]
];

With this, Sharp will link the EntityList to the new Show:

And voilà. The “Edit” button leads to the Form.

Notice that sections are separators, that a section with one single field (like “description” here) is a good solution to display long text, which can be collapsed.

Of course, this page could be improved, but let’s focus on main issues:

How to add Commands in a Show?

In the EntityList, we can attach a list of instance Commands on each spaceship; well, those commands could easily be attached to the Show page, defining a buildShowConfig() method:

Commands of course work exactly the same as if they were declared in an EntityList (and in particular, the authorization system applies), and can be used in these two spots as you want. The visual result of this is:

A list of instance Commands…

And an EntityState handler.

How to embed a list in a Show?

This is I think the best feature of Show pages: we can embed, without a lot of work, a related EntityList right in the Show. In our case it seems useful to add the list of Pilots attached to a Spaceship. Since we already defined a PilotSharpList elsewhere, we can include it in our Show page:

And with that the whole pilots list, with filters, pagination and all its stuff, is embedded:

This isn’t really helping, we want to display only the pilots attached to the current spaceship… We can do that adding a few configuration lines, using the existing spaceships filter:

Notice we both value the Spaceship filter with the current $instanceId and we hide it (since we don’t want the user to change this), leading to the much more useful:

Only attached pilots are shown now.

Including Sharp’s reorder system is not difficult, from there; the API also allows to hide specific Commands or features (like search, which can be overkilling here). Finally you can, and that’s maybe a good choice, use a more specific version of an EntityList by extending it and adding / removing some behavior.

Now in our case, we would like to directly attach a newly created Pilot to the current Spaceship. On this topic, what happens if we click on the “New” button of the Pilots list? Well, the Pilot form is stacked and displayed, and Sharp takes us back to this Spaceship Show afterwards, thanks to an internal breadcrumb management.

So how to attach the new Pilot? with Context Api, you can grab this breadcrumb information and do… whatever you have to, when saving the Pilot. For instance:

If it seems odd to you to do this kind of stuff manually, remember that Sharp does not interfere with your data structure: you can do this however you need to.

What about single resources?

Mmm, this is for another post, but a quick spoiler: Sharp’s Show page can be used without any EntityList, and it is quite good to handle single resources like user preferences, for instance.

This Show page feature is available in Sharp 4.2, which is an open-source project developed by Code 16, hosted on Github and fully documented here. You’ll find a bunch of posts related to this project right here on Medium, and feel free to join me on twitter for anything else.