# Widgets

Widgets display statistical information on a variety of dashboards.

You can use whatever is needed on the front-end, but you must use the underlying widget logic for everything on the back-end.

# Building widgets

To build a widget you extend the App\Services\Widgets\Contracts\Widget abstract class. This will perform the necessary permission checks.

The Widget abstract requires you to implement one method abilities. This should return an array or a string with any capabilities that are required to view this widget. It checks it with an "OR" method. If everyone can see your widget, you may simply return null or false.

use App\Services\Widgets\Contracts\Widget;

class MyAwesomeWidget extends Widget {
    public function abilities()
    {
        return null;
    }
}

When the widget above is rendered it will be rendered as a custom HTML tag, using the kebab-case version of the class name.

<my-awesome-widget></my-awesome-widget>

You can create a Vue component for this element, or override the toHtml() method on your widget to return something else, like a Blade view.

public function toHtml()
{
    return view('widgets.my-awesome-widget');
}

For convenience, you can also define data to return directly within the widget, using the data() method. This method is called if the widget has been requested via the App\Services\Widgets\Http\Controllers\Api\DataController.

This method receives an array of options and should return an array. For a more speedy response the contents of data() is cached in the controller and remembered for 60 minutes.

public function data($options = [])
{
    $name = $options['name'] ?? 'John';
    
    return [
        'something' => 'foo'. $name
    ];
}

# Registering widgets

The widget manager takes care of the widgets. You can register your widget through a service providers register method.

app('widgets')->register(new MyAwesomeWidget());

You can even register it using an array.

app('widgets')->register([
    new MyAwesomeWidget(),
    new MyOtherAwesomeWidget(),
    new MyNotSoAwesomeWidget(),
]);

# Displaying widgets

To display widgets you have two options.

# Use the render method

This method will echo the rendered html directly. The method takes two arguments. The first is an array of widget names to show and the second is a user object, used for authorizing widgets.

@php(app('widgets')->render([\App\Services\Candidates\Widgets\CandidatesWidget::class], auth()->user()));

# Use the show method

The show method is similar to the render method, but instead it returns a Collection of widgets. This can be used when you need to wrap your widgets in a certain way.

The collection contains the widget instances you requested.

@php($widgets = [
    \App\Services\Social\Widgets\SocialMediaWidget::class,
    \App\Services\Candidates\Widgets\DemographicsWidget::class,
    \App\Services\Candidates\Widgets\CareerTypesWidget::class,
])

@foreach(app('widgets')->show($widgets, auth()->user()) as $widget)
    <div class="card">
        <div class="card-block">
            <div class="card-title">{{$widget->name()}}</div>
            {!! $widget->toHtml() !!}
        </div>
    </div>
@endforeach