Extending Shopper
How to extend the Shopper admin panel sidebar
This guide covers how to add custom navigation items to the Shopper admin panel using the sidebar extension system.
Overview
Shopper uses an event-based system to build the sidebar. When the sidebar is rendered, it dispatches a SidebarBuilder event that you can listen to and add your own menu groups and items.
Creating a Sidebar Extension
1. Create an Extension Class
Create a class that extends AbstractAdminSidebar:
<?php
namespace App\Sidebar;
use Shopper\Sidebar\AbstractAdminSidebar;
use Shopper\Sidebar\Contracts\Builder\Group;
use Shopper\Sidebar\Contracts\Builder\Item;
use Shopper\Sidebar\Contracts\Builder\Menu;
class BlogSidebar extends AbstractAdminSidebar
{
public function extendWith(Menu $menu): Menu
{
$menu->group(__('Blog'), function (Group $group): void {
$group->weight(5);
$group->setAuthorized();
$group->item(__('Posts'), function (Item $item): void {
$item->weight(1);
$item->setAuthorized();
$item->useSpa();
$item->route('shopper.blog.posts.index');
$item->setIcon('phosphor-article');
});
$group->item(__('Categories'), function (Item $item): void {
$item->weight(2);
$item->setAuthorized();
$item->useSpa();
$item->route('shopper.blog.categories.index');
$item->setIcon('phosphor-folder');
});
});
return $menu;
}
}The $this->user property is available in your extension class to access the authenticated user for authorization checks.
Shopper draws its own entries with Phosphor icons (phosphor-*), and the admin panel styles fill every sidebar icon with the text color. Use Phosphor, or another Blade Icons set drawn with filled shapes: an outline icon, such as the Untitled UI icons that the sidebar package installs (untitledui-*), gets its outline filled in and shows as a solid shape.
2. Register the Extension
Register your sidebar extension in a service provider:
<?php
namespace App\Providers;
use App\Sidebar\BlogSidebar;
use Illuminate\Support\ServiceProvider;
use Shopper\Sidebar\SidebarBuilder;
class AppServiceProvider extends ServiceProvider
{
public function register(): void
{
$this->app['events']->listen(SidebarBuilder::class, BlogSidebar::class);
}
}Shopper registers its own sidebar listeners in the register() method of a service provider. The sidebar is built later, while the admin request runs, so a listener registered in boot() works too.
Weight System
The weight value determines the order of items and groups. Lower values appear first:
| Section | Weight |
|---|---|
| Dashboard | 1 |
| Catalog | 2 |
| Sales | 3 |
| Customers | 3 |
| Your Extension | 4 and above |
Choose a weight value that positions your menu in the desired location. The Settings link sits in the sidebar footer and does not use a weight.
Adding Sub-Items
Items can have nested sub-items for dropdown menus:
$group->item(__('Blog'), function (Item $item): void {
$item->weight(1);
$item->setAuthorized();
$item->route('shopper.blog.posts.index');
$item->setIcon('phosphor-article');
// Sub-items
$item->item(__('All Posts'), function (Item $subItem): void {
$subItem->weight(1);
$subItem->setAuthorized();
$subItem->useSpa();
$subItem->route('shopper.blog.posts.index');
});
$item->item(__('Create Post'), function (Item $subItem): void {
$subItem->weight(2);
$subItem->setAuthorized();
$subItem->useSpa();
$subItem->route('shopper.blog.posts.create');
});
});The sidebar adds the sh-items-has-child class to an item that has sub-items, which enables the dropdown styling.
Authorization
Permission-Based Authorization
Use Laravel's authorization system to control visibility:
$group->item(__('Posts'), function (Item $item): void {
// Only show if user can manage posts
$item->setAuthorized($this->user->can('manage_posts'));
// ... rest of configuration
});Role-Based Authorization
$group->item(__('Admin Settings'), function (Item $item): void {
$item->setAuthorized($this->user->isAdmin());
// ... rest of configuration
});Adding Badges
Show notification counts or labels on menu items. Every call to badge() adds a badge, so check the count before adding it:
use Shopper\Core\Enum\OrderStatus;
use Shopper\Core\Models\Order;
$group->item(__('Orders'), function (Item $item): void {
// ... item configuration
// Add a badge with the new order count
$count = Order::query()->where('status', OrderStatus::New)->count();
if ($count > 0) {
$item->badge($count, 'bg-danger-500 text-white');
}
});Adding Quick Actions (Append)
Add action buttons next to menu items:
$group->item(__('Customers'), function (Item $item): void {
// ... item configuration
// Add a "+" button to quickly create a customer
$item->append(function (Append $append): void {
$append->route('shopper.customers.create');
$append->setIcon('untitledui-plus');
$append->setName(__('Add Customer'));
$append->setClass('sh-sidebar-item-nav');
$append->setAuthorized($this->user->hasPermissionTo('add_customers'));
});
});Complete Example
Here's a complete example of a blog sidebar extension:
<?php
namespace App\Sidebar;
use App\Models\Post;
use Shopper\Sidebar\AbstractAdminSidebar;
use Shopper\Sidebar\Contracts\Builder\Append;
use Shopper\Sidebar\Contracts\Builder\Badge;
use Shopper\Sidebar\Contracts\Builder\Group;
use Shopper\Sidebar\Contracts\Builder\Item;
use Shopper\Sidebar\Contracts\Builder\Menu;
class BlogSidebar extends AbstractAdminSidebar
{
public function extendWith(Menu $menu): Menu
{
$menu->group(__('Content'), function (Group $group): void {
$group->weight(5);
$group->setAuthorized();
$group->item(__('Blog'), function (Item $item): void {
$item->weight(1);
$item->setAuthorized($this->user->can('manage_blog'));
$item->route('shopper.blog.posts.index');
$item->setIcon('phosphor-note-pencil');
// Badge for draft posts
$drafts = Post::draft()->count();
if ($drafts > 0) {
$item->badge(function (Badge $badge) use ($drafts): void {
$badge->setValue($drafts);
$badge->setClass('text-xs bg-warning-100 text-warning-700');
});
}
// Quick create button
$item->append(function (Append $append): void {
$append->route('shopper.blog.posts.create');
$append->setIcon('untitledui-plus');
$append->setName(__('New Post'));
$append->setClass('sh-sidebar-item-nav');
});
// Sub-items
$item->item(__('All Posts'), function (Item $subItem): void {
$subItem->weight(1);
$subItem->setAuthorized();
$subItem->useSpa();
$subItem->route('shopper.blog.posts.index');
});
$item->item(__('Categories'), function (Item $subItem): void {
$subItem->weight(2);
$subItem->setAuthorized();
$subItem->useSpa();
$subItem->route('shopper.blog.categories.index');
});
$item->item(__('Tags'), function (Item $subItem): void {
$subItem->weight(3);
$subItem->setAuthorized();
$subItem->useSpa();
$subItem->route('shopper.blog.tags.index');
});
});
$group->item(__('Pages'), function (Item $item): void {
$item->weight(2);
$item->setAuthorized($this->user->can('manage_pages'));
$item->useSpa();
$item->route('shopper.pages.index');
$item->setIcon('phosphor-file-text');
});
});
return $menu;
}
}Using Closures for Dynamic Sidebars
For simpler cases, you can use a closure instead of a class:
use Illuminate\Support\Facades\Event;
use Shopper\Sidebar\SidebarBuilder;
Event::listen(SidebarBuilder::class, function (SidebarBuilder $sidebar) {
$menu = $sidebar->getMenu();
$menu->group('Quick Links', function ($group) {
$group->weight(100);
$group->item('Documentation')
->setUrl('https://docs.example.com')
->isNewTab()
->setIcon('phosphor-book-open');
});
$sidebar->add($menu);
});Routes Configuration
Add your routes in the routes/shopper.php file (configured in config/shopper/routes.php):
use App\Http\Controllers\Shopper\CategoryController;
use App\Http\Controllers\Shopper\PostController;
use Illuminate\Support\Facades\Route;
Route::prefix('blog')->name('blog.')->group(function (): void {
Route::get('posts', [PostController::class, 'index'])->name('posts.index');
Route::get('posts/create', [PostController::class, 'create'])->name('posts.create');
Route::get('categories', [CategoryController::class, 'index'])->name('categories.index');
});All routes in routes/shopper.php are automatically prefixed with the Shopper route prefix and have the shopper. route name prefix. So the blog.posts.index route above becomes shopper.blog.posts.index.
Last updated on
Edit on GitHub