Widgets ¶

Os widgets são blocos de construção reutilizáveis usados nas views (visões) para criar e configurar complexos elementos de interface do usuário sob uma modelagem orientada a objetos. Por exemplo, um widget datapicker pode gerar um calendário que permite aos usuários selecionarem uma data que desejam inserir em um formulário. Tudo o que você precisa fazer é apenas inserir um código na view (visão) conforme o seguinte:

<?php
use yii\jui\DatePicker;
?>
<?= DatePicker::widget(['name' => 'date']) ?>

Existe uma quantidade considerável de widgets empacotados no Yii, como o active form, o menu, o jQuery UI widgets, o Twitter Bootstrap widgets, etc. A seguir, iremos introduzir os conhecimentos básicos sobre os widgets. Por favor, consulte a documentação de classes da API se você quiser saber mais sobre o uso de um determinado widget.

Usando Widgets ¶

Os widgets são usados principalmente nas views (visões). Você pode chamar o método yii\base\Widget::widget() para usar um widget em uma view (visão). O método possui um array de configuração para inicializar o widget e retornar o resultado da renderização do widget. Por exemplo, o código a seguir insere um widget datapicker configurado para usar o idioma Russo e manter a data selecionada no atributo from_date do $model.

<?php
use yii\jui\DatePicker;
?>
<?= DatePicker::widget([
    'model' => $model,
    'attribute' => 'from_date',
    'language' => 'ru',
    'clientOptions' => [
        'dateFormat' => 'yy-mm-dd',
    ],
]) ?>

Alguns widgets podem ter um bloco de conteúdo que deve ser colocado entre as chamadas dos métodos yii\base\Widget::begin() e yii\base\Widget::end(). Por exemplo, o código a seguir usa o widget yii\widgets\ActiveForm para gerar um formulário de login. O widget irá gerar as tags de abertura e de fechamento do <form> respectivamente nos lugares onde os métodos begin() e end() foram chamados. Qualquer conteúdo entre estes métodos serão renderizados entre as tags de abertura e de fechamento do <form>.

<?php
use yii\widgets\ActiveForm;
use yii\helpers\Html;
?>

<?php $form = ActiveForm::begin(['id' => 'login-form']); ?>

    <?= $form->field($model, 'username') ?>

    <?= $form->field($model, 'password')->passwordInput() ?>

    <div class="form-group">
        <?= Html::submitButton('Login') ?>
    </div>

<?php ActiveForm::end(); ?>

Observe que ao contrário do yii\base\Widget::widget() que retorna a renderização de um widget, o método yii\base\Widget::begin() retorna uma instância do widget que pode ser usado para construir o seu conteúdo.

Criando Widgets ¶

Para criar um widget, estenda a classe yii\base\Widget e sobrescreva os métodos yii\base\Widget::init() e/ou yii\base\Widget::run(). Normalmente, o método init() deve conter os códigos que normalizam as propriedade do widget, enquanto o método run() deve conter o código que gera o resultado da renderização do widget. O resultado da renderização pode ser feito diretamente dando "echo" ou pelo retorno de uma string no método run().

No exemplo a seguir, o HelloWidget codifica o HTML e exibe o conteúdo atribuído à sua propriedade message. Se a propriedade não for definida, será exibido "Hello World" como padrão.

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::encode($this->message);
    }
}

Para usar este widget, simplesmente insira o código a seguir em uma view (visão):

<?php
use app\components\HelloWidget;
?>
<?= HelloWidget::widget(['message' => 'Good morning']) ?>

O HelloWidget abaixo é uma variante que pega o conteúdo entre as chamadas de begin() e end(), codifica o HTML e em seguida os exibe.

namespace app\components;

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

class HelloWidget extends Widget
{
    public function init()
    {
        parent::init();
        ob_start();
    }

    public function run()
    {
        $content = ob_get_clean();
        return Html::encode($content);
    }
}

Como você pode ver, o buffer de saída do PHP é iniciado no método init() para que qualquer conteúdo entre as chamadas de init() e run() possam ser capturadas, processadas e retornadas em run().

Informação: Ao chamar o yii\base\Widget::begin(), uma nova instância do widget será criada e o método init() será chamado logo ao final de seu construtor. Ao chamar o yii\base\Widget::end(), o método run() será chamado cujo o resultado da renderização será dado echo pelo end().

O código a seguir mostra como você pode usar esta nova variante do HelloWidget:

<?php
use app\components\HelloWidget;
?>
<?php HelloWidget::begin(); ?>

    um conteúdo qualquer...

<?php HelloWidget::end(); ?>

Algumas vezes, um widget pode precisar renderizar um grande conteúdo. Enquanto você pode inserir todo este conteúdo no método run(), uma boa prática é colocá-lo em uma view (visão) e chamar o yii\base\Widget::render() para renderizá-lo. Por exemplo,

public function run()
{
    return $this->render('hello');
}

Por padrão, as views (visões) para um widget devem ser armazenadas em arquivos sob o diretório WidgetPath/views, onde o WidgetPath significa o diretório que contém os arquivo da classe do widget. Portanto, o exemplo anterior irá renderizar o arquivo de view (visão) @app/components/views/hello.php, assumindo que a classe widget está localizada sob o diretório @app/components. Você pode sobrescrever o método yii\base\Widget::getViewPath() para personalizar o diretório que conterá os arquivos de views (visões) do widget.

Boas Práticas ¶

Os widgets são uma maneira orientada a objetos de reutilizar códigos de view (visão).

Ao criar os widgets, você ainda deve seguir o padrão MVC. Em geral, você deve manter a lógica nas classes widgets e manter as apresentações nas views (visões).

Os widgets devem ser projetados para serem autossuficientes. Isto é, ao utilizar um widget, você deverá ser capaz de removê-lo de uma view (visão) sem fazer qualquer outra coisa. Isto pode ser complicado se um widget requerer recursos externos, tais como CSS, JavaScript, imagens, etc. Felizmente, o Yii fornece o suporte para asset bundles, que pode ser utilizado para resolver este problema.

Quando um widget contiver somente código de view (visão), será bem semelhante a uma view (visão). Na verdade, neste caso, a única diferença é que um widget é uma classe para ser redistribuída, enquanto uma view é apenas um simples script PHP que você preferirá manter em sua aplicação