Yii2 Widgets & Using Built-in Widgets

Introduction

Yii2 provides a powerful and flexible widget system that allows developers to create reusable UI components. Widgets are a type of reusable component that encapsulates a specific functionality and can be easily included in views. Yii2 comes with a set of built-in widgets, but you can also create custom widgets as needed.

Understanding Widgets in Yii2

Widgets in Yii2 are small, reusable components that help in rendering content dynamically. They are implemented as PHP classes extending yii\base\Widget. When a widget is used, Yii2 instantiates it, runs its logic, and outputs the result.

Widgets in Yii2 follow this structure:

1. Init: Prepares the widget before it gets executed.
2. Run: Executes the widget and returns the output.
3. View Rendering: Widgets usually render a view file.

Using Built-in Widgets

Yii2 provides several built-in widgets, including:

• ActiveForm - yii\widgets\ActiveForm
• ListView - yii\widgets\ListView
• DetailView - yii\widgets\DetailView
• GridView - yii\grid\GridView
• Menu - yii\widgets\Menu
• Breadcrumbs - yii\widgets\Breadcrumbs

Example of a Built-in Widget

Using ActiveForm Widget

use yii\widgets\ActiveForm;
use yii\helpers\Html;

$form = ActiveForm::begin();
    echo $form->field($model, 'username');
    echo $form->field($model, 'email');
    echo Html::submitButton('Submit', ['class' => 'btn btn-primary']);
ActiveForm::end();

This widget simplifies form creation and validation using Yii2's model system.

Creating a Custom Widget

Sometimes, built-in widgets do not fulfill all requirements, and custom widgets are needed. Below is an example of a custom widget.

Steps to Create a Custom Widget

1. Create a new PHP class extending yii\base\Widget.
2. Implement the run() method.
3. Optionally, include a separate view file for the widget output.

Example of a Custom Widget

Step 1: Create a Widget Class

namespace app\components;

use yii\base\Widget;
use yii\helpers\Html;

class HelloWidget extends Widget
{
    public $message;

    public function init()
    {
        parent::init();
        if ($this->message === null) {
            $this->message = 'Hello, World!';
        }
    }

    public function run()
    {
        return Html::tag('h1', Html::encode($this->message), ['class' => 'hello-widget']);
    }
}

Step 2: Use the Widget in a View

use app\components\HelloWidget;

echo HelloWidget::widget(['message' => 'Welcome to Yii2!']);

This will output:

<h1 class="hello-widget">Welcome to Yii2!</h1>

Real-World Example: Profile Menu Widget

Below is a real-world example of a Profile Menu Widget, commonly used in dashboards to show user information and options.

Widget Class (ProfileMenu.php)

namespace fdcore\widgets;

use Yii;
use yii\base\Widget;

class ProfileMenu extends Widget
{
    public $active_url;
    public $display = true;
    public $show_changepassword = true;
    public $show_darkmode_icon = false;

    public function run()
    {
        if (!Yii::$app->user->identity) {
            $this->display = false;
        }

        if ($this->display) {
            return $this->render('profilemenu', [
                'show_changepassword' => $this->show_changepassword,
                'show_darkmode_icon' => $this->show_darkmode_icon,
            ]);
        }
    }
}

Widget View File (profilemenu.php)

<?php if ($show_darkmode_icon) { ?>
<li class="dropdown nav-item">
    <a class="nav-link theme-layout layout-setting">
        <span class="dark-layout">🌙</span>
        <span class="light-layout">☀️</span>
    </a>
</li>
<?php } ?>

<li class="dropdown main-profile-menu">
    <a class="nav-link profile-user" href="#" data-bs-toggle="dropdown">
        <img src="/images/profile.jpg" alt="">
    </a>
    <div class="dropdown-menu">
        <div class="menu-header-content p-3 border-bottom">
            <div class="d-flex">
                <div class="main-img-user">
                    <img src="/images/profile.jpg" alt="">
                </div>
                <div class="ms-3 my-auto">
                    <h6 class="tx-15"> <?= Yii::$app->user->identity->fullname ?? '' ?> </h6>
                    <span class="tx-12"> <?= Yii::$app->user->identity->username ?? '' ?> </span>
                </div>
            </div>
        </div>
        <?php if ($show_changepassword) { ?>
            <a class="dropdown-item popupButton" value="/site/changepassword"><i class="fa fa-key"></i> Change Password</a>
        <?php } ?>
        <a class="dropdown-item" href="/site/logout" data-method="post">
            <i class="far fa-arrow-alt-circle-left"></i> Sign Out
        </a>
    </div>
</li>

Using the Profile Menu Widget in Views

echo ProfileMenu::widget(['show_changepassword' => true, 'show_darkmode_icon' => true]);

This widget dynamically displays a profile menu based on user authentication and provides options to log out or change the password.

Conclusion

Yii2 widgets are an essential feature for building reusable UI components. This tutorial covered:

• Understanding Yii2 widgets
• Using built-in widgets
• Creating custom widgets
• A real-world example of a profile menu widget

By mastering Yii2 widgets, you can create modular and maintainable web applications.