Skip to content

yiisoft/widget

master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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 Factory instance to create widget objects, so you can require dependencies by listing them in your widget's constructor and set default values when initializing the factory. To initialize the widget factory call WidgetFactory::initialize() once before using widgets:

/**
 * @var \Psr\Container\ContainerInterface $container
 */
 
$widgetDefaults = [
    MyWidget::class => [
        'withNumber()' => [42],
    ],
];

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

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

About

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

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Packages

No packages published

Languages