Skip to content
widgets / 1

Creating widgets

Last updated:

On this page

A widget type is a class that extends Javaabu\Widgets\Widget, with a Blade view and, if you render with React, a component.

The class

namespace App\Widgets;

use App\Models\Post;
use Javaabu\Stencil\Fields\Select;
use Javaabu\Stencil\Fields\TextInput;
use Javaabu\Widgets\Models\WidgetInstance;
use Javaabu\Widgets\Widget;

class RecentPostsWidget extends Widget
{
    public static function key(): string
    {
        return 'recent-posts';
    }

    public function name(): string
    {
        return __('Recent posts');
    }

    public function description(): ?string
    {
        return __('The latest posts, newest first.');
    }

    public function icon(): ?string
    {
        return 'newspaper';
    }

    public function settings(): array
    {
        return [
            TextInput::make('title')->label(__('Title'))->maxLength(255)->translatable(),
            TextInput::make('count')->label(__('Number of posts'))->integer()->minValue(1)->maxValue(20)->default(5)->required(),
            Select::make('category_id')->label(__('Category'))->options(fn () => Category::pluck('name', 'id')->all()),
        ];
    }

    public function data(WidgetInstance $widget): array
    {
        $posts = Post::query()
            ->published()
            ->when($widget->setting('category_id'), fn ($query, $category_id) => $query->where('category_id', $category_id))
            ->latest('published_at')
            ->limit($widget->setting('count'))
            ->get(['id', 'title', 'slug']);

        return [
            'posts' => $posts->map(fn (Post $post) => ['title' => $post->title, 'url' => route('posts.show', $post)])->all(),
        ];
    }

    public function shouldRender(WidgetInstance $widget): bool
    {
        return Post::query()->published()->exists();
    }
}
Method Default What it's for
key() required The unique key stored with each instance. Don't change it once widgets are saved.
name() required The name admins see
description() null A line about the widget on the admin page
icon() null A Lucide icon name
settings() [] The settings form: stencil components, with their labels, rules and defaults. Layouts (Section, Grid) work too.
data(WidgetInstance $widget) [] Extra data for the view and the React component, computed when the widget renders
view() widgets::widgets.{key} The Blade view
component() studly key (RecentPosts) The React component's name
title(WidgetInstance $widget) the title setting What the admin list calls an instance. It falls back to name().
shouldRender(WidgetInstance $widget) true Return false to skip an instance, such as when it has nothing to show

Register it in a service provider, or add it to config('widgets.widgets'):

use App\Widgets\RecentPostsWidget;
use Javaabu\Widgets\Facades\Widgets;

Widgets::register(RecentPostsWidget::class);

To replace a built-in widget, register your class with the same key.

Settings

Settings are stored as JSON on the widget instance, keyed by field name. Reading them:

$widget->setting('count');                 // the value, or the field's default
$widget->setting('title');                 // translatable: the current locale, falling back to the default locale
$widget->localizedSettings();              // every setting, as the view gets them
$widget->translations('title');            // ['en' => 'Latest', 'dv' => 'އެންމެ ފަހުގެ']

Defaults come from the fields' default(), so widgets saved before you added a setting still get a value. Everything stencil offers works in settings(): validation rules, visibleWhen() conditions, live() fields and custom field types. Settings that hold Dhivehi should use ->thaana() or, better, ->translatable(); see Translatable settings.

The Blade view

The view gets $widget (the WidgetInstance), $settings (every setting in the current locale) and each key from data():

{{-- resources/views/widgets/recent-posts.blade.php --}}
@if(filled($settings['title']))
    <h2 class="widget-title">{{ $settings['title'] }}</h2>
@endif

<ul class="widget-posts">
    @foreach($posts as $post)
        <li><a href="{{ $post['url'] }}">{{ $post['title'] }}</a></li>
    @endforeach
</ul>

Point view() at it:

public function view(): string
{
    return 'widgets.recent-posts';
}

Don't add a wrapper: the location's wrapper adds the <section> around the widget.

The React component

The component gets widget, settings and data, the same values as the Blade view:

// resources/js/widgets/RecentPosts.tsx
import type { WidgetComponentProps } from "@javaabu/widgets"

type Settings = { title?: string | null; count: number }
type Data = { posts: { title: string; url: string }[] }

export function RecentPosts({ settings, data }: WidgetComponentProps<Settings, Data>) {
  return (
    <>
      {settings.title ? <h2 className="widget-title">{settings.title}</h2> : null}
      <ul className="widget-posts">
        {data.posts.map((post) => (
          <li key={post.url}>
            <a href={post.url}>{post.title}</a>
          </li>
        ))}
      </ul>
    </>
  )
}

Register it once, where your app starts, by widget key or component name:

// resources/js/app.tsx
import { registerWidgets } from "@javaabu/widgets"
import { RecentPosts } from "./widgets/RecentPosts"

registerWidgets({ "recent-posts": RecentPosts })

Or pass it to one location: <WidgetLocation name="sidebar" widgets={…} components={{ RecentPosts }} />. A widget without a component is skipped, with a warning in development.

Keep the Blade view and the component's markup the same, so a page looks the same in either stack.

Testing a widget

use App\Widgets\RecentPostsWidget;
use Javaabu\Widgets\Facades\Widgets;
use Javaabu\Widgets\Models\WidgetInstance;

public function test_it_lists_recent_posts(): void
{
    Widgets::location('sidebar');
    Post::factory()->published()->create(['title' => 'ޚަބަރު']);

    WidgetInstance::create(['location' => 'sidebar', 'type' => 'recent-posts', 'settings' => ['count' => 3]]);

    $this->assertStringContainsString('ޚަބަރު', Widgets::render('sidebar')->toHtml());
    $this->assertEquals('ޚަބަރު', Widgets::toArray('sidebar')[0]['data']->posts[0]['title']);
}

To test the form, post to the admin route as a user with edit_widgets: $this->post('/widgets/sidebar?type=recent-posts', ['count' => '3']).

Documentation
All packages

javaabu/widgets

Source on GitHub