README

Yii Widget

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.

Requirements

PHP 8.0 or higher.

Installation

The package could be installed with Composer:

composer require yiisoft/widget

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 render() method.

final class MyWidget extends \Yiisoft\Widget\Widget
{
    public function render(): 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 render() 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.

Documentation

Guide: English, Português - Brasil
Internals

If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.

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.

yiisoft / widget

Maintainers

Details