DOCSEARCHbyAlgolia
Submit Docs

Sharp for Laravel

website·Indexed 33 days ago

https://sharp.code16.fr/docs/10.x/guide/

An administration panel for Laravel 11+ and PHP 8.3+ that allows developers to manage entities through Entity Lists, Forms, Show Pages, and Dashboards. It includes a variety of form fields (text, editor, upload, geolocation, etc.) and show fields, as well as tools for state management, filtering, and reordering instances.

Tokens
56.3K
Snippets
314
Records
403
Agent score
63%

What's inside Sharp

  1. Overview of the Geolocation form field

    The Geolocation field is a map-based input used to pick a precise location and return its coordinates as latitude and longitude. It is implemented via the Code16\Sharp\Form\Fields\SharpFormGeolocationField class.

  2. Implement a numeric text field using SharpFormNumberField

    Use the Code16\Sharp\Form\Fields\SharpFormNumberField class to create a numeric text field in a form. This field is designed specifically for handling numeric input and supports constraints on minimum and maximum values, as well as step increments for UI controls.

  3. Display dynamic HTML content using SharpFormHtmlField

    The Code16\Sharp\Form\Fields\SharpFormHtmlField is a read-only field used to display dynamic information within a form. It does not accept user input (fromFront returns null).

  4. Understand Sharp core concepts and terminology

    Sharp is designed around the concept of entities. An entity is a data structure with meaning in an application context (e.g., a Person, Post, or Order). While optimized for Eloquent Models, a Sharp entity can represent a single Model, a portion of a Model, or multiple Models. An individual occurrence of an entity is called an instance.

    Entities are typically managed through three primary UI components:

    1. Entity List: A view of all instances of an entity. It supports sorting, filtering, pagination, and searching. It also provides access to commands (actions applied to a single instance or the entire list) and state changers (e.g., toggling a 'published' status).
    2. Show Page: An optional detailed view for a specific instance.
    3. Form: Used to create a new instance or update an existing one.

  5. Implement a Single Show for unique resources

    Use a Single Show when a resource is unique (e.g., an account or configuration item) and does not fit a standard List/Show schema. To implement this, extend Code16\Sharp\Show\SharpSingleShow. You must implement buildShowFields(FieldsContainer $showFields) and buildShowLayout(ShowLayout $showLayout). Unlike standard shows, you must implement findSingle(): array without parameters, as the logic to determine the instance (e.g., based on the authenticated user) is handled internally.
    class ProfileSingleShow extends SharpSingleShow
{
    public function findSingle(): array
    {
        return $this->transform(auth()->user());
    }
}

  7. Test Entity Lists and List Commands

    The sharpList(string $entityKey) method initiates a fluent interaction with an Entity List. You can verify the list data, apply filters using withFilter(), execute Entity Commands via entityCommand(), execute Instance Commands via instanceCommand(), or delete an instance.
    // Test list data and filtering
$this->sharpList(Post::class)
    ->withFilter(CategoryFilter::class, 1)
    ->get()
    ->assertOk()
    ->assertListData(fn (AssertableJson $data) => $data
        ->count(3)
        ->has('0.title', 'My first post')
    );

// Test an Entity Command with a form
$this->sharpList(Post::class)
    ->entityCommand(ExportPosts::class)
    ->getForm()
    ->post(['format' => 'csv'])
    ->assertOk();

// Test an Instance Command
$this->sharpList(Post::class)
    ->instanceCommand(PublishPost::class, 1)
    ->post()
    ->assertOk();

// Delete an instance
$this->sharpList(Post::class)
    ->delete(1)
    ->assertOk();

  8. Update custom transformers for related models in Sharp 9.x

    In Sharp 9.x, the $instance parameter in setCustomTransformer now refers to the related model instead of the main model. This ensures the instance is the correct entity being transformed.
    // Sharp 9.x rewrite
$this
    ->setCustomTransformer('customer:name', function ($value, $instance, $attribute) {
        // $instance is now the Customer instance, not the Order instance
        return $instance->name;
    })
    ->transform(Order::find(1));

  9. Display localized data on a Show Page

    To implement a locale selector on a Show Page, configure the getDataLocalizations() method and mark the desired fields as localized using setLocalized().
    class BookShow extends SharpShow
{
    protected function buildShowFields(FieldsContainer $showFields): void
    {
        $showFields->addField(
            SharpShowTextField::make('title')
                ->setLabel('Title')
                ->setLocalized()
        );
    }

    public function getDataLocalizations(): array
    {
        return ['en', 'fr'];
    }
}

  10. Link upload models to entities using Morph relationships

    To associate uploads (like a cover or PDF) with a model, use a morphOne relationship. For Laravel 12+, use withAttributes to define the model_key. For versions prior to Laravel 12, use a where clause.
    // Laravel 12+
class Book extends Model
{
    public function cover()
    {
        return $this->morphOne(Media::class, 'model')
            ->withAttributes(['model_key' => 'cover']);
    }
}

// Before Laravel 12
class Book extends Model
{
    public function cover()
    {
        return $this->morphOne(Media::class, 'model')
            ->where('model_key', 'cover');
    }
}