Skip to content

Configuration

Configure the sidebar cache, dimensions, breakpoint, collapsing and breadcrumb view, then customize the views and clear the cache.

The sidebar package reads its options from config/sidebar.php. Publish the file to change them:

php artisan vendor:publish --tag="sidebar-config"

Configuration Options

The file has five options: the cache, the two widths, the mobile breakpoint, collapsing, and the breadcrumb view.

Caching

Building a sidebar runs every listener, permission check and badge query on each request. The cache option stores the built sidebar instead:

'cache' => [
    'method' => null,
    'duration' => 1440,
],
OptionValuesDescription
methodnull, static, user-basedThe caching method. Any other value throws a SidebarResolverNotSupported exception.
durationIntegerHow long a cached sidebar is kept, in minutes. The default, 1440, is one day.

Each method stores the sidebar differently:

  • null builds the sidebar on every request. This is the default.
  • static stores one copy of each sidebar for each locale, shared by every user, under the shopper.sidebar. key followed by an md5 hash of the sidebar class name.
  • user-based stores one copy for each user and locale, tagged with that key. It needs a cache store that supports tags, such as Redis or Memcached. With a store that does not, such as file or database, the sidebar is built on every request, as with null.

With static, the first user who loads the sidebar decides what everyone sees: entries hidden by permissions stay hidden or visible for every user, and badge counts stay at their first value until the cache expires. The Shopper admin hides entries by permission, so keep null or use user-based there. With user-based, badge counts are also cached: flush the cache when they must change, as described in Clearing the Cache.

Dimensions

The two widths of the sidebar, expanded and collapsed:

'width' => '15rem',
'collapsed_width' => '4.5rem',
OptionDefaultDescription
width15remThe width of the expanded sidebar.
collapsed_width4.5remThe width of the collapsed sidebar.

Your layout passes these values to the CSS variables --sidebar-width and --sidebar-collapsed-width, as described in Injecting CSS Variables.

Responsive Breakpoint

The width in pixels below which the sidebar works as a mobile drawer:

'breakpoint' => 1024,

Below this width, the sidebar stays hidden until it is opened, toggle() opens and closes it instead of collapsing it, and a click on an entry closes it, as does the Escape key in the Livewire component. The store reads the value from the data-sidebar-breakpoint attribute of the <body>.

Collapsible

Whether the sidebar can collapse to icons from the breakpoint up:

'collapsible' => true,

With false, the store's collapse() and toggleCollapse() methods do nothing, and the default wrapper view hides its collapse button. The store reads the value from the data-sidebar-collapsible attribute of the <body>.

The Blade view that renders the breadcrumb trail:

'breadcrumbs' => [
    'view' => 'sidebar::breadcrumbs',
],

The package does not render this view by itself: your layout includes it, as described in Displaying the Breadcrumbs. In a Shopper application, Shopper sets this option to shopper::components.breadcrumbs when it registers, after the published file is loaded. To use another view there, set the option from the boot() method of a service provider:

config(['sidebar.breadcrumbs.view' => 'partials.breadcrumbs']);

Full Configuration Example

The published file with its default values:

config/sidebar.php
return [

    'cache' => [
        'method' => null,
        'duration' => 1440,
    ],

    'width' => '15rem',

    'collapsed_width' => '4.5rem',

    'breakpoint' => 1024,

    'collapsible' => true,

    'breadcrumbs' => [
        'view' => 'sidebar::breadcrumbs',
    ],

];

Environment Variables

The package reads no environment variable. To change an option per environment, such as the cache method in production, call env() in your published config/sidebar.php with variable names of your choice:

'cache' => [
    'method' => env('SIDEBAR_CACHE_METHOD'),
    'duration' => (int) env('SIDEBAR_CACHE_DURATION', 1440),
],

Then set the variables in the .env file of each environment:

SIDEBAR_CACHE_METHOD=user-based
SIDEBAR_CACHE_DURATION=60

Accessing Configuration

The helper functions of the Shopper\Sidebar namespace read the options:

use function Shopper\Sidebar\sidebar_breakpoint;
use function Shopper\Sidebar\sidebar_collapsed_width;
use function Shopper\Sidebar\sidebar_config;
use function Shopper\Sidebar\sidebar_is_collapsible;
use function Shopper\Sidebar\sidebar_width;

$cacheMethod = sidebar_config('cache.method');
$width = sidebar_width();
$collapsedWidth = sidebar_collapsed_width();
$breakpoint = sidebar_breakpoint();
$collapsible = sidebar_is_collapsible();

With the default configuration, they return null, 15rem, 4.5rem, 1024 and true. Helper Functions lists every helper.

Injecting CSS Variables

The views size the sidebar with CSS variables, and the store reads its breakpoint and collapsing options from the <body>. Set both in your layout:

resources/views/layouts/app.blade.php
<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
<head>
    <meta charset="utf-8">
    <style>
        :root {
            --sidebar-width: {{ \Shopper\Sidebar\sidebar_width() }};
            --sidebar-collapsed-width: {{ \Shopper\Sidebar\sidebar_collapsed_width() }};
        }
    </style>
</head>
<body
    data-sidebar-breakpoint="{{ \Shopper\Sidebar\sidebar_breakpoint() }}"
    data-sidebar-collapsible="{{ \Shopper\Sidebar\sidebar_is_collapsible() ? 'true' : 'false' }}"
>
    {{ $slot }}
</body>
</html>

The store's init() method reads the two data-* attributes when Alpine.js registers the store.

Customizing Views

Publish the views to change their markup:

php artisan vendor:publish --tag="sidebar-views"

The views are copied to resources/views/vendor/sidebar/, and Laravel uses your copies instead of the package views:

ViewRendersVariables
menu.blade.phpThe list of groups$groups, the rendered groups
group.blade.phpA group, with its heading$group, $items (the rendered entries)
item.blade.phpAn entry, with its badges, quick actions and sub-items$item, $items, $badges, $appends, $active
badge.blade.phpA badge$badge
append.blade.phpA quick action link$append
breadcrumbs.blade.phpThe breadcrumb trailNone, it calls sidebar_breadcrumbs()
livewire/sidebar.blade.phpThe wrapper of the Livewire component$sidebar, $renderedSidebar, $class, $collapsible

Example: Customizing the Item View

In the item view, $item is the entry builder, while $items, $badges and $appends hold the sub-items, badges and quick actions already rendered as HTML. $active tells whether the entry or one of its sub-items matched the request on the server. This version uses Tailwind classes and keeps the x-data and $store.sidebar bindings, so the active state still follows wire:navigate visits:

resources/views/vendor/sidebar/item.blade.php
<li
    @class(['store-sidebar-entry', 'store-sidebar-entry-current' => $active])
    x-data="{ url: @js($item->getUrl()), activeWhen: @js($item->getActiveWhen()) }"
>
    <a
        href="{{ $item->getUrl() }}"
        class="flex items-center gap-3 rounded-lg p-2 text-gray-700 hover:bg-gray-50"
        x-bind:class="{ 'bg-gray-100 font-medium text-gray-900': $store.sidebar?.isActive(url, activeWhen) }"
        @if ($item->withSpa()) wire:navigate @endif
        @if ($item->getNewTab()) target="_blank" @endif
    >
        @if ($item->iconSvg())
            {!! $item->getIcon() !!}
        @elseif ($item->getIcon() !== null)
            @svg($item->getIcon(), 'size-5 ' . $item->getIconClass(), $item->getIconAttributes())
        @endif

        <span class="flex-1" x-show="! $store.sidebar?.isCollapsed">{{ $item->getName() }}</span>

        @foreach ($badges as $badge)
            {!! $badge !!}
        @endforeach
    </a>

    @foreach ($appends as $append)
        {!! $append !!}
    @endforeach

    @if (count($items) > 0)
        <ul role="list" class="ml-4 space-y-1">
            @foreach ($items as $subItem)
                {!! $subItem !!}
            @endforeach
        </ul>
    @endif
</li>

Clearing the Cache

php artisan cache:clear empties the whole application cache, the sidebars included. The cache keys are hashed, so use the Shopper\Sidebar\Infrastructure\SidebarFlusher service rather than cache:forget to flush one sidebar. The container binds it to the flusher of the configured method:

use App\Sidebar\StoreSidebar;
use Shopper\Sidebar\Infrastructure\SidebarFlusher;

app(SidebarFlusher::class)->flush(StoreSidebar::class);

The static flusher deletes the shared copy, the user-based flusher deletes the copies of every user through the tag, and with null there is nothing to flush. The SidebarManager flushes every registered sidebar at once:

use Shopper\Sidebar\Infrastructure\SidebarFlusher;
use Shopper\Sidebar\SidebarManager;

app(SidebarManager::class)->flush(app(SidebarFlusher::class));

Flush after a change that a cached sidebar shows, such as new permissions for a role. In a Shopper application, the admin sidebar class is Shopper\Sidebar\AdminSidebar.

Last updated on

Edit on GitHub