Widgets

Widgets are interfaces that can be dynamically initialized by the administrator on any page.

In simple terms, a widget is an interface with logic that can be embedded on any page.

Widget Initialization

To initialize a widget in the system, you need to call the widgets()->register() function inside the ServiceProvider (or Extension):

public function register(\DI\ContainerBuilder $containerBuilder): void
{
    // Here we create an instance of our widget class
    widgets()->register(new ServersWidget);
}

Removing a Widget

Similarly, you need to remove the widget when uninstalling the module. This can be done in the Installer class:

Installer.php

<?php

class Installer extends AbstractModuleInstaller
{
    /** install() method */

    public function uninstall(\Flute\Core\Modules\ModuleInformation &$module) : bool
    {
        // Here we remove our widget from the system, providing the path to the class as an argument
        widgets()->unregister(ServersWidget::class);

        return true;
    }
}

Widget Structure

Widgets do not have a predefined structure. The main thing is for the widget to have a class responsible for its initialization in the system. For example:

<?php

namespace Flute\Modules\Monitoring\Widgets;

use Flute\Core\Database\Entities\Server;
use Flute\Core\Widgets\AbstractWidget;
use Flute\Modules\Monitoring\database\Entities\TestEntity;
use Flute\Modules\Monitoring\Services\ServersMonitorService;
use Nette\Utils\Html;

class ServersWidget extends AbstractWidget
{
    /**
     * Constructor, where you can add loading of widget assets, etc.
     */
    public function __construct()
    {
        $this->setAssets([
            mm('Monitoring', 'Resources/assets/js/monitoring.js'),
            mm('Monitoring', 'Resources/assets/scss/monitoring.scss'),
        ]);
    }

    /**
     * Function to render the widget
     */
    public function render(array $data = []): string
    {
        return render('Modules/Monitoring/Resources/Views/servers');
    }

    /**
     * Only for LazyLoad mode!
     *
     * Function to show HTML placeholder of the widget. May return nothing.
     */
    public function placeholder(array $settingValues = []): string
    {
        $row = Html::el('div');
        $row->addClass('row gx-4 gy-4');

        $col = Html::el('div');
        $col->addClass('col-md-4');

        $placeHolder = Html::el('div');
        $placeHolder->addClass('skeleton');
        $placeHolder->style('height', '200px');

        $col->addHtml($placeHolder);

        $row->addHtml($col);
        $row->addHtml($col);
        $row->addHtml($col);

        return $row->toHtml();
    }

    /**
     * Function to return the name of the widget
     */
    public function getName(): string
    {
        return 'Monitoring widget';
    }
}

Widget Settings

Flute allows you to create settings for widgets and automatically generate an interface for them. To create settings, simply write:

public function getDefaultSettings(): array
{
    $setting = new WidgetSettings;
    $setting->name = 'type';
    $setting->description = 'some.phrase';
    $setting->type = 'select';
    $setting->setValue([
        'items' => [
            'default',
            'table'
        ]
    ]);

    return [
        'type' => $setting
    ];
}

In this example, a setting with a dropdown is created. All settings will be passed as an argument to the placeholder and register functions. Setting types may vary. To find out what other types exist, see the WidgetSettings model and the already implemented modules.

Other

In a widget, there are many other functions for customization, but here are the main ones:

Setting an Image

This image will be visible in the page editor's modal:

public function __construct()
{
    $this->setImage('path_to_image.webp');
}

Setting LazyLoad Mode

LazyLoad mode is a mode in which the widget will be loaded only after the page is fully loaded. This provides faster loading for users if the widget requires a lot of resources to load.

warning

In LazyLoad mode, it is important to define a placeholder() to create skeleton blocks or others.

To set the LazyLoad parameter, simply specify it in __construct():

public function __construct()
{
    // We set the LazyLoad mode for the widget
    $this->setLazyLoad(true);
}

Widget Reload

Also, in LazyLoad widgets, there is a function for automatic reloading at the user's end. This is useful if you need to display up-to-date information from the widget.

note

During reloading, the render() method will be called each cycle.

Example of setting the reload time:

public function __construct()
{
    // Reload every 5 seconds
    $this->setReloadTime(5000);
}