Appearance

Building an Entity List ​

We need an Entity List to display the list of instances for an entity. This list can be paginated, searchable, filtered, ... as we'll see below.

Generator ​

bash
php artisan sharp:make:entity-list <class_name> [--model=<model_name>]
php artisan sharp:make:entity-list <class_name> [--model=<model_name>]

Write the class ​

First let's write the applicative class, and make it extend Code16\Sharp\EntityList\SharpEntityList. Therefore, there are two methods to implement:

  • buildList(EntityListFieldsContainer $fields) for the structure,
  • and getListData() for the actual data of the list.

There are a two more optional methods, for the list config and instance deletion. Each one is detailed here:

buildList ​

A field is a column in the Entity List. This first function is responsible to describe each column:

php
function buildList(EntityListFieldsContainer $fields)
{
    $fields
        ->addField(
            EntityListField::make('name')
                ->setLabel('Full name')
                ->setSortable()
                ->setWidth(6)
                ->setWidthOnSmallScreens(8)
                ->setHtml()
        )
        ->addField([...]);
}
function buildList(EntityListFieldsContainer $fields)
{
    $fields
        ->addField(
            EntityListField::make('name')
                ->setLabel('Full name')
                ->setSortable()
                ->setWidth(6)
                ->setWidthOnSmallScreens(8)
                ->setHtml()
        )
        ->addField([...]);
}

Setting the label, allowing the column to be sortable and to display html is optional.

The -⁠>setWidth(int) method accepts an integer on a 12-based grid, and is optional too: if missing, it will be deduced (you can use -⁠>setWidthFill() to force this last behavior). You can also call -⁠>widthOnSmallScreens(int) or -⁠>widthOnSmallScreensFill) to define a custom width value for small screens. To hide the column on small screens, use -⁠>hideOnSmallScreens().

getListData ​

Now the real work: grab and return the actual list data. This method must return an array of instances of our entity. You can do this however you want, so let's see a generic example:

The returned array is meant to be built with 2 rules:

  • each item must define the keys declared in the buildList() function,
  • plus one attribute for the identifier, which is id by default (more on that later).

So for instance, if we defined 2 columns name and price:

php
function getListData()
{
    return [
        [
            'id' => 1,
            'name' => 'Carrot',
            'price' => '0.5'
        ], [
            'id' => 2,
            'name' => 'Potato',
            'price' => '0.95'
        ]
    ];
}
function getListData()
{
    return [
        [
            'id' => 1,
            'name' => 'Carrot',
            'price' => '0.5'
        ], [
            'id' => 2,
            'name' => 'Potato',
            'price' => '0.95'
        ]
    ];
}

Of course, real code would imply some data request in a DB, or a file for instance; the important thing is that Sharp don't care.

Transformers ​

In a more realistic project, you'll want to transform your data before sending it to the front code. Sharp can help with that, as explained in the detailed How to transform data documentation.

Handle query params ​

The EntityList has a valued $this-⁠>queryParams property. This object will be filled by Sharp with query params:

  • sorting: $this-⁠>queryParams-⁠>sortedBy() and $this-⁠>queryParams-⁠>sortedDir()
  • search: $this-⁠>queryParams-⁠>hasSearch() and $this-⁠>queryParams-⁠>searchWords()
  • filters: $this-⁠>queryParams-⁠>filterFor($filter)

If the Entity List was configured to handle sort, filters or search (see below to learn how), and if the user performed such an action, values will be accessible here.

You can use the queryParams everywhere except in the buildListConfig() function. Use cases could be, apart from filtering data: organizing columns, or maybe hiding commands...

Sort ​

$this-⁠>queryParams-⁠>sortedBy() contains the name of the attribute, and $this-⁠>queryParams-⁠>sortedDir() the direction: asc or desc.

Note that the ability of sorting a column is defined in buildList().

$this-⁠>queryParams-⁠>hasSearch() returns true if the user entered a search, and $this-⁠>queryParams-⁠>searchWords() returns an array of search terms. This last method can take parameters, here's its full signature:

php
public function searchWords(
    $isLike = true,
    $handleStar = true,
    $noStarTermPrefix = '%',
    $noStarTermSuffix = '%'
)
public function searchWords(
    $isLike = true,
    $handleStar = true,
    $noStarTermPrefix = '%',
    $noStarTermSuffix = '%'
)
  • $isLike: if true, each term will be surrounded by % (by default).
  • $handleStar: if true, and if a char * is found in a term, it will be replaced by % (default), and this term won't be surrounded by % (to allow "starts with" or "ends with" searches).
  • $noStarTermPrefix and $noStarTermSuffix: the char to use in a $isLike case.

Here's a code sample with an Eloquent Model:

php
if ($this->queryParams->hasSearch()) {
    foreach ($this->queryParams->searchWords() as $word) {
        $spaceships->where(function ($query) use ($word) {
            $query->orWhere('name', 'like', $word)
                ->orWhere('email', 'like', $word);
            });
        }
    }
}
if ($this->queryParams->hasSearch()) {
    foreach ($this->queryParams->searchWords() as $word) {
        $spaceships->where(function ($query) use ($word) {
            $query->orWhere('name', 'like', $word)
                ->orWhere('email', 'like', $word);
            });
        }
    }
}
Filters ​

A filter is referenced by a filterKey and has a value. So we can grab this calling $filterValue = $this-⁠>queryParams-⁠>filterFor($filterKey), and use the value in our query code.

Pagination ​

It's very common to return in getListData() paginated results: return a Illuminate\Contracts\Pagination\LengthAwarePaginator in this case.

With Eloquent or the QueryBuilder, this means calling -⁠>paginate($count) on the query.

delete ​

Here you might write the code performed on a deletion of the instance. It can be anything, here's an Eloquent example:

php
function delete($id): void
{
    Product::findOrFail($id)->delete();
}
function delete($id): void
{
    Product::findOrFail($id)->delete();
}

Deletion is typically an action you perform in a Show Page, but it is also available in the Entity List for convenience. You can configure this action to hide it, and of course leverage specific authorizations (more on this below).

buildListConfig ​

Finally, this last function must describe the list config. Let's see an example:

php
function buildListConfig()
{
    $this->configureInstanceIdAttribute('id')
        ->configureSearchable()
        ->configureDefaultSort('name', 'asc')
        ->configurePaginated();
}
function buildListConfig()
{
    $this->configureInstanceIdAttribute('id')
        ->configureSearchable()
        ->configureDefaultSort('name', 'asc')
        ->configurePaginated();
}

Here is the full list of available methods:

  • configureInstanceIdAttribute(string $instanceIdAttribute): define this if the id attribute of an instance is not id

  • configureReorderable(ReorderHandler|string $reorderHandler): allow instances to be rearranged; see detailed documentation

  • configureSearchable(): Sharp will display a search text input and process its content to fill EntityListQueryParams $queryParams (see above)

  • configureDefaultSort(string $sortBy, string $sortDir = "asc"): EntityListQueryParams $queryParams will be filled with this default value (see above)

  • configurePaginated(bool $paginated = true): this means that getListData() must return an instance of LengthAwarePaginator (see above) and that Sharp will display pagination links if needed

  • configureMultiformAttribute(string $attribute): handle various types of entities; see detailed doc

  • configurePageAlert(string $template, string $alertLevel = null, string $fieldKey = null, bool $declareTemplateAsPath = false): display a dynamic message above the list; see detailed doc

  • configureEntityState(string $stateAttribute, $stateHandlerOrClassName): add a state toggle, see detailed doc

  • configurePrimaryEntityCommand(string $commandKeyOrClassName): define an instance command as "primary", by passing its key or full cass name. The command should be declared for this Entity List (see related doc).

  • configureDelete(bool $hide = false, ?string $onfirmationText = null): the first argument is to show / hide the delete command on each instance (shown by default); this is only useful to hide the link if you want to only display the delete action in the Show Page (if you have defined one), this is NOT to be used for authorization purpose (see dedicated documentation on this topic). The second argument is the message to display in the confirmation dialog (a sensible default will be used).

Configure the Entity List ​

The Entity List must be declared in the correct entity class, as documented here: Write an entity).

After this we can access the Entity List at the following URL: /sharp/s-list/products (replace "products" by our entity key).

To go ahead and learn how to add a link in the Sharp side menu, look here.

Released under the MIT License.

Copyright © 2017-present Code16