Entity States

Entity states are a little bit of sugar to easily propose a state management on entities. It could be a simple "draft / publish" state for a page, or something more advanced for an order, for instance.

Generator

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

Write the Entity state class

First, you'll have to write a class that extends the Code16\Sharp\EntityList\Commands\EntityState abstract class.

You'll have to implement two functions: buildStates() and updateState($instanceId, $stateId).

Build the states

The goal is to declare the available states for the entity, using $this->addState():

protected function buildStates()
{
    $this->addState("active", "Active", "green")
        ->addState("inactive", "Retired", "orange")
        ->addState("building", "Building process", static::GRAY_COLOR)
        ->addState("conception", "Conception phase", static::DARKGRAY_COLOR);
}

$this->addState() take 3 parameters:

• first, a key, identifting the state,
• then, the state label as shown to the user,
• and finally a color to display.

For the color, you may indicate:

• an HTML color name
• a Sharp constant, from its UI: PRIMARY_COLOR, SECONDARY_COLOR, GRAY_COLOR, LIGHTGRAY_COLOR, DARKGRAY_COLOR
• or an hexadecimal value, starting with #.

Update a state

When the user clicks on a state to update it, this is the functional code called.

public function updateState($instanceId, $stateId)
{
    Spaceship::findOrFail($instanceId)->update([
        "state" => $stateId
    ]);

    return $this->refresh($instanceId);
}

Note the return $this->refresh($instanceId);: Entity states can return either a refresh or a reload (as described in the previous chapter, Commands), but if omited the refresh of the $instanceId is the default (meaning in the code sample above this line can be deleted).

Configure the state

Once the Entity state class is defined, we have to add it in the Entity List config:

function buildListConfig()
{
    $this->setEntityState("state", SpaceshipEntityState::class)
    [...]
}

The first parameter is a key which should be the name of the attribute.

Authorizations

Entity states can declare an authorization check very much like Instance Commands:

public function authorizeFor($instanceId): bool 
{
    return Spaceship::findOrFail($instanceId)->owner_id == sharp_user()->id;
}