Evolve Docs

Appearance

Global Search and Command Palette ​

Add your resources to the Evolve global search, and your screens and actions to the Cmd-K palette.

Implement the Searchable interface ​

Your models should implement the Searchable interface and define the following functions:

php
public function scopeSearch(Builder $query, string $keyword)
{
   // Eloquent query to search for a given `$keyword`
}

public function getSearchableTitle(): string
{
    // Define the title for a search result
}

public function getSearchableDescription(): ?string
{
    // Define the description for a search result
}

public function getSearchableAdminUrl(): string
{
    // Define the backend route for when a user 
    // clicks on a search result in the control panel
}

Search results, the activity log and the media usage list also show single blocks. A click on one opens the editor of the record the block sits on. If your model carries blocks (use HasBlocks), implement BlockContainer and return the URL of its block editor. Add ?blockId= so the editor opens the block directly:

php
use Racerfish\Evolve\Contracts\BlockContainer;
use Racerfish\Evolve\Models\Block;

class Order extends Model implements BlockContainer
{
    use HasBlocks;

    public function blockEditUrl(Block $block): string
    {
        return route('shop.order.edit', $this->getKey()) . '?blockId=' . $block->getKey();
    }
}

The route must render the block editor (@livewire('evolve::block.editor', ['blockable' => $item])). Nested blocks ask their parent block, so a card inside a cards block opens in the same editor. A model without the contract links to the page editor, which only fits pages. Pages, sections and all models of the bundled modules implement it.

Register searchable models ​

Register your searchable models in config/evolve.php or in the module registration searchable option:

php
Evolve::registerModule('blog', [
    // ...
    'searchable' => [
        Post::class,
    ]
]);

Optionally name the heading of your results in the Cmd-K palette. Without it the plural class name is used:

php
public static function getSearchableGroupLabel(): string
{
    return __('shop::views.orders');
}

Content search is limited to the roles in evolve.roles.search (default developer, admin, content_manager).

Command palette ​

Cmd+K lists panel screens (views) and things to start (actions) next to the content results. Each entry is a PanelCommand pointing at a named route. It only shows when the route exists and the user passes every role: middleware on it, so you rarely need to repeat roles.

Modules pass their commands with the registration. The module label (or name) is shown next to each entry:

php
use Racerfish\Evolve\Support\PanelCommand;

Evolve::registerModule('blog', [
    // ...
    'label' => 'blog::views.blog', // optional, defaults to 'name'
    'commands' => [
        PanelCommand::view('blog::views.posts', 'blog.post.index')->icon('newspaper'),
        PanelCommand::view('blog::views.categories', 'blog.category.index')->icon('newspaper'),
        PanelCommand::action('blog::views.new-post', 'blog.post.create')->keywords(['article', 'artikel']),
    ],
]);

A host app registers its own in a service provider. A closure runs per request and can build commands from data:

php
use Racerfish\Evolve\Facades\Evolve;
use Racerfish\Evolve\Support\PanelCommand;

Evolve::registerCommands([
    PanelCommand::view('Orders', 'app.order.index')->icon('bag')->keywords('bestellungen'),
    PanelCommand::action('New order', 'app.order.index', ['create' => 'true']),
    fn () => Shop::pluck('name', 'id')->map(
        fn (string $name, int $id) => PanelCommand::view($name, 'app.shop.show', ['shop' => $id])->icon('bag')
    ),
]);
  • view() and action() take a label (translation key or plain text), a route name and route parameters. Actions get the plus icon.
  • ->icon() takes a panel icon name (or a Font Awesome alias).
  • ->keywords() adds search terms in any language. The English label is searchable anyway.
  • ->context() sets the muted text next to the label.
  • ->roles('admin|developer') narrows an entry further than its route does.
  • For a list with a drawer, point the action at the list with ['create' => 'true']. For a resource with its own create page, point it at the .create route.