Skip to content
widgets / 1

Locations

Last updated:

On this page

A location is a place in your theme where admins can put widgets: a sidebar, a footer column, the top of the home page. Locations are defined in code. Admins can't create them.

Defining a location

use Javaabu\Widgets\Facades\Widgets;
use Javaabu\Widgets\Widgets\ImageWidget;
use Javaabu\Widgets\Widgets\LinkWidget;
use Javaabu\Widgets\Widgets\TextWidget;

Widgets::location('sidebar', fn () => __('Sidebar'))
    ->description(fn () => __('Shown next to posts and pages'))
    ->max(6);

Widgets::location('footer', fn () => __('Footer'))
    ->allow([TextWidget::class, LinkWidget::class])
    ->max(3)
    ->permission('edit_footer_widgets')
    ->order(10);

Widgets::location('home_top', fn () => __('Home page'))
    ->deny([ImageWidget::class])
    ->wrapper('theme.widgets.card');
Method What it does
Widgets::location($key, $label) Defines the location, or returns it to change it. The label is a string or a closure, translated with __() when shown. Without a label, it's the headline of the key.
->description($text) Shown under the location on the admin page
->allow([...]) Only these widgets can be added: classes or keys
->deny([...]) These widgets can't be added
->max($count) The most widgets the location holds. Admins can't add or move more widgets into it.
->permission($name) The permission needed to change this location's widgets, instead of edit_widgets. It's registered with javaabu/permissions for you. See Permissions.
->wrapper($view) The Blade view each widget is wrapped in, instead of config('widgets.wrapper')
->order($position) Where the location is listed on the admin page, lowest first, then in the order defined

Locations can also be listed in config/widgets.php when a label is all they need:

'locations' => [
    'sidebar' => 'Sidebar',
    'footer' => 'Footer',
],

Widgets::locations() returns every location in order. Widgets::findLocation('sidebar') returns one or null, and Widgets::removeLocation('footer') removes one. Widgets in a location that no longer exists stay in the database, but they don't render or appear on the admin page.

Rendering a location in Blade

<aside>
    <x-widgets::location name="sidebar" class="flex flex-col gap-6" />
</aside>

It renders:

<div class="widgets widgets-sidebar flex flex-col gap-6" data-widget-location="sidebar">
    <section class="widget widget-text" id="widget-12" data-widget="text">
        <h2 class="widget-title">މަރުޙަބާ</h2>
        <div class="widget-text">…</div>
    </section>
    …
</div>

When the location has no widgets, it renders nothing. Add always to render the empty container anyway. To show something around the location only when it has widgets, use Widgets::has():

@if(Widgets::has('sidebar'))
    <aside class="sidebar">
        <x-widgets::location name="sidebar" />
    </aside>
@endif

Widgets::render('sidebar') returns the same widgets as an HtmlString, without the container.

The wrapper

Each widget is wrapped in widgets::wrapper, which gets $widget (the WidgetInstance), $definition (the Widget), $location and $slot:

{{-- resources/views/theme/widgets/card.blade.php --}}
<div class="card" id="widget-{{ $widget->id }}">
    <div class="card-body">{{ $slot }}</div>
</div>

Set it for one location with ->wrapper('theme.widgets.card'), or for all of them with config('widgets.wrapper').

Rendering a location in React

Send the widgets with the page. For widgets on every page, share them from HandleInertiaRequests:

use Javaabu\Widgets\Facades\Widgets;

public function share(Request $request): array
{
    return [
        ...parent::share($request),
        'widgets' => fn () => Widgets::props(['sidebar', 'footer']),
    ];
}

Then render them:

import { usePage } from "@inertiajs/react"
import { WidgetLocation, type WidgetLocations } from "@javaabu/widgets"

export function Sidebar() {
  const { widgets } = usePage<{ widgets: WidgetLocations }>().props

  return <WidgetLocation name="sidebar" widgets={widgets.sidebar} className="flex flex-col gap-6" />
}

<WidgetLocation> renders the same markup as <x-widgets::location>. It renders nothing when there are no widgets, unless you pass always. Pass wrapper={({ widget, children }) => …} to wrap each widget yourself.

Widgets::toArray('sidebar') gives one location, and Widgets::props() gives every location. Each widget is:

{ "id": 12, "type": "text", "component": "Text", "location": "sidebar", "settings": { "title": "މަރުޙަބާ", "text": "…" }, "data": {} }

Settings are in the current locale. data is what the widget's data() returned.

Reading widgets in PHP

Call Returns
Widgets::widgets('sidebar') Every WidgetInstance in the location, in order, including widgets whose type is no longer registered
Widgets::visible('sidebar') The widgets that render: registered types whose shouldRender() is true
Widgets::has('sidebar') Whether any widget renders
Widgets::render('sidebar') The HTML of the visible widgets
Widgets::toArray('sidebar') / Widgets::props([...]) The widgets for React

A location's widgets are loaded once per request. See Storage and caching to cache them between requests.

Documentation
All packages

javaabu/widgets

Source on GitHub