yiisoft/widget

Widget

dev-master / 3.0.x-dev 2021-10-20 09:43 UTC

This package is auto-updated.

Last update: 2021-10-20 09:43:13 UTC


README

68747470733a2f2f796969736f66742e6769746875622e696f2f646f63732f696d616765732f7969695f6c6f676f2e737667

Yii Widget


Latest Stable Version Total Downloads Build status Scrutinizer Code Quality Code Coverage Mutation testing badge static analysis type-coverage

Widgets are reusable building blocks used to create complex and configurable user interface elements in an object-oriented fashion.

This package provides an abstract class and a factory for creating widgets, ready-made widgets are provided in the yiisoft/yii-widgets package.

Installation

The package could be installed via composer:

composer require yiisoft/widget --prefer-dist

General usage

In order to implement your own widget, you need to create a class that extends the abstract class Yiisoft\Widget\Widget. In most cases it is enough to implement run() method.

final class MyWidget extends \Yiisoft\Widget\Widget
{
    protected function run(): string
    {
        return 'My first widget.'.
    }
}

To get the string "My first widget." in the view, call the widget() method. Inside which the Yiisoft\Widget\WidgetFactory will create an instance of the MyWidget, and when converting the object to a string, the declared run() method will be called.

<?= MyWidget::widget() ?>

The Yiisoft\Widget\WidgetFactory factory uses a PSR-11 Container instance to create widget objects, so you can require dependencies by listing them in your widget's constructor. To initialize the widget factory call WidgetFactory::initialize() once before using widgets.

/**
 * @var \Psr\Container\ContainerInterface $container
 */

\Yiisoft\Widget\WidgetFactory::initialize($container);

It is a good idea to do that for the whole application. See Yii example in the configuration file of this package config/bootstrap.php.

Configuring the widget

You can configure the widget when creating its instance, for example, the widget class must accept some ID when initializing the object.

final class MyWidget extends \Yiisoft\Widget\Widget
{
    private string $id;

    public function __construct(string $id)
    {
        $this->id = $id;
    }

    protected function run(): string
    {
        return $this->id;
    }
}

To set a value for the ID, you can pass it in the configuration array to the widget() method:

<?= MyWidget::widget([
    '__construct()' => [
        'id' => 'value',
    ],
]) ?>

For a description of the configuration syntax, see the yiisoft/factory package documentation.

Widget for capturing content

Some widgets can take a block of content which should be enclosed between the invocation of begin() and end() methods. These are wrapping widgets that mimic opening and closing HTML tags that wrap some content. They are used a bit differently:

<?= MyWidget::widget()->begin() ?>
    Content
<?= MyWidget::end() ?>

For your widget to do this, you need override the parent begin() method and don't forget to call parent::begin():

final class MyWidget extends \Yiisoft\Widget\Widget
{
    public function begin(): ?string
    {
        parent::begin();
        ob_start();
        ob_implicit_flush(false);
        return null;
    }

    protected function run(): string
    {
        return (string) ob_get_clean();
    }
}

The package ensures that all widgets are properly opened, closed and nested.

Additional methods for customizing the run

In addition to the run() method, you can override two other methods, beforeRun() and afterRun().

The beforeRun() method is called right before running the widget. The return value of the method will determine whether the widget should continue to run. When overriding this method, make sure you call the parent implementation like the following:

protected function beforeRun(): bool
{
    if (!parent::beforeRun()) {
       return false;
    }

    // your custom code here

    return true; // or false to not run the widget
}

The afterRun() method is called right after running the widget. The return value of the method will be used as the widget return value. If you override this method, your code should look like the following:

protected function afterRun(string $result): string
{
    $result = parent::afterRun($result);
    // your custom code here
    return $result;
}

Testing

Unit testing

The package is tested with PHPUnit. To run tests:

./vendor/bin/phpunit --testdox --no-interaction

Mutation testing

The package tests are checked with Infection mutation framework with Infection Static Analysis Plugin. To run it:

./vendor/bin/roave-infection-static-analysis-plugin

Static analysis

The code is statically analyzed with Psalm. To run static analysis:

./vendor/bin/psalm

License

The Yii Widget is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

Support the project

Open Collective

Follow updates

Official website Twitter Telegram Facebook Slack